Contexte

ZNC est un bouncer IRC (BNC) avancé qui reste connecté aux serveurs IRC
en permanence, même lorsque l’utilisateur est déconnecté. Il conserve
l’historique des messages, maintient la présence sur les canaux, et permet à
plusieurs clients IRC de se connecter simultanément au même compte.
Contrairement aux clients IRC classiques, ZNC centralise la connexion et partage l’état
entre tous les clients connectés (web, mobile, desktop).

Actuellement, ZNC 1.8.2 (paquet Debian 11) tourne comme un service systemd
(znc.service) sur l’ancien serveur dédié ({{IP_ANCIEN}},
{{HOSTNAME_ANCIEN}}) sous l’utilisateur _znc, avec ses données dans
/home/znc/.znc/ (2,4 Go, 4 utilisateurs actifs).
On migre vers Docker Compose sur le nouveau serveur ({{IP_NOUVEAU}}, {{HOSTNAME_NOUVEAU}},
SSH port {{PORT_SSH_NOUVEAU}}), où tournent déjà Odoo 17, Odoo 8, Akeneo PIM, ownCloud,
TeamSpeak 3 et EmuLinker.

Architecture cible : 1 conteneur Docker (image officielle znc:1.10.1)
avec port 4353/tcp exposé directement (pas de reverse proxy).
ZNC utilise le même port pour les connexions IRC et l’interface web admin.
La migration inclut une mise à jour de ZNC 1.8.2 vers 1.10.1 (dernière version stable).
ZNC gère automatiquement la migration du format de configuration znc.conf
au premier démarrage.

1) Diagnostiquer l’installation actuelle

Première étape : se connecter à l’ancien serveur et identifier la version
de ZNC, le port d’écoute, le répertoire de données, et l’utilisateur système.

Pourquoi ce diagnostic ? Avant la migration, nous devons connaître
la version actuelle (pour comprendre l’ampleur de la mise à jour vers 1.10.1),
le port d’écoute (pour le reproduire dans Docker), et l’emplacement des données
(configuration, certificats, logs de buffer). Ces informations garantissent une migration
complète sans perte de données.

1.1 Résumé de l’installation

Résumé de notre installation :

• Version : ZNC 1.8.2+deb2+deb11u1 (paquet Debian 11, mise à jour vers 1.10.1)
• Répertoire de données : /home/znc/.znc/ (2,4 Go)
• Port d’écoute : 4353 (TCP, port personnalisé, SSL activé)
• Interface web : AllowWeb = true sur le même port (intégrée dans ZNC)
• Utilisateur système : _znc (utilisateur Debian par défaut pour ZNC)
• Service : znc.service (systemd, enabled)
• Processus : /usr/bin/znc -f --datadir=/home/znc/.znc
• Modules globaux : identfile, adminlog, log
• Réseau IRC : QuakeNet (193.27.78.5:6667 — euroserv.fr.quakenet.org)
• Certificat SSL : znc.pem (mai 2015, utilisé pour cert + clé + DH)
• Utilisateurs ZNC : 4 ({{ZNC_USER_1}}, {{ZNC_USER_2}}, {{ZNC_USER_3}}, {{ZNC_ADMIN}}) — 17 répertoires dans users/ dont certains inactifs
• Administrateur : {{ZNC_ADMIN}} (seul user avec Admin = true)
• Mots de passe : SHA-256 (seront migrés en Argon2id par ZNC 1.10.1)
• Mémoire utilisée : 11,4 Mo

1.2 Fichiers critiques à préserver

• configs/znc.conf — configuration complète (4 utilisateurs actifs, réseaux IRC,
  canaux, modules activés, paramètres SSL)
• znc.pem — certificat SSL auto-signé du bouncer (mai 2015, connexions client → ZNC)
• znc.pem.old — ancien certificat (backup)
• users/ — répertoires utilisateur (logs de buffer, certificats clients, paramètres individuels)
• moddata/ — données des modules (logs persistés, notes, historique de commandes)
• modules/ — modules compilés personnalisés (répertoire présent mais probablement vide)

Tout le répertoire ~/.znc/ doit être copié :
ZNC stocke non seulement la configuration dans znc.conf, mais aussi l’historique
des messages (buffers), les certificats SSL, les données des modules, et les paramètres
utilisateur. Copier uniquement znc.conf résulterait en une perte de l’historique
et nécessiterait de recréer le certificat SSL.

2) Créer la structure des répertoires Docker

Sur le nouveau serveur :

• data/ — sera monté comme /znc-data dans le conteneur (tout le répertoire ZNC)
• backup/ — pour stocker les exports temporaires de l’ancien serveur

