# Testing and troubleshooting Amazon GameLift Servers
This section provides guidance for diagnosing and resolving issues with your Amazon GameLift hosting solution. Whether you're experiencing problems during development, deployment, or production operations, these resources will help you identify root causes and implement effective solutions.
+ **Development and testing environments** - Set up iterative development workflows that mirror production conditions, enabling you to catch and resolve integration issues early in your development cycle.
+ **Fleet deployment and management** - Diagnose common fleet creation failures, server process activation issues, scaling problems, and deployment errors that can prevent your game servers from running properly.
+ **Runtime diagnostics and monitoring** - Access live fleet instances for real-time troubleshooting, performance analysis, and configuration validation to resolve issues affecting player experience.
Use these resources alongside Amazon GameLift's monitoring and logging capabilities to maintain optimal performance and availability for your multiplayer games.
# Set up for iterative development with Amazon GameLift Servers Anywhere
Amazon GameLift Servers provides tools and solutions to help you set up a hosted test environment for use during game development. With these tools, you can create an environment that mirrors the real-world player experience of managed hosting with Amazon GameLift Servers and supports a rapid, iterative development process.
With a separate test environment, you remove the overhead of an Amazon GameLift Servers managed fleet during testing. You no longer have to upload each new game server build iteration, create a new fleet for it, and then wait 15\$1 minutes to it to activate. Instead, you can create a new build, quickly update the test fleet with the new build, start it, and commence testing.
Using an Amazon GameLift Servers Anywhere fleet, you can set up a test environment using a local device, such as your development workstation. You can also set up a test environment using a cloud-based hosting resource.
Set up an Anywhere test environment to develop and test a range of scenarios, including these:
+ Test your game server integration with the Amazon GameLift Servers server SDK. You can test even without a working game client by using AWS CLI calls to start new game sessions and track game session events.
+ Test interactions between your game client, backend service, and the Amazon GameLift Servers service as you develop components for your game. Fine-tune the player experience for joining a game.
+ Experiment with your FlexMatch matchmaker design. Try out rule set variations and other matchmaking feature implementations. Set up and test matchmaking backfill.
+ Try out other Amazon GameLift Servers hosting features, such as runtime configuration settings (with the Amazon GameLift Servers Agent) for game server life cycle management.
+ Quickly build, test, and repeat to validate all aspects of your game's player experience, including multiplayer interactions, in a live, hosted environment.
Later, as you prepare your game for launch, you'll want to add Amazon GameLift Servers managed fleets to fine-tune your hosting configurations and test additional scenarios, including the following:
+ Experiment with and test game session queue designs, including use of multi-location fleets, Spot and On-Demand fleets, and multiple instance types.
+ Try out game session placement options with managed fleets, including the use of optional latency policies and fleet prioritization settings.
+ Configure capacity scaling to meet player demand, using automatic or manual scaling options.
+ Set up AWS CloudFormation with Amazon GameLift Servers managed fleets to manage your hosting resources long term.
**Fast Build Update Tool (for development only)**
With managed EC2 fleets, to deploy a game server build update, you need to upload each new build to Amazon GameLift Servers and create a new fleet for it.
The Fast Build Update Tool lets you can bypass these steps during development, saving you time and allowing for faster development iteration. With this tool, you can quickly update your game build files across all computes in an existing fleet. The tool has several options; you can replace an entire game build or change 6 specific files, and you can manage how to restart game server processes after the updates. You can also use it to update individual computes in a fleet.
To get the Fast Build Update Tool and learn more about how to use it, visit the Amazon GameLift Servers Toolkit repo for [ The Fast Build Update Tool](https://github.com/aws/amazon-gamelift-toolkit/tree/main/fast-build-update-tool) in Github.
**Topics**
+ [Build a cloud-based test environment](integration-dev-iteration-cloud.md)
+ [Set up local testing with Amazon GameLift Servers Anywhere](integration-testing.md)
+ [Test your integration using Amazon GameLift Servers Local](integration-testing-local.md)
# Build a cloud-based test environment
**Note**
This topic covers iterative testing for games that are integrated with the server SDK for Amazon GameLift Servers version 5.x. If your game uses server SDK version 4.x or earlier, see [Test your integration using Amazon GameLift Servers Local](integration-testing-local.md).
Use an Amazon GameLift Servers Anywhere fleet to iteratively build and test your game components in a cloud-based hosted environment. Create an Anywhere fleet with hosting resources and a connection to the Amazon GameLift Servers service, run your game servers on them, and test game functionality as needed.
**Deploy an Anywhere fleet with the Amazon GameLift Servers Agent**
If your game server build is integrated with Amazon GameLift Servers SDK 5.x or later, you can deploy it to a cloud-based Anywhere fleet with the Amazon GameLift Servers Agent. The Agent is a background process that manages game server life cycles and other tasks on each compute in a fleet. These tasks include registering the compute with an Anywhere fleet, acquiring an authentication token, and starting/stopping game server processes based on a set of instructions. The Agent is controlled by a fleet's runtime configuration, which you can update at any time during the life of the fleet. (The Agent is automatically deployed to managed EC2 fleets.) For more information and to download the Agent, see the [Amazon GameLift Servers GitHub repository](https://github.com/aws/amazon-gamelift-agent).
## Set up iterative testing with Amazon EC2
Use the guided workflow in this [Amazon GameLift Servers toolkit solution]( https://github.com/aws/amazon-gamelift-toolkit/tree/main/development-instance-with-amazon-gamelift-anywhere-and-gamelift-agent) to set up a cloud-based hosting environment that mirrors the managed hosting experience with Amazon GameLift Servers.
The GitHub repository provides a set of scripts that automate most of the processes for setting up a test environment with Amazon GameLift Servers Anywhere and the Amazon GameLift Servers Agent. It also provides guidance for updating the environment whenever you have a new game server build to test. You can run a single script that deploys a test environment with a sample game server build, or you can walk through each step to set it up with your own game server build.
In this workflow, you'll work entirely in the AWS Management Console, using AWS CloudShell to run scripts and complete command-line tasks.
**Note**
For the tasks in this tutorial, you need an AWS account user with permissions for the following services: Amazon GameLift Servers, AWS CloudShell, Amazon S3, AWS Systems Manager, Amazon EC2, and AWS Identity and Access Management. Users with admin-level access to the AWS account already have the required permissions.
The workflow covers the following tasks:
+ **Package a game server build for Amazon GameLift Servers. **The workflow provides a script to build a sample C\$1\$1 game server, which has already been integrated with the server SDK for Amazon GameLift Servers version 5.x and is ready for hosting. Alternatively, you can work with your own game project if you've completed integration.
+ **Set up an Amazon Simple Storage Service bucket to store game server builds and dependencies.** As you produce new versions of your game builds, you can store them in S3 and use the scripts to update the Anywhere fleet for game testing.
+ **Get and build the Amazon GameLift Servers Agent.** The Agent manages game server processes on a hosting resource based on your configuration. It uses the same logic and behaves identically to Amazon GameLift Servers managed EC2 hosting.
+ **Set up an Anywhere fleet for your hosting resources.** With an Anywhere fleet you can use the Amazon GameLift Servers service for hosting resources that aren't managed by Amazon GameLift Servers. In this step, you'll also configure the runtime configuration, which instructs Amazon GameLift Servers Agent when and how to start game server processes.
+ **Set up an Amazon EC2 instance.** This is your test environment for iterative testing. It is much faster to use a standard EC2 instance instead of a fully managed Amazon GameLift Servers instance (which is optimized for production-level usage). With a standard EC2 instance, you can quickly and continually update the game server as needed.
+ **Deploy your game server build and Amazon GameLift Servers Agent to the Amazon EC2 instance. **The workflow provides a script that gets the latest version of your game build and all dependencies and installs it on your EC2 instance. In this workflow, dependencies include the Amazon GameLift Servers Agent and the CloudWatch Agent.
+ **Start the Amazon GameLift Servers Agent.** Once installed, the Agent automatically starts and begins executing instructions. These include:
+ Register the EC2 instance as a compute in the Amazon GameLift Servers Anywhere fleet.
+ Establish a WebSocket connection with the Amazon GameLift Servers service and get the latest runtime configuration.
+ Start up game server processes based on the instructions in the runtime configuration. In this workflow, the Agent is instructed to start a single process of the game server executable.
+ **Test your game scenarios.** With the test environment set up and your latest game server build installed, you can commence testing. The workflow walks through several steps for testing including starting a game session. Access CloudWatch game server logs to track progress as the game session starts up and prepares to accept players.
As you develop your game components, including a game client and client-side backend service, you can include these in your test scenarios. Use a game client to request a game session, retrieve connection info from the Amazon GameLift Servers service, and then connect directly to the game session.
+ **Deploy a new game server build and repeat tests.** As you develop your game, you can generate new game server builds, then quickly deploy them to the EC2 test environment for testing. Upload them to the Amazon S3 bucket and then use the workflow scripts to update the test environment.
## Transition your game to Amazon GameLift Servers managed fleets
After you've completed development testing and you're ready to prepare for launch, this is a good time to switch over to Amazon GameLift Servers managed fleets. Use managed fleets to fine-tune and test your game hosting resources. Implement your game session placement solution (queues and matchmakers), select optimum hosting hardware (including Spot fleets) and locations, and choose a strategy for scaling capacity. You might also want to start using AWS CloudFormation to more efficiently manage the life cycles of all your game hosting resources, including fleets, queues, and matchmakers.
It requires minimal effort to transition from a cloud-based Anywhere test fleet to an Amazon GameLift Servers managed fleet. You don't need to change any game code, and you can reuse the same queues and matchmakers. Do the following tasks:
+ **Create an Amazon GameLift Servers build resource.** With an Anywhere test fleet, you have to manually deploy your game server build and dependencies to each fleet compute. With a managed fleet, upload your game build package to Amazon GameLift Servers, which automatically deploys it to all fleet computes. See [Create a game server build for Amazon GameLift Servers](gamelift-build-cli-uploading.md) for details on packaging your game build files and creating a build resource with files in an Amazon S3 bucket.
+ **Create a managed fleet.** Create a fleet using the console or AWS CLI, specifying an EC2 managed fleet. This type of fleet requires additional configuration settings, including specifying the build resource and instance types. You can use the same runtime configuration to manage game server life cycle on each fleet compute. See [Create an Amazon GameLift Servers managed EC2 fleet](fleets-creating.md) for details on creating a managed fleet.
+ **Redirect fleet aliases (optional).** If you set up aliases to use with your Anywhere fleets, you can reuse the same aliases for your managed fleets. See [Create an Amazon GameLift Servers alias](aliases-creating.md) for details on creating or updating an alias.
# Set up local testing with Amazon GameLift Servers Anywhere
**Note**
This topic covers local testing for games that are integrated with the server SDK for Amazon GameLift Servers version 5.x. If your game uses server SDK version 4.x or earlier, see [Test your integration using Amazon GameLift Servers Local](integration-testing-local.md).
Use an Amazon GameLift Servers Anywhere fleet and your own hardware to iteratively build and test your game components in a simulated hosted environment. Set up an Anywhere fleet and register a local device to establish a connection to the Amazon GameLift Servers service. Install your game server build onto the device, start a game server process, and test game functionality as needed. You can update your game server build as often as needed to test each new build iteration.
With an Anywhere fleet, you can test using the AWS CLI or with test scripts. If you've integrated a game client with Amazon GameLift Servers, you can run the client on the same local device or on a different device.
Testing locally with an Anywhere fleet is particularly useful for testing your game server integration with Amazon GameLift Servers. You have full visibility into all hosting activity on the local machine, as well as events and logging data.
**Note**
Are you using the Amazon GameLift Servers plugin for Unreal Engine or Unity? These tools include guided workflows for setting up local testing with an Anywhere fleet. Follow the documentation for [Plugin for Unity: Set up local testing with Amazon GameLift Servers Anywhere](unity-plug-in-anywhere.md) or [Plugin for Unreal: Host your game locally with Amazon GameLift Servers Anywhere](unreal-plugin-anywhere.md).
**Topics**
+ [Set up a local Anywhere fleet](#integration-testing-anywhere-fleet)
+ [Update and install your game server](#integration-testing-dev)
+ [Test game session activity](#integration-testing-test)
+ [Iterate on your game server](#fleet-anywhere-iteration)
+ [Transition your game to Amazon GameLift Servers managed fleets](#fleet-anywhere-transition)
## Set up a local Anywhere fleet
Follow these steps to create an Anywhere fleet for your local workstation. For detailed instructions using either the AWS CLI or the AWS Management Console for Amazon GameLift Servers, see [Create an Amazon GameLift Servers Anywhere fleet](fleets-creating-anywhere.md).
**To create the Anywhere fleet**
1. **Create a custom location for your local workstation. (AWS CLI or console).** A custom location is simply a label for the compute resource you plan to include in your Anywhere fleet. Custom location names must start with `custom-`. For example: `custom-my_laptop`. See [Create a custom location](fleets-creating-anywhere.md#fleet-anywhere-location).
1. **Create an Anywhere fleet (AWS CLI or console).** In this step, create the fleet resource with the custom location for your local workstation. See [Create an Anywhere fleet](fleets-creating-anywhere.md#fleet-anywhere-create).
Make a note of the new fleet's ID or ARN value. You'll need this value for the next step.
1. **Register your local workstation as a fleet compute (AWS CLI only).** An Anywhere fleet must have at least one compute resource to host your game servers. See [Add a compute to the fleet](fleets-creating-anywhere.md#fleet-anywhere-compute). To add a compute to the fleet, you need the following information:
+ A compute name. Each compute in a fleet must have a unique name.
+ The Anywhere fleet identifier. You can use either the `FleetID` or `FleetArn`.
+ The compute's connection info. Specify either an `IpAddress` or `DnsName`. This is how Amazon GameLift Servers and game clients will connect to game servers.
+ A custom location in the Anywhere fleet.
Make a note of the `GameLiftServiceSdkEndpoint` return value. You'll need this value when you update your game server to run on an Anywhere fleet.
## Update and install your game server
This task assumes that you've already integrated a game server build with Amazon GameLift Servers server SDK 5.x. The integration process involves adding code to your game server so that it can interact with the Amazon GameLift Servers service to start and manage game sessions.
For an Anywhere fleet, you need to manually configure certain game server settings. On an Amazon GameLift Servers managed fleet, these settings are configured automatically.
**To prepare your game server for an Anywhere fleet**
1. **Get an authentication token.** Your game server must include an authentication token with every communication with the Amazon GameLift Servers service. Amazon GameLift Servers auth tokens are short-lived and must be regularly refreshed.
As a best practice, create a script to complete the following tasks:
+ Call the AWS CLI action `get-compute-auth-token`.
+ Store the returned token value where game server processes can retrieve it, such as in an environment variable on the local compute.
Install the script with your game server on the compute. Set the script to run before starting the first game server process. While game server processes are active, run the script regularly to maintain a valid auth token. All game server processes on the compute can use the same auth token.
1. **Update your Amazon GameLift Servers game server code.** When you integrated your game server code with the server SDK for Amazon GameLift Servers, you added a call to the action `InitSdk()`. When the game server runs on an Anywhere fleet, this call requires additional server parameters. For more information, see [Initialize the server process](gamelift-sdk-server-api.md#gamelift-sdk-server-initialize) and the [Server SDK 5.x for Amazon GameLift Servers](reference-serversdk.md) for your development language. The server parameters are:
+ `webSocketUrl` – Set this parameter to the `GameLiftServiceSdkEndpoint` value that is returned when you register a compute with the fleet.
+ `hostId` – Set this parameter to the compute name that you specify when you register a compute with the Anywhere fleet.
+ `fleetId` – Set this parameter to the ID of the Anywhere fleet.
+ `authToken` – Set this parameter to the token that is returned in response to a request to retrieve an authenticaiton token for a compute.
+ `processId` – Set this parameter to identify a game server process that's running on the local compute. Each concurrent game server process must have a unique process ID.
The server parameter values that each game server process uses needs to be specific to the Anywhere fleet compute where the process is running. For details on how to get the appropriate values for a compute, see [Add a compute to the fleet](fleets-creating-anywhere.md#fleet-anywhere-compute). As a best practice, set `webSocketUrl`, `hostId`, `fleetId`, and `authToken` as environment variables on the local compute. All server processes that run on the compute will use these values.
1. Install the game server build on the local compute. Include all dependencies needed to run the game server.
1. Start one or more game server processes running on the local compute. When the game server process calls the server SDK action `ProcessReady()`, the process is ready to host a game session.
## Test game session activity
Test your game server integration by working with game sessions. If you don't have a game client integrated with Amazon GameLift Servers functionality, you can use the AWS CLI to start game sessions. Try the following scenarios:
+ **Create a game session.** Call [create-game-session ](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/gamelift/create-game-session.html) command (or the [ CreateGameSession](https://docs.aws.amazon.com/gameliftservers/latest/apireference/API_CreateGameSession.html) API operation). Specify your Anywhere fleet's ID and custom location. This call returns a unique identifier for the new game session.
+ **Check game session status. **Call [describe-game-sessions](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/gamelift/describe-game-sessions.html) command (or the [DescribeGameSessions](https://docs.aws.amazon.com/gameliftservers/latest/apireference/API_DescribeGameSessions.html) API action). Specify the game session ID. This call returns detailed game session information, including the game session status. Game sessions in Active status are ready for players to connect. To get a list of all game sessions for the fleet, call [list-game-sessions](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/gamelift/list-game-sessions.html) command (or the [ListGameSessions](https://docs.aws.amazon.com/gameliftservers/latest/apireference/API_ListGameSessions.html) API action).
+ **Connect to the game session.** If your game client has the ability to join a game session, use the connection information included in the game session information.
## Iterate on your game server
You can use the same Anywhere fleet and compute to test other versions of your game server build.
1. **Clean up your existing `GameSession`.** If the game server process crashes or won't call `ProcessEnding()`, Amazon GameLift Servers cleans up the `GameSession` after the game server stops sending health checks.
1. **Generate a new game server build.** Make changes to your game server and package an revised build.
1. **Update the game server build on your local compute.** Your previous Anywhere fleet is still active and your laptop is still registered as a compute resource in the fleet.
1. **Get an updated authorization token.** Call the [get-compute-auth-token](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/gamelift/get-compute-auth-token.html) CLI command and store the token on the local compute.
1. **Start one or more game server processes running on the local compute.** When the game server process calls `ProcessReady()`, it's ready to be used for testing.
## Transition your game to Amazon GameLift Servers managed fleets
After you've completed development testing and you're ready to prepare for launch, this is a good time to switch over to Amazon GameLift Servers managed fleets. Use managed fleets to fine-tune and test your game hosting resources. Implement your game session placement solution (queues and matchmakers), select optimum hosting hardware (including Spot fleets) and locations, and choose a strategy for scaling capacity. You might also want to start using AWS CloudFormation to more efficiently manage the life cycles of all your game hosting resources, including fleets, queues, and matchmakers.
You need to make a few minor modifications to transition from a local Anywhere test fleet to an Amazon GameLift Servers managed fleet. You can reuse the same queues and matchmakers. Do the following tasks:
+ **Change the game server code call to `InitSdk()`.** Remove the server parameters. For a managed fleet, Amazon GameLift Servers automatically tracks this information.
+ **Create an Amazon GameLift Servers build resource.** With an Anywhere test fleet, you have to manually deploy your game server build and dependencies to each fleet compute. With a managed fleet, you create and upload your game build package to Amazon GameLift Servers, which automatically deploys it to all fleet computes. See [Create a game server build for Amazon GameLift Servers](gamelift-build-cli-uploading.md) for details on packaging your game build files and creating a build resource with files in an Amazon S3 bucket. Don't include scripts that register a compute and get an authentication token, as Amazon GameLift Servers automatically handles these tasks with managed fleets.
+ **Create a managed fleet.** Create a fleet using the console or AWS CLI, specifying an EC2 managed fleet. This type of fleet requires additional configuration settings, including specifying the build resource and instance types. You alls need to set up a runtime configuration to manage game server life cycle on each fleet compute. See [Create an Amazon GameLift Servers managed EC2 fleet](fleets-creating.md) for details on creating a managed fleet.
+ **Redirect fleet aliases (optional).** If you set up aliases to use with your Anywhere fleets, you can reuse the same aliases for your managed fleets. See [Create an Amazon GameLift Servers alias](aliases-creating.md) for details on creating or updating an alias.
# Test your integration using Amazon GameLift Servers Local
**Note**
This topic covers testing for games that are integrated with the server SDK for Amazon GameLift Servers version 3.x and 4.x only. Your server SDK package includes a compatible version of Amazon GameLift Servers Local. If you're using server SDK version 5.x, see [Local testing with GameLift Server SDK 5.x](https://docs.aws.amazon.com/gameliftservers/latest/developerguide/integration-testing-local.html) for local testing with an Amazon GameLift Servers Anywhere fleet. For guidance on migrating from SDK 4.x to 5.x, see [Migrate to GameLift Server SDK 5.x](https://docs.aws.amazon.com/gamelift/latest/developerguide/reference-serversdk5-migration.html).
Use Amazon GameLift Servers Local to run a limited version of the managed Amazon GameLift Servers service on a local device and test your game integration against it. This tool is useful when doing iterative development on your game integration. The alternative—uploading each new build to Amazon GameLift Servers and configuring a fleet to host your game—can take several or more each time.
With Amazon GameLift Servers Local, you can verify the following:
+ Your game server is correctly integrated with the Server SDK and is properly communicating with the Amazon GameLift Servers service to start new game sessions, accept new players, and report health and status.
+ Your game client is correctly integrated with the AWS SDK for Amazon GameLift Servers and is able to retrieve information on existing game sessions, start new game sessions, join players to games and connect to the game session.
Amazon GameLift Servers Local is a command-line tool that starts a self-contained version of the managed Amazon GameLift Servers service. Amazon GameLift Servers Local also provides a running event log of server process initialization, health checks, and API calls and responses. Amazon GameLift Servers Local recognizes a subset of the AWS SDK actions for Amazon GameLift Servers. You can make calls from the AWS CLI or from your game client. All API actions perform locally just as they do in the Amazon GameLift Servers web service.
Each server process should only host a single game session. The game session is the executable you use to connect to Amazon GameLift Servers Local. When the game session is completed, you should call `GameLiftServerSDK::ProcessEnding` and then exit the process. When testing locally with Amazon GameLift Servers Local, you can start multiple server processes. Each process will connect to Amazon GameLift Servers Local. You can then create one game session for each server process. When your game session ends, your game server process should exit. You must then manually start another server process.
Amazon GameLift Servers local supports the following APIs:
+ CreateGameSession
+ CreatePlayerSession
+ CreatePlayerSessions
+ DescribeGameSessions
+ DescribePlayerSessions
## Set up Amazon GameLift Servers local
Amazon GameLift Servers Local is provided as an executable `.jar` file bundled with the [Server SDK](https://aws.amazon.com/gamelift/servers/getting-started/). It can be run on Windows or Linux and used with any Amazon GameLift Servers-supported language. For SDK version 4.0.2, you can download it from the [official GitHub releases](https://github.com/amazon-gamelift/amazon-gamelift-servers-csharp-server-sdk/releases). The GameLiftLocal.jar file is included in the GameLift-CSharp-ServerSDK-4.0.2.zip artifact.
Before running Local, you must also have the following installed.
+ A build of the server SDK for Amazon GameLift Servers version 3.1.5 to 4.x.
+ Java 8
## Test a game server
If you want to test your game server only, you can use the AWS CLI to simulate game client calls to the Amazon GameLift Servers Local service. This verifies that your game server is performing as expected with the following:
+ The game server launches properly and initializes the server SDK for Amazon GameLift Servers.
+ As part of the launch process, the game server notifies Amazon GameLift Servers that the server is ready to host game sessions.
+ The game server sends health status to Amazon GameLift Servers every minute while running.
+ The game server responds to requests to start a new game session.
1. **Start Amazon GameLift Servers Local.**
Open a command prompt window, navigate to the directory containing the file `GameLiftLocal.jar` and run it. By default, Local listens for requests from game clients on port 8080. To specify a different port number, use the `-p` parameter, as shown in the following example:
```
java -jar GameLiftLocal.jar -p 9080
```
Once Local starts, you see logs indicating that two local servers were started, one listening for your game server and one listening for your game client or the AWS CLI. Logs continue to report activity on the two local servers, including communication to and from your game components.
1. **Start your game server.**
Start your Amazon GameLift Servers-integrated game server locally. You don't need to change the endpoint for the game server.
In the Local command prompt window, log messages indicate that your game server has connected to the Amazon GameLift Servers Local service. This means that your game server successfully initialized the server SDK for Amazon GameLift Servers (with `InitSDK()`). It has called `ProcessReady()` with the log paths shown and, if successful, is ready to host a game session. While the game server is running, Amazon GameLift Servers logs each health status report from the game server. The following log messaging example shows a successfully integrated game server:
```
16:50:53,217 INFO || - [SDKListenerImpl] nioEventLoopGroup-3-1 - SDK connected: /127.0.0.1:64247
16:50:53,217 INFO || - [SDKListenerImpl] nioEventLoopGroup-3-1 - SDK pid is 17040, sdkVersion is 3.1.5 and sdkLanguage is CSharp
16:50:53,217 INFO || - [SDKListenerImpl] nioEventLoopGroup-3-1 - NOTE: Only SDK versions 3.1.5 and above are supported in GameLiftLocal!
16:50:53,451 INFO || - [SDKListenerImpl] nioEventLoopGroup-3-1 - onProcessReady received from: /127.0.0.1:64247 and ackRequest requested? true
16:50:53,543 INFO || - [SDKListenerImpl] nioEventLoopGroup-3-1 - onProcessReady data: logPathsToUpload: "C:\\game\\logs"
logPathsToUpload: "C:\\game\\error"
port: 1935
16:50:53,544 INFO || - [HostProcessManager] nioEventLoopGroup-3-1 - Registered new process true, true,
16:50:53,558 INFO || - [SDKListenerImpl] nioEventLoopGroup-3-1 - onReportHealth received from /127.0.0.1:64247 with health status: healthy
```
Potential error and warning messages include the following:
+ Error: "ProcessReady did not find a process with pID: **\$1 Was InitSDK() invoked?"
+ Warning: "Process state already exists for process with pID: **\$1 Is ProcessReady(...) invoked more than once?"
1. **Start the AWS CLI.**
Once your game server successfully calls `ProcessReady()`, you can start making client calls. Open another command prompt window and start the AWS CLI tool. The AWS CLI by default uses the Amazon GameLift Servers web service endpoint. You must override this with the Local endpoint in every request using the `--endpoint-url` parameter, as shown in the following example request.
```
AWS gamelift describe-game-sessions --endpoint-url http://localhost:9080 --fleet-id fleet-123
```
In the AWS CLI command prompt window, `AWS gamelift` commands result in responses as documented in the [AWS CLI Command Reference](https://docs.aws.amazon.com/cli/latest/reference/gamelift).
1. **Create a game session.**
With the AWS CLI, submit a [CreateGameSession()](https://docs.aws.amazon.com/gamelift/latest/apireference/API_CreateGameSession.html) request. The request should follow the expected syntax. For Local, the `FleetId` parameter can be set to any valid string (`^fleet-\S+`).
```
AWS gamelift create-game-session --endpoint-url http://localhost:9080 --maximum-player-session-count 2 --fleet-id
fleet-1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d
```
In the Local command prompt window, log messages indicate that Amazon GameLift Servers Local has sent your game server an `onStartGameSession` callback. If a game session is successfully created, your game server responds by invoking `ActivateGameSession`.
```
13:57:36,129 INFO || - [SDKInvokerImpl]
Thread-2 - Finished sending event to game server to start a game session:
arn:aws:gamelift:local::gamesession/fleet-1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d/gsess-ab423a4b-b827-4765-aea2-54b3fa0818b6.
Waiting for ack response.13:57:36,143 INFO || - [SDKInvokerImpl]
Thread-2 - Received ack response: true13:57:36,144 INFO || -
[CreateGameSessionDispatcher] Thread-2 - GameSession with id:
arn:aws:gamelift:local::gamesession/fleet-1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d/gsess-ab423a4b-b827-4765-aea2-54b3fa0818b6
created13:57:36,227 INFO || - [SDKListenerImpl]
nioEventLoopGroup-3-1 - onGameSessionActivate received from: /127.0.0.1:60020 and ackRequest
requested? true13:57:36,230 INFO || - [SDKListenerImpl]
nioEventLoopGroup-3-1 - onGameSessionActivate data: gameSessionId:
"arn:aws:gamelift:local::gamesession/fleet-1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d/gsess-abcdef12-3456-7890-abcd-ef1234567890"
```
In the AWS CLI window, Amazon GameLift Servers responds with a game session object including a game session ID. Notice that the new game session's status is Activating. The status changes to Active once your game server invokes ActivateGameSession. If you want to see the changed status , use the AWS CLI to call `DescribeGameSessions()`.
```
{
"GameSession": {
"Status": "ACTIVATING",
"MaximumPlayerSessionCount": 2,
"FleetId": "fleet-1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
"GameSessionId": "arn:aws:gamelift:local::gamesession/fleet-1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d/gsess-abcdef12-3456-7890-abcd-ef1234567890",
"IpAddress": "127.0.0.1",
"Port": 1935
}
}
```
## Test a game server and client
To check your full game integration, including connecting players to games, you can run both your game server and client locally. This allows you to test programmatic calls from your game client to the Amazon GameLift Servers Local. You can verify the following actions:
+ The game client is successfully making AWS SDK requests to the Amazon GameLift Servers Local service, including to create game sessions, retrieve information on existing game sessions, and create player sessions.
+ The game server is correctly validating players when they try to join a game session. For validated players, the game server may retrieve player data (if implemented).
+ The game server reports a dropped connection when a player leaves the game.
+ The game server reports ending a game session.
1. **Start Amazon GameLift Servers Local.**
Open a command prompt window, navigate to the directory containing the file `GameLiftLocal.jar` and run it. By default, Local listens for requests from game clients on port 8080. To specify a different port number, use the `-p` parameter, as shown in the following example.
```
./gamelift-local -p 9080
```
Once Local starts, you see logs showing that two local servers were started, one listening for your game server and one listening for your game client or the AWS CLI.
1. **Start your game server.**
Start your Amazon GameLift Servers-integrated game server locally. See [Test a game server](#integration-testing-local-server) for more detail on message logs.
1. **Configure your game client for Local and start it.**
To use your game client with the Amazon GameLift Servers Local service, you must make the following changes to your game client's setup, as described in [Set up the Amazon GameLift Servers API](gamelift-sdk-client-api.md#gamelift-sdk-client-api-initialize):
+ Change the `ClientConfiguration` object to point to your Local endpoint, such as `http://localhost:9080`.
+ Set a target fleet ID value. For Local, you do not need a real fleet ID; set the target fleet to any valid string (`^fleet-\S+`), such as `fleet-1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d`.
+ Set AWS credentials. For Local, you do not need real AWS credentials; you can set the access key and secret key to any string.
In the Local command prompt window, once you start the game client, log messages should indicate that it has initialized the `GameLiftClient` and is successfully communicated with the Amazon GameLift Servers service.
1. **Test game client calls to the Amazon GameLift Servers service.**
Verify that your game client is successfully making any or all of the following API calls:
+ [CreateGameSession()](https://docs.aws.amazon.com/gamelift/latest/apireference/API_CreateGameSession.html)
+ [DescribeGameSessions()](https://docs.aws.amazon.com/gamelift/latest/apireference/API_DescribeGameSessions.html)
+ [CreatePlayerSession()](https://docs.aws.amazon.com/gamelift/latest/apireference/API_CreatePlayerSession.html)
+ [CreatePlayerSessions()](https://docs.aws.amazon.com/gamelift/latest/apireference/API_CreatePlayerSessions.html)
+ [DescribePlayerSessions()](https://docs.aws.amazon.com/gamelift/latest/apireference/API_DescribePlayerSessions.html)
In the Local command prompt window, only calls to `CreateGameSession()` result in log messages. Log messages show when Amazon GameLift Servers Local prompts your game server to start a game session (`onStartGameSession` callback) and gets a successful `ActivateGameSession` when your game server invokes it. In the AWS CLI window, all API calls result in responses or error messages as documented.
1. **Verify that your game server is validating new player connections.**
After creating a game session and a player session, establish a direct connection to the game session.
In the Local command prompt window, log messages should show that the game server has sent an `AcceptPlayerSession()` request to validate the new player connection. If you use the AWS CLI to call `DescribePlayerSessions()`, the player session status should change from Reserved to Active.
1. **Verify that your game server is reporting game and player status to the Amazon GameLift Servers service.**
For Amazon GameLift Servers to manage player demand and correctly report metrics, your game server must report various statuses back to Amazon GameLift Servers. Verify that Local is logging events related to following actions. You may also want to use the AWS CLI to track status changes.
+ **Player disconnects from a game session** – Amazon GameLift Servers Local log messages should show that your game server calls `RemovePlayerSession()`. An AWS CLI call to `DescribePlayerSessions()` should reflect a status change from `Active` to `Completed`. You might also call `DescribeGameSessions()` to check that the game session's current player count decreases by one.
+ **Game session ends** – Amazon GameLift Servers Local log messages should show that your game server calls `TerminateGameSession()`.
**Note**
Previous guidance was to call `TerminateGameSession()` when ending a game session. This method is deprecated with Amazon GameLift Servers Server SDK v4.0.1. See [End a game session](gamelift-sdk-server-api.md#gamelift-sdk-server-shutdownsession).
+ **Server process is terminated** – Amazon GameLift Servers Local log messages should show that your game server calls `ProcessEnding()`. An AWS CLI call to `DescribeGameSessions()` should reflect a status change from `Active` to `Terminated` (or `Terminating`).
## Variations with local
When using Amazon GameLift Servers Local, keep in mind the following:
+ Unlike the Amazon GameLift Servers web service, Local does not track a server's health status and initiate the `onProcessTerminate` callback. Local simply stops logging health reports for the game server.
+ For calls to the AWS SDK, fleet IDs are not validated, and can be any string value that meets the parameter requirements (`^fleet-\S+`).
+ Game session IDs created with Local have a different structure. They include the string `local`, as shown here:
```
arn:aws:gamelift:local::gamesession/fleet-123/gsess-56961f8e-db9c-4173-97e7-270b82f0daa6
```
# Debug Amazon GameLift Servers fleet issues
This topic provides guidance on how to resolve issues with your Amazon GameLift Servers managed EC2 fleets.
## Fleet creation issues
When you create a managed EC2 fleet, the Amazon GameLift Servers service initiates a workflow that creates the fleet, deploys EC2 instances with your game server build installed, and starts game server processes on each instance. For a detailed description, see . A fleet cannot host game sessions and players until it reaches **Active** status.
You can debug issues that prevent fleets from becoming active by identifying the fleet creation phase where the issue occurred and reviewing fleet creation events and logs. If the logs do not offer useful information, it's possible that the problem is due to an internal service error. In this situation, try to create the fleet again. If the problem persists, try re-uploading the game build to resolve possible file corruption). You can also contact Amazon GameLift Servers support or post a question on the forum.
**Downloading and validating the build**
During this phase, Amazon GameLift Servers gets your uploaded game server build, extracts the files, and runs any install scripts. If fleet creation fails during these phases, look at fleet events and logs to pinpoint the issue. Possible causes include:
+ Amazon GameLift Servers can't get the compressed build file (event `FLEET_BINARY_DOWNLOAD_FAILED`). Verify that the build's storage location can be accessed, that you're creating a fleet in the same AWS Region as the build, and that Amazon GameLift Servers has the correct permissions to access it.
+ Amazon GameLift Servers can't extract the build files (event `FLEET_CREATION_EXTRACTING_BUILD`).
+ An install script in the build files failed to complete successfully (event `FLEET_CREATION_FAILED_INSTALLER`).
**Building fleet resources**
Issues during this phase usually involve the allocation and deployment of fleet resources. Possible causes include:
+ The requested instance type isn't available.
+ The requested fleet type (Spot or On-Demand) isn't available.
**Activating game server processes**
During this phase, Amazon GameLift Servers is attempting a number of tasks and testing key elements, including the game server's viability, runtime configuration settings, and the game server's ability to connect with the Amazon GameLift Servers service using the Server SDK.
In this phase, you can remotely access a fleet instance to further investigate issues. See [Connect to fleet instances](fleets-remote-access.md).
Possible issues include:
+ Server processes don't start running. This suggests an issue with the fleet's runtime configuration settings (events `FLEET_VALIDATION_LAUNCH_PATH_NOT_FOUND` or `FLEET_VALIDATION_EXECUTABLE_RUNTIME_FAILURE`. Verify that you've correctly set the launch path and optional launch parameters.
+ Server processes start running, but the fleet fails to activate. If server processes start and run successfully, but the fleet does not move to **Active** status, a likely cause is that the server process is failing to communicate with the Amazon GameLift Servers service. Verify that your game server is making these correct server SDK calls (see [Initialize the server process](gamelift-sdk-server-api.md#gamelift-sdk-server-initialize)):
+ Server process fails to initialize (event `SERVER_PROCESS_SDK_INITIALIZATION_TIMEOUT`). The server process is not successfully calling `InitSdk()`.
+ Server process fails to notify Amazon GameLift Servers when it's ready to host a game session (event `SERVER_PROCESS_PROCESS_READY_TIMEOUT`). The server process initialized but didn't call `ProcessReady()` in time.
+ A VPC peering connection request failed. For fleets that are created with a VPC peering connection (see [To set up VPC peering with a new fleet](vpc-peering.md#fleets-creating-aws-cli-vpc)), VPC peering is done during this **Activating** phases. If a VPC peering fails for any reason, the new fleet will fail to move to **Active** status. You can track the success or failure of the peering request by calling [describe-vpc-peering-connections](https://docs.aws.amazon.com/cli/latest/reference/gamelift/describe-vpc-peering-connections.html). Be sure to check that a valid VPC peering authorization exists ([describe-vpc-peering-authorizations](https://docs.aws.amazon.com/cli/latest/reference/gamelift/describe-vpc-peering-authorizations.html), since authorizations are only valid for 24 hours.
## Server process issues
**Server processes start but fail quickly or report poor health.**
Other than issues with your game build, this outcome can happen when trying to run too many server processes simultaneously on the instance. The optimum number of concurrent processes depends on both the instance type and your game server's resource requirements. Try reducing the number of concurrent processes, which is set in the fleet's runtime configuration, to see if performance improves. You can change a fleet's runtime configuration using either the Amazon GameLift Servers console (edit the fleet's capacity allocation settings) or by calling the AWS CLI command [update-runtime-configuration](https://docs.aws.amazon.com/cli/latest/reference/gamelift/update-runtime-configuration.html).
## Fleet deletion issues
**Fleet can't be terminated due to max instance count.**
The error message indicates that the fleet being deleted still has active instances, which is not allowed. You must first scale a fleet down to zero active instances. This is done by manually setting the fleet's desired instance count to "0" and then waiting for the scale-down to take effect. Be sure to turn off auto scaling, which will counteract manual settings.
**VPC actions are not authorized.**
This issue only applies to fleets that you have specifically created VPC peering connections for (see [Set up VPC peering for Amazon GameLift Servers](vpc-peering.md). This scenario occurs because the process of deleting a fleet also includes deleting the fleet's VPC and any VPC peering connections. You must first get an authorization by calling the service API for Amazon GameLift Servers [ CreateVpcPeeringAuthorization()](https://docs.aws.amazon.com/gamelift/latest/apireference/API_CreateVpcPeeringAuthorization.html) or use the AWS CLI command `create-vpc-peering-authorization`. Once you have the authorization, you can delete the fleet.
# Remotely access fleet resources
You can connect to any instance in your active Amazon GameLift Servers managed EC2 or managed container fleets. For container fleets, you can also connect to individual containers running on an instance to troubleshoot game sessions, inspect logs, and debug runtime issues. Common reasons to remotely access an instance include:
+ Troubleshoot issues with your game server integration.
+ Fine-tune your runtime configuration and other fleet-specific settings.
+ Monitor real-time game server activity, such as log tracking.
+ Run benchmarking tools using actual player traffic.
+ Investigate specific issues with a game session or server process.
When connecting to an instance, keep the following in mind:
+ You can connect to any instance in an active fleet. Generally, you can't connect to non-active fleets, such as fleets that are in the process of activating or are in an error state. (These fleets might have limited availability for a short period of time.) For help with fleet activation issues, see [Debug Amazon GameLift Servers fleet issues](fleets-creating-debug.md).
+ Connecting to an active instance doesn't affect the instance's hosting activity. The instance continues to start and stop server processes based on the runtime configuration. It activates and runs game sessions. The instance might shut down in response to a scale down event or other event.
+ Any changes you make to files or settings on the instance might impact the instance's active game sessions and connected players.
# Connect to fleet instances
You can remotely connect to any active Amazon GameLift Servers managed EC2 or managed container fleet instance to troubleshoot game server issues, inspect logs, and debug runtime behavior. Connect using the Amazon GameLift Servers console or the AWS CLI.
## Remote access through the console
You can connect to fleet instances directly from the Amazon GameLift Servers console using Amazon EC2 Systems Manager (SSM). This method provides secure access without requiring additional setup or credential management. For container fleets, after connecting to the instance, you can access individual containers running on it. For more information, see [Connect to containers](containers-remote-access.md).
1. In the Amazon GameLift Servers console, choose **Managed EC2** or **Managed containers** from the navigation pane, and then **Fleets**.
1. Choose the fleet ID that contains the instance you want to access.
1. On the fleet details page, choose the **Instances** tab to view all compute instances for the fleet.
1. Select the instance you want to connect to, then choose **Connect**. This displays the Connect to instance dialog which informs you of the details of the connection, and allows you to view the script that will be used to connect to your instance. Confirm by choosing **Connect** again.
1. In the connection dialog, choose **Run** to create a new SSM session. The system authenticates your session through AWS Key Management Service (AWS KMS) and opens a terminal in your browser.
**Note**
Console-based remote access is available for fleets running server SDK version 5.x. For fleets running earlier SDK versions, use the AWS CLI method described in the following section.
## Remote access with the AWS CLI
The following instructions describe how to remotely connect to an instance using the AWS command line interface (CLI). You can also make programmatic calls using the AWS SDK, as documented in the [service API reference for Amazon GameLift Servers](https://docs.aws.amazon.com/gamelift/latest/apireference/).
### Gather instance data
To connect to an Amazon GameLift Servers managed EC2 fleet instance, you need the following information:
+ The ID of the instance you want to connect to. You can use either the instance ID or ARN.
+ the server SDK for Amazon GameLift Servers version being used on the instance. The server SDK is integrated with the game build that is running on the instance.
The following instructions describe how complete these tasks using the AWS CLI. You must know the fleet ID for the instance you want to connect to.
1. **Get the compute name.** Get a list of all active computes in the fleet. Call [list-compute](https://docs.aws.amazon.com/cli/latest/reference/gamelift/list-compute.html) with a fleet ID or ARN. For a single-location fleet, specify the fleet identifier only. For a multi-location fleet, specify the fleet identifier and a location. With managed EC2 fleets, `list-compute` returns a list of fleet instances, and the property `ComputeName` is the instance ID. Find the compute you want to access.
**Request**
```
aws gamelift list-compute \
--fleet-id fleet-2222bbbb-33cc-44dd-55ee-6666ffff77aa \
--location sa-east-1
```
**Response**
```
{
"ComputeList": [
{
"FleetId": "fleet-2222bbbb-33cc-44dd-55ee-6666ffff77aa",
"FleetArn": "arn:aws:gamelift:us-west-2::fleet/fleet-2222bbbb-33cc-44dd-55ee-6666ffff77aa",
"ComputeName": "i-0abc12d3e45fa6b78",
"IpAddress": "00.00.000.00",
"DnsName": "b08444ki909kvqu6zpw3is24x5pyz4b6m05i3jbxvpk9craztu0lqrbbrbnbkks.uwp57060n1k6dnlnw49b78hg1rw4rcz7.us-west-2.amazongamelift.com",
"ComputeStatus": "Active",
"Location": "sa-east-1",
"CreationTime": "2023-07-09T22:51:45.931000-07:00",
"OperatingSystem": "AMAZON_LINUX_2023",
"Type": "c4.large"
}
]
}
```
1. **Find the server SDK version.** For this information you need to look up the build that is deployed to the fleet. Server SDK version is a build property.
1. Call [describe-fleet-attributes](https://docs.aws.amazon.com/cli/latest/reference/gamelift/describe-fleet-attributes.html) with a fleet ID or ARN to get the fleet's build ID and ARN.
1. Call [describe-build](https://docs.aws.amazon.com/cli/latest/reference/gamelift/describe-build.html) with the build ID or ARN to get the build's server SDK version.
For example:
**Request**
```
aws gamelift describe-fleet-attributes \
--fleet-ids fleet-2222bbbb-33cc-44dd-55ee-6666ffff77aa
```
**Response**
```
{
"FleetAttributes": [
{
"FleetId": "fleet-2222bbbb-33cc-44dd-55ee-6666ffff77aa",
"ComputeType": "EC2",
"BuildId": "build-3333cccc-44dd-55ee-66ff-00001111aa22",
. . .
}
]
}
```
**Request**
```
aws gamelift describe-build \
--build-id build-3333cccc-44dd-55ee-66ff-00001111aa22
```
**Response**
```
"Build": {
"BuildId": "build-1111aaaa-22bb-33cc-44dd-5555eeee66ff",
"Name": "My_Game_Server_Build_One",
"OperatingSystem": "AMAZON_LINUX_2023",
"ServerSdkVersion": "5.1.1",
. . .
}
```
## Connect to an instance (server SDK 5)
If the instance you want to connect to is running a game build with server SDK version 5.x, connect to the instance using Amazon EC2 Systems Manager (SSM). You can access remote instances that are running either Windows or Linux. For container fleets, after connecting to the instance, you can access individual containers running on it. For more information, see [Connect to containers](containers-remote-access.md).
**Before you start:**
Complete the SSM setup steps and install the SSM plugin on your local machine. For more information, see [ Setting up SSM](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-getting-started.html) and [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 *Amazon EC2 Systems Manager User Guide*.
1. **Request access credentials for the instance.** Call [get-compute-access](https://docs.aws.amazon.com/cli/latest/reference/gamelift/get-compute-access.html) with the fleet ID and the compute name for the instance you want to connect to. Amazon GameLift Servers returns a set of temporary credentials for accessing the instance. For example:
**Request**
```
aws gamelift get-compute-access \
--compute-name i-11111111a222b333c \
--fleet-id fleet-2222bbbb-33cc-44dd-55ee-6666ffff77aa
--region us-west-2
```
**Response**
```
{
"ComputeName": "i-11111111a222b333c",
"Credentials": {
"AccessKeyId": "ASIAIOSFODNN7EXAMPLE",
"SecretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
"SessionToken": "AQoDYXdzEJr..."
},
"FleetArn": "arn:aws:gamelift:us-west-2::fleet/fleet-2222bbbb-33cc-44dd-55ee-6666ffff77aa",
"FleetId": "fleet-2222bbbb-33cc-44dd-55ee-6666ffff77aa"
}
```
1. **Export the access credentials (optional).** You can export the credentials to environment variables and use them to configure the AWS CLI for the default user. For more details, see [ Environment variables to configure the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html) in the AWS Command Line Interface User Guide.
```
export AWS_ACCESS_KEY_ID=ASIAIOSFODNN7EXAMPLE
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
export AWS_SESSION_TOKEN=AQoDYXdzEJr...
```
1. **Connect to the fleet instance.** Start an SSM session with the instance you want to connect to. Include the AWS Region or location of the instance. For more information, including how to set up SSM and the SSM plugin, see [ Starting a session (AWS CLI)](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-sessions-start.html#sessions-start-cli) in the *Amazon EC2 Systems Manager User Guide*.
The start-session request will automatically use the credentials that you acquired in Step 1.
```
aws ssm start-session \
--target i-11111111a222b333c \
--region us-west-2 \
```
**Note**
If you get an access denied error, you might have an `AWS_PROFILE` environment variable set to an AWS profile, which causes AWS CLI to use the wrong credentials for remote access. To resolve, temporarily unset your `AWS_PROFILE` environment variable. Alternatively, you can create a custom AWS profile for your remote access credentials and add the `--profile` command line parameter to your `start-session` request.
## Connect to an instance (server SDK 4.x or earlier)
If the instance you want to connect to is running a game build with server SDK version 4 or earlier, use the following instructions. You can connect to instances that are running either Windows or Linux. Connect to a Windows instance using a remote desktop protocol (RDP) client. Connect to a Linux instance using an SSH client.
1. **Request access credentials for the instance.** When you have an instance ID, use the command [get-instance-access](https://docs.aws.amazon.com/cli/latest/reference/gamelift/get-instance-access.html) to request access credentials. If successful, Amazon GameLift Servers returns the instance's operating system, IP address, and a set of credentials (user name and secret key). The credentials format depends on the instance operating system. Use the following instructions to retrieve credentials for either RDP or SSH.
+ **For Windows instances** – To connect to a Windows instance, RDP requires a user name and password. The `get-instance-access` request returns these values as simple strings, so you can use the returned values as is. Example credentials:
```
"Credentials": {
"Secret": "aA1bBB2cCCd3EEE",
"UserName": "gl-user-remote"
}
```
+ **For Linux instances** – To connect to a Linux instance, SSH requires a user name and private key. Amazon GameLift Servers issues RSA private keys and returns them as a single string, with the newline character (`\n`) indicating line breaks. To make the private key usable, take these steps: (1) convert the string to a `.pem` file, and (2) set permissions for the new file. Example credentials returned:
```
"Credentials": {
"Secret": "-----BEGIN RSA PRIVATE KEY-----nEXAMPLEKEYKCAQEAy7WZhaDsrA1W3mRlQtvhwyORRX8gnxgDAfRt/gx42kWXsT4rXE/b5CpSgie/\nvBoU7jLxx92pNHoFnByP+Dc21eyyz6CvjTmWA0JwfWiW5/akH7iO5dSrvC7dQkW2duV5QuUdE0QW\nZ/aNxMniGQE6XAgfwlnXVBwrerrQo+ZWQeqiUwwMkuEbLeJFLhMCvYURpUMSC1oehm449ilx9X1F\nG50TCFeOzfl8dqqCP6GzbPaIjiU19xX/azOR9V+tpUOzEL+wmXnZt3/nHPQ5xvD2OJH67km6SuPW\noPzev/D8V+x4+bHthfSjR9Y7DvQFjfBVwHXigBdtZcU2/wei8D/HYwIDAQABAoIBAGZ1kaEvnrqu\n/uler7vgIn5m7lN5LKw4hJLAIW6tUT/fzvtcHK0SkbQCQXuriHmQ2MQyJX/0kn2NfjLV/ufGxbL1\nmb5qwMGUnEpJaZD6QSSs3kICLwWUYUiGfc0uiSbmJoap/GTLU0W5Mfcv36PaBUNy5p53V6G7hXb2\nbahyWyJNfjLe4M86yd2YK3V2CmK+X/BOsShnJ36+hjrXPPWmV3N9zEmCdJjA+K15DYmhm/tJWSD9\n81oGk9TopEp7CkIfatEATyyZiVqoRq6k64iuM9JkA3OzdXzMQexXVJ1TLZVEH0E7bhlY9d8O1ozR\noQs/FiZNAx2iijCWyv0lpjE73+kCgYEA9mZtyhkHkFDpwrSM1APaL8oNAbbjwEy7Z5Mqfql+lIp1\nYkriL0DbLXlvRAH+yHPRit2hHOjtUNZh4Axv+cpg09qbUI3+43eEy24B7G/Uh+GTfbjsXsOxQx/x\np9otyVwc7hsQ5TA5PZb+mvkJ5OBEKzet9XcKwONBYELGhnEPe7cCgYEA06Vgov6YHleHui9kHuws\nayav0elc5zkxjF9nfHFJRry21R1trw2Vdpn+9g481URrpzWVOEihvm+xTtmaZlSp//lkq75XDwnU\nWA8gkn6O3QE3fq2yN98BURsAKdJfJ5RL1HvGQvTe10HLYYXpJnEkHv+Unl2ajLivWUt5pbBrKbUC\ngYBjbO+OZk0sCcpZ29sbzjYjpIddErySIyRX5gV2uNQwAjLdp9PfN295yQ+BxMBXiIycWVQiw0bH\noMo7yykABY7Ozd5wQewBQ4AdSlWSX4nGDtsiFxWiI5sKuAAeOCbTosy1s8w8fxoJ5Tz1sdoxNeGs\nArq6Wv/G16zQuAE9zK9vvwKBgF+09VI/1wJBirsDGz9whVWfFPrTkJNvJZzYt69qezxlsjgFKshy\nWBhd4xHZtmCqpBPlAymEjr/TOlbxyARmXMnIOWIAnNXMGB4KGSyl1mzSVAoQ+fqR+cJ3d0dyPl1j\njjb0Ed/NY8frlNDxAVHE8BSkdsx2f6ELEyBKJSRr9snRAoGAMrTwYneXzvTskF/S5Fyu0iOegLDa\nNWUH38v/nDCgEpIXD5Hn3qAEcju1IjmbwlvtW+nY2jVhv7UGd8MjwUTNGItdb6nsYqM2asrnF3qS\nVRkAKKKYeGjkpUfVTrW0YFjXkfcrR/V+QFL5OndHAKJXjW7a4ejJLncTzmZSpYzwApc=\n-----END RSA PRIVATE KEY-----",
"UserName": "gl-user-remote"
}
```
When using the AWS CLI, you can automatically generate a `.pem` file by including the *--query* and *--output* parameters to your `get-instance-access` request.
To set permissions on the `.pem` file, run the following command:
```
$ chmod 400 MyPrivateKey.pem
```
1. **Open a port for the remote connection.** You can access instances in Amazon GameLift Servers fleets through any port authorized in the fleet configuration. You can view a fleet's port settings using the command [https://docs.aws.amazon.com/cli/latest/reference/gamelift/describe-fleet-port-settings.html](https://docs.aws.amazon.com/cli/latest/reference/gamelift/describe-fleet-port-settings.html).
As a best practice, we recommend opening ports for remote access only when you need them and closing them when you're finished. You can't update port settings after creating a fleet but before it's active. If you get stuck, re-create the fleet with the port settings open.
Use the command [https://docs.aws.amazon.com/cli/latest/reference/gamelift/update-fleet-port-settings.html](https://docs.aws.amazon.com/cli/latest/reference/gamelift/update-fleet-port-settings.html) to add a port setting for the remote connection (such as `22` for SSH or `3389` for RDP). For the IP range value, specify the IP addresses for the devices you plan to use to connect (converted to CIDR format). Example:
```
$ AWS gamelift update-fleet-port-settings
--fleet-id "fleet-2222bbbb-33cc-44dd-55ee-6666ffff77aa"
--inbound-permission-authorizations "FromPort=22,ToPort=22,IpRange=54.186.139.221/32,Protocol=TCP"
```
The following example opens up port 3389 on a Windows fleet
```
$ AWS gamelift update-fleet-port-settings
--fleet-id "fleet-2222bbbb-33cc-44dd-55ee-6666ffff77aa"
--inbound-permission-authorizations "FromPort=3389,ToPort=3389,IpRange=54.186.139.221/32,Protocol=TCP"
```
1. **Open a remote connection client.** Use Remote Desktop for Windows or SSH for Linux instances. Connect to the instance using the IP address, port setting, and access credentials.
SSH example:
```
ssh -i MyPrivateKey.pem gl-user-remote@192.0.2.0
```
## View files on remote instances
Once connected to a fleet instance, you have full user and administrative access. This means you also have the ability to cause errors or failures with game hosting. If the instance is hosting games with active players, you might run the risk of crashing game sessions and dropping players, or disrupting game shutdown processes which could cause errors in saved game data and logs.
For container fleets, after accessing the container (see [Connect to containers](containers-remote-access.md)), the following file locations apply within the container filesystem. For EC2 fleets, these file locations apply directly on the instance.
Look for these resources on a hosting instance:
+ **Game build files.** These files are the game build that you uploaded to Amazon GameLift Servers. They include one or more game server executables, assets, and dependencies. Game build files are in a root directory called `game`:
+ On Windows: `c:\game`
+ On Linux: `/local/game`
+ **Game log files.** Find the log files that your game server generates in the `game` root directory at whatever directory path you designated.
+ **Amazon GameLift Servers hosting resources.** The root directory `Whitewater` contains files used by the Amazon GameLift Servers service to manage game hosting activity. Don't modify these files for any reason.
+ **Runtime configuration.** Don't access runtime configuration for individual instances. To make changes to a runtime configuration property, update the fleet's runtime configuration (see the AWS SDK operation [UpdateRuntimeConfiguration](https://docs.aws.amazon.com/gamelift/latest/apireference/API_UpdateRuntimeConfiguration.html) or the AWS CLI [update-runtime-configuration](https://docs.aws.amazon.com/cli/latest/reference/gamelift/update-runtime-configuration.html)).
+ **Fleet data.** A JSON file contains information about the fleet that the instance belongs to, for use by server processes running on the instance. The JSON file is in the following location:
+ On Windows: `C:\GameMetadata\gamelift-metadata.json`
+ On Linux: `/local/gamemetadata/gamelift-metadata.json`
+ **TLS certificates.** If the instance is on a fleet that has TLS certificate generation enabled, look for certificate files, including the certificate, certificate chain, private key, and root certificate in the following location:
+ On Windows: `c:\\GameMetadata\Certificates`
+ On Linux: `/local/gamemetadata/certificates/`
# Connect to containers
For Amazon GameLift Servers container fleets, you can access game server containers running on a fleet instance. Use container access to troubleshoot game sessions, inspect logs, and debug runtime issues.
## Connect to a container
**Before you start:**
Connect to the fleet instance. For instructions, see [Connect to fleet instances](fleets-remote-access.md).
Run the following command to list running containers on the instance:
```
sudo docker ps
```
The output lists all containers running on the instance, including game server containers and internal Amazon GameLift Servers containers. Look for containers with your game server image to identify the game server containers.
**Example output:**
```
CONTAINER ID IMAGE COMMAND CREATED STATUS
b9676e9489f5 game-server-container "/bin/sh -c ./$GAME_…" 2 days ago Up 2 days
1d1c8443efe2 support-container "/bin/sh -c ./$SUPPO…" 2 days ago Up 2 days
```
To connect to a game server container, use the container short ID from the `CONTAINER ID` column. This gives you full read and write access to the container filesystem.
```
sudo docker exec -it container-short-id sh
```
## Connect to a container through the console
You can connect to game server containers from the Amazon GameLift Servers console using Amazon EC2 Systems Manager (SSM). This method provides secure access without requiring additional setup or credential management. You can connect to a container from either the **Computes** tab or the **Game sessions** tab on the fleet details page.
1. In the Amazon GameLift Servers console, choose **Managed containers** from the navigation pane, and then **Fleets**.
1. Choose the fleet ID that contains the container or game session you want to access.
1. On the fleet details page, choose one of the following tabs:
+ **Computes** – Lists the containers running on the fleet. Select the container you want to connect to.
+ **Game sessions** – Lists the game sessions for the fleet. Select the game session to connect to the container hosting it.
1. Choose **Connect**. Copy the command displayed to connect to the container, then choose **Connect** again.
1. In the connection dialog, choose **Run** to create a new SSM session. The system authenticates your session through AWS Key Management Service (AWS KMS) and opens a terminal in your browser.
1. Once you have connected to the instance, paste the docker command from step 4 and execute it on the instance to access the container.
## Connect to container hosting a game session
To connect to the game server container hosting a specific game session, follow these steps.
1. **Get the compute name.** Call [describe-game-sessions](https://docs.aws.amazon.com/cli/latest/reference/gamelift/describe-game-sessions.html) to get the `ComputeName` for the game session.
**Request**
```
aws gamelift describe-game-sessions \
--fleet-id fleet-2222bbbb-33cc-44dd-55ee-6666ffff77aa \
--game-session-id arn:aws:gamelift:us-west-2::gamesession/fleet-2222bbbb-33cc-44dd-55ee-6666ffff77aa/gs-1111aaaa-2222-3333-4444-5555bbbb66cc
```
**Response**
```
{
"GameSessions": [
{
"GameSessionId": "arn:aws:gamelift:us-west-2::gamesession/fleet-2222bbbb-33cc-44dd-55ee-6666ffff77aa/gs-1111aaaa-2222-3333-4444-5555bbbb66cc",
"FleetId": "fleet-2222bbbb-33cc-44dd-55ee-6666ffff77aa",
"ComputeName": "62c5ff7f7a9a445d84877074c80aeafc",
"Status": "ACTIVE",
. . .
}
]
}
```
Note the `ComputeName` value from the response (for example, `62c5ff7f7a9a445d84877074c80aeafc`).
1. **Get compute access and container attributes.** Call [get-compute-access](https://docs.aws.amazon.com/cli/latest/reference/gamelift/get-compute-access.html) with the fleet ID and compute name.
The response includes the following fields:
+ `ContainerIdentifiers` – The `ContainerName` and `ContainerRuntimeId` for each container.
+ `GameServerContainerGroupDefinitionArn` – The ARN of the container group definition.
+ `Credentials` – Temporary credentials to connect to the instance.
**Request**
```
aws gamelift get-compute-access \
--fleet-id fleet-2222bbbb-33cc-44dd-55ee-6666ffff77aa \
--compute-name 62c5ff7f7a9a445d84877074c80aeafc
```
**Response**
```
{
"ComputeName": "62c5ff7f7a9a445d84877074c80aeafc",
"ContainerIdentifiers": [
{
"ContainerName": "game-server",
"ContainerRuntimeId": "02accb92cd9bef3373300e7151d5c2b3dcca3b06eff1bb4e345085fc008d4678"
}
],
"Credentials": {
"AccessKeyId": "ASIAIOSFODNN7EXAMPLE",
"SecretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
"SessionToken": "AQoDYXdzEJr..."
},
"FleetId": "fleet-2222bbbb-33cc-44dd-55ee-6666ffff77aa",
"GameServerContainerGroupDefinitionArn": "arn:aws:gamelift:us-west-2::containergroupdefinition/MyGameServerGroup"
}
```
1. **Connect to the instance.** Use the credentials from step 2 to connect to the fleet instance. For detailed instructions, see [Connect to fleet instances](fleets-remote-access.md).
1. **Find the game server container name.** Call [describe-container-group-definition](https://docs.aws.amazon.com/cli/latest/reference/gamelift/describe-container-group-definition.html) using the `GameServerContainerGroupDefinitionArn` from step 2 to identify the game server container name.
**Request**
```
aws gamelift describe-container-group-definition \
--name arn:aws:gamelift:us-west-2::containergroupdefinition/MyGameServerGroup
```
**Response**
```
{
"ContainerGroupDefinition": {
"ContainerGroupDefinitionArn": "arn:aws:gamelift:us-west-2:123456789012:containergroupdefinition/MyGameServerGroup:3",
"Name": "MyGameServerGroup",
"ContainerGroupType": "GAME_SERVER",
"GameServerContainerDefinition": {
"ContainerName": "game-server",
. . .
},
. . .
}
}
```
Note the `GameServerContainerDefinition.ContainerName` value (for example, `game-server`).
1. **Identify the game server container runtime ID.** Using the game server container name from the previous step, find the matching entry in the `ContainerIdentifiers` from the `get-compute-access` response in step 2. Note the `ContainerRuntimeId` value.
1. **Connect to the container.** Use the `ContainerRuntimeId` as the container ID and run the following command:
```
sudo docker exec -it 02accb92cd9bef3373300e7151d5c2b3dcca3b06eff1bb4e345085fc008d4678 sh
```