Environnement de test ou unipersonnel local

Suivez ce guide d’installation si vous souhaitez utiliser happyDomain directement sur votre machine, le plus simplement possible, sans disposer de la gestion d’utilisateurs.

C’est une configuration simple, qui est appropriée pour évaluer happyDomain ou pour l’utiliser sans authentification sur sa propre machine, ou avec une authentification fournie par un reverse proxy.

Vous pouvez le déployer en utiliser Docker ou bien en téléchargeant l’un des exécutables mis à votre disposition. Nous verrons ci-après les deux méthodes.

Via Docker/podman

Si vous être familier de Docker (ou podman), vous pouvez disposer d’happyDomain en quelques secondes avec la ligne de commande suivante :

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

Si vous souhaitez rendre les données persistantes, il faut ajouter un volume :

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

Quelque soit votre choix, rendez-vous ensuite sur http://localhost:8081 pour commencer à utiliser happyDomain.

Via l’exécutable

1. Commencez par télécharger l’exécutable correspondant à votre architecture de processeur sur : https://get.happydomain.org/master/. Les versions darwin sont pour MacOS, tandis que les versions linux sont pour GNU/Linux. Toutes les versions distribuées sont statiques et devraient fonctionner quelque soit votre libc (GNU libc la plupart du temps, musl pour Alpine, …).

2. Rendez le binaire que vous avez téléchargé exécutable : chmod +x happydomain-OS-ARCH.

3. Exécutez le binaire : HAPPYDOMAIN_NO_AUTH=1 ./happydomain-OS-ARCH.

4. Rendez-vous sur http://localhost:8081/ pour commencer à utiliser happyDomain.

Que font ces options ?

L’option HAPPYDOMAIN_NO_AUTH=1 est un paramètre qui indique à happyDomain qu’il ne doit pas attendre d’authentification : les domaines sont partagées entre toutes les connexions qui arrivent. En fait, cela va automatiquement créer un utilisateur par défaut et désactiver toutes les fonctionnalités de connexion, d’enregistrement de compte, …

Peut-on le mettre sur Internet comme ça ?

Non ! Il est primordial que vous n’exposiez pas votre happyDomain sur Internet sans authentification. En effet, tout son contenu serait accessible à n’importe qui, et pourrait prendre possession de votre/vos domaines.

Utilisez systématiquement un reverse-proxy tel que nginx, Apache, HAproxy, Treafik, … en ajoutant une étape de filtrage ou d’authentification basique.

Par exemple, vous pouvez filtrer les IP qui peuvent accéder au service. Voici un exemple de configuration pour nginx, filtrant les IP (directive allow) :

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;
    }

}

Vous pouvez aussi ajouter une authentification à base de mot de passe simple.

Avec Docker

happyDomain est sponsorisé Docker. Vous trouverez notre image officielle sur le Docker Hub.

Cette image exécutera happyDomain en tant que processus unique, avec une base de données LevelDB (similaire à sqlite, LevelDB est une base de données stockée sur le disque, il n’est pas nécessaire de configurer quoi que ce soit d’autre).

Versions, étiquettes and architectures supportés

Toutes les étiquettes (tags) sont construites pour les architectures de processeur les plus courantes (amd64, arm64 et arm/v7). Nous ne construisons des images uniquement basées sur la distribution Alpine Linux, ce qui assure des images de taille minimale.

Actuellement, les étiquettes disponibles sont :

• latest: il s’agit de la version la plus récente, correspondant à la branche master de notre dépôt de sources.

Utilisation de l’image

À des fins de test

Vous pouvez tester happyDomain ou l’utiliser pour votre usage personnel, avec l’option HAPPYDOMAIN_NO_AUTH=1 : cela créera automatiquement un compte par défaut, et désactivera toutes les fonctionnalités liées à la gestion des utilisateurs (inscription, connexion, …).

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

Les données sont stockées dans le répertoire /data. Si vous souhaitez conserver vos paramètres d’une exécution à l’autre, vous devrez attacher ce répertoire à un volume géré par Docker ou à un répertoire sur votre hôte :

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