Docker Compose v2 : si ce n’est pas déjà fait lors des migrations
précédentes (Odoo, TeamSpeak, EmuLinker), installer Docker Compose v2 avec
apt install docker-compose-plugin. Les commandes utilisent docker compose
(avec espace) au lieu de docker-compose (avec tiret).

3) Créer le docker-compose.yml

Contenu :

Points clés :

• znc:1.10.1 — image officielle Docker de ZNC, dernière version stable.
  Mise à jour depuis ZNC 1.8.2 (Debian 11)
• ports: "4353:4353" — port personnalisé configuré dans notre znc.conf
  (le port standard IRC SSL est 6697, mais notre installation utilise 4353)
• ./data:/znc-data — bind mount pour toutes les données ZNC (configuration,
  utilisateurs, certificats, modules, logs)
• Pas de network_mode: host — contrairement à EmuLinker, ZNC n’a besoin
  que d’un ou deux ports TCP, le NAT Docker est acceptable

Port personnalisé : notre installation utilise le port 4353
(au lieu du port standard 6697). Ce port est défini dans znc.conf (section
) et doit correspondre au mapping dans docker-compose.yml.

Mise à jour automatique de la configuration : on utilise directement
l’image znc:1.10.1 même si l’ancien serveur tourne une version plus ancienne.
ZNC gère la migration de configuration automatiquement au premier démarrage —
il met à jour le format de znc.conf si nécessaire et crée
un backup znc.conf.pre-1.10.1 de l’ancienne version. Aucune intervention manuelle requise.

4) Exporter les données depuis l’ancien serveur

Arrêter ZNC avant l’export : ZNC écrit les fichiers de configuration
et les buffers sur disque lors d’un arrêt propre. Copier les fichiers pendant que ZNC tourne
peut donner une configuration incohérente (buffers tronqués, fichiers en cours d’écriture).
Utiliser systemctl stop znc ou znc --quit pour un arrêt propre,
jamais kill -9.

5) Transférer via rsync

Depuis le nouveau serveur :

Durée estimée : 2,4 Go entre serveurs OVH (réseau interne ~1 Gbps),
le transfert prend moins d’une minute.

6) Adapter la configuration pour Docker

Après le transfert, vérifier certains paramètres de configuration
pour s’assurer qu’ils sont compatibles avec l’environnement Docker.

Paramètres à vérifier :

1. Port d’écoute (section Listener) — doit correspondre au mapping Docker
2. Adresse IP d’écoute (BindHost) — supprimer l’ancienne IP si présente
3. SSL — vérifier que SSL reste activé
4. Chemins SSL absolus (critique) — supprimer les 3 lignes SSLCertFile,
   SSLDHParamFile, SSLKeyFile qui pointent vers /home/znc/.znc/
   (chemin inexistant en Docker)

6.1 Port d’écoute

Chercher la section dans znc.conf :

Le port 4353 doit correspondre à celui exposé
dans docker-compose.yml ("4353:4353").
Ne pas le changer sauf si on veut migrer vers un port différent.

AllowIRC + AllowWeb : notre Listener accepte
à la fois les connexions IRC (clients bouncers) et les connexions web (interface admin)
sur le même port 4353. C’est le comportement standard de ZNC.

6.2 Adresse IP d’écoute (BindHost)

Vérifier qu’il n’y a pas de ligne BindHost = {{IP_ANCIEN}} (ancienne IP)
dans la section :

BindHost et Docker : si BindHost est configuré avec
l’ancienne IP ({{IP_ANCIEN}}), le supprimer ou le remplacer par 0.0.0.0.
En Docker, ZNC doit écouter sur toutes les interfaces (0.0.0.0) pour que le port mapping
fonctionne. Une ancienne IP bloquerait les connexions entrantes.

6.3 SSL activé

Vérifier que SSL = true dans la section Listener.
Notre installation utilise SSL sur le port 4353. Le certificat znc.pem (mai 2015)
est copié automatiquement avec le rsync. Il continuera à fonctionner même après
la mise à jour vers ZNC 1.10.1.

6.4 Chemins SSL (critique)

La configuration de l’ancien serveur contient des chemins absolus pour le certificat SSL :

Ces chemins n’existent pas dans le conteneur Docker.
En Docker, le répertoire de données est /znc-data/ (pas /home/znc/.znc/).
Si ces lignes restent inchangées, ZNC ne démarrera pas :
Unable to load certificate.

Correction : supprimer ces 3 lignes de znc.conf.

