Installation hors ligne
Cette page installe navin-manager dans un réseau bancaire sans accès à Internet. Les mêmes étapes valent en ligne : seule l'origine des archives change.
1. Prérequis
| Élément | Exigence |
|---|---|
| Hôte de la console | Famille RHEL 8, 9 ou 10 (RHEL, Rocky Linux, AlmaLinux, Oracle Linux 8/9, CentOS Stream 9/10) avec python3.12, ou Ubuntu 24.04 avec python3.12. Ubuntu 22.04 n'est qu'un hôte géré : il ne fournit aucun Python 3.11 ou plus récent maintenu. 4 CPU, 8 Go de mémoire, 50 Go pour le miroir. |
| Hôtes gérés | Systèmes certifiés : RHEL 8/9/10, Rocky Linux 8/9/10, AlmaLinux 8/9/10, Oracle Linux 8/9, CentOS Stream 9/10, Ubuntu 22.04/24.04, Debian 12, Arch Linux (rolling). Une version plus récente de ces familles (par exemple Ubuntu 26.04, Debian 13, Oracle Linux 10) ou une dérivée d'Arch Linux (Manjaro, EndeavourOS) passe les vérifications préalables avec un avertissement ; une version en fin de vie (CentOS 7 et 8, RHEL 7, Ubuntu 20.04 et antérieures, Debian 11 et antérieures) ou une autre famille est bloquée. x86_64 ou aarch64. Python 3.9 ou plus récent, openssl, tar, une horloge synchronisée (chronyd ou systemd-timesyncd). Podman 4 ou plus récent pour la méthode podman. Pare-feu de l'hôte : l'agent ouvre les ports publics avec firewalld ou ufw ; avec vos propres règles nftables ou iptables, ouvrez les ports indiqués par les vérifications préalables à l'installation. |
| Base de la console | PostgreSQL 14 ou plus récent exploité par la banque dans son propre cluster, une base navin_manager, un rôle navin_manager qui la possède, TLS avec l'autorité de la banque. |
| Certificats | Un certificat serveur pour l'hôte de la console (PKI de la banque), avec le nom DNS utilisé par les opérateurs et les agents. |
| Réseau | Opérateurs vers la console sur 8460/tcp ; hôtes gérés vers la console sur 8460/tcp (enregistrement) et 8461/tcp (API agent et miroir). Rien ne s'ouvre vers les hôtes gérés. |
2. Construire le bundle hors ligne (hors de la banque)
Sur un hôte de construction relié à Internet, depuis une copie de navin-manager :
navin-manager/server/.venv/bin/python navin-manager/packaging/offline/build-bundle.py \
--catalog navin-manager/catalog --out /srv/navin-bundle/mirror \
--services all --methods binary,podman,python --arch x86_64 --python-versions 3.9,3.11,3.12 \
--gpg-key release@bank.example
Le constructeur télécharge chaque archive nommée par le catalogue, la vérifie avec le fichier d'empreintes publié
par son projet, enregistre les images de conteneurs avec podman save et note leur empreinte, télécharge les paquets
Python et écrit manifest.json avec le sha256 de chaque fichier. Une archive sans empreinte publiée est refusée,
sauf avec --trust-on-first-download ; le manifeste garde alors la trace de ce choix pour l'entrée concernée. Le
résultat comprend bundle.tar, bundle.tar.sha256 et, avec --gpg-key, une signature détachée.
Derrière un proxy d'entreprise, définissez NM_MIRROR_PROXY=http://proxy.bank.example:3128 (et NM_MIRROR_NO_PROXY
avec les hôtes joints directement, par exemple nexus.bank.example,.bank.internal) ou passez --proxy et
--no-proxy. Le proxy porte les téléchargements des archives et des empreintes, pip download et podman pull ;
sans lui, les variables standard https_proxy et no_proxy s'appliquent. Les agents et la console n'utilisent
jamais de proxy : ils se parlent directement.
Pour les hôtes sans accès à un dépôt de paquets, ajoutez --os-repo (avec --gpg-key), et la méthode package si
elle sert, sur une machine de la version des hôtes (par exemple Ubuntu 24.04) :
navin-manager/server/.venv/bin/python navin-manager/packaging/offline/build-bundle.py \
--catalog navin-manager/catalog --out /srv/navin-bundle/mirror \
--services all --methods binary,podman,python,package --os-repo \
--gpg-key release@bank.example
Le constructeur ajoute alors dans os/<id>-<version>-<arch>/ un dépôt signé des paquets système dont les méthodes
choisies ont besoin : podman (avec uidmap sur Debian et Ubuntu), tar, chaque interpréteur Python et son module
venv, les paquets de la méthode package et ceux de --os-packages, avec toutes leurs dépendances pour un hôte
minimal. Sur la famille Debian, InRelease est signé et l'index donne le sha256 de chaque paquet ; sur la famille
RHEL, repodata/repomd.xml.asc signe l'index et chaque paquet garde la signature de son éditeur, vérifiée par
rpmkeys --checksig pendant la construction. Pour une autre version d'hôte (par exemple RHEL 9), copiez le
répertoire --out sur une machine de cette version et relancez la construction avec le même --out : les dépôts
intacts des passes précédentes sont conservés. --os-apt-option et --os-dnf-option désignent les sources des
téléchargements, par exemple le miroir interne de la banque. Une fois le miroir chargé, l'agent d'un hôte de cette
version installe les prérequis et les paquets de la méthode package depuis ce dépôt seul, sans jamais désactiver une
vérification de signature ; un hôte d'une autre version, ou un paquet absent du dépôt, passe par les dépôts
configurés sur l'hôte.
Les paquets de l'agent recommandent podman (et uidmap sur Debian et Ubuntu) : apt et dnf les installent avec
l'agent quand les dépôts de l'hôte les proposent. Un agent sans root (bac à sable) n'installe aucun paquet système :
la validation d'une installation podman indique alors la commande à lancer sur l'hôte.
Construisez les paquets de navin-manager et de l'agent avec navin-manager/packaging/build-packages.sh (voir
packaging/README.fr.md (navin-manager/packaging/README.fr.md)) : le RPM du serveur se construit dans un environnement RHEL
avec python3.12 (un seul RPM pour la famille RHEL 8, 9 et 10), le DEB du serveur sur Ubuntu 24.04, les paquets de
l'agent n'importe où.
3. Transférer et vérifier
Copiez bundle.tar, son empreinte, sa signature et les paquets selon la procédure de transfert de la banque, puis
sur l'hôte de la console :
sha256sum -c bundle.tar.sha256
gpg --import navin-bundle.pub
gpg --verify bundle.tar.asc bundle.tar
Le bundle se décompresse dans le répertoire du miroir une fois le serveur installé (étape 7), où
verify-bundle.py contrôle la taille et le sha256 de chaque fichier par rapport à manifest.json.
4. Installer le serveur
RHEL, Rocky, AlmaLinux :
dnf install ./navin-manager-1.0.0-1.el9.x86_64.rpm
Ubuntu 24.04 :
apt install ./navin-manager_1.0.0_amd64.deb
Arch Linux (le paquet dépend du Python d'Arch Linux pour lequel il a été construit ; pacman -S postgresql d'abord
pour une base locale) :
pacman -U ./navin-manager-1.0.0-1-x86_64.pkg.tar.zst
Le paquet crée l'utilisateur système navin-manager, l'environnement applicatif dans /opt/navin-manager, le
catalogue dans /usr/share/navin-manager/catalog, les migrations SQL dans /usr/share/navin-manager/sql, la console
dans /usr/share/navin-manager/ui, /var/lib/navin-manager, /var/log/navin-manager et l'unité systemd
navin-manager.service.
5. Configurer
Modifiez /etc/navin-manager/server.yaml (chaque clé se surcharge par NM_<CLÉ> dans /etc/navin-manager/server.env) :
| Clé | Valeur |
|---|---|
database_url | postgresql://navin_manager@<db-host>:5432/navin_manager?sslmode=verify-full&sslrootcert=/etc/navin-manager/tls/postgresql-ca.pem. Placez le mot de passe dans server.env (NM_DATABASE_URL, mode 0640) ou dans ~navin-manager/.pgpass, jamais dans server.yaml. |
tls_cert_file, tls_key_file | Certificat et clé de la console. |
public_url | URL de la console, par exemple https://<manager-host>:8460. |
agent_url | URL de l'API agent, par exemple https://<manager-host>:8461. |
NM_METRICS_TOKEN | Dans server.env : 32 caractères ou plus, utilisé par Prometheus pour lire /metrics. |
mirror_url, registry | Facultatifs : un Nexus ou un Artifactory de la banque qui contient l'arborescence du miroir, un registre Harbor, Quay ou Nexus qui contient les images. Sans eux, les agents utilisent le miroir local de la console. |
Le paquet a créé la clé maître /etc/navin-manager/master.key (32 octets aléatoires, propriété de navin-manager,
mode 0600). Vérifiez les réglages, puis démarrez le serveur (l'unité applique les migrations de la base avant de
servir) :
navin-manager check
systemctl enable --now navin-manager
Gardez une copie de /etc/navin-manager/master.key dans le coffre de la banque : tous les secrets stockés en
dépendent. navin-manager check liste chaque réglage qui interdit un démarrage en production (TLS, certificats
clients, attribut du cookie, jeton de métriques, coût scrypt, clé maître, sslmode).
6. Première connexion
Ouvrez https://<manager-host>:8460 et connectez-vous avec navin et le mot de passe initial que le paquet a
écrit dans /etc/navin-manager/server.env (NM_ADMIN_PASSWORD). Ce mot de passe ne sert qu'une fois : la console
demande aussitôt votre propre mot de passe (au moins 12 caractères, minuscules, majuscules, chiffres et symboles).
Mot de passe perdu :
navin-manager reset-admin
Dans Administration, Authentification, reliez le LDAP ou l'Active Directory de la banque, ou un fournisseur OIDC (Keycloak, Entra ID), associez les groupes aux rôles et ajustez la politique de sécurité.
7. Charger le miroir
Décompressez le bundle vérifié (il contient le répertoire mirror/), contrôlez chaque fichier et confiez-le au
compte de service :
tar -xf /media/transfer/bundle.tar -C /var/lib/navin-manager
python3 /usr/share/navin-manager/packaging/verify-bundle.py --mirror /var/lib/navin-manager/mirror
chown -R navin-manager:navin-manager /var/lib/navin-manager/mirror
Puis, dans Administration, Miroir, choisissez Recharger (ou appelez POST /api/v1/mirror/reload?verify=true). La
page liste les services dont des archives manquent dans le miroir : ils ne s'installent pas tant qu'un bundle qui les
contient n'est pas chargé.
Signature du manifeste (manifest.json.sig)
Par défaut (NM_MIRROR_SIGNATURE=required), le serveur refuse un manifest.json sans signature Ed25519 détachée
manifest.json.sig valide : erreur mirror_manifest_unsigned (pas de signature) ou
mirror_manifest_signature_invalid (manifeste ou signature modifié, clé inconnue). Le contrôle a lieu au chargement
et de nouveau à chaque livraison aux agents : un manifeste remplacé après le chargement est refusé. Sans cette
signature, quiconque peut écrire dans le miroir remplace une archive et son empreinte.
- Construction :
build-bundle.py ... --sign-key /chemin/securise/mirror-signing.pem(clé privée Ed25519 PEM, jamais dans le bundle). Créer la clé :openssl genpkey -algorithm ed25519 -out mirror-signing.pempuisopenssl pkey -in mirror-signing.pem -pubout -out mirror-signing.pub.pem. - Clés de confiance du serveur : fichier PEM
NM_MIRROR_TRUSTED_KEYS_FILEet/ou réglage du Hubhub.trusted_keys_pem. - Contrôle hors serveur :
verify-bundle.py --mirror ... --trusted-keys mirror-signing.pub.pem. - Migration d'un miroir existant non signé : vérifiez-le (
verify-bundle.py --mirror) puissign-manifest.py --mirror /var/lib/navin-manager/mirror --sign-key mirror-signing.pem, et rechargez. Le temps de la migration seulement,NM_MIRROR_SIGNATURE=unsigned-allowedaccepte un manifeste sans signature ; chaque chargement est alors tracé dans l'audit (mirror.reload,signature.status = unsigned). verify-bundle.py --strictrefuse aussi les images sans digest épinglé dans le catalogue (trust: first-download).
8. Ajouter les hôtes
Créez un cluster, puis ajoutez des hôtes de l'une des deux façons suivantes.
Paquet de l'agent. Dans Hôtes, Ajouter des hôtes, créez un jeton d'amorçage. Installez l'agent sur chaque hôte et lancez la commande d'enregistrement affichée par la console (elle contient le jeton et l'empreinte sha256 de l'autorité de la console). L'agent livré est le binaire Go statique (aucun Python sur l'hôte, voir Agent d'hôte) ; prenez le paquet de l'architecture de l'hôte :
dnf install ./navin-manager-agent-go-1.0.0-1.x86_64.rpm
nm-agent register --server https://<manager-host>:8460 --token <token> --ca-sha256 <fingerprint>
systemctl enable --now navin-manager-agent
Sur Ubuntu, utilisez apt install ./navin-manager-agent-go_1.0.0_amd64.deb, sur Arch Linux
pacman -U ./navin-manager-agent-go-1.0.0-1-x86_64.pkg.tar.zst. L'agent Python
(navin-manager-agent-1.0.0-1.noarch.rpm, navin-manager-agent_1.0.0_all.deb,
navin-manager-agent-1.0.0-1-any.pkg.tar.zst, Python 3.9 ou plus récent) reste fourni et utilise la même commande,
la même configuration et la même unité.
Amorçage SSH. Indiquez les noms d'hôtes, un utilisateur SSH, la clé privée et l'empreinte SHA256 de la clé de chaque hôte. La console vérifie chaque empreinte, copie le paquet de l'agent depuis le miroir, l'installe et enregistre l'hôte. La clé reste en mémoire pendant l'opération et n'est jamais stockée.
Les contrôles préalables d'un hôte s'affichent dès son enregistrement : système, architecture, mémoire, CPU, disques, horloge, SELinux, systemd, Podman, OpenSSL, Python, limite de fichiers ouverts.
9. Installer la plateforme
Dans Clusters, Installer des services, choisissez les services, placez leurs composants sur les hôtes (l'assistant affiche les règles de placement de chaque mode et les vérifie en direct), reliez chaque dépendance à un service géré ou à une connexion existante (le PostgreSQL de la banque en production), relisez la configuration (les valeurs recommandées viennent des faits des hôtes) et lancez l'installation. La page de l'opération affiche chaque étape et les journaux en direct de chaque tâche.
10. Servir les paquets depuis un dépôt local
Sur un site sans accès aux dépôts Navin, servez les paquets du bundle depuis un dépôt local pour que dnf, apt et
pacman les résolvent comme n'importe quel autre paquet. <version> est la version publiée, par exemple 1.0.0.
RHEL, Rocky Linux, AlmaLinux, Oracle Linux, CentOS Stream (createrepo_c vient du miroir RHEL de votre organisation) :
dnf install -y createrepo_c
mkdir -p /srv/repo/navin && cp /var/lib/navin-manager/mirror/agent/*.rpm navin-manager-*.rpm /srv/repo/navin/
createrepo_c /srv/repo/navin
printf '[navin]\nname=Navin Enterprise\nbaseurl=file:///srv/repo/navin\ngpgcheck=0\nenabled=1\n' > /etc/yum.repos.d/navin.repo
dnf install -y navin-manager-agent-go
Résultat attendu : dnf repolist affiche navin. Passez à gpgcheck=1 dès que les paquets sont signés avec la clé
RPM de votre organisation (rpmsign --addsign).
Ubuntu, Debian :
mkdir -p /srv/repo/navin && cp *.deb /srv/repo/navin/ && cd /srv/repo/navin
dpkg-scanpackages --multiversion . > Packages && gzip -k -f Packages
echo 'deb [trusted=yes] file:/srv/repo/navin ./' > /etc/apt/sources.list.d/navin.list
apt-get update && apt-get install -y navin-manager-agent-go
Résultat attendu : apt-cache policy navin-manager-agent-go montre le dépôt local.
Arch Linux : pacman -U installe directement les fichiers des paquets ; le dépôt signé [navin] produit par
os/repo.sh peut aussi être copié sur un serveur web interne, sa section SigLevel = Required DatabaseRequired
refuse un paquet non signé.
En cas d'échec : dnf ou apt ne peut pas lire le répertoire quand SELinux ou les droits l'interdisent : lancez
restorecon -R /srv/repo/navin et donnez-lui le mode 0755.
11. Archives hors ligne de l'installateur guidé
os/build.sh install-archive [debian|rhel|arch] construit une archive par famille,
navin-install-<version>-<famille>.tar.gz avec son .sha256 : l'installateur, les paquets de cette famille avec leur
SHA256SUMS, le guide. Copiez l'archive avec son empreinte, puis :
sha256sum -c navin-install-<version>-rhel.tar.gz.sha256
tar xzf navin-install-<version>-rhel.tar.gz && cd navin-install-<version>-rhel
sudo ./navin-install preflight manager
L'installateur vérifie les paquets avec SHA256SUMS avant chaque installation et ne change rien tant qu'un contrôle
échoue. Les étapes figurent dans Installer le Navin Manager.
12. Dépannage
| Symptôme | Cause | Correction |
|---|---|---|
sha256sum -c signale FAILED | le fichier a été altéré pendant le transfert | copiez-le de nouveau depuis l'hôte de construction |
gpg --verify signale BAD signature | le bundle ou la clé diffère de celui qui a été signé | arrêtez : vérifiez l'origine du bundle et de navin-bundle.pub |
| La page Miroir liste des artefacts manquants | le bundle ne contient pas ces services ou ces méthodes | construisez un bundle qui les contient (--services, --methods) et chargez-le |
Une installation s'arrête avec artifact_missing | le miroir n'a pas l'artefact de cette version | chargez le bundle de cette version, puis Recharger le manifeste |
Une tâche échoue avec checksum_mismatch | le fichier du miroir diffère de manifest.json | lancez verify-bundle.py --mirror, puis dépaquetez de nouveau le bundle vérifié |
La validation refuse la méthode podman avec podman_missing | l'agent tourne sans root (bac à sable), ou l'hôte n'a ni dnf, ni apt-get, ni pacman | lancez sur l'hôte la commande donnée par le message (par exemple sudo apt-get install -y podman uidmap), puis actualisez les faits de l'hôte |
apt-get update ou dnf échoue sur le dépôt navin-os | un fichier du dépôt embarqué a changé ou sa signature ne correspond pas à la clé du bundle | lancez verify-bundle.py --mirror, dépaquetez de nouveau le bundle vérifié, puis Recharger le manifeste |