Code source wiki de Mettre en place un sous-domaine

Modifié par Gaetan RETEL le 2025/10/05 00:35

version	line-number	content
1.2	1	Lorsqu'une VM est mise en place, et que le service qu'elle doit héberger est installé, il est grand temps de rendre ce service accessible à l'extérieur du réseau d'ATILLA.
1.3	2
2.1	3	{{toc/}}
1.3	4
6.1	5	= Idée générale =
1.4	6
6.1	7	Avant de suivre les étapes de mise en place, c’est intéressant de comprendre ce qu’on va faire ^^.^^
2.1	8
	9	Dans l'infra d'ATILLA, les connexions à un service web (members.atilla.org, learn.atilla.org, …) passent en grande majorité par Bill, qui acte comme d'un frontal web : c’est lui qui réceptionne les connexions HTTP(s) et qui les renvoie aux bons services internes par la suite. On dit également que Bill joue le rôle de //reverse-proxy//.
	10
	11	En plus de cela, Bill gère la terminaison des connexions HTTPs : c’est à dire que lorsqu’une connexion HTTPs arrive sur Bill, elle est déchiffrée, puis renvoyée en HTTP à la machine virtuelle qui correspond. Cela permet de ne pas complexifier l’installation des services, et d’avoir un endroit central ou gérer les certificats SSL.
	12
	13	[[image:reverse-proxy-arch.png]]
	14
6.1	15	En pratique, Bill dispose d'un serveur Nginx, qui va réceptionner toute requête HTTP(s) sur un des sites d'ATILLA et qui transfère cette requête à la VM qui héberge le service correspondant.
2.1	16
6.1	17	= Enregistrement du sous-domaine =
2.1	18
3.2	19	La première chose à faire est de déclarer au monde que le domaine sur lequel vous souhaitez déployer votre service existe. Il n’y a pas de convention à proprement parler sur le choix du sous-domaine. Si vous déployez un service de gestion de tickets (par exemple, GLPI), le domaine auquel ce service pourra être accessible peut très bien être ##glpi.atilla.org## ou même ##tickets.atilla.org##.
	20
	21	Pour déclarer ce domaine, rendez-vous sur la machine qui sert de DNS dans l’infra (aujourd’hui, il s’agit de Bill). Deux fichiers devront être édités :
6.1	22
3.2	23	* ##/etc/bind/internal/db.atilla.org## : les entrées DNS qui sont exposées à tous les utilisateurs au sein du réseau d’ATILLA et de l’EISTI
	24	* ##/etc/bind/external/db.atilla.org## : les entrées DNS qui sont exposées à tous les utilisateurs venant de l’extérieur
	25
3.7	26	Dans ces deux fichiers, rajoutez une ligne comme celle-ci (note : les sous-domaines sont triés par ordre alphabétique) :
3.2	27
	28	{{code language="none"}}
	29	monservice IN CNAME bill
	30	{{/code}}
	31
7.1	32	N'oubliez pas de mettre à jour les config sur le gitlab en faisant un push : [[https:~~/~~/gitlab.atilla.org/adminsys/dns-config>>https://gitlab.atilla.org/adminsys/dns-config]]
	33
3.2	34	… puis redémarrez le serveur DNS :
	35
	36	{{code language="none"}}
	37	systemctl restart bind9
	38	{{/code}}
	39
	40	Cela aura pour effet de déclarer le sous-domaine ##monservice.atilla.org##.
	41
	42	Si vous devez déclarer un service sur ##*.eistiens.net##, il faudra éditer les fichiers ##db.eistiens.net## dans les dossiers ##internal## et ##external## de la configuration du DNS.
	43
3.4	44	{{warning}}
	45	Lorsqu’on fait une modification dans une configuration DNS, il y a toujours un temps dit de "propagation", pendant lequel l’entrée qui a été déclarée n’est pas tout de suite accessible par tout le monde. Cela peut prendre jusqu’à 24h pour qu’une entrée soit réellement accessible par tous. Cela est également vrai lorsqu’on modifie ou supprime une entrée.
	46	{{/warning}}
	47