Pourquoi supprimer plutôt que corriger ?
Quand ces lignes sont absentes, ZNC utilise automatiquement
/znc.pem comme certificat, clé et paramètres DH.
Le conteneur Docker définit --datadir=/znc-data, donc ZNC trouvera
le certificat à /znc-data/znc.pem — exactement là où le rsync
l’a copié. Pas besoin de coder le chemin en dur.

Migration 1.8.2 → 1.10.1 : au premier démarrage avec ZNC 1.10.1,
le bouncer mettra à jour automatiquement le format de znc.conf.
Un backup de l’ancien fichier est créé automatiquement (znc.conf.pre-1.10.1).
Les mots de passe sont migrés de SHA-256 vers Argon2id (si disponible).

7) Ouvrir les ports dans le firewall

Sur l’ancien serveur, 3 règles firewall étaient configurées pour ZNC.
Sur le nouveau serveur, seul le port principal est nécessaire :

Résultat attendu :

7.1 Règles de l’ancien serveur (pour référence)

L’ancien serveur avait 3 règles firewall pour ZNC :

• ACCEPT TCP 4353 0.0.0.0/0 (znc-Bouncer) — port d’écoute ZNC.
  À recréer sur le nouveau serveur
• ACCEPT TCP 6667 193.27.78.5 (znc-Quakenet-euroserv.fr.quakenet.org) —
  autorise les connexions depuis le serveur IRC QuakeNet.
  Pas nécessaire sur le nouveau serveur : les connexions vers QuakeNet
  sont sortantes (initiateées par ZNC), gérées par le conntrack du firewall
• ACCEPT TCP 113 0.0.0.0/0 (znc-Ident) — protocole ident (RFC 1413),
  utilisé par le module identfile.
  Optionnel : voir note ci-dessous

Port 113 (ident) en Docker : le module identfile chargé
dans notre znc.conf écrit un fichier .oidentd.conf pour que
le démon oidentd réponde aux requêtes ident des serveurs IRC.
En Docker, oidentd n’est pas installé dans le conteneur.
Si aucun serveur IRC n’exige de réponse ident (QuakeNet ne l’exige pas pour les bouncers),
cette règle n’est pas nécessaire.

Utiliser MyVestaCP CLI : toujours utiliser les commandes MyVestaCP
(v-add-firewall-rule, v-update-firewall) pour modifier le firewall,
jamais iptables directement. Les règles ajoutées avec iptables
seraient perdues au prochain redémarrage du serveur.

8) Arrêter l’ancien ZNC

Avant de démarrer le nouveau serveur Docker, arrêter définitivement l’ancien
pour éviter les conflits de connexion :

9) Démarrer ZNC Docker

Retour sur le nouveau serveur :

Vérifier que le conteneur est en cours d’exécution :

Vérifier que le port est bien en écoute :

Résultat attendu :

Premier démarrage après mise à jour : au premier démarrage
après la migration vers ZNC 1.10.1, le bouncer peut prendre quelques secondes supplémentaires
pour migrer la configuration vers le nouveau format. Les logs afficheront des messages indiquant
la conversion de znc.conf. C’est normal.

10) Tester la connexion

Tester que ZNC répond correctement sur le port configuré :

Interface web admin : l’interface web admin de ZNC est accessible sur le même
port que les connexions IRC. Ouvrir https://{{IP_NOUVEAU}}:4353 dans un navigateur
(accepter le certificat auto-signé). Notre configuration a AllowWeb = true
dans le Listener, donc l’interface web est active.
Se connecter avec le compte admin {{ZNC_ADMIN}}.

Module webadmin non chargé : notre znc.conf
ne charge pas le module webadmin globalement. L’interface web basique fonctionne
(login, changement de mot de passe), mais pour l’administration complète (gestion des utilisateurs,
réseaux, modules), ajouter dans la section globale de znc.conf :
LoadModule = webadmin. Alternativement, l’utilisateur {{ZNC_ADMIN}} a le module
controlpanel chargé, qui permet l’administration via des commandes IRC
(/msg *controlpanel help).

11) Configurer les clients IRC

Mettre à jour la configuration des clients IRC pour pointer vers le nouveau serveur :

11.1 Paramètres de connexion

• Serveur : {{IP_NOUVEAU}} (ou nom de domaine si configuré)
• Port : 4353
• SSL : activé
• Mot de passe : utilisateur:motdepasse (format ZNC standard)
• Nom d’utilisateur : utilisateur (ou utilisateur/réseau
  pour se connecter à un réseau spécifique)

11.2 Mise à jour DNS (si applicable)

