Testing or local single-user environment

Follow this installation guide if you want to use happyDomain directly on your machine, as simply as possible, without user management.

This is a simple configuration, suitable for evaluating happyDomain or for using it without authentication on your own machine, or with authentication provided by a reverse proxy.

You can deploy it using Docker or by downloading one of the available executables. Both methods are described below.

Via Docker/podman

If you are familiar with Docker (or podman), you can have happyDomain up and running in seconds with the following command:

docker container run -e HAPPYDOMAIN_NO_AUTH=1 -p 8081:8081 happydomain/happydomain

If you want to make the data persistent, you need to add a volume:

docker volume create happydns_data
docker container run -v happydns_data:/data -e HAPPYDOMAIN_NO_AUTH=1 -p 8081:8081 happydomain/happydomain

Whatever your choice, go to http://localhost:8081 to start using happyDomain.

Via the executable

1. Start by downloading the executable matching your processor architecture from: https://get.happydomain.org/master/. The darwin versions are for macOS, while the linux versions are for GNU/Linux. All distributed versions are static and should work regardless of your libc (GNU libc in most cases, musl for Alpine, …).

2. Make the binary you downloaded executable: chmod +x happydomain-OS-ARCH.

3. Run the binary: HAPPYDOMAIN_NO_AUTH=1 ./happydomain-OS-ARCH.

4. Go to http://localhost:8081/ to start using happyDomain.

What do these options do?

The HAPPYDOMAIN_NO_AUTH=1 option is a parameter that tells happyDomain not to require authentication: domains are shared among all incoming connections. In practice, this automatically creates a default user and disables all login, account registration, and related features.

Can I expose it on the Internet like this?

No! It is essential that you do not expose your happyDomain instance on the Internet without authentication. Without it, all its content would be accessible to anyone, and they could take control of your domain(s).

Always use a reverse proxy such as nginx, Apache, HAproxy, Traefik, … adding a filtering or basic authentication step.

For example, you can filter the IPs that can access the service. Here is a sample nginx configuration filtering IPs (using the allow directive):

server {
    listen 80;
    listen [::]:80;

    server_name happydomain.example.com;

    location / {
        allow 42.42.42.42;
        deny all;

        proxy_pass	http://localhost:8081;
        proxy_set_header  X-Forwarded-For  $proxy_add_x_forwarded_for;
    }

}

You can also add basic password authentication.

Using Docker

happyDomain is sponsored by Docker. You’ll find the official container image on the Docker Hub.

The image runs happyDomain as a single process with a LevelDB database stored on disk — no extra database to configure.

Supported tags and architectures

All tags are built for amd64, arm64 and arm/v7 and are based on Alpine.

Currently available tags:

• latest: the most up-to-date version, corresponding to the master branch.

Quick start (single container)

For a quick test or personal use, pass HAPPYDOMAIN_NO_AUTH=1 to skip account management:

docker run -e HAPPYDOMAIN_NO_AUTH=1 -p 8081:8081 happydomain/happydomain

Data are stored inside the container. To keep them across restarts, attach a volume:

docker volume create happydomain_data
docker run -e HAPPYDOMAIN_NO_AUTH=1 -v happydomain_data:/data -p 8081:8081 happydomain/happydomain

For a production single-container setup that sends e-mail:

docker run \
  -e HAPPYDOMAIN_MAIL_SMTP_HOST=smtp.yourcompany.com \
  -e HAPPYDOMAIN_MAIL_SMTP_USERNAME=happydomain \
  -e HAPPYDOMAIN_MAIL_SMTP_PASSWORD=secret \
  -v /var/lib/happydomain:/data \
  -p 8081:8081 \
  happydomain/happydomain

Full deployment with all checkers

happyDomain ships every checker built-in, but several of them rely on external tools (DNSViz, Zonemaster, Matrix federation tester) that are packaged in their own container images. Running these as separate services gives you the full checker experience and better isolation.

The recommended approach is docker compose. Save the following file as docker-compose.yml and run docker compose up -d.

services:
  happydomain:
    image: happydomain/happydomain
    ports:
      - "8080:8081"
    environment:
      # Uncomment for single-user / testing
      # HAPPYDOMAIN_NO_AUTH: "1"

      # Mail configuration (required for multi-user production use)
      # HAPPYDOMAIN_MAIL_SMTP_HOST: "mailer"

      # ── DNS / DNSSEC ─────────────────────────────────────────────────────
      HAPPYDOMAIN_CHECKER_DNSVIZ_ENDPOINT: "http://checker-dnsviz:8080"
      HAPPYDOMAIN_CHECKER_DNSSEC_ENDPOINT: "http://checker-dnssec:8080"
      HAPPYDOMAIN_CHECKER_ZONEMASTER_ENDPOINT: "http://checker-zonemaster:8080"
      HAPPYDOMAIN_CHECKER_ZONEMASTER_ZONEMASTERAPIURL: "http://zonemaster:5000"
      HAPPYDOMAIN_CHECKER_DELEGATION_ENDPOINT: "http://checker-delegation:8080"
      HAPPYDOMAIN_CHECKER_AUTHORITATIVE_CONSISTENCY_ENDPOINT: "http://checker-authoritative-consistency:8080"
      HAPPYDOMAIN_CHECKER_ALIAS_ENDPOINT: "http://checker-alias:8080"
      HAPPYDOMAIN_CHECKER_LEGACY_RECORDS_ENDPOINT: "http://checker-legacy-records:8080"
      HAPPYDOMAIN_CHECKER_NS_RESTRICTIONS_ENDPOINT: "http://checker-ns-restrictions:8080"
      HAPPYDOMAIN_CHECKER_RESOLVER_PROPAGATION_ENDPOINT: "http://checker-resolver-propagation:8080"
      HAPPYDOMAIN_CHECKER_REVERSE_ZONE_ENDPOINT: "http://checker-reverse-zone:8080"
      HAPPYDOMAIN_CHECKER_PTR_ENDPOINT: "http://checker-ptr:8080"
      HAPPYDOMAIN_CHECKER_DANGLING_ENDPOINT: "http://checker-dangling:8080"

      # ── Security / Certificates ───────────────────────────────────────────
      HAPPYDOMAIN_CHECKER_TLS_ENDPOINT: "http://checker-tls:8080"
      HAPPYDOMAIN_CHECKER_DANE_ENDPOINT: "http://checker-dane:8080"
      HAPPYDOMAIN_CHECKER_CAA_ENDPOINT: "http://checker-caa:8080"
      HAPPYDOMAIN_CHECKER_BLACKLIST_ENDPOINT: "http://checker-blacklist:8080"

      # ── E-mail ────────────────────────────────────────────────────────────
      HAPPYDOMAIN_CHECKER_SMTP_ENDPOINT: "http://checker-smtp:8080"
      HAPPYDOMAIN_CHECKER_EMAIL_AUTOCONFIG_ENDPOINT: "http://checker-email-autoconfig:8080"
      HAPPYDOMAIN_CHECKER_OPENPGPKEY_SMIMEA_ENDPOINT: "http://checker-email-keys:8080"

      # ── Web & Protocols ───────────────────────────────────────────────────
      HAPPYDOMAIN_CHECKER_HTTP_ENDPOINT: "http://checker-http:8080"
      HAPPYDOMAIN_CHECKER_SSH_ENDPOINT: "http://checker-ssh:8080"
      HAPPYDOMAIN_CHECKER_PING_ENDPOINT: "http://checker-ping:8080"
      HAPPYDOMAIN_CHECKER_SRV_ENDPOINT: "http://checker-srv:8080"

      # ── Collaboration / Messaging ─────────────────────────────────────────
      HAPPYDOMAIN_CHECKER_MATRIXIM_ENDPOINT: "http://checker-matrix:8080"
      HAPPYDOMAIN_CHECKER_MATRIXIM_FEDERATIONTESTERSERVER: "http://matrixfederationtester:8080/api/report?server_name=%s"
      HAPPYDOMAIN_CHECKER_XMPP_ENDPOINT: "http://checker-xmpp:8080"
      HAPPYDOMAIN_CHECKER_SIP_ENDPOINT: "http://checker-sip:8080"

      # ── Directory & Auth ──────────────────────────────────────────────────
      HAPPYDOMAIN_CHECKER_LDAP_ENDPOINT: "http://checker-ldap:8080"
      HAPPYDOMAIN_CHECKER_KERBEROS_ENDPOINT: "http://checker-kerberos:8080"
      HAPPYDOMAIN_CHECKER_STUNTURN_ENDPOINT: "http://checker-stun-turn:8080"

      # ── CalDAV / CardDAV ──────────────────────────────────────────────────
      HAPPYDOMAIN_CHECKER_CALDAV_ENDPOINT: "http://checker-caldav:8080"
      HAPPYDOMAIN_CHECKER_CARDDAV_ENDPOINT: "http://checker-carddav:8080"

      # ── Optional: happyDeliver integration ────────────────────────────────
      # HAPPYDOMAIN_CHECKER_HAPPYDELIVER_ENDPOINT: "http://checker-happydeliver:8080"

    restart: unless-stopped
    volumes:
      - storage:/var/lib/happydomain:rw

  # ── DNS / DNSSEC checkers ──────────────────────────────────────────────────

  checker-dnsviz:
    image: happydomain/checker-dnsviz
    restart: unless-stopped

  checker-dnssec:
    image: happydomain/checker-dnssec
    restart: unless-stopped

  checker-zonemaster:
    image: happydomain/checker-zonemaster
    restart: unless-stopped

  zonemaster:
    image: zonemaster/backend
    command: full
    restart: unless-stopped

  checker-delegation:
    image: happydomain/checker-delegation
    restart: unless-stopped

  checker-authoritative-consistency:
    image: happydomain/checker-authoritative-consistency
    restart: unless-stopped

  checker-alias:
    image: happydomain/checker-alias
    restart: unless-stopped

  checker-legacy-records:
    image: happydomain/checker-legacy-records
    restart: unless-stopped

  checker-ns-restrictions:
    image: happydomain/checker-ns-restrictions
    restart: unless-stopped

  checker-resolver-propagation:
    image: happydomain/checker-resolver-propagation
    restart: unless-stopped

  checker-reverse-zone:
    image: happydomain/checker-reverse-zone
    restart: unless-stopped

  checker-ptr:
    image: happydomain/checker-ptr
    restart: unless-stopped

  checker-dangling:
    image: happydomain/checker-dangling
    restart: unless-stopped

  # ── Security / Certificate checkers ───────────────────────────────────────

  checker-tls:
    image: happydomain/checker-tls
    restart: unless-stopped

  checker-dane:
    image: happydomain/checker-dane
    restart: unless-stopped

  checker-caa:
    image: happydomain/checker-caa
    restart: unless-stopped

  checker-blacklist:
    image: happydomain/checker-blacklist
    restart: unless-stopped

  # ── E-mail checkers ────────────────────────────────────────────────────────

  checker-smtp:
    image: happydomain/checker-smtp
    restart: unless-stopped

  checker-email-autoconfig:
    image: happydomain/checker-email-autoconfig
    restart: unless-stopped

  checker-email-keys:
    image: happydomain/checker-email-keys
    restart: unless-stopped

  # ── Web & Protocol checkers ────────────────────────────────────────────────

  checker-http:
    image: happydomain/checker-http
    restart: unless-stopped

  checker-ssh:
    image: happydomain/checker-ssh
    restart: unless-stopped

  checker-ping:
    image: happydomain/checker-ping
    restart: unless-stopped
    cap_add:
      - NET_RAW  # required for ICMP ping

  checker-srv:
    image: happydomain/checker-srv
    restart: unless-stopped

  # ── Collaboration / Messaging checkers ─────────────────────────────────────

  checker-matrix:
    image: happydomain/checker-matrix
    restart: unless-stopped

  matrixfederationtester:
    image: matrixdotorg/federation-tester-backend
    environment:
      BIND_ADDRESS: "0.0.0.0:8080"
    restart: unless-stopped

  checker-xmpp:
    image: happydomain/checker-xmpp
    restart: unless-stopped

  checker-sip:
    image: happydomain/checker-sip
    restart: unless-stopped

  # ── Directory & Auth checkers ──────────────────────────────────────────────

  checker-ldap:
    image: happydomain/checker-ldap
    restart: unless-stopped

  checker-kerberos:
    image: happydomain/checker-kerberos
    restart: unless-stopped

  checker-stun-turn:
    image: happydomain/checker-stun-turn
    restart: unless-stopped

  # ── CalDAV / CardDAV checkers ──────────────────────────────────────────────

  checker-caldav:
    image: happydomain/checker-caldav
    restart: unless-stopped

  checker-carddav:
    image: happydomain/checker-carddav
    restart: unless-stopped

