Charte
Conventions communes de la documentation : entités, adressage, nommage, niveaux de test, gabarit de page.
Entités et domaines
En bref
Niveau : référence
Durée de lecture : 3 minutes
Prérequis : avoir lu « Erminig, une société fictive »
Les entités, c'est quoi ?
Toute la documentation se déroule dans un univers fictif unique. Cette page liste ses acteurs et leurs noms de domaine. Une page qui cite un nom absent de cette liste est à corriger.
| Entité | Nature | Rôle dans le scénario | Domaine |
|---|---|---|---|
| Erminig | ESN bretonne | Infogérance et hébergement ; son système d'information sert de laboratoire | erminig.example |
| Nébuleuse | Offre d'hébergement d'Erminig | Une VM dédiée par client, applications libres à la carte, administration par Ansible et bastion Teleport | nebuleuse.example (service et bastion) |
| Atelier Penhoat | Client Nébuleuse « alpha » (TPE artisanale) | Cloud, photos, gestionnaire de mots de passe | penhoat.example |
| Cabinet Kerjean | Client Nébuleuse « beta » (cabinet) | Cloud, gestionnaire de mots de passe | kerjean.example |
| Kerlann Agglomération | Communauté d'agglomération, client en infogérance | Siège, annuaire, messagerie, parc des communes membres | kerlann.example (annuaire : ad.kerlann.example) |
| Communes membres | Kerven, Lannaron, Trévenan, Plouvelen, Saint-Gweltaz, Kerdalec | Mairies reliées au siège | kerven.example, lannaron.example, trevenan.example, plouvelen.example, saint-gweltaz.example, kerdalec.example |
| Écoles | École du Menez (Kerven), école de Kersaint (Lannaron), école des Genêts (Trévenan) | Parc pédagogique en clients légers (Edubuntu) | ecole.example, commun aux trois écoles |
Kerlann Agglomération est un seul client. Les communes et les écoles sont dans son parc, avec des noms de domaine différents. Chaque école est sur un réseau qui n'expose rien : un domaine commun suffit.
Pourquoi .example ?
Le suffixe .example est réservé par la norme (RFC 2606) : il ne peut appartenir à personne, donc aucun nom de la documentation ne désigne une organisation réelle. Les noms de domaine sont écrits en minuscules, avec des tirets.
Qui intervient ?
Deux prénoms fictifs servent de fil conducteur : camille (support Erminig) et alex (administrateur). Les comptes suivent des règles décrites dans la page « Domaines et nommage ».
Page suivante : Plans d'adressage.
Plans d'adressage
En bref
Niveau : référence
Durée de lecture : 5 minutes
Prérequis : « Entités et domaines »
Pourquoi des plans lisibles ?
Chaque entité suit une règle simple : le troisième octet de l'adresse identifie le réseau, et le numéro de VLAN en découle. Une adresse se lit alors sans tableau : 10.10.3.21 est dans le VLAN 103, réseau des services internes d'Erminig.
Trois plans coexistent, un par univers, avec des plages distinctes pour éviter tout recouvrement lors des liaisons VPN.
| Univers | Plage privée | Plage publique fictive |
|---|---|---|
| Erminig (système d'information) | 10.10.0.0/16 |
198.51.100.0/24 |
| Nébuleuse (administration) | 10.99.0.0/24 |
192.0.2.0/24 |
| Kerlann Agglomération | 10.20.0.0/16 |
203.0.113.0/27 |
Les plages publiques sont des blocs réservés à la documentation (RFC 5737).
Règle de numérotation commune
Dans chaque réseau /24 :
| Plage | Usage |
|---|---|
.1 |
Passerelle |
.2 à .9 |
Équipements réseau |
.11 à .99 |
Serveurs |
.100 à .199 |
DHCP |
.200 à .254 |
Réservé |
Erminig
Réseau 10.10.0.0/16, découpé en /24. Le troisième octet va de 0 à 8, le VLAN vaut 100 plus cet octet.
| Réseau | VLAN | Usage | Machines (exemples) |
|---|---|---|---|
10.10.0.0/24 |
100 | Infrastructure réseau | fw-01 .1 ; sw-core-01 .2 ; sw-acces-01 .3 |
10.10.1.0/24 |
101 | Administration des hyperviseurs | pve-01 .11 ; pve-02 .12 ; pve-03 .13 |
10.10.2.0/24 |
102 | Serveurs de production | app-01 .11 |
10.10.3.0/24 |
103 | Services internes | dns-01 .11 ; dns-02 .12 ; dhcp-01 .13 ; glpi-01 .21 ; zabbix-01 .22 ; vault-01 .23 ; ntfy-01 .24 |
10.10.4.0/24 |
104 | Accès et sécurité | vpn-01 .11 ; crowdsec-01 .12 |
10.10.5.0/24 |
105 | Postes des collaborateurs | DHCP de .100 à .199 |
10.10.6.0/24 |
106 | Wi-Fi invités | DHCP de .100 à .199, réseau isolé |
10.10.7.0/24 |
107 | DMZ | proxy-01 .11 |
10.10.8.0/24 |
108 | Sauvegarde | bkp-01 .11 |
10.10.250.0/24 |
350 | Pool VPN des nomades | Adresses attribuées par OpenVPN |
Adresses publiques : pare-feu fw-01 en 198.51.100.2, proxy-01 en 198.51.100.10, vpn-01 en 198.51.100.11.
Nébuleuse
| Machine | Adresse d'administration | Adresse publique | Nom |
|---|---|---|---|
| Serveur Ansible | 10.99.0.2 |
aucune | ansible-01.nebuleuse.example |
| Bastion Teleport | 10.99.0.3 |
192.0.2.5 |
bastion.nebuleuse.example |
client-alpha (Atelier Penhoat) |
10.99.0.21 |
192.0.2.21 |
sso., cloud., photos., vault. + penhoat.example |
client-beta (Cabinet Kerjean) |
10.99.0.22 |
192.0.2.22 |
sso., cloud., vault. + kerjean.example |
Le client numéro n reçoit 10.99.0.(20 + n) et 192.0.2.(20 + n). Un troisième client aurait donc 10.99.0.23 et 192.0.2.23.
Le réseau d'administration 10.99.0.0/24 n'est accessible que depuis 10.10.1.0/24 (administration des hyperviseurs), à travers le pare-feu fw-01.
Kerlann Agglomération
Réseau 10.20.0.0/16. Le troisième octet identifie le site.
| Troisième octet | Site | Réseau | Usage |
|---|---|---|---|
| 0 | Siège | 10.20.0.0/24 |
Infrastructure réseau : fw-sie-01 .1 ; sw-sie-core-01 .2 |
| 1 | Siège | 10.20.1.0/24 |
Serveurs : dc-sie-01 .11 ; dc-sie-02 .12 ; fs-sie-01 .21 ; hv-sie-01 .31 ; hv-sie-02 .32 ; mail-sie-01 .41 |
| 2 | Siège | 10.20.2.0/24 |
Postes administratifs |
| 3 | Siège | 10.20.3.0/24 |
Impression et téléphonie |
| 4 | Siège | 10.20.4.0/24 |
Wi-Fi |
| 5 | Siège | 10.20.5.0/24 |
Gestion des équipements (commutateurs, onduleurs) |
| 10 à 15 | Mairies | 10.20.10.0/24 à 10.20.15.0/24 |
Kerven (10), Lannaron (11), Trévenan (12), Plouvelen (13), Saint-Gweltaz (14), Kerdalec (15) |
| 20 et 21 | École du Menez | 10.20.20.0/24 et 10.20.21.0/24 |
Administratif et pédagogique ; serveur srv-emn-01 en 10.20.20.11 |
| 22 et 23 | École de Kersaint | 10.20.22.0/24 et 10.20.23.0/24 |
Idem ; serveur srv-eks-01 en 10.20.22.11 |
| 24 et 25 | École des Genêts | 10.20.24.0/24 et 10.20.25.0/24 |
Idem ; serveur srv-egn-01 en 10.20.24.11 |
| 250 | Nomades | 10.20.250.0/24 |
Pool VPN des agents en déplacement |
| 254 | Interconnexions | 10.20.254.0/24 |
Liens VPN site à site, un /30 par site distant |
Le serveur d'une école porte une seconde adresse de passerelle sur son réseau pédagogique (par exemple 10.20.21.1 pour le Menez) et y sert le DHCP.
Adresses publiques : pare-feu 203.0.113.2, extrémité VPN 203.0.113.3, proxy de messagerie 203.0.113.10. Les communes et les écoles sortent par le siège et n'ont pas d'adresse publique propre.
Page suivante : Domaines et nommage.
Domaines et nommage
En bref
Niveau : référence
Durée de lecture : 4 minutes
Prérequis : « Entités et domaines »
Pourquoi des règles de nommage ?
Un nom bien construit se lit comme une adresse : le rôle, le site et le numéro de la machine apparaissent sans consulter l'inventaire. Les règles ci-dessous s'appliquent à toutes les pages.
Les machines
| Périmètre | Règle | Exemples |
|---|---|---|
| Hôtes d'Erminig | <rôle>-<nn>, domaine erminig.example |
dns-01.erminig.example, glpi-01.erminig.example |
| Hôtes de Kerlann | <rôle>-<site>-<nn> ; domaine ad.kerlann.example pour les machines jointes à l'annuaire |
dc-sie-01, fs-sie-01, srv-emn-01 |
| Hôtes de Nébuleuse | client-<nom> dans l'inventaire Ansible |
client-alpha, client-beta |
| Conteneurs | <client>_<service> |
alpha_traefik |
Codes de site de Kerlann : sie (siège), kev (Kerven), lan (Lannaron), tre (Trévenan), plo (Plouvelen), sgw (Saint-Gweltaz), kdl (Kerdalec). Pour les écoles : emn (Menez), eks (Kersaint), egn (Genêts).
Les préfixes Nébuleuse
| Élément | Règle | Exemple |
|---|---|---|
| Variables Ansible | nebuleuse_* |
nebuleuse_apps |
| Jails Fail2ban | nebuleuse-<service> |
nebuleuse-nextcloud |
| Répertoire de travail | /opt/nebuleuse |
|
| Secrets chiffrés | vault_* |
vault_authentik_secret_key |
Les comptes
| Type | Règle | Exemple |
|---|---|---|
| Administrateur | adm-<nom> |
adm-alex |
| Compte de service | svc-<outil> |
svc-backup |
| Support Erminig | prénom fictif | camille |
L'annuaire de Kerlann et le modèle AGDLP
L'annuaire est central et mutualisé entre Kerlann et ses communes : forêt ad.kerlann.example, nom NetBIOS KERLANN. Les droits suivent le modèle AGDLP : les comptes (Accounts) entrent dans des groupes globaux (Global), qui entrent dans des groupes de domaine local (Domain Local), lesquels reçoivent les droits (Permissions) sur les dossiers.
Organisation de l'annuaire : une unité d'organisation racine ENTITES, puis une unité par entité (KERLANN, KERVEN, LANNARON, etc.) contenant deux sous-unités, GG et GDL.
OU=GG,OU=KERLANN,OU=ENTITES,DC=ad,DC=kerlann,DC=example
| Type de groupe | Règle | Exemple |
|---|---|---|
| Global (GG), par service | <ENTITE>_GG_<SERVICE> |
KERLANN_GG_FINANCE |
| Domaine local (GDL), par dossier et par droit | <ENTITE>_GDL_<numéro-répertoire>_<droit> |
KERVEN_GDL_02-01_ECRITURE |
<ENTITE> vaut KERLANN ou le nom de la commune en majuscules. Le droit vaut VUE, LECTURE ou ECRITURE.
Les secrets et les paramètres régionaux
Tout secret d'exemple a la forme FICTIF-<usage>-<n>, par exemple FICTIF-db-motdepasse-1. Aucune valeur n'est réelle. Fuseau horaire : Europe/Paris. Langue : fr_FR.
Un nom ou une adresse absent de la Charte ne doit pas apparaître dans une page. En cas de besoin, la Charte est complétée d'abord.
Page suivante : Niveaux de test.
Niveaux de test
En bref
Niveau : référence
Durée de lecture : 2 minutes
Prérequis : aucun
Pourquoi afficher un niveau de test ?
Une documentation qui affirme tout avoir testé se discrédite à la première erreur. Chaque page indique donc, dans l'encadré « En bref », ce qui a réellement été fait. Aucune page n'affirme un test qui n'a pas eu lieu.
| Niveau | Signification |
|---|---|
| Testé | Rejoué de bout en bout sur des machines de laboratoire, avec les sorties réelles et la version indiquée |
| Reconstitué | Procédure issue d'un cas réel, rebâtie avec des données fictives mais non rejouée ici |
| Illustratif | Exemple pédagogique, non exécuté |
Le cas des environnements Windows
Les pages Active Directory, GPO, Hyper-V et Exchange décrivent des procédures utilisées en production. Elles sont au niveau Reconstitué : les scripts et les étapes viennent de cas réels, avec des noms, des groupes et des données entièrement fictifs. Les captures d'écran sont refaites ou nettoyées pour ne rien révéler.
Quel livre documente quel environnement
| Livre | Environnement fictif | Niveau visé |
|---|---|---|
| Nébuleuse (Ansible, Traefik, Authentik, Teleport…) | Serveur Ansible, bastion, clients alpha et beta | Testé (deux VM Debian 12) |
| Proxmox | Hyperviseurs pve-01 à pve-03 d'Erminig |
Testé ou Reconstitué |
| DNS et DHCP | dns-01, dns-02, dhcp-01 d'Erminig |
Testé |
| OpenVPN | vpn-01 d'Erminig, lien site à site vers Kerlann |
Testé |
| Teleport | Bastion partagé par Erminig et Nébuleuse | Testé |
| Vaultwarden | vault-01 d'Erminig |
Testé |
| Fail2Ban, CrowdSec | proxy-01 en DMZ chez Erminig |
Testé |
| GLPI | glpi-01 : service desk d'Erminig, une entité par client |
Testé |
| Active Directory, GPO | dc-sie-01 et dc-sie-02 de Kerlann |
Reconstitué |
| Hyper-V | hv-sie-01 et hv-sie-02 de Kerlann |
Reconstitué |
| Samba | fs-sie-01 de Kerlann |
Testé |
| Zimbra | mail-sie-01 de Kerlann |
Reconstitué |
| Edubuntu, OpenLDAP | srv-emn-01 (École du Menez), puis les deux autres écoles |
Testé après reconstruction sur des versions actuelles |
| Alcatel | Commutateurs du siège de Kerlann | Reconstitué (équipement physique) |
| Nextcloud, Docker | Applications de Nébuleuse et services d'Erminig | Testé |
Le niveau « visé » devient le niveau réel une fois la procédure rejouée. D'ici là, la page affiche Reconstitué.
Page suivante : Gabarit de page.
Gabarit de page
En bref
Niveau : référence
Durée de lecture : 4 minutes
Prérequis : aucun
Pourquoi un gabarit ?
Toutes les pages techniques suivent le même plan. Le lecteur sait où trouver le principe, les commandes et les pièges, quel que soit le livre. Cette page décrit ce plan et les règles d'écriture.
Le plan d'une page
| Ordre | Élément | Contenu |
|---|---|---|
| 1 | Titre | Un titre de niveau 1, court et orienté tâche |
| 2 | Encadré Information « En bref » | Niveau, durée, prérequis, niveau de test |
| 3 | « X, c'est quoi ? » | Le principe en quelques phrases |
| 4 | Tableau Composant / Rôle | Les éléments en jeu et leur rôle |
| 5 | Schéma en une ligne | Le flux de bout en bout, en gras, avec des flèches |
| 6 | Contraintes ou étapes | Liste numérotée |
| 7 | Fichiers et commandes | Blocs de code commentés |
| 8 | Pièges | Les erreurs rencontrées et leur correction |
| 9 | Vérification | Comment confirmer que le résultat est bon |
| 10 | Page suivante | Un renvoi vers la suite logique |
Les encadrés
Les encadrés sont créés avec le menu Légendes > Informations de l'éditeur BookStack. Ils servent à deux usages :
- L'encadré « En bref », placé juste sous le titre. Il contient quatre lignes (niveau, durée, prérequis, niveau de test), la première en gras comme titre.
- Les remarques, placées là où elles sont utiles : une précision, une mise en garde légère, un renvoi. Elles s'écrivent directement, sans préfixe « Note ».
En bref
Niveau : intermédiaire
Durée : 30 minutes
Prérequis : un serveur Debian 12, accès SSH
Niveau de test : testé sur Debian 12 (voir « Niveaux de test »)
Les règles d'écriture
| Règle | Détail |
|---|---|
| Ton impersonnel | Pas de « tu », de « vous » ni de « je » dans les pages techniques. La première personne est réservée aux pages d'accueil. |
| Une page, une tâche | Au-delà d'environ 1 500 mots utiles, la page est découpée |
| Termes anglais | Les termes techniques restent en anglais (playbook, reverse proxy, jail) |
| Code commenté | Chaque bloc de code est précédé d'une phrase qui dit ce qu'il fait et pourquoi |
| Données fictives | Noms, adresses et secrets viennent de la Charte |
| Honnêteté | Le niveau de test affiché correspond à ce qui a été fait |
Une page de présentation de livre est unique : une seule page remplace les séries de pages génériques (« À quoi ça sert ? », « Pourquoi l'utiliser ? »…).
Vérifier une page avant publication
- Le plan ci-dessus est respecté.
- Aucun nom, aucune adresse ni aucun secret ne sort de la Charte.
- Le niveau de test est exact.
- Les blocs de code sont valides et commentés.
- Les captures d'écran ne montrent aucune information réelle.
Page suivante : retour à la page Bienvenue, ou premier livre de l'étagère Base de connaissance.