Sous-sections de Les principaux écrans
La page d'accueil
Vos domaines
La page d’accueil présente la liste de l’ensemble des domaines gérés par happyDomain, quelque soit leur hébergeur :
Cliquez sur l’un des domaines pour commencer à y apporter des modifications (ajouter un sous-domaine, ajouter un service, …).
Vos registres et hébergeurs de domaines
Sur la droite, vous voyez la liste des différents hébergeurs de vos domaines :
Vous pouvez ajouter un nouvel hébergeur en cliquant sur le bouton +, présent dans l’en-tête du tableau.
En cliquant sur une ligne de ce tableau, vous filtrerez la liste des domaines pour n’afficher que les domaines gérés par cet hébergeur.
Vous verrez aussi, si l’hébergeur permet de lister les domaines qui vous appartiennent, les domaines que vous pouvez ajouter à happyDomain :
Pour afficher à nouveau la liste dans son intégralité, recliquez simplement sur l’hébergeur qui est sélectionné.
Modifier ou supprimer un hébergeur
Si vous constatez une erreur ou n’avez plus besoin d’un hébergeur, cliquez sur les … sur la ligne de l’hébergeur concerné. Vous aurez alors la possibilité de choisir entre mettre à jour les informations ou supprimer l’hébergeur :
Notez que vous ne pourrez pas supprimer l’hébergeur tant que des domaines y faisant référence, existeront dans la liste de gauche.
Ajouter un domaine
Vous avez un nouveau domaine que vous souhaitez gérer dans happyDomain ? Commencez par entrer son nom dans le champ présent sous la liste. Vous serez ensuite guidé vers l’écran permettant de choisir l’hébergeur.
Le champ n’apparaît pas lorsqu’un hébergeur est sélectionné à droite. Sauf si cet hébergeur ne permet pas de lister les domaines :
Dans ce cas, la validation du champ recherchera automatiquement le nouveau domaine auprès de l’hébergeur sélectionné, comme l’indique le message juste au dessus du champ.
Les hébergeurs
Vous accédez à cette page en cliquant sur le lien « Les hôtes de mes domaines » dans le menu en haut.
Vos registres et hébergeurs de domaines
Cette page montre uniquement la liste des registres et des hébergeurs de domaines que vous avez ajouté à votre compte, et vous permet d’en ajouter.
Vous pouvez ajouter un nouvel hébergeur en cliquant sur le bouton +, présent en haut de la page.
En cliquant sur une ligne du tableau, vous accéderez aux paramètres qu’utilise happyDomain pour contacter cet hébergeur.
C’est là que vous allez pouvoir modifier le nom que vous avez donné à cet hébergeur, et que vous pourrez modifier les paramètres d’accès.
Ajouter un hébergeur
Vous accédez à cet écran en cliquant sur le lien « Les hébergeurs de mes domaines » dans le menu en haut, puis en cliquant sur le bouton « + Ajouter un nouvel hébergeur de domaines ».
Les registres et hébergeurs de domaines compatibles
La première étape lorsque vous souhaitez ajouter un domaine, est de déterminer chez quel hébergeur il se trouve.
Dans cet écran, on vous demande de sélectionner, parmi la liste des hébergeurs compatibles (d’autres seront ajoutés plus tard, si vous ne trouvez pas le votre, contactez-nous !), l’hébergeur chez qui vous avez votre domaine :
Une fois que vous l’avez sélectionné, vous êtes dirigé vers l’écran de paramétrage de la connexion à l’hébergeur.
Paramètres de l'hébergeur
Vous accédez à cet écran soit :
- lorsque vous souhaitez ajouter un hébergeur, après avoir sélectionné le fournisseur,
- lorsque vous souhaitez modifier les paramètres de connexion entre happyDomain et un hébergeur, par exemple sur la page d’accueil.
Nom de la connexion
Afin de vous y retrouvez parmi les différents hébergeurs, le premier champ qui vous est demandé est un nom.
Ce nom servira uniquement pour vous permettre d’identifier facilement l’hébergeur de votre domaine, si vous en avez plusieurs.
Autres champs
Chaque hébergeur a besoin d’informations différentes pour établir une connexion avec happyDomain.
Suivez les instructions sur chaque écran.
Ajout d'un domaine
Vous accédez à cet écran après avoir validé sur la page d’accueil le formulaire d’ajout de domaine (et que vous n’aviez pas préalablement sélectionné d’hébergeur dans le filtre de droite).
Choix de l’hébergeur
Vous pouvez voir sur cet écran les différents hébergeurs que vous avez déjà configuré.
Si votre domaine fait parti d’un des comptes listés, cliquez simplement dessus, il sera ajouté automatiquement.
Si vous n’avez pas encore ajouté l’hébergeur, vous pouvez le faire maintenant, en suivant le lien « Ajouter maintenant ! ».
Votre domaine
Documentation à faire
Mon compte
Vous accédez à cette page en cliquant sur le lien « Mon compte » dans le menu en haut.
Paramètres du compte
L’écran est divisé en 3 parties. La première va vous permettre de modifier les paramètres liés à votre compte : tel que la langue de l’interface ou la manière dont l’aide contextuelle est affichée.
Changer de mot de passe
La seconde partie de l’écran vous permet de changer de mot de passe.
Changer l’adresse électronique de compte
Il n’est pour l’instant pas possible de changer l’adresse électronique de votre compte. Nous vous invitons à nous contacter si vous souhaitez la changer.
Supprimer son compte
La dernière partie de la page vous permet de supprimer votre compte happyDomain.
Une fois la suppression validée, votre compte ne sera plus accessible et l’ensemble des données vous appartenant sera supprimé peu de temps après, lors d’un nettoyage régulier de la base de données.
À partir du moment où vous supprimez votre compte, vos domaines continueront de répondre selon la dernière mise à jour que vous avez effectué sur happyDomain. La suppression n’affectera pas les données distribuées.
Outils : le résolveur DNS
Documentation à faire
Sous-sections de Installation et deploiement
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
-
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, …).
-
Rendez le binaire que vous avez téléchargé exécutable : chmod +x happydomain-OS-ARCH.
-
Exécutez le binaire : HAPPYDOMAIN_NO_AUTH=1 ./happydomain-OS-ARCH.
-
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.
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
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 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).
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 :
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 :
- 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.
- 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
- Rendez-vous sur la page https://api.ovh.com/createApp/.
- 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 à indiqué 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