volumes:
  storage:

How it works

Each checker runs as a standalone HTTP service. happyDomain delegates check requests to the matching container via the HAPPYDOMAIN_CHECKER_<ID>_ENDPOINT environment variable. When an endpoint is not set, the corresponding checker runs locally inside the happyDomain process instead.

Two checkers rely on additional third-party backends:

• Zonemaster (checker-zonemaster) queries the zonemaster/backend service. The HAPPYDOMAIN_CHECKER_ZONEMASTER_ZONEMASTERAPIURL variable tells the checker where that backend listens.
• Matrix federation tester (checker-matrix) queries the matrixdotorg/federation-tester-backend service. The HAPPYDOMAIN_CHECKER_MATRIXIM_FEDERATIONTESTERSERVER variable points to its report endpoint.

Optional: happyDeliver

If you run a happyDeliver instance for mail-flow monitoring, uncomment the HAPPYDOMAIN_CHECKER_HAPPYDELIVER_ENDPOINT line and add the corresponding service:

  checker-happydeliver:
    image: happydomain/checker-happydeliver
    restart: unless-stopped

Optional: blacklist API keys

The checker-blacklist service works without API keys (it uses DNS-based blocklists by default), but you can enable additional sources — Google Safe Browsing, VirusTotal, abuse.ch URLhaus — by configuring the matching admin options from the happyDomain administration interface once the stack is running.

Admin interface

happyDomain exposes administration commands through a Unix socket. The container includes the hadmin wrapper:

docker exec my_container hadmin /api/users
docker exec my_container hadmin /api/users/0123456789/send_validation_email -X POST

hadmin is a thin wrapper around curl — start with the URL path, then add any curl options after it.

Using a configuration file

Instead of environment variables, you can place a configuration file either in /data/happydomain.conf (inside the data volume) or bind-mount it to /etc/happydomain.conf:

docker run -v happydomain.conf:/etc/happydomain.conf -p 8081:8081 happydomain/happydomain

Configuration

happyDomain respects the methodology 12 factor and allows to act on the application configuration in several ways.

How do I configure happyDomain?

It is possible to configure happyDomain in three different ways: configuration file, environment, command line. All options are available for each of these mechanisms.

The precedence, when an option is defined by several mechanisms simultaneously, is that an option present in a configuration file will be overwritten by the environment, which will be overwritten by an option passed on the command line

Configuration by file

When the application is launched, the first configuration file from the following list will be used:

• ./happydomain.conf
• $XDG_CONFIG_HOME/happydomain/happydomain.conf
• /etc/happydomain.conf

Only the first existing file is taken into account. It is not possible to have part of its options in /etc/happydomain.conf and part in ./happydomain.conf, only the latter configuration file will be taken into account.

It is possible to specify a custom path by adding it as an additional parameter to the command line. Thus, to use the configuration file located at /etc/happydomain/config, we would use :

./happydomain /etc/happydomain/config

Configuration file format

Comments line has to begin with #, it is not possible to have comments at the end of a line, by appending # followed by a comment.

Place on each line the name of the config option and the expected value, separated by =. For example:

storage-engine=leveldb
leveldb-path=/var/lib/happydomain/db/

Configuration by the environment

When happyDomain is started, all variables beginning with HAPPYDOMAIN_ are scanned for valid configuration options.

You can do the same thing as in the previous example, with the following environment variables:

HAPPYDOMAIN_STORAGE_ENGINE=leveldb
HAPPYDOMAIN_LEVELDB_PATH=/var/lib/happydomain/db/

You just have to replace dash by underscore.

Command line configuration

Finally, the command line can be used to pass options, according to the usual UNIX format.

To continue the previous example, we can perform the same configuration with the following command line:

./happydomain -storage-engine leveldb -leveldb-path /var/lib/happydomain/db/

or by using the = sign to clearly assign the value.

./happydomain -storage-engine=leveldb -leveldb-path=/var/lib/happydomain/db/

Configuration items

The complete list of configurable items can be listed by calling happyDomain with the -h or --help option.

Here is a list of the main options:

General parameters

bind

Bind port/socket to use to expose happyDomain.

admin-bind

Bind port/socket to use to expose the administration API.

default-ns

Address and port of the name resolver server to be used by default when name resolution is required.

dev

URL to which all requests related to the graphical interface will be returned.

externalurl

URL of the service, as it should appear in emails and content to the public.

disable-providers-edit

Disallow all actions on provider (add/edit/delete), eg. for demo mode.

Page layout

custom-head-html

String to be placed before the end of the HTML header.

custom-body-html

String to be placed before the end of the HTML body.

hide-feedback-button

Hide the icon on page that permit to give feedback.

msg-header-text

Custom message banner to add at the top of the app.

msg-header-color

Background color class of the banner added at the top of the app (default “danger”, can be primary, secondary, info, success, warning, danger, light, dark, or any bootstrap color class).

Data storage

storage-engine

Allows you to choose the data storage mechanism among all supported mechanisms.

LevelDB (storage-engine=leveldb)

leveldb-path

Path to the folder containing the LevelDB database to use.

