> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kvelden.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Web TLS certificate & hostname

> Give the appliance a hostname and install a trusted TLS certificate so browsers show a secure padlock instead of a warning.

<Info>
  Configure this under **Admin → Network & TLS** as the appliance **owner**. The
  appliance ships with a self-signed certificate so the UI is reachable
  immediately; replace it before inviting users.
</Info>

## What a trusted padlock requires

A browser shows a green padlock (no warning) only when **all three** are true:

1. The appliance is reached by a **hostname (FQDN)** — not a bare IP. Public CAs
   do not issue certificates for private IP addresses.
2. The certificate's **SAN matches** that hostname.
3. The client **trusts the issuer** — a public CA (trusted everywhere), or an
   internal CA whose root your organisation has distributed to client trust
   stores.

## Step 1 — Set the hostname/FQDN

Under **Admin → Network & TLS → Hostname / FQDN**, enter the DNS name that
resolves to the appliance (for example `enclave.company.com`) and save. This
becomes the canonical address used in generated links (invitations, resets), and
the services restart briefly to apply it.

<Tip>
  Create the DNS **A record** pointing at the appliance IP first, so the name
  resolves before you issue a certificate for it.
</Tip>

## Step 2 — Install a certificate

You have two options, both under **Admin → Network & TLS → Web TLS Certificate**.

<Tabs>
  <Tab title="Option A — Upload a CA-signed certificate (recommended)">
    Obtain a certificate for your FQDN from a public CA (DigiCert, Let's Encrypt,
    your enterprise ACME, …) and paste the PEM blocks:

    * **Server certificate (leaf)** — the certificate issued for your hostname.
    * **CA / intermediate chain** — the issuing intermediate(s); required so
      browsers can build the chain. (Optional if already appended to the leaf.)
    * **Private key** — the matching key (PKCS#8, PKCS#1 or SEC1 PEM).

    The appliance verifies the key matches the certificate, checks the chain and
    expiry, then installs it and reloads the web server (a \~1–2 second blip).
    Result: a green padlock everywhere, with no client configuration.

    <Note>
      The private key is written to the appliance and is **never** stored in the
      database, returned by any API, or logged.
    </Note>
  </Tab>

  <Tab title="Option B — Generate a self-signed certificate">
    Generate a self-signed certificate for the appliance (defaults to the
    configured hostname plus its IPs; add more names/IPs if needed and choose a
    validity period).

    Browsers will still warn **until you distribute the certificate to client
    trust stores**. Use **Download current certificate** and push it to your
    fleet via GPO / MDM / Jamf. This is the enterprise "internal PKI" path — no
    public CA required, but it needs a one-time trust rollout.
  </Tab>
</Tabs>

## Verifying

After installing, reload `https://<your-fqdn>`. The **current certificate** panel
shows the subject, issuer, SANs and expiry, with a **CA-signed** or
**self-signed** badge. A CA-signed cert whose SANs include your FQDN should show
the padlock with no warning.

## Rotation & renewal

Repeat **Option A** with the new certificate before the old one expires — the
appliance installs it and reloads the proxy with no further steps. Set a calendar
reminder ahead of the expiry date shown in the certificate panel.

## Clustered appliance (VIP ingress)

In a [high-availability cluster](/enclave/appliance/clustering), users reach a
floating **VIP** that terminates TLS on whichever node currently holds it — so the
web certificate matters on **every** node, not just one. In a cluster the web
certificate is a **cluster-scoped** property: you upload it **once** and the
appliance distributes it to every node — do **not** upload it per node here.

* **Recommended:** in **Admin → Cluster / High Availability → Ingress settings**,
  set the **Service hostname / FQDN** and upload **one CA-signed** certificate whose
  SAN includes the **canonical FQDN *and* the VIP**. The appliance seals it and
  applies it to every node, so a failover is seamless — the client sees a matching,
  trusted certificate no matter which node answers.
* **Self-signed:** until you upload a cluster certificate, the appliance keeps each
  node's self-signed certificate covering the VIP, so `https://<VIP>` matches after a
  failover. But self-signed certificates are **different on each node** (different
  key), so a client that trusts or pins one node's certificate will warn when the VIP
  moves. Upload one CA-signed certificate for a single-trust experience.

See [High availability & clustering](/enclave/appliance/clustering) for the full
service-endpoint setup.

## Related

* [First-run setup](/enclave/appliance/first-run)
* [High availability & clustering](/enclave/appliance/clustering)
* [Private Virtual Appliance](/enclave/appliance/overview)