# SSL certificates

## Overview

Instruqt can automatically generate SSL certificates for VMs using [Let's Encrypt](https://letsencrypt.org/).  Automatic SSL certificate generation simplifies the process of securing virtual machines within your Instruqt sandbox environments. 

## Add SSL certificates

You can add an SSL certificate to a VM using the web UI or the Instruqt CLI. 

{% tabs %}
{% tab title="🌐 Web UI" %}

1. Select a VM in your track's sandbox. 
2. Click **Show optional settings**. 
3. Select **Provision SSL certificate**. 
4. Click **Save host**.
   {% endtab %}

{% tab title="💻 Instruqt CLI" %}

1. Within a track's `config.yml` file, add the `provision_ssl_certificate` flag to a `virtualmachine` config to enable SSL certificate generation:

   ```yaml
   config.yml

   version: "3"
   virtualmachines:
   - name: host01
     image: ubuntu-minimal-2004-lts
     shell: /bin/bash
     machine_type: n1-standard-1
     allow_external_ingress:
     - http
     - https
     - high-ports
     provision_ssl_certificate: true
   ```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
Enable external ingress to port `443` (HTTPS)  or `high-ports` on the VM to make use of the new certificates.
{% endhint %}

## Use SSL certificates

When enabled,  Instruqt will provision a certificate for the following domain names:

* `${hostname}.${_SANDBOX_ID}.instruqt.io`
* `*.${hostname}.${_SANDBOX_ID}.instruqt.io`

The certificate is made available via the [GCP metadata service](https://cloud.google.com/compute/docs/metadata/overview) for that virtual machine instance. The public key is available under the `ssl-certificate` attribute, the private key under the `ssl-certificate-key` attribute. You can download them using a `curl` statement to the metadata service.

Here is an example of how to retrieve the SSL certificate using `curl`:

```bash
curl -s -o /etc/ssl/certs/sandbox.crt -H "Metadata-Flavor: Google" \
    "http://metadata.google.internal/computeMetadata/v1/instance/attributes/ssl-certificate"
```

```bash
curl -s -o /etc/ssl/private/sandbox.key -H "Metadata-Flavor: Google" \
    "http://metadata.google.internal/computeMetadata/v1/instance/attributes/ssl-certificate-key"
```

{% hint style="info" %}
The certificates can retrieved and configured using a track or challenge's [setup scripts](https://docs.instruqt.com/lifecycle-scripts#track-setup-script).
{% endhint %}