E-Mail parameters

We use go-mail as a library to send mails.

mail-from

Defines the name and address of the sender of emails sent by the service.

Note that without the mail-smtp-* options, happyDomain will use the sendmail binary to send mail. This can be coupled with the msmtp or ssmtp packages, for example, to set the parameters for the whole system.

mail-smtp-host

IP or host name of the SMTP server to use.

mail-smtp-port

Port to use on the remote server.

mail-smtp-username

When authentication is required on the remote server, username to use.

mail-smtp-password

When authentication is required on the remote server, password to use.

Authentication

no-auth

Disables the notion of users and access control. A default account is used.

disable-embedded-login

Disables the internal user/password login in favor of external-auth or OIDC.

disable-registration

Forbids new account creation through public form/API (still allow registration from external services).

external-auth

URL base of the authentication and registration service to be used instead of the embedded login system.

jwt-secret-key

Secret key used to verify JWT tokens.

See also OpenID Connect settings.

Specific to registrars

Some registrars require third-party applications to identify themselves in addition to the user.

Bind

with-bind-provider

Enable the BIND provider (not suitable for cloud/shared instance as it’ll access the local file system).

OVH

Please refer to this documentation to generate the identifiers.

ovh-application-key

Application key for OVH API.

ovh-application-secret

Secret key for OVH API.

OpenID Connect

happyDomain supports user authentication via the OpenID Connect protocol. If you have an authentication provider (Auth0, Okta, …) or Identity Provider (IdP) software such as Keycloak, Authentik, Authelia, … you can use it with happyDomain, and possibly dispense with the embedded registration and authentication system.

Configuration

To enable OpenID Connect, you’ll need to set the following options:

HAPPYDOMAIN_OIDC_PROVIDER_URL=https://auth.example.com/
HAPPYDOMAIN_OIDC_CLIENT_ID=youClientId
HAPPYDOMAIN_OIDC_CLIENT_SECRET=0a1b2c3d4e6f7A8B9C0D

The PROVIDER_URL setting should be defined to the base URL of your authentication service. The service should expose a settings discovery endpoint (at /.well-known/openid-configuration).

OpenID Connect provider settings

You’ll need to setup a new application in your authentication provider, with the following settings:

• Provider type: OIDC ou OAuth2
• Grant type: Authorization Code
• Application type: Web ou PWA
• Client type: private
• Scopes: openid, profile, email

Also define the allowed callback URL to:

• https://yourHappyDomain.example.com/auth/callback

Connect to a remote BIND server

BIND is an authoritative and recursive DNS server developed by the Internet Systems Consortium.

It is possible to use it with happyDomain through Dynamic DNS (RFC 2136).

This documentation will guide you through configuring BIND to enable Dynamic DNS and connect your domains to happyDomain.

Configure BIND to enable Dynamic DNS

First, you need to edit the main BIND configuration file (usually /etc/named.conf or /etc/bind/named.conf depending on your distribution) to add a secret that will be shared between happyDomain and BIND to authenticate the changes. Then you must indicate which domains will be managed by happyDomain.

Adding a Shared Secret

Under the main key section of your configuration, add the following key:

key "happydomain" {
    algorithm hmac-sha512;
    secret "<SOME_SECRET>";
};

Replace <SOME_SECRET> with a string obtained using openssl rand -base64 48.

Creating an Authorization Rule for happyDomain

In addition to the key, you must specify how the key can be used by defining an ACL and allowing updates from it.

Add the following ACL to your configuration:

acl "happydomain_acl" {
    key happydomain;
};

Allowing Updates for Each Zone

Now that you have created a rule allowing the happydomain key to make changes, you need to indicate to which zones this rule applies.

For each zone, you must add an update-policy statement referencing the happydomain_acl ACL:

For example, for an existing happydomain.org zone, add the update-policy statement as follows:

zone "happydomain.org" {
    type master;
    file "/var/named/happydomain.org.db";
    update-policy {
        grant happydomain_acl name happydomain.org. ANY;
    };
};

The update-policy statement is a list, so you may already have other policies in this list. In this case, just add the grant statement for happydomain_acl.

Allowing Updates for All Zones

If you manage many zones, it may be more convenient to set the default authorization for all zones. In this case, you can use a global update-policy in the options section:

options {
    update-policy {
        grant happydomain_acl zonesub ANY;
    };
};

This will apply the update-policy to all zones, allowing the happydomain_acl to update any record.

Apply the Configuration

After modifying the configuration file, reload the BIND service to apply the changes:

rndc reload

Link happyDomain and BIND

Once BIND is well configured, you can link it to happyDomain using the Dynamic DNS connector :

Follow these steps:

1. Navigate to the Dynamic DNS connector on the host selection page in happyDomain.
2. Fill in the form with the address where your BIND server is accessible.
3. Fill in the Key fields with the information from the key section in the BIND configuration:
   • Key Name: corresponds to the key name in BIND’s configuration (e.g., happydomain).
   • Key Algorithm: corresponds to the algorithm (e.g., hmac-sha512).
   • Secret Key: corresponds to the secret.

Once the provider is added, it does not allow you to list existing domains, but you can still manually add all your domains.

By following these steps, you will have configured BIND to work with happyDomain using Dynamic DNS, ensuring secure and authenticated DNS updates.

Connect to a local knot

Knot is an authoritative DNS server developed by the cz.nic association.

It is possible to use it with happyDomain through Dynamic DNS (RFC 2136).

Configure Knot to enable Dynamic DNS

First, you have to edit the main knot configuration file (usually /etc/knot/knot.conf) to add a secret that will be shared between happyDomain and knot to authenticate the changes. Then you have to indicate which domains will be managed by happyDomain.

Adding a shared secret

Under the main key section of your configuration, add the following key:

key:
  [...]
  - id: happydomain
    algorithm: hmac-sha512
    secret: "<SOME_SECRET>"

Obviously replace <SOME_SECRET> with a string as obtained with openssl rand -base64 48.

Creating an authorization rule for happyDomain

In addition to the key, you must specify in the configuration how the key can be used.

To do this, under the main acl section, we add:

acl:
  [...]
  - id: acl_happydomain
    key: happydomain
    action: transfer
    action: update

This associates the key defined just before with the actions transfer and update, respectively to allow retrieving the zone and to update records.

Associate the authorization to each zone

Now that you have created a rule allowing the happydomain key to make changes, you need to indicate to which zones this rule applies.

For each zone, you must add an acl element referencing the acl_happydomain rule:

For example, for an existing happydomain.org zone, we will add the acl line as follows:

zone:
  [...]
  - domain: happydomain.org
    acl:
      - acl_happydomain
    [...]

The acl element is a list, so you may already have other acl elements in this list. In this case you just need to add the acl_happydomain element to the already existing list.

You have to add this acl element for each zone, unless you use the following trick.

Associate the authorization to all zones

If you manage many zones, it may be more convenient to set the default authorization for all zones. In this case, instead of the previous section, we will modify the default template:

template:
  - id: default
    acl:
      - acl_happydomain
  [...]

The default template is applied to all zones by default. By doing so, all zones will inherit the acl_happydomain rule.

Apply the configuration

Now that the configuration file has been modified, tell knotd to reload its configuration:

knotc reload

Link happyDomain and knot

Once knot well configured, you can link it to happyDomain using the Dynamic DNS connector :

Then fill in the form with the address where your knot server is accessible, then fill in the different Key fields with the information from the knot’s key section:

• Key Name : corresponds to id in knot’s configuration ;
• Key Algorithm : corresponds to algorithm ;
• Secret Key : corresponds to secret.

Once the provider is added, it does not allow you to list existing domains, but you can still manually add all your domains.

OVH API configuration

In order to manage domains hosted by OVH, an additional configuration step is required.

Authentication to the OVH API works in 2 stages:

1. First, you need to register an application (e.g. happyDomain). An application has an identifier and a secret that must be entered as a happyDomain parameter.
2. For each OVH account you wish to manage, the happyDomain interface redirects you to the OVH page for creating the Consumer key.

The application must be created from an existing OVH account, regardless of whether it has domains or not; it is a matter of identifying the person responsible for implementing the designated application. Access to account data, and in particular to the domains they manage, is via the Consumer key.

For more information, see this page: https://docs.ovh.com/gb/en/api/api-rights-delegation/#application-registration

Register your happyDomain instance with OVH

1. Go to https://api.ovh.com/createApp/.
2. Fill in the form with a name and description that reflects the name and use of your application, e.g. happyDomain.

Once the form has been validated, you’ll get a key and a secret. This information must be specified in the happyDomain configuration:

ovh-application-key

Application key pour l’API d’OVH

ovh-application-secret

Clef secrète pour l’API d’OVH

SOA (Start Of Authority)

The Start Of Authority (SOA) record is defined by RFC 1035. It is mandatory and unique: exactly one SOA must sit at the apex (the root) of every DNS zone. Its presence declares that the name server is authoritative for the zone and carries the parameters that govern how the zone is replicated between servers and cached by resolvers.

