# Use Cloud-Init and User Data

User data is a way to automatically provision your instance with additional
software or settings.
You can provide a set of commands (a script) or enter cloud-config
information as YAML.
It is important to understand that the User Data provided will be used only
when the machine is created.

## Cloud Init Datasources

Historically, Exoscale templates used the `Cloudstack` cloud-init datasource.
Since Cloud Init version `19.3`, Exoscale has its own datasource.

Although the new Exoscale datasource is backwards-compatible with the
Cloudstack datasource, new features such as managed private networks require
using the Exoscale datasource. We recommend using the Exoscale datasource for
all installations.

## Adding User Data
When you create a new instance, the wizard lets you enter user data
at the bottom of the form.

You can find everything that can be done with user data and Cloud-Init in the
[documentation](https://cloudinit.readthedocs.io/en/latest/index.html).

## Example: Script

In this example, we install `screen` and `htop` on an Ubuntu instance using Apt
after having
upgraded all packages on an Debian/Ubuntu system.

Add the following to the `User Data` field to install the `screen` package:

```yaml
#cloud-config
runcmd:
    - apt-get --yes upgrade
    - apt-get --yes install screen htop
```
**Note:** Cloud-Init has pre-built directives for many items. Therefore,
the previous scripts launched as command lines can be achieved with:

```yaml
#cloud-config
package_upgrade: true
packages:
  - screen
  - htop
```

## Example: Cloud-Config YAML

We will set our locale to en_US.UTF-8 using cloud-config YAML.
Add the following YAML in the user data:

```yaml
#cloud-config
locale: "en_US.UTF-8"
```

## Example: Installing Wordpress

See our [Wordpress tutorial](https://www.exoscale.com/syslog/Hello-world/).

## Querying the User Data and Meta Data from the Instance

`User Data` and `Meta Data` can be retrieved from an instance to
integrate in scripts for example or configuration management tools.
This information is published on the Link Local Address
169.254.169.254 which is private between the hypervisor and the
running instance.

* User Data (the cloud-config contents)

```bash
curl http://metadata.exoscale.com/latest/user-data
```

* Meta Data, such as instance size or IP address

```bash
curl http://metadata.exoscale.com/latest/meta-data
curl http://metadata.exoscale.com/latest/meta-data/public-ipv4
```

The list of available metadata is:

|metadata name|description|
|---|---|
|availability-zone|The [zone - datacenter](https://www.exoscale.com/datacenters) in which the instance is running|
|cloud-identifier|Returns "Exoscale Compute Platform" if running on Exoscale|
|instance-id|The unique identifier or UUID for the instance|
|local-hostname|The name of the instance as set during the add instance phase|
|local-ipv4|The primary network IP address of the instance|
|public-hostname|Same as `local-hostname`|
|public-ipv4|The public IP address of the instance|
|public-keys|The associated SSH public key associated to the instance|
|service-offering|The size of the instance|
|vm-id|Same as `instance-id`|


## Adding Password Management to Your Templates

Exoscale provides an optional password reset feature that allows users
to set a temporary admin or root password as well as reset the existing
admin or root password from the Exoscale Portal.

This password is provided to an instance via the Link Local Address
169.254.169.254 on port 8080:

```bash
curl  --header "DomU_Request: send_my_password" http://169.254.169.254:8080
```

After the password is retrieved and changed on the running instance, issue a
command to indicate that the password was saved and that it can be deleted:

```bash
$ curl  --header "DomU_Request: saved_password" http://169.254.169.254:8080
```

**Notes:**

* Linux-based distributions with a standard Cloud-Init implementation will follow the process outlined above automatically if the system allows for password-based logins.
* Passwords are only provided one time back to the user who starts or resets an instance and are not persisted at the orchestration layer.