Introduction

Emulot is a tool suite including a command line interface as well as an HTTP interface for managing emulator instances and configurations, specifically focused on QEMU. The idea is to be able to easy store, share, and run instances without needing to remember all the details. The configurations are currently accepted as TOML represenations of the QEMU command line options.

Configutation

emulot is configured using a configuration file passed via the --config flag on the command line. It uses what's though to be reasonable default when no configuration is provided.

The configuration file uses TOML. It currently two sections [client] and [daemon].

client

url - The base URL of the API to the HTTP daemon. This is expected to be tcp://<hostname>:<post> or unix:///path/to/emulotd.sock.

daemeon

This section is explained in the [emulot daemon](./cli/daemon.md) documentation.

Tips for emulation

Serial port geometry

If you use emulot run to connect to the virtual machine via the serial port, it will likely cause the default geometry of the shell to be 80x24. This may not be obvious until you run an application that uses these values like vim or other text editors which rely on curses. To fix this on Linux, you can run stty rows <rows> cols <cols> to set a new expected geometry.

Command Line Tool

The emulot command is the main entrypoint in from the program. After you've installed emulot, the following options are available:

emulot run [<config>] - Runs a configuration in foreground without a daemon
emulot daemon - Starts up an HTTP daemon for managing emulators
emulot create <name> [<config>] - Creates a new guest configuration
emulot remove <name> - Removes a guest configuration
emulot start <name> - Starts a guest configuration
emulot stop <name> - Stops a guest configuration

The run command

This is the one command that currently doesn't require a daemon since it starts a single configuration file in the foreground and takes the form:

emulot run <config>

or:

emulot run

The latter form takes the configuration from stdin similar to and for the same reasons as the create command.

The daemon command

This command starts an HTTP daemon that is required for most other commands and takes the form:

emulot daemon

Configuration

The daemon has some configurations that are located within [daemon] section of the configuration file.

listen - Defines how the daemon listens for communication and is of two forms:
- unix:///path/to/file.sock for a UNIX socket server
- tcp://localhost:8081 for a TCP server
storage_uri - Defines the SQLite database for persistence

The create command

This command creates a new guest using a configuration and takes the form:

emulot create <name> <config>

or:

emulot create <name>

In the latter form, it accepts the configuration from stdin which allows integration with applications like curl.

For example:

curl http://example.com/path/to/config.toml | qemu create <name>

The remove command

This command removes a guest configuration and takes the form:

emulot remove <name>

The start command

This command starts a guest configuration and takes the form:

emulot start <name>

The stop command

This command stops a running guest and takes the form:

emulot stop <name>

API

The Emulot API is an HTTP API for managing emulation configurations and instances. While the CLI accepts TOML, the HTTP interface accepts JSON as a more natural format for HTTP interfaces. Currently, the only existing endpoint is:

Guests - Management of the guest configurations and instnaces

Guests API

/guests/create/<name> - Creates a guest with the provided configuration
- Method: POST
- Request Body:
```
{
    "arch": "i386",
    "memory": 512
}
```
/guests/list - Lists all the guest names mapped to their ID
- Method: GET
- Response Body:
```
[
    {"guest-a": 1 },
    {"guest-b2": 2 }
]
```
/guests/remove/<id>- Remove a guest configuration
- Method: DELETE
/guests/start/<id> - Start a guest
- Method: POST
/guests/stop/<id> - Stop a guest
- Method: POST