Fields of the SOA record

The SOA record gathers seven values:

The SOA in happyDomain

happyDomain does not present the SOA as a standalone record to edit field by field. Instead, the apex of your zone is modelled as an Origin service, which groups the SOA together with the zone’s name servers (NS records). You will therefore find the SOA at the root of your domain, alongside the list of authoritative name servers, rather than in a separate form.

The serial is, in most cases, handled automatically. When you publish your changes, many DNS providers manage the serial themselves: happyDomain detects this capability and re-reads the zone after publication to reflect the serial the provider actually assigned. You normally do not need (nor are you expected) to set it by hand.

For more on how the apex and other groupings are represented, see the /en/reference/services/ chapter.

TXT

A TXT record (defined in RFC 1035) attaches one or more free-form text strings to a name in your zone. It carries no predefined meaning of its own, which makes it one of the most versatile record types: any application is free to define its own convention for the text it stores there.

Common uses

Because a TXT record can hold arbitrary text, it has become the carrier for many widespread conventions:

• Domain ownership and site verification — a provider asks you to publish a token so it can confirm you control the domain.
• SPF — declares which servers are allowed to send e-mail for your domain.
• DKIM — publishes the public key used to sign your outgoing e-mail.
• DMARC — sets the policy applied when SPF or DKIM checks fail.
• Various other key or policy publications defined by different tools.

For most of these purposes, happyDomain offers dedicated, higher-level services (SPF, DKIM, DMARC, site verification, and more) that are easier and safer to use than a raw TXT record: they guide you with the right fields and validate the syntax for you. Browse them in the /en/reference/services/ chapter, in particular the e-mail-related services. Prefer those services whenever one matches your need.

Editing a TXT record in happyDomain

In the zone editor, a plain TXT record appears as a Text Record service. It is intentionally minimal: a single field holds the text content of the record.

To work with one:

1. Open the subdomain where the record should live (the apex of the zone, or any subdomain such as www).
2. Add or open the Text Record service.
3. Type the full text string in its only field.
4. Adjust the TTL if needed, then publish your changes to apply them.

The value you enter is stored verbatim. Editing it and publishing updates the corresponding TXT record on that subdomain.

E-Mail

The E-Mail service lets you declare the mail servers responsible for a zone, and points you to the companion services that control how mail is sent and authenticated for that domain.

In happyDomain, this service is named E-Mail servers: its single job is to publish the MX records that tell the rest of the Internet where to deliver mail addressed to your domain. Everything that protects outgoing mail (proving that a message really comes from you) is handled by separate, dedicated services described further down.

Receiving mail: MX records

An MX (Mail eXchanger) record names a host that accepts mail for the domain. A zone usually publishes several of them so that delivery keeps working if one server is unavailable.

Each entry has two parts:

• Priority — a number that orders the servers. Sending servers try the lowest number first; higher numbers are used only as fallbacks. Two records sharing the same priority are treated as equivalent and load-balanced.
• Mail server — the hostname of the machine that receives the mail (for example mx1.example.com.). This host must itself resolve to an address; it should not be a bare IP.

A common setup looks like this:

Here mx1 is tried first, and mx2 is the backup.

Sending mail: authentication and anti-spoofing

Publishing MX records is enough to receive mail, but it says nothing about which servers are allowed to send mail on your behalf. Without that, anyone can forge messages using your domain. happyDomain offers several dedicated services, each managing its own DNS records, to establish that posture:

• SPF (Sender Policy Framework) — a TXT record, usually at the zone apex, that lists the servers authorized to send mail for the domain. Receivers compare the sending server against this list.
• DKIM (DomainKeys Identified Mail) — publishes the public half of a signing key as a TXT record under a ._domainkey selector. Your mail servers sign outgoing messages, and receivers verify the signature against this published key.
• DMARC (Domain-based Message Authentication, Reporting and Conformance) — a TXT record at _dmarc that tells receivers what to do with messages failing SPF or DKIM checks (let them through, quarantine, or reject), and where to send aggregate reports.

Two further services cover transport security and reporting:

• MTA-STS — declares that mail to your domain must be delivered over a secured (TLS) connection.
• TLS-RPT — collects reports about TLS delivery problems encountered by sending servers.

These services are independent of the E-Mail servers service. You can add only the ones you need, but a complete and well-protected mail configuration typically combines MX, SPF, DKIM and DMARC.

In the zone editor

To configure mail for a subdomain in the happyDomain zone editor:

1. Add the E-Mail servers service to the subdomain and fill in one line per mail server, with its priority and hostname.
2. Add SPF, DKIM and DMARC as their own services on the relevant subdomain (SPF and DMARC usually at the apex). Each one presents a dedicated form rather than raw record text.

Because each of these is a distinct abstract service, you manage them separately even though they all work together to make mail for your domain both deliverable and trustworthy. See the /en/reference/services/ chapter for the full list of available services.

Domain expiry

The Domain expiry checker watches the registration expiry date of a domain name and warns you before it lapses. Letting a domain expire can mean losing it to another registrant, so this is one of the most important domain-level checks.

This is a domain-level checker: it concerns the domain registration itself, not its DNS records. The expiry date is obtained from the registry through a WHOIS/RDAP lookup, together with the registrar name.

What it checks

A single rule, domain_expiry_check, compares the number of days remaining until expiry against two thresholds and reports the corresponding status.

The message always reports how many days remain until expiry, regardless of status.

The checker also exposes a metric, domain_expiry_days_remaining, labelled with the registrar, so the time left can be tracked over time.

Options

In happyDomain

Enable this checker from the domain’s Checks view; see /en/pages/checks/ for how to configure and schedule checks. The domain name is filled in automatically.

For the inverse situation, watching a domain you do not yet own so you can register it once it lapses, see the /en/reference/checkers/domain-availability/ checker and /en/pages/domain-availability/. Related domain-level checkers include /en/reference/checkers/domain-lock/ and /en/reference/checkers/domain-contact/.

Domain transfer lock

The Domain transfer lock checker verifies that a domain carries the EPP status codes that protect it against unauthorized transfers, updates or deletions. A locked domain (for example one bearing clientTransferProhibited) cannot be transferred away without first removing the lock, which is a key defence against domain hijacking.

This is a domain-level checker: the status codes are read from the registry through a WHOIS/RDAP lookup, not from the zone’s DNS records.

What it checks

A single rule, domain_lock_check, compares the EPP status codes reported by the registry against the list of statuses you require.

Comparison is tolerant of formatting: spaces, dashes and underscores are ignored and case does not matter, so clientTransferProhibited, client-transfer-prohibited and client transfer prohibited are all treated as equal.

Options

In happyDomain

Enable this checker from the domain’s Checks view; see /en/pages/checks/ for how to configure and schedule checks. The domain name is filled in automatically.

This checker pairs naturally with /en/reference/checkers/domain-expiry/ and /en/reference/checkers/domain-contact/ to keep the registration of a domain under control.

Domain contacts

The Domain contacts checker compares the contact information registered for a domain (registrant, administrative and technical contacts) against the values you expect. An unexpected change to a contact, especially the registrant, can be an early sign of a hijack or of an administrative mistake.

This is a domain-level checker: the contact data is read from the registry through a WHOIS/RDAP lookup. Many registries redact contact fields for privacy; this checker detects redaction and reports it rather than treating it as a mismatch.

What it checks

A single rule, domain_contact_check, evaluates each contact role you selected and emits one result per role.

Comparisons are case-insensitive and exact. Redaction is detected from common markers in the contact fields such as redacted, privacy, withheld, not disclosed, data protected, contact privacy and whoisguard.

Options

In happyDomain

Enable this checker from the domain’s Checks view; see /en/pages/checks/ for how to configure and schedule checks. The domain name is filled in automatically.

This checker complements /en/reference/checkers/domain-expiry/ and /en/reference/checkers/domain-lock/, which together keep the registration of a domain under watch.

Domain availability

The Domain availability checker watches a domain name you do not own and notifies you the moment it becomes available for registration. It is the counterpart of /en/reference/checkers/domain-expiry/: instead of protecting a domain you hold, it lets you grab one as soon as it lapses.

This is a domain-level checker: registration status is determined from the registry through a WHOIS/RDAP lookup. A domain is considered available when the registry reports that it does not exist.

What it checks

A single rule, domain_availability_check, reports whether the watched domain is still registered or has become free.

Options

This checker has no user-tunable options. The watched domain name is supplied automatically.

In happyDomain

Unlike the other domain-level checkers, Domain availability is not scheduled on the domains you manage. It is driven by the dedicated availability-watch list. See /en/pages/domain-availability/ for how to add a domain to watch, and /en/pages/checks/ for the general checks workflow.

External-reference expiry

