AWS Emulator command reference

The aws-emulator command starts an instance of AWS Emulator. You install it with the Linux package, or run it in a container that you build. For installation, see Getting started with AWS Emulator. The container takes the same options as the native command.

Synopsis

The command takes only options. It has no subcommands.

aws-emulator [options]

With no options, the emulator listens for HTTPS requests on 127.0.0.1:9297. It serves the AWS APIs and its health route on that one port. It runs in the foreground until you stop it.

Options

The following table lists every option. Long options also accept the form --option=value, for example --port=9300. If you give an option that the emulator doesn’t know, it prints an error and exits with code 2.

Output

The emulator writes its log to standard output as JSON lines, one JSON object for each line. When it’s ready, it writes one startup line, whose message field is emulator server information. The following table describes the fields in the startup line.

You can rely on this line and its fields. Find it by its message field, not by its position, because other lines can come before it. For example, if you start the emulator with -p 0, read the actual port from endpoint_url. For the files, see Local files. For how to use them with your tools, see Pointing your AWS SDK at AWS Emulator.

The emulator also writes one line of plain text to standard error. This telemetry notice says whether telemetry is on and how to turn it off. For more information, see Telemetry in AWS Emulator.

If the emulator listens on an address other than loopback, or if authentication is off, it also writes a warning line. This line says who can reach the emulator. The rest of the log isn’t a stable interface. Its fields can change in any release, and so can the help text. To check whether the emulator is ready, use the health route. For more information, see Control routes.

Control routes

Besides the AWS APIs, the emulator serves one control route. It serves this route on the same port as the APIs, over HTTPS. There’s no separate admin port.

The following example checks the health of an emulator on the default port. It uses the certificate that the emulator wrote for that port.

curl --cacert ~/.aws/emulator/9297/ca.pem https://127.0.0.1:9297/__admin/health

To wait for the emulator in a script, use the loop in To point your SDK at a local emulator.

The emulator doesn’t provide routes to reset state or to control state transitions. It keeps all state in memory. To start with empty state, restart the emulator.

Local files

When it starts, the emulator writes the following files to a subdirectory of ~/.aws/emulator/ named for its port, for example ~/.aws/emulator/9297/.

The emulator creates each file so that only your user can read and write it (mode 0600). It deletes the files when it stops cleanly. A clean stop is Ctrl+C, SIGTERM, or an idle timeout set with --idle-timeout.

If the emulator crashes, the files stay. The next emulator that starts on the same port replaces them, so you don’t need to delete them yourself.

When you run the emulator in a container, the paths in config are paths inside the container. For the settings to use on your host, see To point your SDK at a local emulator.

For the files that telemetry uses, see Telemetry in AWS Emulator.

Credentials and authentication

By default, the emulator requires API requests to be signed with Signature Version 4 (SigV4). Operations that AWS serves without a signature, such as AWS STS AssumeRoleWithWebIdentity, don’t need one. The emulator accepts both signed headers and presigned URLs. Each time it starts, it generates a new key pair. Currently, the keys have the following format:

The keys work only with the emulator run that generated them. They don’t expire while the emulator runs. They stop working when the emulator stops, and they don’t work with an emulator on another port.

The emulator rejects unsigned requests and requests signed with other keys. Keys that you create in the emulator itself, through IAM (CreateAccessKey) or AWS STS, also work. Some services accept requests that aren’t signed with standard SigV4. The emulator doesn’t handle those requests the same way as AWS. For more information, see What we do.

The emulator rejects a request with HTTP 403, or with HTTP 404 if it can’t tell which service the request is for. The error depends on the reason, as shown in the following table.

The emulator rejects a request whose signed time is more than 15 minutes from its own clock, as AWS does. It also rejects presigned URLs after they expire.

Each emulator acts as one AWS account, 000000000000. To check that your tools talk to the emulator, see To check that you’re using the emulator.

If you start the emulator with --auth off, it serves every request, signed or not, and doesn’t write a credentials file. Before you use this option, see What you do.

The size and format of the generated credentials can change in any release. Don’t validate them in your code.

When the port is in use

If another process already uses the port, the emulator prints the following error, followed by an operating system error code. Then it exits with code 1.

emulator serve failed: server I/O error: Address already in use

The emulator writes no files in this case. The files of an emulator that already runs on that port stay as they are. To fix the error, choose another port with -p, or use -p 0 to let the operating system pick a free port.

Stopping the emulator

The emulator runs in the foreground. To stop it, press Ctrl+C or send the process SIGTERM. If you set --idle-timeout, the emulator also stops by itself after that idle time.

In each case, the emulator stops cleanly. It sends its final telemetry batch if telemetry is on, and deletes its files for that port. The emulator keeps all emulated resources in memory, so they’re gone when it stops.