En production

happyDomain a besoin d’envoyer du courrier électronique, afin de vérifier les adresses et d’effectuer la récupération des mots de passe, vous devez donc configurer un relais SMTP. Utilisez les options HAPPYDOMAIN_MAIL_SMTP_HOST, HAPPYDOMAIN_MAIL_SMTP_PORT (par défaut 25), HAPPYDOMAIN_MAIL_SMTP_USERNAME et HAPPYDOMAIN_MAIL_SMTP_PASSWORD à cette fin :

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

Si vous préférez utiliser un fichier de configuration, vous pouvez le placer soit dans /data/happydomain.conf pour utiliser le volume, soit lier votre fichier à /etc/happydomain.conf :

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

Étendre l’image de base

Par défaut, happyDomain utilise sendmail, si vous préférez, vous pouvez créer votre propre image avec le paquet ssmtp :

FROM happydomain/happydomain
RUN apk --no-cache add ssmtp
COPY my_ssmtp.conf /etc/ssmtp/ssmtp.conf

Interface d’administration

happyDomain expose certaines commandes d’administration à travers un socket unix. Le conteneur docker contient un script pour accéder à cette partie d’administration : hadmin.

Vous pouvez l’utiliser de cette manière :

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

Il s’agit en fait d’une surcouche au-dessus de curl, mais vous devez commencer par l’URL, et placer les options après.

Configuration

happyDomain respecte la méthodologie 12 factor et permet notamment d’agir sur la configuration de l’application de plusieurs manières.

Par quels moyens configurer happyDomain ?

Il est possible de configurer happyDomain de trois manières différentes : fichier de configuration, environnement, ligne de commande. Toutes les options sont disponibles pour chacun de ces mécanismes.

La précédence, lorsqu’une option est définie par plusieurs mécanismes simultanément, est qu’une option présente dans un fichier de configuration sera écrasé par l’environnement, qui sera écrasée par une option passée sur la ligne de commande.

Configuration par fichier

Au lancement de l’application, le premier fichier de configuration parmi la liste suivante sera utilisé :

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

Seulement le premier fichier existant est pris en compte. Il n’est pas possible d’avoir une partie de ses options dans /etc/happydomain.conf et une autre dans ./happydomain.conf, seul ce dernier fichier de configuration sera pris en compte.

Il est possible de préciser un chemin personnalisé en l’ajoutant comme paramètre supplémentaire à la ligne de commande. Ainsi, pour utiliser le fichier de configuration situé à /etc/happydomain/config, on utilisera :

./happydomain /etc/happydomain/config

Format du fichier de configuration

Une ligne de commentaires commence par #, il n’est pas possible d’avoir des commentaires à la fin d’une ligne, en ajoutant # suivi d’un commentaire.

Placez sur chaque ligne le nom de l’option de configuration et la valeur attendue, séparés par =. Par exemple :

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

Configuration par l’environnement

Au lancement d’happyDomain, toutes les variables commençant par HAPPYDOMAIN_ sont analysées à la recherche d’options de configuration valides.

Vous pouvez réaliser la même chose que dans l’exemple précédent, avec les variables d’environnement suivantes :

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

Notez que les - sont remplacés par des _ dans les variables d’environnement.

Configuration par la ligne de commande

Enfin, la ligne de commande peut être utilisée pour passer des options, selon le format UNIX usuel.

Pour continuer l’exemple précédent, nous pouvons réaliser la même configuration avec la ligne de commande suivante :

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

ou encore en utilisant le signe = pour assigner clairement la valeur.

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

Éléments de configuration

La liste exhaustive des éléments configurables peut être listé en appelant happyDomain avec l’option -h ou --help.

Voici la liste des principales options :

Paramètres généraux

bind

Interface (ip, port) à utiliser pour exposer le service happyDomain.

admin-bind

Interface (ip, port ou socket) à utiliser pour exposer l’API d’administration.

default-ns

Adresse et port du serveur résolveur de noms à utiliser par défaut lorsqu’une résolution de nom est nécessaire.