The External-reference expiry checker looks up the registration facts of the external domains your zone refers to. When a record points at a name you do not own (a CNAME to a third-party service, an MX to an external provider, an NS delegation…), the safety of your zone depends on that external domain staying registered. If it expires and is re-registered by someone else, the pointer can be hijacked.

This is a zone-level checker: it enumerates the external targets discovered in the zone and performs one WHOIS/RDAP lookup per distinct registrable domain. Targets sharing the same registrable domain reuse a single lookup, and lookups run with a bounded concurrency so a large zone does not overwhelm the registry.

What it checks

This checker is primarily a collector. It gathers per-target WHOIS facts (registrable name, expiry date, creation date, registrar, status) and publishes them for the dangling-reference checker, which is where the actionable verdicts about expiration, redemption or recent re-registration are emitted.

Its own rule, external_whois_collected, reports only how the collection went:

Options

This checker has no user-tunable options. The list of external targets is supplied automatically from the zone’s discovered references.

In happyDomain

Enable this checker from the zone’s Checks view; see /en/pages/checks/ for how to configure and schedule checks. The discovery of external targets is automatic.

For the registration of the domains you own directly, see /en/reference/checkers/domain-expiry/.

DNSSEC validation

The DNSSEC checker audits the operational hygiene of a signed zone. It does not re-validate the cryptographic chain of trust end to end (that work is delegated to a dedicated DNSViz-based checker); instead it focuses on the policy and day-to-day operational aspects of signing: which algorithms and key sizes are in use, whether signatures are fresh and valid, how negative answers are denied (NSEC vs NSEC3), and whether every authoritative server serves a consistent view.

This checker is domain-level: it operates on the zone apex. From a bootstrap recursive resolver it discovers the apex name servers and looks up the parent DS, then queries each authoritative server directly.

What it checks

The checker evaluates the following rules. Several of them are governed by the options described further down.

Chain and key material

Algorithms and key strength

Signatures

Denial of existence (NSEC / NSEC3)

TTL hygiene

Options

The administrator can also set a bootstrap resolver (host:port) used to discover the apex name servers and look up the parent DS; it defaults to /etc/resolv.conf.

In happyDomain

Enable the DNSSEC checker on a domain from its Checks view. See /en/pages/checks/ for the full workflow of adding, scheduling and reading checks. For delegation-side DS/DNSKEY hand-off, see the /en/reference/checkers/delegation/ checker.

Delegation

The Delegation checker audits how a zone is delegated from its parent. It cross-examines the parent zone and the child name servers to confirm that the hand-off is coherent: that the parent and child agree on the NS set, that glue records are correct, that the DNSSEC DS/DNSKEY chain lines up, and that every delegated server is reachable and actually authoritative for the zone.

This checker is service-level: it targets a Delegation service (abstract.Delegation) published on a subdomain, and is configured from that service’s own Checks tab.

What it checks

Each rule emits a stable finding code so results can be matched deterministically.

Name-server count and parent discovery

NS and glue at the parent

DNSSEC hand-off

Child reachability and authoritativeness

Options

In happyDomain

Enable the Delegation checker from the Checks tab of a Delegation service. See /en/pages/checks/ for the full workflow. For consistency between the authoritative servers of the apex itself (rather than the parent/child hand-off), see /en/reference/checkers/authoritative-consistency/; for the DNSSEC hygiene of the signed zone, see /en/reference/checkers/dnssec/.

Authoritative consistency

The Authoritative consistency checker probes every authoritative name server of a zone and verifies that they agree — with one another and with the parent delegation. Where the /en/reference/checkers/delegation/ checker focuses on the parent/child hand-off, this checker concentrates on the apex itself: do all the servers serve the same NS and SOA, are they all reachable over UDP and TCP, do they support EDNS0, do they answer authoritatively, and how fast do they respond?

This checker is service-level: it targets an Origin or NS-only Origin service (abstract.Origin, abstract.NSOnlyOrigin) and is configured from that service’s Checks tab.

What it checks

Each rule emits a finding code. Several severities depend on the options below.

Options

In happyDomain

Enable the Authoritative consistency checker from the Checks tab of an Origin service. See /en/pages/checks/ for the full workflow. To compare what recursive resolvers around the world see against the authoritative answer, pair it with /en/reference/checkers/resolver-propagation/.

Name-server restrictions

The Name-server restrictions checker verifies that the authoritative name servers of a zone are properly locked down. For each declared name server it resolves the host name, then runs a set of DNS probes against every returned IPv4 and IPv6 address (IPv6 targets are skipped gracefully when the host has no IPv6 connectivity). The goal is to catch common misconfigurations that leak data or turn a name server into an abuse vector: open zone transfers, open recursion, and unbounded ANY responses.

This checker is service-level: it targets an Origin or NS-only Origin service (abstract.Origin, abstract.NSOnlyOrigin) and is configured from that service’s Checks tab.

What it checks

Each rule emits one finding per probed name-server address, with a stable code.

Options

This checker has no user-tunable options: it runs a fixed set of probes against each resolved name-server address.

In happyDomain

Enable the Name-server restrictions checker from the Checks tab of an Origin service. See /en/pages/checks/ for the full workflow. For the broader health and agreement of those same authoritative servers, see /en/reference/checkers/authoritative-consistency/.

Resolver propagation

The Resolver propagation checker measures how a zone is seen from the outside, across the public internet. It probes a curated catalog of public recursive resolvers (Cloudflare, Google, Quad9, OpenDNS, Yandex, regional ISPs and more) over several transports (UDP, TCP, DoT, DoH) and from multiple regions, then compares their answers both to each other and to the zone’s authoritative name servers. This surfaces propagation gaps, regional splits, SOA serial drift, stale caches, DNSSEC validation failures, SERVFAIL/NXDOMAIN inconsistencies and resolver filtering.

This checker is service-level: it targets an Origin or NS-only Origin service (abstract.Origin, abstract.NSOnlyOrigin) and is configured from that service’s Checks tab.

What it checks

Options

In happyDomain

Enable the Resolver propagation checker from the Checks tab of an Origin service. See /en/pages/checks/ for the full workflow. This checker is the outward-facing counterpart to /en/reference/checkers/authoritative-consistency/, which examines the authoritative servers directly; running both gives you the picture from the origin and from the resolvers that query it.

Reverse zone

The Reverse zone checker inspects the PTR records of a reverse DNS zone (in-addr.arpa or ip6.arpa) and validates that they are well formed and consistent with forward DNS. It verifies Forward-Confirmed Reverse DNS (FCrDNS), that targets resolve and are syntactically valid host names, flags generic or auto-generated names and short TTLs, and catches multiple-PTR-per-IP violations (RFC 1912 §2.1). Correct reverse DNS matters in practice: mail servers and SSH endpoints routinely reject or downgrade connections from IPs without proper FCrDNS.

This checker is zone-level: it operates on the full content of a reverse zone (it applies to the domain and reads the whole zone).

What it checks

Options

In happyDomain

Enable the Reverse zone checker on a reverse (in-addr.arpa / ip6.arpa) domain from its Checks view. See /en/pages/checks/ for the full workflow.

PTR records

The PTR / Reverse DNS checker verifies that an IP address has a correct, usable reverse-DNS record. A PTR maps an IP back to a hostname; mail servers, SSH daemons and many logging tools rely on it, and a missing or inconsistent PTR is one of the most common reasons outgoing mail is rejected.

This is a service-level checker: it runs on a PTR service and is configured from that service’s own Checks tab. It locates the reverse zone (under in-addr.arpa or ip6.arpa), queries the authoritative servers, and inspects what they actually serve — both for IPv4 and IPv6 addresses.

What it checks

The checker runs a chain of rules, from structural sanity through query success to target hygiene and Forward-Confirmed Reverse DNS (FCrDNS).

The ptr.target_resolves and ptr.fcrdns_match rules are critical by default but drop to a warning when Require forward-confirmed reverse DNS is turned off.

Options

In happyDomain

Add the PTR service to the subdomain holding the reverse record, then enable this checker from that service’s Checks tab. See /en/pages/checks/ for configuring and scheduling checks. The reverse zone, the PTR record and the declared target are filled in automatically from the service.

For the forward side of alias and hostname resolution, see the related /en/reference/checkers/alias/ checker.

Alias chain

The CNAME / DNAME / ALIAS chain checker follows the alias chain of a name and verifies that it resolves cleanly: no loops, not too many hops, sane TTLs, a resolvable final target, no forbidden record coexistence, and a properly signed CNAME RRset when the zone uses DNSSEC.

This is a service-level checker: it runs on a CNAME (or special CNAME) service and is configured from that service’s own Checks tab. Starting from the queried name it locates the zone apex, walks each CNAME/DNAME hop, and finally resolves the chain’s target to A/AAAA records.

What it checks

Each rule emits a finding code. Some severities are softened by the options below.

Options

In happyDomain

Add the CNAME service to the subdomain, then enable this checker from that service’s Checks tab. See /en/pages/checks/ for configuring and scheduling checks. The parent domain and subdomain are filled in automatically.

