# What runs on your machines

What the platform adds to an instance's first boot next to your user data, what it can and cannot see, and what happens when something fails.

Everything the platform puts on the machine travels in the first boot, as parts of a multipart
cloud-init document next to your own user data, which runs unchanged. `GET …/user-data` returns
only your part. The one way in is Connect, on by default: it lets the console open a terminal and
add keys through an outbound SSH connection, logging in to the machine's own sshd with a
two-minute certificate signed by your organization's user CA. Every such login shows in the
machine's sshd log. Launch with `connect: false`, or run `systemctl disable --now ews-connect` on
the machine, to turn it off.

## What the first boot adds

| Part               | What it does                                                                                                                                  | When                                          |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
| Instance identity  | Writes `/etc/ews/instance-identity` (root only) and the helper `/usr/local/bin/ews-instance`; rotates the secret at every boot and once a day | Always; runs before your script               |
| Connect            | Keeps one outbound SSH connection to the platform for the browser terminal and for adding keys later                                          | Unless launched with `connect: false`         |
| No root password   | Locks the root password; sshd lets root in with a key only and takes no passwords, unless your own cloud-config turns them on                 | Always                                        |
| Patch reporter     | `ews-patch`, see [Keep the OS patched](keep-the-os-patched.md)                                                                                | With `osPatching`                             |
| NAT route          | Routes IPv4 through the network's NAT gateway                                                                                                 | No public IPv4 and an `available` NAT gateway |
| Private routes     | Routes the private address ranges through the network, so a site-to-site VPN added to it reaches the machine                                  | Always                                        |
| Elastic IP binding | Every 20 seconds, adds the elastic IPs associated with this instance to its public interface and removes ones it added that are gone          | Always (see below)                            |
| Volume helper      | Opens encrypted volumes at `/dev/mapper/ews-vol-…`, see [Use encrypted volumes](encrypted-volumes.md)                                         | Always (see below)                            |

User data is limited to 32 KiB by the provider. When the elastic IP binding and the volume helper do
not both fit next to your script, the volume helper is kept and the elastic IP binding is left out.
If the volume helper does not fit even without the binding, it is left out and the binding is kept
if it fits; the instance then cannot open encrypted volumes until you
[install the helper](encrypted-volumes.md). Your own user data always goes in. An instance without
the binding needs the commands the console shows for its elastic IP.

## What the platform sees

- The instance's state, addresses, type and zone, from the provider.
- What the parts above report: Connect's status, the patch state, the elastic IPs bound, whether
  the volume helper reported in.
- The identity secret is stored only as its hash, and stops working when the instance terminates.
- An encrypted volume's key is handed only to the instance the provider reports the volume
  attached to.

## When something fails

- A launch the provider refuses leaves no instance behind. If the provider cannot confirm that no
  machine was left, the instance stays, `stopped`, with the error on its page so you can find it.
- A start, stop, reboot or resize that fails at the provider returns the instance to its previous
  state with the error on its page. A terminate that fails leaves it `stopping` with the error.
- A launch whose machine does not finish booting leaves the instance `stopped` with the error.
- A NAT gateway is one machine. A check every 5 minutes puts back a missing `0.0.0.0/0` route; a
  gateway whose machine is gone, or whose setup failed, turns `failed`. Delete it and create it
  again.
- A security group change that cannot be applied answers `502`; the group shows **Not applied**
  until a change succeeds.

## Related

- [Security](security.md)
- [Give an instance a role](give-an-instance-a-role.md)
