TLS

This page explains how to add TLS support for Netbox. There are many ways to do this.

TLS for localhost

This guide is intended for people developing with or on Netbox or Netbox-Docker on their computer. It allows to access Netbox-Docker through TLS on https://localhost:8443, https://127.0.0.1:8443 and https://[::1]:8443.

First install mkcert on your computer. It creates and installs a local CA-Certificate, which is used to create other certificates. This way your certificates are trusted on your own computer and you don't get a TLS warning in your tools (browsers, cURL, and so forth).

Use mkcert to create the certificates for localhost and it's IPv4 and IPv6 addresses:

mkcert -install
mkcert localhost 127.0.0.1 ::1

This should create a file called localhost+2.pem and another file called localhost+2-key.pem. The TLS proxy hitch needs these files in a combined form:

cat localhost+2.pem localhost+2-key.pem > cert_and_key.pem

Continue with TLS Using Hitch.

TLS for the world

In order to setup TLS to serve public traffic to your Netbox it is recommended to set up a reverse proxy that is independent from Netbox. You can do this by installing a webserver like nginx on your host machine directly or by running it in a container, as explained below with Hitch. But we strongly advise against changing the Nginx configuration that ships with Netbox Docker.

TLS Using Hitch

Hitch is a high performance TLS proxy by the people behind the famous Varnish.

First you need to combine your TLS key and TLS certificate into one file:

cat key.pem certificate.pem > cert_and_key.pem

To run the TLS proxy a Docker image of hitch can be used. Add the following to your docker-compose.override.yml file:

# docker-compose.override.yml

services:
  # ...

  tls:
    image: zazukoians/hitch
    environment:
      HITCH_PEM: /app/cert_and_key.pem # path within the container to the TLS certificate
      HITCH_PARAMS: --backend=[nginx]:8080 --frontend=[*]:443 # listen on *:443 and forward traffic to nginx:8080
    depends_on:
      - nginx
    volumes:
      - ./cert_and_key.pem:/app/cert_and_key.pem # mount the TLS certificate
    ports:
      - 8443:443 # bind the container's port 443 to the host's port 8443 -> https://[::1]:8443

NOTE:

Starting with Netbox Docker 0.28.0, the nginx service is no longer in use. The traffic must be forwarded to the netbox service directly:

-      HITCH_PARAMS: --backend=[nginx]:8080 --frontend=[*]:443 # listen on *:443 and forward traffic to nginx:8080
+      HITCH_PARAMS: --backend=[netbox]:8080 --frontend=[*]:443 # listen on *:443 and forward traffic to netbox:8080