# 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](/sandboxes/lifecycle-scripts.md#track-setup-script).
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.instruqt.com/sandboxes/hosts/ssl-certificates.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.