Related checkers: /en/reference/checkers/dangling/ watches for alias targets that have become unregistered or NXDOMAIN, and /en/reference/checkers/ptr/ covers the reverse-DNS side.

Dangling records

The Dangling subdomains checker scans a zone for pointer records (CNAME, MX, SRV, NS) whose targets have gone stale: they resolve to NXDOMAIN, or their external registrable domain has expired, is in pendingDelete, or was recently re-registered. This is the subdomain-takeover attack class popularised in 2017, where institutions ended up serving hostile content from CNAMEs pointing at decommissioned third-party services after attackers re-registered the lapsed targets.

This is a zone-level checker: it needs the full zone content and runs a single pass over it, consolidating findings by owner rather than producing one result per record.

What it checks

The checker walks every service in the working zone and extracts pointer records from CNAME, special CNAME, MX, unknown SRV and orphan (bare NS/CNAME/MX) bodies. For each (owner, type, target) triple it classifies the target as in-zone or external (relative to the zone’s registrable domain), performs a single time-bounded DNS resolution to detect immediate breakage, and publishes a discovery entry so a companion domain_expiry checker can run RDAP/WHOIS on external targets.

It emits one finding per impacted owner, ranked by descending severity:

Options

In happyDomain

Enable this checker on the domain from the /en/pages/checks/ view; the domain name and zone content are filled in automatically. Because it is zone-scoped, it runs over the whole zone in a single pass.

Related checkers: /en/reference/checkers/alias/ validates the structure of individual alias chains, and /en/reference/checkers/domain-expiry/ watches your own domains’ expiry — the same WHOIS machinery that powers this checker’s external-target signals.

CAA

The CAA Compliance checker verifies that the TLS certificates actually deployed on a domain were issued by a Certification Authority that the domain’s CAA records authorize. A CAA (Certification Authority Authorization) record lets a domain declare which CAs may issue certificates for it; this checker confirms reality matches that policy.

This is a service-level checker: it runs on a CAA policy service. It performs no network probes of its own — it reads the parsed CAA policy from the service body and the TLS certificates observed by the /en/reference/checkers/dane/ / checker-tls family, then maps each observed issuer to its CAA identifier domain using the Common CA Database (CCADB).

What it checks

A single rule, caa_compliance, loads the zone’s CAA issue / issuewild policy, gathers every TLS probe observed on the target, resolves each certificate’s issuer (by Authority Key Identifier, falling back to the issuer Distinguished Name) against the embedded CCADB “CAA Identifiers” mapping, and compares the result against the allow list.

The issuer-to-CAA-domain mapping comes from an embedded snapshot of CCADB’s “CAA Identifiers (V2)” report. Refreshing it only requires re-embedding a newer CSV and recompiling — no code change and no network dependency at build time.

Options

This checker has no user-tunable options. Both inputs are filled in automatically:

In happyDomain

Add the CAA policy service to the relevant subdomain (usually the apex), then enable this checker from that service’s Checks tab. See /en/pages/checks/ for configuring and scheduling checks. For the comparison to produce a verdict, a TLS-probing checker such as /en/reference/checkers/dane/ (or the standalone checker-tls) must have observed certificates on the target.

DANE / TLSA

The DANE / TLSA checker verifies that the TLSA records published for a service correctly pin the TLS certificate that the matching endpoint actually presents. DANE (DNS-based Authentication of Named Entities) lets a domain bind a certificate or public key to a name through DNS, secured by DNSSEC; this checker confirms the binding holds.

This is a service-level checker: it runs on a TLSAs service. It groups the declared TLSA records by (port, proto, base), publishes one TLS endpoint discovery entry per endpoint so checker-tls probes it, then matches each TLSA against the observed certificate chain following RFC 6698.

What it checks

How the TLSA fields are interpreted

• Usage 0 (PKIX-TA) / 1 (PKIX-EE) — the TLSA must match and the chain must validate against the public PKIX trust roots.
• Usage 2 (DANE-TA) / 3 (DANE-EE) — the TLSA itself acts as the trust anchor; PKIX validity is informational.
• Selector 0 (full certificate) or 1 (Subject Public Key Info), and matching type 0 (full) / 1 (SHA-256) / 2 (SHA-512), are matched against the chain slot implied by the usage.

Options

The domain, subdomain and TLSAs service are filled in automatically.

In happyDomain

Add the TLSA service to the subdomain, then enable this checker from that service’s Checks tab. See /en/pages/checks/ for configuring and scheduling checks. The checker publishes its endpoints for checker-tls to probe, so allow a probe cycle before the first match result appears.

Related checker: /en/reference/checkers/caa/ verifies, on the same certificates, that the issuing CA was authorized by the domain’s CAA policy.

TLS posture

The TLS checker (internal name TLS) evaluates the transport-security posture of every TLS endpoint exposed by a domain. It does not scan ports on its own: it consumes discovery entries of type tls.endpoint.v1 published by other service checkers (XMPP, SRV, CalDAV, CardDAV, SMTP…). For each discovered endpoint it performs a real TCP dial, an optional protocol-specific STARTTLS upgrade, and a full TLS handshake, then reports a per-endpoint posture.

Scope: domain-level. The checker runs against the whole domain and folds in the endpoints that every other service checker has advertised. A given endpoint is therefore only probed if some service checker (for example /en/reference/checkers/smtp/) published it.

What it checks

STARTTLS upgrades are supported for SMTP/submission, IMAP, POP3, and XMPP (c2s and s2s). When a service checker marks an endpoint as requiring STARTTLS, the absence of the upgrade is reported as Critical; otherwise it is treated as opportunistic and reported as Warning.

Options

The list of discovery entries is filled automatically from what other checkers publish and is not user-editable.

In happyDomain

The TLS checker is a domain-level check: enable it from the domain’s checks view. Because it works on endpoints discovered by other checkers, it pairs naturally with service-level checkers that publish TLS endpoints, such as /en/reference/checkers/smtp/.

For the general workflow of configuring and reading checks, see /en/pages/checks/.

HTTP / HTTPS

The HTTP / HTTPS checker probes the web server declared by a Server service over plain HTTP (port 80) and HTTPS (port 443), then evaluates a battery of independent rules on the responses: reachability, the HTTP→HTTPS redirect chain, and the modern set of HTTP security headers (HSTS, CSP, frame options, cross-origin isolation…) along with cookie hygiene.

Scope: service-level. It attaches to services of type abstract.Server (a subdomain that publishes A/AAAA records) and is configured from that service’s Checks tab.

Deep TLS and certificate analysis is intentionally delegated to the /en/reference/checkers/tls/ checker; this checker relies on TLS only as a transport.

What it checks

Options

In happyDomain

This is a service-level checker: configure it from the Checks tab of the Server service on the relevant subdomain. For deep certificate posture, add the /en/reference/checkers/tls/ checker as well. For the general workflow of configuring and reading checks, see /en/pages/checks/.

Ping

The Ping (ICMP) checker measures basic network reachability for the addresses behind a service. It sends a small number of ICMP echo requests to each A/AAAA address and reports whether the target replied, its average round-trip time (RTT), the observed packet-loss ratio, and whether at least one IPv6 address answered.

Scope: service-level. It attaches to services of type abstract.Server (a subdomain that publishes A/AAAA records) and is configured from that service’s Checks tab.

What it checks

Options

In happyDomain

This is a service-level checker: configure it from the Checks tab of the Server service on the relevant subdomain. Its short default interval makes it well suited to lightweight, frequent reachability monitoring. For the general workflow of configuring and reading checks, see /en/pages/checks/.

SMTP

The Inbound SMTP (MX posture) checker exercises the inbound side of a domain’s mail service. For every MX target of the zone it performs the live probes a human operator would run with swaks or telnet … 25: TCP connect, ESMTP banner and EHLO, STARTTLS negotiation, mail-transaction probes (null sender, postmaster, open-relay), reverse DNS / FCrDNS, extension inventory, and IPv4/IPv6 coverage. The result is an actionable HTML report.

Scope: service-level. It attaches to services of type svcs.MXs (the DNS-level MX record set) and is configured from that service’s Checks tab.

The probe answers “can this domain receive mail correctly?”. It does not test outbound deliverability (SPF/DKIM/DMARC alignment, spam scoring, blacklist status), which is the job of the /en/reference/checkers/happydeliver/ checker. Mail-transaction probes always stop at RCPT and emit RSET: no DATA is sent, so no mail is delivered.

What it checks

Certificate posture itself is out of scope here: each MX target is published as a tls.endpoint.v1 discovery entry (opportunistic STARTTLS), and the /en/reference/checkers/tls/ checker runs certificate analysis on the same connection. Its findings are folded back into the smtp.tls_quality rule and the HTML report.

Options

In happyDomain