dev

URL vers laquelle toutes les requêtes liées à l’interface graphique seront renvoyées.

externalurl

URL du service, tel qu’il doit apparaître dans les mails et contenus à destination du public.

disable-providers-edit

Interdit toute action sur les fournisseurs de service DNS (ajour/édition/suppression), par exemple pour avoir un mode de démonstration.

Mise en page

custom-head-html

Chaîne de caractères à placer avant la fin de l’en-tête HTML.

custom-body-html

Chaîne de caractères à placer avant la fin du corps HTML.

hide-feedback-button

Cache l’icône permettant de donner son retour d’expérience.

msg-header-text

Ajoute un message personnalisé dans une bannière en haut de toutes les pages.

msg-header-color

Classe de couleur de fond pour la bannière ajoutée en haut de l’application web (par défaut “danger”, pourrait être primary, secondary, info, success, warning, danger, light, dark, ou toute autre classe de couleur bootstrap).

Stockage des données

storage-engine

Permet de choisir le mécanisme de stockage des données parmi tous les mécanismes supportés.

LevelDB (storage-engine=leveldb)

leveldb-path

Chemin vers le dossier contenant la base LevelDB à utiliser.

Paramètres e-mail

Nous employons go-mail comme bibliothèque pour envoyer les mails.

mail-from

Définit le nom et l’adresse de l’expéditeur des mails envoyés par le service.

Notez que sans les options mail-smtp-*, happyDomain utilisera le binaire sendmail pour envoyer les mails. Cela peut être couplé aux paquets msmtp ou ssmtp par exemple, pour définir les paramètres pour tout le système.

mail-smtp-host

IP ou nom d’hôte du serveur SMTP à utiliser.

mail-smtp-port

Port à utiliser sur le serveur distant.

mail-smtp-username

Lorsque de l’authentification est nécessaire sur le serveur distant, nom d’utilisateur à utiliser.

mail-smtp-password

Lorsque de l’authentification est nécessaire sur le serveur distant, mot de passe à utiliser.

Authentification

no-auth

Désactive la notion d’utilisateurs et de contrôle d’accès. Un compte par défaut est utilisé.

disable-embedded-login

Désactive le mécanisme de connexion interne en faveur de l’external-auth ou d’OIDC.

disable-registration

Interdit la création de nouveau compte à travers le formulaire ou l’API (cela ne désactive pas la création de compte lorsque l’on se connecte pour la première fois à partir d’un service d’authentification externe).

external-auth

Base de l’URL du service d’authentification et d’enregistrement à utiliser à la place du système de connexion embarqué.

jwt-secret-key

Clef secrète utilisée pour vérifier les tokens JWT.

Voir aussi paramètres OpenID Connect.

Spécifique aux bureaux d’enregistrement

Certain bureau d’enregistrement nécessitent que les applications tierces s’identifient en plus d’identifier l’utilisateur.

Bind

with-bind-provider

Active BIND en tant que fournisseur DNS (attention, ce paramètre n’est pas adapté à un environnement partagé/cloud car il accède au système de fichiers local).

OVH

Veuillez vous référer à cette documentation afin de générer les identifiants.

ovh-application-key

Application key pour l’API d’OVH

ovh-application-secret

Clef secrète pour l’API d’OVH

OpenID Connect

happyDomain supporte l’authentification d’utilisateurs via le protocole OpenID Connect. Si vous avez un prestataire pour l’authentification (Auth0, Okta, …) ou que vous avez un logiciel dit “Identity Provider” (IdP) tel que Keycloak, Authentik, Authelia, … vous pouvez l’utiliser avec happyDomain et vous passez, éventuellement, du système d’inscription et d’authentification embarqué.

Configuration

Pour activer l’authentification OpenID Connect, vous aurez besoin de définir les options suivantes :

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

L’option PROVIDER_URL correspond à l’URL de base du service d’authentification. Celui-ci doit mettre à disposition une page de découverte de ses paramètres (accessible à /.well-known/openid-configuration).

Paramétrage du fournisseur OpenID Connect