Nom de domaine : si un domaine est configuré pour ZNC
(exemple : {{DOMAINE_IRC}} ou bouncer.example.com),
mettre à jour l’enregistrement DNS A vers {{IP_NOUVEAU}}.
Après propagation DNS (quelques minutes à quelques heures), les clients
pourront se connecter via le nom de domaine au lieu de l’IP.

11.3 Accepter le certificat SSL

Le certificat ZNC est auto-signé (znc.pem, mai 2015).
Les clients IRC qui étaient connectés à l’ancien serveur ont déjà accepté
ce certificat. Seule l’adresse IP change — les clients devront confirmer
le certificat pour la nouvelle IP.

Certificat ancien : le certificat date de 2015. Il est recommandé
de le regénérer après la migration avec
docker compose exec znc /opt/znc/bin/znc --makepem. Les clients devront accepter
le nouveau certificat une seule fois.

12) Désactiver définitivement l’ancien serveur

Une fois la migration validée et tous les clients connectés au nouveau serveur :

---

Dépannage

ZNC ne démarre pas : « Permission denied »

Cause : le conteneur ZNC officiel tourne avec l’UID 1000.
Sur l’ancien serveur, les fichiers appartiennent à _znc (UID variable selon
le système). Après le rsync, les UID ne correspondent peut-être pas.

Cette étape sera probablement nécessaire : sur l’ancien serveur,
les fichiers appartiennent à _znc (UID Debian). L’image Docker officielle
utilise UID 1000. Le chown est quasi-obligatoire après le transfert.

Erreur SSL : « Unable to load certificate »

Cause la plus probable : les chemins SSL absolus dans znc.conf
pointent vers l’ancien répertoire (/home/znc/.znc/znc.pem) qui n’existe pas
dans le conteneur Docker.

« Invalid Password » après la migration

Symptôme : la connexion SSL réussit (TLSv1.3), ZNC répond,
mais le mot de passe est rejeté avec « Invalid Password ».
Les logs Docker ne montrent aucune erreur.

Causes possibles :

• Migration SHA-256 → Argon2id : ZNC 1.10.1 tente de migrer les hash
  de mots de passe de SHA-256 (1.8.2) vers Argon2id. Si la migration échoue silencieusement,
  les hash deviennent invalides
• Format d’authentification client : le client IRC doit envoyer le mot de passe
  au format utilisateur:motdepasse (ou utilisateur/réseau:motdepasse)
  dans le champ « Server Password »
• Mot de passe oublié : si le mot de passe n’a pas été utilisé
  depuis longtemps, il peut simplement être oublié

Solution — regénérer le mot de passe :

Alternative via le web admin : si le module webadmin est chargé,
on peut changer le mot de passe directement depuis l’interface web
(https://{{IP_NOUVEAU}}:4353) sans éditer znc.conf manuellement.
Mais il faut d’abord pouvoir se connecter — d’où la méthode manuelle ci-dessus.

Les clients ne peuvent pas se connecter

Causes possibles :

• Le firewall bloque le port
• Le port dans docker-compose.yml ne correspond pas à celui dans znc.conf
• BindHost est configuré avec l’ancienne IP

Le panel web admin ne répond pas

Cause : le module webadmin n’est pas activé dans znc.conf.

Ajouter dans la section globale (avant les sections ) :

Redémarrer ZNC :

Erreur : « Config file version mismatch »

Cause : ZNC 1.10.1 détecte le format 1.8.2 de znc.conf
et tente de le migrer automatiquement. Ce n’est normalement pas une erreur bloquante.

---

Récapitulatif de l’architecture finale

Liste complète des ports utilisés :

• 8069/8169/8269/8369 — Odoo 17 (via reverse proxy)
• 8469 — Odoo 8 (via reverse proxy)
• 8480 — Akeneo PIM (via reverse proxy)
• 8490 — ownCloud (via reverse proxy)
• 9987/udp + 9988/udp — TeamSpeak 3 voix (direct)
• 10011/tcp — TeamSpeak 3 ServerQuery (localhost seulement)
• 30033/tcp — TeamSpeak 3 transfert fichiers (direct)
• 27886-27944/udp — EmuLinker Kaillera (direct, host network)
• 54715-54730/udp — EmuLinker P2P (direct, host network)
• 4353/tcp — ZNC IRC bouncer + web admin (direct)

---

À suivre

ZNC est maintenant opérationnel en Docker avec la dernière version stable (1.10.1).
Dans les prochains articles :

• Counter-Strike 1.6 en Docker — migration du serveur de jeu CS 1.6
• Sauvegardes automatisées — stratégie de backup pour tous les services Docker
• Monitoring et alertes — surveillance centralisée des conteneurs