Amazon GameLift
Developer Guide (Version )

Remotely Access Fleet Instances

You can remotely access any fleet instance that is currently running in an Amazon GameLift fleet. This capability is useful for troubleshooting fleet activation issues. You can also use this feature to get real-time game server activity, such as track log updates or run benchmarking tools using actual player traffic.

When remotely accessing individual Amazon GameLift instances, keep the following in mind:

  • The Amazon GameLift service continues to manage fleet activity and capacity. Establishing a remote connection to an instance does not affect how Amazon GameLift manages it in any way. As a result, the instance continues to execute the fleet runtime configuration, stop and start server processes, create and terminate game sessions, and allow player connections. In addition, the Amazon GameLift service may terminate the instance at any time as part of a scale down event.

  • Making local changes to an instance that is hosting active game sessions and has live players connected may significantly affect player experience. For example, your local changes have the potential to drop individual players, crash game sessions or even shut down the entire instance with multiple game sessions and players affected.

For more information on how games are deployed and managed on Amazon GameLift instances, see the following topics:

Connect to an Instance

You can access remote instances that are running either Windows or Linux. To connect to a Windows instance, use a remote desktop protocol (RDP) client. To connect to a Linux instance, use an SSH client.

Use the AWS CLI get the information you need to access a remote instance. For help, see the AWS CLI Command Reference. If you haven't yet installed the AWS CLI, see the topic Install the AWS CLI.

  1. Find the ID of the instance you want to connect to. When requesting access, you must specify an instance ID. You can get information on all fleet instances using the command describe-instances with a fleet ID. This example retrieves the first three instances in a fleet:

    $ aws gamelift describe-instances --fleet-id "fleet-a7abc071-5537-4f0f-b5ee-1b5c1187565f" --limit 3
  2. Request access credentials for the instance. Once you have an instance ID, use the command get-instance-access to request access credentials and other information. If successful, Amazon GameLift 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:

    $ aws gamelift get-instance-access --fleet-id "fleet-a7abc071-5537-4f0f-b5ee-1b5c1187565f" --instance-id "i-01463992e435d836c"

    For Linux instances – To connect to a Linux instance, SSH requires a user name and private key. Amazon GameLift 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, you must (1) convert the string to a .pem file, and (2) set permissions for the new file.

    • To convert the string to a properly formatted .pem file, add special parameters to your get-instance-access request, as shown in the following example. This example automatically outputs the returned value of Secret to a text file named MyPrivateKey.pem, and replaces all the \n characters with line breaks.

      $ aws gamelift get-instance-access --fleet-id "fleet-a7abc071-5537-4f0f-b5ee-1b5c1187565f" --instance-id "i-01463992e435d836c" --query 'InstanceAccess.Credentials.Secret' --output text > MyPrivateKey.pem
    • To set permissions on the new file, run the following command

      $ chmod 400 MyPrivateKey.pem
  3. Open a port for the remote connection. Instances in Amazon GameLift fleets can only be accessed through ports authorized in the fleet configuration. You can view a fleet's port settings using the command describe-fleet-port-settings.

    As a best practice, we recommend opening ports for remote access only when you need them and closing them when you're finished. Use the command update-fleet-port-settings 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-a7abc071-5537-4f0f-b5ee-1b5c1187565f" --inbound-permission-authorizations "FromPort=22,ToPort=22,IpRange=,Protocol=TCP"
  4. 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.

View and Update Remote Instances

When connected to an instance remotely, you have full user and administrative access. This means you also have the ability to cause errors and failures in game hosting. If the instance is hosting games with active players, you run the risk of crashing game sessions and dropping players, as well as disrupting game shutdown processes and causing errors in saved game data and logs.

Hosting resources on an instance can be found in the following locations:

  • Game build files. These are the files included in the game build you uploaded to Amazon GameLift. They include one or more game server executables, assets and dependencies. These files are located in a root directory called game:

    • On Windows: c:\game

    • On Linux: /local/game

  • Game log files. Any log files your game server generates are stored in the game root directory at whatever directory path you designated.

  • Amazon GameLift hosting resources. Files used by the Amazon GameLift service to manage game hosting are located in a root directory called Whitewater. These files should not be changed for any reason.

  • Runtime configuration. The fleet runtime configuration is not accessible for individual instances. To test changes to a runtime configuration (launch path, launch parameters, maximum number of concurrent processes), you must update the fleet-wide runtime configuration (see the AWS SDK action UpdateRuntimeConfiguration or the AWS CLI update-runtime-configuration).