Vous aurez besoin de créer une application dans votre fournisseur d’authentification, avec les paramètres suivants :

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

Définissez également une adresse de retour autorisée :

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

Connexion à un serveur BIND distant

BIND est un serveur DNS récursif et faisant autorité développé par l’Internet Systems Consortium.

Il est possible de l’utiliser avec happyDomain en passant par le Dynamic DNS (RFC 2136).

Cette documentation vous guidera dans la configuration de BIND pour activer le DNS dynamique, puis pour relier ensemble happyDoain et votre serveur BIND.

Configurer BIND pour activer le DNS dynamique

Tout d’abord, vous devez modifier le fichier de configuration principal de BIND (généralement /etc/named.conf ou /etc/bind/named.conf selon votre distribution) pour ajouter un secret qui sera partagé entre happyDomain et BIND pour authentifier les modifications. Ensuite, vous devez indiquer quels domaines seront gérés par happyDomain.

Ajouter un secret partagé

Sous la section principale key de votre configuration, ajoutez la clé suivante :

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

Remplacez <SOME_SECRET> par une chaîne obtenue en utilisant openssl rand -base64 48.

Créer une règle d’autorisation pour happyDomain

En plus de la clé, vous devez spécifier comment la clé peut être utilisée en définissant une ACL et en autorisant les mises à jour à partir de celle-ci.

Ajoutez l’ACL suivante à votre configuration :

acl "happydomain_acl" {
    key happydomain;
};

Autoriser les mises à jour pour chaque zone

Maintenant que vous avez créé une règle permettant à la clé happydomain d’apporter des modifications, vous devez indiquer à quelles zones cette règle s’applique.

Pour chaque zone, vous devez ajouter une déclaration update-policy référencant l’ACL happydomain_acl :

Par exemple, pour une zone existante happydomain.org, ajoutez la déclaration update-policy comme suit :

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

La déclaration update-policy est une liste, donc vous pouvez déjà avoir d’autres politiques dans cette liste. Dans ce cas, ajoutez simplement la déclaration grant pour happydomain_acl.

Autoriser les mises à jour pour routes les zones

Si vous gérez de nombreuses zones, il peut être plus pratique de définir l’autorisation par défaut pour toutes les zones. Dans ce cas, vous pouvez utiliser une update-policy globale dans la section options :

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

Cela appliquera la update-policy à toutes les zones, permettant à l’ACL happydomain_acl de mettre à jour n’importe quel enregistrement.

Appliquer la configuration

Après avoir modifié le fichier de configuration, rechargez le service BIND pour appliquer les modifications :

rndc reload

Lier happyDomain et BIND

Une fois BIND bien configuré, vous pouvez le lier à happyDomain en utilisant le connecteur Dynamic DNS :.

Remplissez ensuite le formulaire avec l’adresse à laquelle votre serveur BIND est accessible, puis ensuite les différents champs Key avec les informations indiqués dans votre configuration :

• Key Name : correspond au champ id ;
• Key Algorithm : correspond au champ algorithm ;
• Secret Key : correspond au champ secret.

Une fois le fournisseur ajouté, il ne permet pas de lister les domaines existants, mais vous pouvez toujours ajouter manuellement tous vos domaines.

En suivant ces étapes, vous aurez configuré BIND pour fonctionner avec happyDomain en utilisant le DNS dynamique, assurant des mises à jour DNS sécurisées et authentifiées.

Connexion à un knot local

Knot est un serveur DNS faisant autorité développé par l’association cz.nic.

Il est possible de l’utiliser avec happyDomain en passant par le Dynamic DNS (RFC 2136).

Configurer Knot pour permettre le Dynamic DNS

Tout d’abord, il faut éditer le fichier de configuration principal de knot (généralement /etc/knot/knot.conf) afin d’ajouter un secret qui sera partagé entre happyDomain et knot pour authentifier les modifications. Puis il faudra indiquer quels domaines vont être gérés par happyDomain.

Ajout d’un secret partagé

Sous la section principale key de votre configuration, ajoutez la clef suivante :

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

