====== DNS & TLS Certificate Configuration ======

Chipmunk requires a valid DNS name and HTTPS certificate to operate securely inside your network.

This guide helps you configure:
  * An internal DNS name (e.g., ''chipmunk.yourcompany.local'')
  * A TLS certificate (PEM format recommended)

===== Step 1: Decide on a DNS Name =====

Choose a hostname for your Chipmunk appliance. This will be used in your App Registration and accessed in your browser.

**Examples:**
  * chipmunk.yourcompany.local
  * chipmunk.archive.yourdomain.com

Then:
  * Create a **DNS A record** in your internal DNS pointing to the Chipmunk appliance's static IP address
  * Ensure this name resolves from any machine that will access the dashboard

===== Step 2: Provide a TLS Certificate (PEM Format Recommended) =====

Chipmunk supports TLS certificates in **PEM format**, which must include:
  * The full certificate chain
  * The private key

You can use:
  * A certificate from a trusted **public CA** (preferred)
  * A certificate issued by your **internal CA**
  * A **self-signed certificate** (supported, but browser warnings will occur)

**Recommended PEM file structure:**
<code>
-----BEGIN CERTIFICATE-----
[your certificate]
-----END CERTIFICATE-----
-----BEGIN PRIVATE KEY-----
[your private key]
-----END PRIVATE KEY-----
</code>

Upload your PEM files during setup or place them in the correct path as instructed by the configuration wizard.

===== Step 3: Self-Signed Certificate (Optional Fallback) =====

If you don’t have access to a public or internal CA, Chipmunk can generate a **self-signed certificate** during setup.

**Important Notes:**
  * You will see browser warnings when accessing the appliance over HTTPS
  * Functionality is unaffected, but user experience is impacted
  * You can replace the self-signed cert with a real certificate at any time

===== Step 4: Match the Hostname in Your Certificate =====

Make sure the **Common Name (CN)** or **Subject Alternative Name (SAN)** in your certificate matches the DNS name you plan to use.

**For example:**
If you access Chipmunk at ''https://chipmunk.yourcompany.local'', then the cert must include that hostname.

===== What You’ll Need During Setup =====

When running the Chipmunk setup wizard after deploying the appliance, have the following ready:

  * ✅ The full DNS name (e.g. ''chipmunk.yourcompany.local'')
  * ✅ A PEM-formatted TLS certificate and private key
  * ✅ OR choose the option to generate a self-signed certificate

-----

Next: [[software:chipmunk:setup:first_run|Complete the First-Time Configuration]]

{{tag>chipmunk dns tls certificate ssl setup pem selfsigned}}