# Keep the OS patched

Launch an Ubuntu instance that installs security updates every night, reboots for them in the platform window and reports its patch state.

**Keep OS patched** is set at launch: a patch reporter goes onto the machine with its first boot,
as a part of the user data in front of yours. Your own user data runs unchanged.

## Prerequisites

- Permission for `ec2:RunInstances`; reading the state needs `ec2:DescribeInstances`.
- An Ubuntu image. Another image is refused with `400` "\"Keep OS patched\" needs an Ubuntu image;
  this one is …".
- Not offered on your organization's own hosts: there the launch is refused with `400` "“Keep OS
  patched” is not offered on this organization’s own hosts yet".

## Turn it on at launch

**Console**
1. Open **Compute**, then choose **Create instance**.
2. Fill in the form (see [Launch an instance](launch-an-instance.md)) with an Ubuntu image.
3. Under **Security**, turn on **Keep OS patched**.
4. Choose **Create instance**.

**CLI**
```sh
dcloud ec2 instances run --region-id de1 --server-type performance-2 \
  --image-id 114690387 --os-patching
```

**API**
```http
POST /ec2/api/instances
{ "serverType": "performance-2", "imageId": 114690387, "regionId": "de1", "osPatching": true }
```

**Terraform**
Set `os_patching = true` on the `dcloud_instance`. Changing it later replaces the instance.

## What it does on the machine

- Ubuntu's unattended-upgrades installs security updates every night and is set never to reboot
  on its own. It also runs once ten minutes after the first boot, so a machine does not wait for
  its first night.
- `ews-patch` reports every 15 minutes (and at boot): pending updates, how many are security
  updates, whether a reboot is needed and for which packages, the running and the newest installed
  kernel, and when it booted.
- When an update needs a reboot, the machine reboots in the platform reboot window
  (02:00–05:00 UTC unless your installation sets another; the instance page names it). The
  reboot is an ordinary reboot, so services you enabled come back on their own.

## See the state

**Console**
Open the instance. Its **Overview** shows **OS patches**.

**CLI**
```sh
dcloud ec2 instances get-patch-state i-3f9a2c07
```

**API**
```http
GET /ec2/api/instances/i-3f9a2c07/patch-state
```

**Terraform:** not available. The patch state is not a resource attribute.

`status` is one of:

| Status             | Meaning                                                         |
| ------------------ | --------------------------------------------------------------- |
| `current`          | Nothing pending.                                                |
| `updates-pending`  | Security updates not yet installed; the nightly run takes them. |
| `reboot-pending`   | An update needs a reboot, waiting for the window.               |
| `reboot-scheduled` | Allowed to reboot, about to be told.                            |
| `rebooting`        | Told to reboot and not back yet.                                |
| `not-reporting`    | No report for three intervals (45 minutes).                     |

`data` is `null` for an instance launched without **Keep OS patched**, and until the machine's
first report. **Keep OS patched** is set at launch only; to change it, launch a new instance.

## Related

- [What runs on your machines](what-runs-on-your-machines.md)
- `ec2.instances.get-patch-state` · `dcloud ec2 instances get-patch-state`