This is a service-level checker: configure it from the Checks tab of the E-Mail servers (MX) service. To confirm that mail your domain sends lands in the inbox, pair it with the /en/reference/checkers/happydeliver/ checker. For the general workflow of configuring and reading checks, see /en/pages/checks/.

Outbound deliverability (happyDeliver)

The Outbound deliverability checker (named Outbound deliverability (via happyDeliver) in happyDomain) measures how a message sent from your domain would actually fare on its way to a recipient’s inbox. Rather than inspecting DNS records in isolation, it drives an external happyDeliver instance to perform an end-to-end test.

This checker is service-level: it is attached to a service (typically the mail configuration of a subdomain) and needs SMTP credentials to send the test message on your behalf.

How it works

For each run, the checker:

1. Allocates a fresh recipient address on the configured happyDeliver instance.
2. Sends a real test email from the tested domain to that address, using the SMTP submission server and credentials you provide.
3. Polls happyDeliver until the message has been received and analysed.
4. Stores happyDeliver’s report and exposes one score per section as a metric.

happyDeliver grades the message across several sections (DNS, authentication, spam filters, blacklists, headers, content) and computes an overall score. The checker turns each section into a rule.

What it checks

Each section rule compares happyDeliver’s score for that section against a configurable minimum. The check is Critical when the score falls below the minimum, otherwise OK.

A separate happydeliver.lifecycle rule reports the outcome of the run itself: OK when the message was analysed, Critical when the test address could not be allocated, the message could not be sent, or happyDeliver returned a wait/fetch/parse error, and Warning when the message was not analysed before the timeout elapsed.

Each section minimum can be tuned through its own min_score_<section> rule option in the happyDomain interface.

Options

Sending (per domain)

Message content (per domain)

Timing (per domain)

Instance (admin, overridable per domain)

In happyDomain

Enable this checker from the service’s Checks tab and provide the SMTP submission details so happyDomain can send the test message. See /en/pages/checks/ for the general workflow of scheduling and reading checks.

Because deliverability depends heavily on your anti-spoofing posture, pair this checker with a well-configured /en/reference/services/email/ setup (SPF, DKIM and DMARC). For the DNSSEC half of your domain’s trust chain, see /en/reference/checkers/dnssec/.

Mail autoconfiguration

The Mail Autoconfiguration checker verifies that mail clients can automatically discover how to connect to your mail servers. When autoconfiguration is published correctly, a user only types their email address and password, and their client (Thunderbird, Outlook, mobile mail apps…) finds the right IMAP/POP and SMTP hosts, ports and security settings on its own.

This checker is service-level: it applies to the mail-autoconfiguration and RFC 6186 services of a domain. For each run it probes the discovery mechanisms used by real-world clients:

• Thunderbird autoconfig (Bucksch draft): https://autoconfig.<domain>/mail/config-v1.1.xml as the primary URL, with the https://<domain>/.well-known/autoconfig/... apex fallback, an optional plain-HTTP variant, the Mozilla ISPDB fallback, and MX-parent fallbacks.
• Microsoft Autodiscover (POX): https://autodiscover.<domain>/autodiscover/autodiscover.xml.
• RFC 6186 SRV records: _imaps, _imap, _pop3s, _pop3, _submissions, _submission, _autodiscover.
• MX resolution, for context and MX-based discovery.

It parses every response, cross-checks the servers advertised by the different sources, and produces an HTML report with paste-ready remediation snippets for the most common failure modes.

What it checks

When a check fails, the report’s “Fix this first” section provides ready-to-copy snippets: a sample config-v1.1.xml and its canonical URLs when nothing is published, a nudge to add the autoconfig. subdomain when only .well-known answers, an HTTPS redirect hint, a certificate-coverage hint, a port cheat-sheet for plaintext servers (SSL 993/465, STARTTLS 143/587), and a ready-to-paste SRV zone excerpt.

Options

Per user

Admin

In happyDomain

Enable this checker from the Checks tab of the relevant mail-autoconfiguration service. See /en/pages/checks/ for scheduling and reading checks.

This checker is the natural companion to a full mail setup: see /en/reference/services/email/ for the MX, SPF, DKIM and DMARC services that govern how mail is delivered and authenticated.

Mail keys (DKIM / OpenPGP)

The Mail keys checker (named OPENPGPKEY & SMIMEA in happyDomain) validates the cryptographic keys a domain publishes in DNS so that correspondents can encrypt mail to its users. It covers two DANE-style record types:

• OPENPGPKEY (RFC 7929) — an individual user’s OpenPGP public key, published under an owner-hashed name below ._openpgpkey.<zone>.
• SMIMEA (RFC 8162) — a user’s S/MIME certificate, published under an owner-hashed name below ._smimecert.<zone>.

This checker is service-level: it applies to the OpenPGP and S/MIME services of a subdomain and runs a comprehensive test suite, then renders an HTML report whose top block points to the fix for the most common failure scenarios.

What it checks

DNS and DNSSEC

OpenPGP (OPENPGPKEY)

S/MIME (SMIMEA)

Options

The domain origin, subdomain, service and service type are auto-filled by happyDomain.

In happyDomain

Enable this checker from the Checks tab of the relevant OpenPGP or S/MIME service. See /en/pages/checks/ for the general workflow.

These records share their security model with DNSSEC: to confirm your zone’s signing chain is itself sound, see /en/reference/checkers/dnssec/. For the surrounding mail configuration, see /en/reference/services/email/.

CalDAV / CardDAV

The CalDAV and CardDAV checkers verify that a domain’s calendar (RFC 4791) and contacts (RFC 6352) servers are discoverable, reachable, and correctly advertise the WebDAV extensions that clients rely on. They are two distinct checkers sharing the same logic: caldav attaches to a CalDAV service (abstract.CalDAV), carddav to a CardDAV service (abstract.CardDAV). The only behavioural difference is the required DAV capability (calendar-access vs addressbook) and a CalDAV-only scheduling check.

Both checkers are service-level: they target the corresponding service published on a subdomain and are configured from that service’s own Checks tab. Discovery follows RFC 6764: the checker resolves a context URL from /.well-known/{caldav,carddav} and from _caldavs._tcp / _carddavs._tcp SRV records (with an optional path= TXT hint), then probes that endpoint.

When no credentials are supplied, only the anonymous phase runs (discovery, transport, OPTIONS). Supplying a username and password unlocks the authenticated phase: principal discovery, home-set, collection enumeration and the REPORT probe.

What it checks

The HTML report surfaces the most common misconfigurations as callouts: /.well-known returning 200, no SRV and no well-known (service unreachable), a plaintext SRV record without a secure counterpart, a server not advertising the required DAV class, and the authenticated phase being skipped for lack of credentials.

Options

Both checkers accept the same options.

In happyDomain

Enable the CalDAV or CardDAV checker from the Checks tab of a CalDAV or CardDAV service. The domain name is filled in automatically; add credentials only if you want the authenticated collection and REPORT checks to run. See /en/pages/checks/ for the full workflow, and /en/reference/checkers/tls/ for the certificate posture of the same endpoints.

LDAP

The LDAP checker probes a domain’s LDAP directory deployment from end to end. Starting from SRV discovery (_ldap._tcp, _ldaps._tcp), it tests reachability of every endpoint, confirms an encrypted channel is available (StartTLS per RFC 2830 or implicit TLS on port 636), introspects the RootDSE, looks for anonymous information disclosure, verifies the directory refuses cleartext binds, and — when credentials are supplied — performs an authenticated bind over TLS with an optional read test on a base DN.

This checker is service-level: it targets an LDAP service (abstract.LDAP) published on a subdomain and is configured from that service’s own Checks tab. For each transport it probes _ldap._tcp (falling back to port 389) and _ldaps._tcp (falling back to port 636), testing each resolved A/AAAA address per IP family.

What it checks

The HTML report leads with the most common failures and includes server-specific remediation (OpenLDAP olcSecurity, 389-ds require_tls…): no encrypted endpoint reachable, StartTLS missing on 389, a StartTLS handshake that fails, a cleartext bind accepted on 389, an LDAPS handshake that fails, anonymous search exposing the DIT, PLAIN/LOGIN-only SASL, lingering LDAPv2, and rejected bind credentials.

Options

In happyDomain

Enable the LDAP checker from the Checks tab of an LDAP service. The domain is filled in automatically; supply a bind DN and password only if you want the authenticated bind and base-DN read tests to run. See /en/pages/checks/ for the full workflow, and /en/reference/checkers/tls/ for the certificate posture of the same endpoints.

Kerberos

The Kerberos checker audits a Kerberos realm starting from its DNS records. From the realm name (derived in uppercase from the domain) and the SRV records grouped under the Kerberos service, it runs a series of anonymous probes and, when credentials are supplied, an optional authenticated round-trip — giving a combined picture of the realm’s availability and security posture.