Remplacez évidemment <SOME_SECRET> par une chaîne de caractères telle qu’obtenue avec openssl rand -base64 48.

Création d’une autorisation pour happyDomain

En plus de la clef, vous devez préciser dans la configuration comment la clef peut être utilisée.

Pour cela, sous la section principale acl, on ajoute :

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

Cela associe la key définie juste avant aux actions transfer et update, respectivement pour permettre de récupérer la zone et pour mettre à jour des enregistrements.

Associer l’autorisation à chaque zone

Maintenant que vous avez créé une règle autorisant la clef happydomain à apporter des modifications, il faut indiquer à quelles zones cette règle s’applique.

Pour chaque zone, il faut ajouter un élément acl référençant la règle acl_happydomain :

Par exemple, pour une zone happydomain.org déjà existante, on ajoutera la ligne acl comme suit :

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

L’élément acl est une liste, vous pouvez donc avoir déjà d’autres éléments acl dans cette liste. Il convient alors d’ajouter simplement l’élément acl_happydomain à la liste déjà existante.

Il faut ajouter cet élément acl pour chaque zone, sauf à utiliser l’astuce suivante.

Associer l’autorisation à toutes les zones

Si vous gérez de nombreuses zones, il peut être plus pratique de définir l’autorisation par défaut pour toutes les zones. Dans ce cas, à la place de la section précédente, on modifiera le modèle default :

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

Le modèle default est appliqué par défaut à toutes les zones. En faisant ainsi, toutes les zones hériteront de la règle acl_happydomain.

Appliquer la configuration

Maintenant que le fichier de configuration a été modifié, indiquez à knotd qu’il doit recharger sa configuration :

knotc reload

Liaison entre happyDomain et knot

Une fois knot bien configuré, vous pouvez le relier à happyDomain en utilisant le connecteur Dynamic DNS :

Remplissez ensuite le formulaire avec l’adresse à laquelle votre serveur knot est accessible, puis ensuite les différents champs Key avec les informations de la section key de knot :

• Key Name : correspond au champ id ;
• Key Algorithm : correspond au champ algorithm ;
• Secret Key : correspond au champ secret.

Une fois le fournisseur ajouté, il ne permet pas de lister les domaines existants, mais vous pouvez tout de même ajouter manuellement tous vos domaines.

Configuration pour l'API OVH

Afin de pouvoir gérer des domaines hébergés par OVH, il est nécessaire de passer par une étape de configuration supplémentaire.

En effet, le principe de fonctionnement de l’authentification à l’API d’OVH se fait en 2 étapes :

1. Tout d’abord il faut enregistrer une application (par exemple happyDomain). Une application dispose d’un identifiant et d’un secret qu’il convient de renseigner en tant que paramètre d’happyDomain.
2. Pour chaque compte OVH que l’on souhaite gérer, l’interface d’happyDomain redirige vers la page d’OVH permettant de créer la Consumer key.

L’application doit être créée à partir d’un compte OVH existant, peu importe qu’il dispose de domaines ou non, il s’agit d’identifier la personne responsable de la mise en œuvre de l’application désignée. L’accès aux données d’un compte, notamment aux domaines qu’ils gèrent, se fait au travers de la Consumer key.

Pour plus d’information, voir cette page : https://docs.ovh.com/gb/en/api/api-rights-delegation/#application-registration

Enregistrer votre instance d’happyDomain auprès d’OVH

1. Rendez-vous sur la page https://api.ovh.com/createApp/.
2. Remplissez le formulaire avec un nom et une description qui refléte le nom et l’usage de votre application, par exemple happyDomain.

Une fois le formulaire validé, vous obtiendrez une clef et un secret. Ces informations sont à indiquer dans la configuration d’happyDomain :

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)

Le SOA est le premier enregistrement d’une zone.

TXT

Documentation à faire

E-Mail

Le service E-Mail permet de définir un serveur de courrier électronique sur la zone, ainsi que le paramétrage de la zone en vue d’envoyer/recevoir des courriels.