6.1	48	= Mise en place des certificats SSL =
3.2	49
3.5	50	Maintenant qu’on a notre domaine, on va pouvoir récupérer des certificats SSL nous permettant de mettre en place le HTTPs sur ce domaine.
3.2	51
3.8	52	L’idée, c’est de récupérer des informations (en l’ocurrence, un certificat et sa clé) nous permettant d’attester que le frontal web est bien le serveur qui correspond au domaine ##monservice.atilla.org##. Lorsqu’un utilisateur se connectera en HTTPs à ce domaine, la première action qui sera effectuée par le navigateur sera de vérifier que le serveur auquel il se connecte est bien le bon, et qu’il peut lui faire confiance.
2.1	53
3.8	54	Il existe plusieurs fournisseurs de certificats SSL dans le monde. ATILLA utilise [[Let’s Encrypt>>https://letsencrypt.org/]], qui nous permet, une fois le certificat mis en place une première fois, de ne pas avoir à se soucier de son renouvellement (le renouvellement de tous les certificats est ensuite effectué de manière automatique).
3.5	55
3.8	56	Let’s Encrypt vient avec un outil, appelé ##certbot##, qui permet d’enregistrer de nouveaux certificats SSL. On va utiliser cet outil pour demander le nouveau certificat.
3.5	57
3.8	58	{{warning}}
	59	La procédure pour demander un nouvau certificat SSL consiste à éteindre le serveur frontal, laisser ##certbot## vérifier que le serveur répond bien au domaine qu’on souhaite certifier, puis rallumer le serveur frontal. Cela occasionne généralement une interruption de service pour la grande majorité des domaines d’atilla.org et d’eistiens.net. Pour éviter que la coupure de service ne dure trop longtemps, assurez vous que Nginx est bien redémarré après la procédure.
	60	{{/warning}}
	61
3.9	62	Pour la demande du nouveau certificat, utilisez la commande suivante. Lorsque certbot demande quelle méthode de vérification utiliser pour générer le certificat, choisissez //Spin-up a temporary webserver//.
	63
3.17	64	{{code language="shell"}}
3.9	65	systemctl stop nginx && certbot certonly -d monservice.atilla.org && systemctl start nginx
3.8	66	{{/code}}
	67
3.9	68	Si certbot termine avec un message du type //Congratulations! Your certificate and chain … bla bla bla//, ça veut dire que c’est bon, le certificat a bien été enregistré. Il doit maintenant être stocké dans ##/etc/letsencrypt/live/monservice.atilla.org/##.
	69
	70	Si vous n’avez pas ce genre de message, avant de démarrer tout diagnostique, assurez-vous de bien redémarrer le serveur Nginx, pour éviter toute interruption de service trop longue :
	71
3.17	72	{{code language="shell"}}
3.9	73	systemctl start nginx
	74	## Pour vérifier que tout va bien
	75	systemctl status nginx
	76	{{/code}}
	77
6.1	78	= Mise en place de la configuration Nginx =
3.10	79
	80	Finalement, on va devoir mettre en place la configuration qui va tout lier ensemble, c’est elle qui va indiquer que, lorsqu’un utilisateur se connecte au service, on utilisera le certificat SSL qui a été généré plus haut, et on enverra les connexions à la machine voulue.
	81
6.1	82	== Méthode manuelle ==
3.10	83
6.1	84	=== Création de la configuration ===
3.13	85
3.14	86	On va créer la configuration d’Nginx dans le dossier ##/etc/nginx/sites-available##. Par convention, le nom du fichier de configuration va correspondre au nom du domaine sur lequel on expose le service. Dans notre cas, il s’agira de ##monservice.atilla.org##.
	87
	88	La plupart du temps, si on ne veut pas s’embêter dans la mise en place de la configuration, le plus simple consiste à copier / coller une configuration d’un service existant, en espérant que celle-ci soit suffisamment standard pour que ça marche.
	89
	90	Voici à peu près ce à quoi doit ressembler la configuration. Attention : il est possible que cela change au fil du temps et que le contenu de ce tuto n’ait pas été mis à jour :).
	91
3.21	92	{{code language="nginx"}}
3.14	93	server {
6.1	94	listen 80;
	95	server_name monservice.atilla.org;
	96	return 301 https://monservice.atilla.org$request_uri;
3.14	97	}
	98
	99	server {
6.1	100	listen 443 ssl http2;
3.14	101
6.1	102	server_name monservice.atilla.org;
3.14	103
6.1	104	ssl on;
	105	ssl_certificate_key /etc/letsencrypt/live/monservice.atilla.org/privkey.pem;
	106	ssl_trusted_certificate /etc/letsencrypt/live/monservice.atilla.org/chain.pem;
	107	ssl_certificate /etc/letsencrypt/live/monservice.atilla.org/fullchain.pem;
3.14	108
6.1	109	access_log /var/log/nginx/monservice.atilla.org/access.log;
	110	error_log /var/log/nginx/monservice.atilla.org/error.log;
3.14	111
6.1	112	location / {
	113	proxy_set_header Host $host;
	114	proxy_set_header X-Forwarded-For $remote_addr;
	115	proxy_pass http://monservice-prod.prod.infra.atilla.org/;
	116	}
3.14	117	}
	118	{{/code}}
	119
3.19	120	Voici ci-après une description rapide des contenus de ce fichier.
3.18	121
3.19	122	On commece par le premier bloc ##server##, celui-ci est très simple et concis, son job, c'est de rediriger tout le traffic HTTP qui arrive sur monservice.atilla.org en HTTPs.
	123
3.20	124	{{code language="nginx"}}
3.19	125	server {
6.1	126	# On écoute sur le port 80 (le port utilisé par défaut avec HTTP)
	127	listen 80;
	128	# On répond aux requêtes qui pointent vers le domaine monservice.atilla.org
	129	server_name monservice.atilla.org;
	130	# On redirige chaque requête vers son équivalent HTTPs
	131	return 301 https://monservice.atilla.org$request_uri;
3.19	132	}
3.18	133	{{/code}}
	134
3.19	135	Le second bloc ##server## permet de définir comment va être géré le traffic HTTPs, c'est ici qu'on a la plupart de la configuration importante.
	136
3.22	137	{{code language="nginx"}}
	138	server {
6.1	139	# On écoute sur le port 443, qui est celui par défaut pour le HTTPs.
	140	# Les deux autres attributs ssl et http2 indiquent :
	141	# * Qu'on va chiffrer la connexion avec SSL (le principe du HTTPs)
	142	# * Qu'on supporte le protocole HTTP/2
	143	listen 443 ssl http2;
3.19	144
6.1	145	# Comme avant, on répond aux requêtes qui pointent vers le domaine monservice.atilla.org
	146	server_name monservice.atilla.org;
3.19	147
6.1	148	# On indique encore une fois qu'on va utiliser le SSL, et on fournit les fichiers qui
	149	# sont nécessaires pour authentifier le serveur et chiffrer la connexion.
	150	ssl on;
	151	ssl_certificate_key /etc/letsencrypt/live/monservice.atilla.org/privkey.pem;
	152	ssl_trusted_certificate /etc/letsencrypt/live/monservice.atilla.org/chain.pem;
	153	ssl_certificate /etc/letsencrypt/live/monservice.atilla.org/fullchain.pem;
3.19	154
6.1	155	# On configure l'emplacement des logs
	156	access_log /var/log/nginx/monservice.atilla.org/access.log;
	157	error_log /var/log/nginx/monservice.atilla.org/error.log;
3.22	158
6.1	159	# C'est ici que la "magie" opère :)
	160	# La directive proxy_pass nous permet de rediriger tout le traffic vers la machine virtuelle qui correspond
	161	# Les directives proxy_set_header permettent d'ajouter des en-têtes spécifiques à destination de la machine virtuelle,
	162	# par exemple pour que celle-ci comprenne qu'elle se trouve derrière un frontal web.
	163	location / {
	164	proxy_set_header Host $host;
	165	proxy_set_header X-Forwarded-For $remote_addr;
	166	proxy_pass http://monservice-prod.prod.infra.atilla.org/;
	167	}
3.22	168	}
	169	{{/code}}
	170
6.1	171	=== Création du dossier de logs ===
3.13	172
3.31	173	Comme vu dans la configuration précédente, on va stocker les logs Nginx dans ##/var/log/nginx/monservice.atilla.org##. Par défaut, ce dossier n'existe pas et il faut le créer (sinon, Nginx ne démarrera pas).
	174
	175	{{code language="shell"}}
	176	mkdir /var/log/nginx/monservice.atilla.org
	177	{{/code}}
	178
6.1	179	=== Activation de la configuration Nginx ===
3.13	180
3.32	181	Finalement, il faut s'assurer qu'Nginx prendra en compte notre fichier de configuration. Si vous regardez dans ##/etc/nginx##, vous verrez deux dossiers :
6.1	182
3.32	183	* ##sites-available##: celui dans lequel la configuration a été créée
	184	* ##sites-enabled##: celui dans lequel la configuration doit être référencée pour être active
	185
	186	Pour activer la configuration en question, rien de plus simple, on fait juste un lien symbolique dans ##sites-enabled## vers le fichier qui convient :
	187
	188	{{code language="shell"}}
	189	ln -sf /etc/nginx/sites-available/monservice.atilla.org /etc/nginx/sites-enabled/atilla.org/
	190	{{/code}}
	191
	192	Avant de terminer cette manip, on vérifie que tout est bon au niveau de la configuration, et que Nginx ne va pas planter au redémarrage :
	193
	194	{{code language="shell"}}
	195	nginx -t
	196	{{/code}}
	197
	198	Et finalement, on redémarre !
	199
	200	{{code language="shell"}}
	201	systemctl restart nginx
	202	{{/code}}
	203
6.1	204	== Méthode plus ou moins automatique ==
3.11	205
3.12	206	On a un [[super projet sur GitLab>>https://gitlab.atilla.org/adminsys/nginx-config-generator]] qui permet d’effectuer les actions de la méthode manuelle de manière automatique. Ce projet est présent sur ##/root/nginx-config-generator## sur Bill, voici comment l’utiliser rapidement. En cas de besoin, référez vous au ##README.md## du projet.
	207
	208	{{code language="shell"}}
	209	cd /root/nginx-config-generator
	210	source venv/bin/activate
	211	python nginx-config.py monservice.atilla.org monservice-prod.prod.infra.atilla.org
	212	## On vérifie que tout va bien avec la config qui a été générée
	213	nginx -t
	214	## On redémarre
	215	systemctl restart nginx
	216	{{/code}}