This checker is service-level: it targets a Kerberos service (abstract.Kerberos) published on a subdomain and is configured from that service’s own Checks tab. It inspects the SRV layout (_kerberos._tcp, _kerberos._udp, _kerberos-master._tcp, _kerberos-adm._tcp, _kpasswd._tcp, _kpasswd._udp), forward-resolves every SRV target (A + AAAA), tests TCP reachability of each KDC/kadmin/kpasswd host and UDP reachability of the KDC via a real AS-REQ. The anonymous AS-REQ probe confirms the realm, reads the supported enctypes from ETYPE-INFO2, detects a PKINIT hint (PA-PK-AS-REQ) and measures clock skew.

What it checks

The HTML report surfaces the most common misconfigurations with a direct remediation hint: no SRV records (publish _kerberos._tcp.REALM. SRV …), an SRV target with no A/AAAA, port 88 unreachable (open TCP+UDP 88), clock skew above the maximum (run ntpd/chrony), weak-enctype-only realms (switch to aes256-cts-hmac-sha1-96), the wrong realm in the reply, and AS-REP roasting exposure (enable requires_preauth).

Options

In happyDomain

Enable the Kerberos checker from the Checks tab of a Kerberos service. The realm domain is filled in automatically; supply a principal and password only if you want the authenticated TGT/TGS round-trip to run. See /en/pages/checks/ for the full workflow.

SIP

The SIP checker probes a domain’s SIP/VoIP deployment from its DNS records, following RFC 3263 resolution: NAPTR → SRV (_sip._udp, _sip._tcp, _sips._tcp) → A/AAAA. It tests reachability on every resolved target:port over UDP, TCP and TLS, then sends a raw SIP OPTIONS ping and inspects the reply (status line, Server/User-Agent, advertised Allow methods, round-trip time).

This checker is service-level: it targets a SIP service (abstract.SIP) published on a subdomain and is configured from that service’s own Checks tab. When no SRV record is published, the checker falls back to <domain>:5060 / <domain>:5061, with a visible info marker in the report.

What it checks

The checker performs, in order: the NAPTR lookup (SIP+D2U, SIP+D2T, SIPS+D2T), the SRV lookup for the three transports (with the 5060/5061 fallback), A/AAAA resolution of every SRV target, TCP connect / UDP send / TLS handshake, and the SIP OPTIONS request with its status, headers and Allow parsed.

Options

In happyDomain

Enable the SIP checker from the Checks tab of a SIP service. The domain is filled in automatically. See /en/pages/checks/ for the full workflow, and /en/reference/checkers/tls/ for the certificate posture of the _sips._tcp endpoints.

SSH

The SSH checker produces a comprehensive security audit of the SSH service exposed by a Server. It connects to the advertised SSH port(s) on every A/AAAA address and reports reachability, banner-to-CVE matches, the full algorithm posture (key exchange, host-key, cipher, MAC, compression), the observed host keys, SSHFP fingerprint alignment, and the authentication methods the server exposes. Results are presented as a “fix me fast” HTML report.

Scope: service-level. It attaches to services of type abstract.Server (a subdomain that publishes A/AAAA and optionally SSHFP records) and is configured from that service’s Checks tab.

What it checks

CVE matching covers, among others, regreSSHion (CVE-2024-6387), the ssh-agent PKCS#11 RCE (CVE-2023-38408), Terrapin (CVE-2023-48795), and several older username-enumeration and command-injection issues.

Options

In happyDomain

This is a service-level checker: configure it from the Checks tab of the Server service on the relevant subdomain. Its SSHFP rules cross-reference the SSHFP records published in your zone, so keeping those records in sync with the server’s host keys improves the result. For the general workflow of configuring and reading checks, see /en/pages/checks/.

XMPP

The XMPP checker probes a domain’s XMPP (Jabber) deployment end-to-end, much like xmpp.net does: it discovers the relevant SRV records, opens a stream to each endpoint, negotiates STARTTLS, inspects the offered SASL mechanisms and confirms that server-to-server federation can authenticate.

This is a service-level checker. It applies to services of type XMPP and is configured from that service’s own Checks tab. It probes the four standard service names (_xmpp-client._tcp, _xmpp-server._tcp, _xmpps-client._tcp, _xmpps-server._tcp), the legacy _jabber._tcp, and falls back to <domain>:5222 / :5269 when no SRV record is published.

What it checks

The probe also covers TCP reachability of A/AAAA targets, stream feature parsing and IPv4/IPv6 coverage, surfaced through the rules above and the HTML report.

Options

In happyDomain

Enable this checker from the Checks tab of an XMPP service; see /en/pages/checks/ for how to configure and schedule checks. The domain is filled in automatically from the service. For the certificate side of the same endpoints, pair it with the /en/reference/checkers/tls/ checker.

Matrix federation

The Matrix federation checker verifies that a Matrix homeserver is correctly set up to federate with the rest of the Matrix network. It delegates the actual probing to a Matrix Federation Tester instance, stores the full report as an observation, and renders a rich HTML summary covering connections, certificates, well-known delegation and DNS/SRV resolution.

This is a service-level checker. It applies to services of type Matrix (instant messaging) and is configured from that service’s own Checks tab.

What it checks

Options

An additional admin-level option, federationTesterServer, sets the URL template of the Federation Tester instance to query. It is configured by the happyDomain operator, not per check, and defaults to https://federationtester.matrix.org/api/report?server_name=%s.

In happyDomain

Enable this checker from the Checks tab of a Matrix service; see /en/pages/checks/ for how to configure and schedule checks. The Matrix domain is filled in automatically from the service.

STUN / TURN

The STUN / TURN checker probes STUN and TURN servers end-to-end. STUN and TURN are the NAT-traversal servers that real-time applications (WebRTC, voice and video) rely on to establish peer-to-peer media: STUN lets a host discover its public reflexive address, while TURN relays media when a direct path cannot be opened.

This is a service-level checker. It runs SRV discovery (or uses an explicit URI), checks TCP/UDP reachability and the TLS/DTLS handshake, issues a STUN binding request, verifies that the TURN server requires authentication, performs an authenticated TURN Allocate, and finally exercises the relay path with a CreatePermission + Send round-trip.

What it checks

Options

In happyDomain

Enable this checker from the Checks tab of the relevant service; see /en/pages/checks/ for how to configure and schedule checks. The zone is filled in automatically; supply a server URI and TURN credentials as needed for your deployment.

Blacklist (DNSBL)

The Blacklist & reputation checker flags whether a domain is currently listed on widely-used reputation systems. It queries a range of sources in parallel and produces a diagnosis-first HTML report whose “Action required” section lists the most impactful listings with a per-operator removal procedure.

Scope: domain-level. The check targets the domain name itself, independent of its DNS records, and is enabled from the domain’s checks view.

What it checks

Each configured source contributes its own per-source rule; a listing on any of them raises the domain’s status. The sources fall into three families:

• DNS-based domain blocklists (DBL/RHSBL) — queried over DNS, no API key required: Spamhaus DBL, SURBL multi, URIBL multi, NordSpam DBL, SpamEatingMonkey Fresh, Tiopan DBL, SORBS RHSBL, plus any extra DNSBL zones an administrator adds.
• Downloaded phishing/malware feeds — fetched and cached in memory: OpenPhish public feed, PhishTank, Botvrij.eu, Disconnect.me, OISD, and a Quad9 secure-DNS comparison.
• Threat-intelligence HTTPS lookups — requiring an API key configured by an administrator: Google Safe Browsing, abuse.ch URLhaus / ThreatFox / MalwareBazaar, VirusTotal v3, AlienVault OTX, Pulsedive, Criminal IP.

When a DNSBL query is refused (many public resolvers are blocked by DBL operators) or an API quota is exhausted, the source is surfaced as a Warning so it does not pollute the OK status. A multi-vendor source such as VirusTotal reports Critical when at least one vendor flags the domain as malicious, and Warning when it is only suspicious.

Options

The only domain-level option is the target itself:

All source selection and credentials are configured per source. Most sources are toggled on or off (and API keys supplied) at the administrator level; a subset of the downloaded-feed sources default to on and can be toggled by the user. See the source’s own documentation for which sources need an API key and how to obtain one.

In happyDomain

This is a domain-level checker: enable it from the domain’s checks view. Listings often reflect a compromise; treat a positive result as a signal to audit the host and rotate credentials, then follow the per-operator delisting links shown in the report. For the general workflow of configuring and reading checks, see /en/pages/checks/.

Legacy records

The Legacy DNS record types checker scans a zone for record types the IETF has deprecated, and reports every occurrence with the relevant RFC reference and a concrete migration suggestion. Deprecated types clutter a zone and, in a few cases, are silently ignored by modern resolvers — so cleaning them up keeps the zone both tidy and unambiguous.

This is a zone-level checker: it walks every service in the working zone in a single pass and consolidates findings by record type, so the report shows one picture rather than one result per record.

What it checks

A single rule, legacy_records, inspects each orphan record body for a deprecated type and groups the findings by severity. The default rule status is critical (the worst severity present bubbles to the top of the report).