CraftFileGate

CraftFileGate est un serveur de fichiers : un client SFTP, un script HTTP ou un navigateur y deposent et y prennent des fichiers, que le serveur range sur un ou plusieurs stockages. Il remplace un serveur SFTP classique (ProFTPD, OpenSSH internal-sftp) quand les fichiers ne vivent pas tous sur un disque local, ou quand les comptes viennent d’un fournisseur d’identite.

Ce qu’il fait

Les mots du guide

Le chapitre Utilisateurs, roles et montages les explique avec des exemples.

Demarrage rapide

Un serveur sur un disque local, un utilisateur alice qui ne voit que son repertoire.

1. Generer une cle d’hote

ssh-keygen -t ed25519 -f /etc/craft-file-gate/host_ed25519 -N ""

Une cle listee dans host_keys mais absente refuse le demarrage.

2. Ecrire la configuration

Creer /etc/craft-file-gate/config.toml :

#:schema ./config.schema.json
[server]
shutdown_grace_period_secs = 30
# max_sessions_per_user = 10  # optionnel, illimite par defaut

[sftp]
listen = "0.0.0.0:2222"
host_keys = ["/etc/craft-file-gate/host_ed25519"]
# login_grace_secs = 120      # connexion non authentifiee coupee au-dela (0 = jamais)

[auth]
jwt_sentinel_username = "jwt"
timeout_secs = 5
# roles_file = "/etc/craft-file-gate/roles.toml"  # optionnel, sinon [[roles]] inline
# authz_base_url = "https://authz.internal"  # optionnel, service de mapping distant

[auth.jwt]
secret = "changez-moi-en-production"
# public_key_file = "/etc/craft-file-gate/jwt_public.pem"  # alternative au secret
# jwks_url = "https://idp.interne/.well-known/jwks.json"   # alternative : cles du fournisseur d'identite
# jwks_refresh_interval_secs = 3600                        # defaut, minimum 1
# username_path = "/sub"       # defaut
# authorities_path = "/groups" # defaut

[auth.methods]
jwt   = { enabled = true }
# Mot de passe et cle publique sont les preuves du magasin local, pas des
# methodes a part : elles se declarent sous `local`.
local = { enabled = true, password = true, pubkey = true }

[admin]
listen = "127.0.0.1:8080"
bearer_token = "changez-moi-en-production"

[log]
level = "info"
format = "json"

# ── Stockage et droits ──
[[backends]]
name = "local"
type = "local"
root = "/srv/sftp"

[[roles]]
name = "utilisateurs"

[[roles.mounts]]
backend = "local"
home_dir = "/{username}"   # alice voit /srv/sftp/alice comme sa racine /
create_home = true

[[roles.mounts.acl]]
path = "/"
rights = ["read", "write", "list", "delete", "rename"]
recursive = true

# ── Utilisateurs locaux ──
[[users]]
username = "alice"
# mot de passe : changez-moi-en-production
password_hash = "$argon2id$v=19$m=19456,t=2,p=1$QzIrOEdtBZI4UL4ddXDbkg$yudDYsZSLamFZHWeKlFpFWtkP4kX6ALV8GNKs3pEXBk"
# authorized_keys = ["ssh-ed25519 AAAA... alice@poste"]
authorities = ["utilisateurs"]

Le secret JWT, le jeton admin et le mot de passe d’alice (changez-moi-en-production) sont publics. Le serveur demarre avec, mais emet un WARN par valeur d’exemple encore en place. Pour remplacer le bloc [[users]] d’alice :

echo -n "mot-de-passe" | craft-file-gate hash-password --user alice

Le processus doit pouvoir ecrire dans /srv/sftp : create_home y cree alice/ a sa premiere connexion.

3. Lancer le serveur

craft-file-gate --config /etc/craft-file-gate/config.toml

Pour Docker et Kubernetes, voir le guide (« Exploiter »).

4. Se connecter

sftp -P 2222 alice@votre-serveur

ls montre le contenu de /srv/sftp/alice, et rien au-dessus.

Et ensuite

Utilisateurs, roles et montages

utilisateur ──authorities──▶ role ──▶ montage ──▶ backend (stockage)
                                       │
                                       └── ACL (droits par chemin)

Aucun droit n’est implicite : un backend que nul role ne monte n’est visible par personne, et le jeton d’administration ne donne acces a aucun fichier.

Un exemple complet

[[backends]]                 # un stockage, decrit une fois
name = "disque"
type = "local"
root = "/srv/sftp"

[[roles]]
name = "utilisateurs"

[[roles.mounts]]             # au moins un par role
backend = "disque"           # un nom de [[backends]]
home_dir = "/{username}"     # ou le montage commence sur le stockage
create_home = true

[[roles.mounts.acl]]         # les droits, relatifs au montage
path = "/"
rights = ["read", "write", "list", "delete", "rename"]
recursive = true

[[users]]
username = "alice"
password_hash = "$argon2id$..."   # craft-file-gate hash-password
authorities = ["utilisateurs"]    # les roles d'alice

alice voit / ; ce / est /srv/sftp/alice sur le disque.

Les cles d’un role et d’un montage

Toutes les cles, avec leur rechargement : Reference [[roles]], [[roles.mounts]].

Ou vont les fichiers

Un chemin client va au montage dont le mount_path le prefixe le plus longuement ; le reste s’ajoute a home_dir, sur le stockage (ce que home_dir designe sur chaque type). .. ne remonte jamais au-dessus de home_dir.

{username} : un repertoire par utilisateur

home_dir = "/{username}" donne a chaque utilisateur son repertoire, avec un seul role. Le nom, jamais nettoye, est fait de A-Z a-z 0-9 . _ -, 1 a 64 caracteres, sans point en tete.

Un montage ou plusieurs

Les chemins entre les montages sont des repertoires synthetiques. Un renommage reste dans son montage.

Cumuler des roles

Un utilisateur a souvent plusieurs roles. Sa session a les montages de tous.

Deux montages differents d’un meme backend ont des home_dir disjoints (/a et /b, pas / et /a) : chaque fichier n’est atteint que sous une ACL.

La doctrine : un role a / est complet

• un role a / est complet : il donne a lui seul tout ce que voit son utilisateur, et ne se cumule avec aucun autre ;
• un role fait pour se cumuler monte sous un nom (/archives).

Voir les recettes.

D’ou viennent les roles

Les roles sont toujours definis dans [[roles]] ou roles_file. Seules les authorities qui ne sont pas des noms de roles vont au service.

Le contrat du service d’autorisation

POST <authz_base_url>/authz/resolve
Content-Type: application/json

{"authorities": ["CN=ACME-Partners,OU=Groups"]}

Reponse attendue : 200 et

{"roles": ["partenaire-acme"]}

authz_base_url et timeout_secs : Reference [auth].

Les roles nommes s’ajoutent a ceux trouves localement ; un nom que [[roles]] ne definit pas est ignore, et un service en panne laisse les roles locaux.

Une session SFTP construit tous ses backends a l’authentification et garde ses montages jusqu’a sa fin, meme apres un rechargement ; une requete REST construit celui du montage qu’elle atteint.

Ce que vous verrez

Un role qui monte plusieurs backends detient leurs credentials : gardez-le en lecture seule, pour un utilisateur dedie authentifie par cle.

Recettes de montages

Chaque recette suppose ce backend :

[[backends]]
name = "disque"
type = "local"
root = "/srv/sftp"

1. Un repertoire par utilisateur

[[roles]]
name = "utilisateurs"

[[roles.mounts]]
backend = "disque"
home_dir = "/{username}"
create_home = true
acl = [{ path = "/", rights = ["read", "write", "list", "delete", "rename"], recursive = true }]

alice voit / = /srv/sftp/alice, cree a sa premiere connexion. Un role a / ne se cumule pas.

2. Un partenaire : depot entrant, releve sortante

Le partenaire depose dans /in sans pouvoir relire, et releve dans /out.

[[roles]]
name = "partenaire-acme"

[[roles.mounts]]
backend = "disque"
home_dir = "/partenaires/acme"
max_file_mb = 500
hidden_stores = { enabled = true, prefix = ".in.", extension = "" }
acl = [
  { path = "/in", rights = ["write", "list"], recursive = true },
  { path = "/out", rights = ["read", "list", "delete"], recursive = true },
]

/in est /srv/sftp/partenaires/acme/in ; un envoi y est publie a la fin du transfert.

Pour que ls / montre in et out, ajoutez une entree non recursive : path = "/", rights = ["list"].

3. Le compte d’exploitation : tous les stockages, en lecture

Un compte qui voit chaque backend a la racine et ne peut rien modifier.

[[backends]]
name = "archives"
type = "s3"
bucket = "archives"
region = "eu-west-3"
prefix = "sftp/"
credentials = { type = "iam_role" }

[[backends]]
name = "acme-amont"
type = "sftp"
host = "sftp.acme.example"
host_key_fingerprint = "SHA256:2hZbXq1b5Xb3vN2mQ6w7l3Fv0tXk4yJ8aUeYp9rS0cE"   # ssh-keygen -lf, verifie hors bande
auth = { type = "password", username = "relais", password = "changez-moi" }

[[roles]]
name = "exploitant"

[[roles.mounts]]
backend = "disque"
mount_path = "/disque"
acl = [{ path = "/", rights = ["read", "list"], recursive = true }]

[[roles.mounts]]
backend = "archives"
mount_path = "/archives"
acl = [{ path = "/", rights = ["read", "list"], recursive = true }]

[[roles.mounts]]
backend = "acme-amont"
mount_path = "/acme-amont"
home_dir = "/depot"
acl = [{ path = "/", rights = ["read", "list"], recursive = true }]

[[users]]
username = "exploitation"
password_hash = "$argon2id$..."   # d'un mot de passe aleatoire, jete : seule la cle sert
authorized_keys = ["ssh-ed25519 AAAA... exploitation@poste"]
authorities = ["exploitant"]

ls / montre acme-amont archives disque ; /archives/2024/x est la cle S3 sftp/2024/x.

Au demarrage, INFO role mounts several backends: ... donne role=exploitant et writable=[] : verifiez-le apres chaque modification du role.

4. Des roles qui se cumulent

[[roles]]
name = "equipe-a"
[[roles.mounts]]
backend = "disque"
mount_path = "/equipe-a"
home_dir = "/equipes/a"
acl = [{ path = "/", rights = ["read", "list"], recursive = true }]

[[roles]]
name = "equipe-b"
[[roles.mounts]]
backend = "disque"
mount_path = "/equipe-b"
home_dir = "/equipes/b"
acl = [{ path = "/", rights = ["read", "write", "list"], recursive = true }]

Un jeton dont la claim groups vaut ["equipe-a", "equipe-b"] ouvre une session avec /equipe-a (lecture) et /equipe-b (lecture et ecriture).

Deux roles sur le meme montage unissent leurs ACL : acme-depot (/in) et acme-releve (/out) sur le montage du cas 2 donnent /in et /out.

5. Des montages ranges : /partenaires/<nom>

Avec acme-amont du cas 3 :

[[roles]]
name = "gestion-partenaires"

[[roles.mounts]]
backend = "disque"
mount_path = "/partenaires/acme"
home_dir = "/partenaires/acme"
acl = [{ path = "/", rights = ["read", "list"], recursive = true }]   # "/" : la racine du montage

[[roles.mounts]]
backend = "acme-amont"
mount_path = "/partenaires/amont"
home_dir = "/depot"
acl = [{ path = "/", rights = ["read", "list"], recursive = true }]

/ et /partenaires sont synthetiques ; /partenaires/amont est le /depot de l’amont.

ACL

L’ACL d’un montage donne des droits, chemin par chemin ; tout le reste est refuse. Elle s’ecrit sous [[roles.mounts.acl]], et son path est relatif au montage.

Ecrire une ACL

[[roles.mounts]]
backend = "disque"
mount_path = "/partenaire"
home_dir = "/partenaires/acme"

[[roles.mounts.acl]]
path = "/"                    # /partenaire pour l'utilisateur
rights = ["list"]             # non recursive : ce dossier seulement

[[roles.mounts.acl]]
path = "/in"                  # /partenaire/in
rights = ["write", "list"]
recursive = true              # et tout ce qui est dessous

Toutes les cles : Reference [[roles.mounts.acl]].

Une ACL ne gouverne que son montage, meme sur un backend monte deux fois.

Les droits

Chaque operation demande son droit sur chaque chemin qu’elle nomme :

Un listage montre tout le repertoire, sans filtrer par l’ACL. list sur /in ne donne pas list sur /.

Quelle entree decide

1. Refus par defaut : un chemin qu’aucune entree ne gouverne est refuse.
2. L’entree la plus specifique decide : celle du chemin exact, sinon l’entree recursive la plus proche au-dessus.
3. Une entree plus specifique qui n’accorde pas le droit refuse, meme sous une entree plus large qui l’accorde.

[[roles.mounts.acl]]
path = "/"
rights = ["read", "write", "list", "delete", "rename"]
recursive = true

[[roles.mounts.acl]]
path = "/archives"
rights = ["read", "list"]
recursive = true

Ici tout est modifiable, sauf /archives et ce qu’il contient, en lecture.

Un deplacement est rejuge sur ce qu’il emporte : un dossier qui contient un sous-dossier protege ne se deplace pas vers un endroit gouverne par une entree plus large, ou le sous-arbre perdrait sa protection.

Plusieurs roles sur un montage

Deux roles sur le meme montage mettent leurs ACL ensemble :

• deux entrees au meme chemin unissent leurs droits, et une seule recursive rend l’union recursive ;
• a des chemins differents, l’entree la plus specifique decide, de quelque role qu’elle vienne.

Une entree etroite d’un role peut donc restreindre ce qu’une entree large d’un autre accordait. Le resultat se lit dans la console, onglet des roles d’une session (GET /admin/sessions/<id>/roles).

Repertoires synthetiques

Avec plusieurs montages sous des noms, un chemin sous aucun montage (/, /partenaires) est synthetique : il n’appartient a aucun backend.

Un point de montage (/partenaires/acme) se liste selon son ACL, mais ne s’ecrit, ne se supprime ni ne se renomme.

Casse des noms

Quand l’ACL d’un backend plie la casse (case_insensitive), /Archives et /archives sont un seul chemin : ecrivez-le une fois par montage.

Portes : SFTP, API REST, explorateur, console

Les portes de fichiers (SFTP, API REST, explorateur) partagent utilisateurs, roles, montages et ACL : un droit accorde l’est partout. La console d’administration n’ouvre aucun fichier. SFTP tient des sessions ; l’API REST n’en a pas, la console montre ses transferts longs en cours (son activite).

SFTP

[sftp]
listen = "0.0.0.0:2222"
host_keys = ["/etc/craft-file-gate/host_ed25519"]

• Seul le sous-systeme sftp est servi : ni shell, ni scp, ni exec, ni renvoi de ports ou d’agent.
• Par JWT : le nom sentinel (jwt par defaut) et le jeton en mot de passe, sftp -P 2222 jwt@serveur.
• Les cles : Porte SFTP et algorithmes SSH.

API REST de fichiers

[admin]
listen = "0.0.0.0:8080"
bearer_token = "changez-moi-en-production"

[api]
enabled = true
prefix = "/api/v1/files"

# lister un repertoire
curl -u alice:mot-de-passe 'http://serveur:8080/api/v1/files/in?list'
# deposer un fichier
curl -u alice:mot-de-passe -T rapport.csv http://serveur:8080/api/v1/files/in/rapport.csv
# telecharger
curl -u alice:mot-de-passe -o rapport.csv http://serveur:8080/api/v1/files/in/rapport.csv

Toutes les cles : Reference [api].

• Une credential par requete ; ni cookie, ni session.
• Un fichier telecharge part en attachment, Cache-Control: no-store, Content-Security-Policy: sandbox, Accept-Ranges: bytes. Une URL de ticket qui fuit telecharge ce fichier jusqu’a son expiration.

Explorateur web

[api.ui]
enabled = true
path = "/files"

Une page sur http://serveur:8080/files, cliente de l’API : memes identifiants, memes ACL. Voir Explorateur de fichiers.

Console et API d’administration

[admin]
listen = "127.0.0.1:8080"
bearer_token = "changez-moi-en-production"
# control_listen = "127.0.0.1:8081"   # une porte a part pour l'administration

La console est sur / de l’ecouteur admin : sessions et montages, bans, configuration sans secret, journaux, metriques, revocations. On s’y connecte par identifiant et mot de passe, ou avec un jeton. /metrics et les sondes sont sur le meme ecouteur, ou sur control_listen, ou sur [server] probes_listen : voir Une porte ou deux.

Ce que vous verrez

Les backends

Un backend est un stockage nomme, decrit une fois dans [[backends]] ; les montages le citent par son nom.

[[backends]]
name = "disque"        # le nom que citent les montages
type = "local"         # local, sftp, s3 ou webhdfs
root = "/srv/sftp"     # les cles propres au type

[[roles]]
name = "utilisateurs"

[[roles.mounts]]
backend = "disque"
home_dir = "/{username}"
acl = [{ path = "/", rights = ["read", "write", "list"], recursive = true }]

Les [[backends]] s’ecrivent dans config.toml ou dans roles_file, ou ils se rechargent a chaud avec les roles.

Les types

Les binaires et images publies portent les quatre types (Les features du binaire).

Les cles de tout backend

Toutes les cles : Reference [[backends]].

Une sous-table ([backends.auth], [backends.credentials]) se rattache au [[backends]] qui la precede : ecrivez-la juste apres lui. GET /admin/config et l’onglet Configuration montrent chaque backend, secrets remplaces par ***.

Cles communes a tous les types

Ce qu’elles font sur chaque type est dans la page du type ; leur defaut et leur effet, dans la meme Reference.

hidden_stores se resout montage, puis backend, puis [server.hidden_stores] ; stale_partials backend, puis [uploads.stale_partials] ; cle par cle (Uploads).

Reservation entre instances

Le premier envoi vers une destination la garde jusqu’a sa fin (pourquoi). Entre instances, c’est un verrou <lock_prefix><nom> pose a cote de la destination. lock_prefix :

• fait de 8 caracteres a 64 octets, sans / ni caractere de controle ;
• nomme aussi les noms jetables du serveur (PPnew.<jeton>, PPprobe., PPstale. pour un prefixe P) ;
• reserve au serveur tout nom qui commence par lui, sans egard a la casse, comme .craftfilegate-upload... : choisissez-en un qu’aucun fichier des utilisateurs ne porte.

Disponibilite

Chaque instance visite chaque backend en arriere-plan ([server.backend_probe]) : up, down apres failures_before_down visites en echec, unknown avant la premiere ; un WARN a chaque changement (Depannage), l’etat dans GET /admin/health, la vue Instances et craftfilegate_backend_up (Metriques). Sur S3, une visite est un ListObjectsV2 facture, toutes les 15 s par instance par defaut.

Local

Le backend local sert un repertoire du systeme de fichiers du serveur, sa racine (root). Chaque montage y a son sous-repertoire, home_dir.

[[backends]]
name = "disque"
type = "local"
root = "/srv/sftp"

[[roles]]
name = "utilisateurs"

[[roles.mounts]]
backend = "disque"
home_dir = "/{username}"
create_home = true
acl = [{ path = "/", rights = ["read", "write", "list", "delete", "rename"], recursive = true }]

alice envoie /rapport.txt : le fichier est /srv/sftp/alice/rapport.txt.

Les cles

Toutes les cles : Reference [[backends]] type = “local” ; cles communes : Les backends.

La racine et les liens symboliques

Aucune operation ne sort de root + home_dir du montage, quels que soient les liens qui s’y trouvent, y compris ce que le serveur fait lui-meme (fichier en cours, verrou, balayage). Un lien vers le home_dir d’un autre montage sort autant qu’un lien hors de la racine.

• Un lien se liste comme un lien (type l ; "is_symlink": true en REST), ou, suivi, comme sa cible. Supprimer ou renommer agit sur le lien.
• Avec hidden_stores, un envoi sur un lien de fichier remplace le lien ; la cible reste intacte.
• Aucune porte ne cree de lien : ils viennent d’un autre processus ou d’une restauration.
• La racine et ses ancetres sont de confiance (une racine a travers un lien est suivie) : inscriptibles par l’administrateur seul.
• Sur un volume partage (NFS…), montez la racine nosymfollow (Linux 5.10 et plus).

Casse des chemins de l’ACL

Sur un stockage qui confond les majuscules (NTFS, APFS et HFS+ par defaut, SMB/CIFS, ext4 ou tmpfs casefold), l’ACL compare les chemins plies : NFD, retrait des points de code ignorables (U+200B…), pliage de casse complet (straße = strasse), NFC.

La sonde cree un fichier en minuscules et le cherche en majuscules dans chaque repertoire ou une entree se resout (le pliage se regle par repertoire, chattr +F) : un repertoire qui plie fait plier le backend, ce qui ne tranche pas plie. Un repertoire absent ou sous {username} n’est pas sonde, et un volume APFS sensible a la casse reste insensible a la normalisation : dans le doute, case_insensitive = true.

La ou l’ACL plie, et sur un serveur Windows, un nom court 8.3 (PROTEG~1) ou fini par . ou une espace n’est pas un chemin valide : desactivez les noms courts (fsutil 8dot3name).

Les cles communes sur un backend local

Le processus agit sous son propre uid ; le mode des fichiers suit son umask.

Sur Linux 5.6 et plus, le noyau impose le confinement (openat2(2), RESOLVE_BENEATH) ; sans openat2, chaque composante est ouverte O_NOFOLLOW (dit une fois en INFO) ; sous Windows, le parent est verifie juste avant l’appel.

Performances et limites

• Un renommage et la publication d’un envoi utilisent RENAME_NOREPLACE. La ou le systeme de fichiers ne l’a pas (NFS, FUSE dont sshfs, 9p), ils retombent sur rename(2) : un ecrasement concurrent n’y est pas detecte, et l’audit d’un envoi qui ecrase dit replaced=unknown.
• Aucun fsync : un succes ne promet pas la durabilite sur disque.
• mkdir cree un niveau ; les parents manquants d’un envoi sont crees un par un, chacun juge par l’ACL.
• La suppression d’un arbre n’est pas comptee : l’audit dit removed=unknown.

Ce que vous verrez

Proxy SFTP

Le backend sftp range les fichiers sur un serveur SFTP amont, joint en SSH sous un compte de service que les utilisateurs ne connaissent pas.

[[backends]]
name = "acme-amont"
type = "sftp"
host = "sftp.acme.example"
host_key_fingerprint = "SHA256:2hZbXq1b5Xb3vN2mQ6w7l3Fv0tXk4yJ8aUeYp9rS0cE"   # verifiee hors bande

[backends.auth]
type = "password"
username = "relais"
password = "changez-moi"

[[roles]]
name = "acme"

[[roles.mounts]]
backend = "acme-amont"
home_dir = "/depot"
acl = [{ path = "/", rights = ["read", "write", "list"], recursive = true }]

Un client du role acme envoie /f.txt : le fichier est /depot/f.txt sur l’amont.

Les cles

Toutes les cles : Reference [[backends]] type = “sftp” ; cles communes : Les backends. Authentification par cle :

[backends.auth]
type = "private_key"
username = "relais"
private_key_pem = """
-----BEGIN OPENSSH PRIVATE KEY-----
...
-----END OPENSSH PRIVATE KEY-----
"""

Preferez une cle ed25519 ou ECDSA. Une cle RSA signe en rsa-sha2-512 ou rsa-sha2-256 selon server-sig-algs, ssh-rsa (SHA-1) en dernier recours.

La cle d’hote de l’amont

Le proxy verifie la cle d’hote de l’amont avant de s’authentifier : sans cela, un intermediaire recevrait les identifiants du compte de service. L’empreinte :

ssh-keyscan -p 22 sftp.acme.example | ssh-keygen -lf -

• Epinglez l’empreinte ED25519, a defaut ECDSA, a defaut RSA : c’est l’ordre dans lequel le proxy negocie.
• Verifiez-la hors bande : sur l’amont, ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub.
• sha256: en minuscules et le bourrage = final sont acceptes.
• Une cle presentee sous forme de certificat est jugee sur la cle qu’il certifie.
• Rotation : une empreinte par backend ; changez-la a la bascule, le rechargement des roles l’applique aux connexions suivantes.

Les envois

Avec hidden_stores.enabled = true, un envoi ecrit dans un fichier en cours de transfert sur l’amont, a cote de la destination, puis le publie :

A l’etape 3, la destination manque le temps d’un aller-retour. Sans hidden_stores, l’envoi ecrit dans la destination, et la reprise et l’ajout sont servis (Uploads).

Le compte de service peut creer, renommer et supprimer dans le repertoire de destination. Un ecrasement remplace l’inode (mode, proprietaire, ACL, attributs etendus perdus) et occupe deux fois la place jusqu’a la publication.

Les cles communes sur un proxy SFTP

Performances et limites

• Lecture : une requete READ en vol par handle ; une lecture a la suite de la precedente est servie depuis le bloc deja lu. Un telechargement dans l’ordre lit le fichier environ une fois sur l’amont.
• Ecriture : des paquets aussi grands que l’amont les accepte, huit en vol.
• Une connexion SSH par session SFTP et par requete REST : la poignee de main pese sur les requetes REST courtes.
• Le proxy parle SFTP v3 (statuts 0 a 8), comme OpenSSH.
• Les liens de l’amont ne sont pas distingues : stat suit un lien, un listage ne marque aucune entree comme lien.

Ce que vous verrez

S3 et compatibles

Le backend s3 range les fichiers comme objets d’un bucket AWS S3 ou d’un stockage compatible (MinIO, Garage, Scaleway…).

[[backends]]
name = "archives"
type = "s3"
bucket = "archives"
region = "eu-west-3"
prefix = "sftp/"
endpoint_url = "https://minio.interne.example:9000"   # sans la cle : AWS

[backends.credentials]
type = "static"
access_key_id = "AKIAEXEMPLE"
secret_access_key = "changez-moi"

[[roles]]
name = "archivistes"

[[roles.mounts]]
backend = "archives"
home_dir = "/{username}"
acl = [{ path = "/", rights = ["read", "write", "list"], recursive = true }]

alice envoie /in/x.txt : l’objet est la cle sftp/alice/in/x.txt.

Les cles

Toutes les cles : Reference [[backends]] type = “s3”.

iam_role : variables AWS_*, profil, role de l’instance ou du pod. Cles communes : Les backends.

Fichiers et repertoires

Une cle et un repertoire du meme nom peuvent coexister, sauf avec refuse_upload_over_directory = true.

Un objet s’ecrit en entier : ni reprise (reput), ni ajout. Seul un fichier se renomme.

Les droits du bucket

Sur le bucket et <prefix>/* :

Un backend en lecture seule n’a besoin que de s3:ListBucket et s3:GetObject.

Les uploads multipart

Un upload multipart jamais complete reste facture jusqu’a son annulation :

• Donnez un prefix a chaque backend : le balayage ne travaille que sous lui.
• Un upload lent envoie une part vide toutes les 15 s, qui le date pour les autres instances ; celles-ci ont le meme uploads.idle_timeout_secs.
• Une regle de cycle de vie reste conseillee :

{"Rules": [{"ID": "abort-incomplete-multipart", "Status": "Enabled", "Filter": {"Prefix": ""},
            "AbortIncompleteMultipartUpload": {"DaysAfterInitiation": 2}}]}

Son delai, compte depuis l’initiation, depasse le plus long envoi. MinIO expire de lui-meme les uploads incomplets (stale_uploads_expiry).

Les ecritures conditionnelles

replaced dans l’audit et le marqueur de reservation reposent sur If-None-Match: * et If-Match de PutObject. Derriere un endpoint_url (et sur AWS avec cross_instance_reservation), le serveur les mesure au demarrage, sur la cle <prefix>/.craftfilegate-upload-precondition.<16 hex> ensuite supprimee ; le verdict tient jusqu’au redemarrage. MinIO : honoured.

Les cles communes sur S3

Performances et limites

• Chaque envoi en cours retient un tampon de 8 Mio (Memoire) ; ses ecritures sont sequentielles.
• Un envoi hors de la racine paie un listage par niveau parent.
• Le client adresse le bucket dans le chemin de l’URL (path-style), AWS compris.
• 10 000 parts au plus par objet, soit environ 78 Gio a 8 Mio la part.
• Sur un bucket versionne, l’auto-test laisse deux versions vides et un marqueur de suppression par demarrage.

Ce que vous verrez

WebHDFS (Knox)

Le backend webhdfs lit HDFS, en lecture seule, a travers WebHDFS d’Apache Knox : HTTPS, un compte de service en Basic, au nom de l’utilisateur (doAs). Knox porte Kerberos vers le cluster. Sert aussi un HttpFS ou un WebHDFS sans Kerberos ; Hadoop 2.8 et plus.

[[backends]]
name = "datalake"
type = "webhdfs"
url = "https://knox.example.com:8443/gateway/default"
auth = { type = "basic", username = "svc-sftp", password_file = "/run/secrets/knox-password" }
ca_bundle = "/etc/craft-file-gate/knox-ca.pem"   # la CA privee de Knox

[[roles]]
name = "analystes"

[[roles.mounts]]
backend = "datalake"
mount_path = "/datalake"
home_dir = "/data/projets"
acl = [{ path = "/", rights = ["read", "list"], recursive = true }]

alice lit /datalake/2026/x.csv : la requete vise <url>/webhdfs/v1/data/projets/2026/x.csv?op=OPEN&doAs=alice.

Les cles

Toutes les cles : Reference [[backends]] type = “webhdfs”.

La connexion a Knox s’ouvre en 5 s au plus ; HTTPS_PROXY n’est pas suivie. Cles communes : Les backends.

Le montage sur WebHDFS

Avec doAs, le nom d’utilisateur est fait de A-Z a-z 0-9 . _ -, 64 caracteres au plus.

hidden_stores, refuse_upload_over_directory, stale_partials, cross_instance_reservation et lock_prefix sont sans objet : rien n’est ecrit. case_insensitive : laissez-la absente, HDFS compare octet a octet.

Prerequis

Le droit de nommer un utilisateur (doAs), avec impersonate = true. Qui le donne depend de ce qui est derriere url :

<property>
  <name>hadoop.proxyuser.svc-sftp.hosts</name>
  <value>sftp-gateway.example.com</value>  <!-- d'ou il se presente -->
</property>
<property>
  <name>hadoop.proxyuser.svc-sftp.groups</name>
  <value>sftp-users</value>                <!-- pour qui il agit -->
</property>

Au demarrage, le serveur fait un GETFILESTATUS de la racine HDFS sous le compte de service, sans doAs, 5 s au plus.

Ce que fait le backend

• Lecture anticipee : 10 Mio lus par paquets SFTP de 32 Kio coutent 3 OPEN avec le defaut ; une lecture qui saute ne demande que sa taille.
• Listages : lus jusqu’au bout, plafonnes a 10 000 pages, 1 000 000 d’entrees et 64 Mio par reponse.
• Redirections : un 307 de Knox est suivi une fois, vers la meme origine (schema, hote, port) que url seulement.
• Une entree SYMLINK est montree comme un lien, et ne se lit pas ; HDFS compare les noms octet a octet, l’ACL aussi.

Performances et limites

• Knox est le goulot : chaque stat, page et plage est une requete HTTPS qu’il relaie au cluster. Les sessions d’un backend partagent un client HTTP.
• timeout_secs couvre une plage entiere : sur un lien lent, montez-le plutot que de baisser read_ahead_bytes.
• Les petits fichiers coutent chacun un GETFILESTATUS et un OPEN : ce backend sert a parcourir HDFS, pas de stockage courant.
• Le corps d’une erreur de Knox n’est jamais recopie dans un journal : seuls le nom de l’exception et le code.

Le fichier de configuration

Un fichier, nomme au lancement

craft-file-gate --config /etc/craft-file-gate/config.toml

-c est la forme courte. Seule [auth] est obligatoire, avec au moins un role et une porte : [sftp], ou [api] avec [admin]. Toutes les cles : la reference.

Decouper : users_file et roles_file

Les utilisateurs, les roles et les backends peuvent vivre a part. Ces fichiers se rechargent a chaud ; config.toml presque pas.

[auth]
users_file = "users.toml"   # les [[users]]
roles_file = "roles.toml"   # les [[roles]] et les [[backends]]

users_file et des [[users]] en ligne ne se cumulent pas : quand users_file est donne, lui seul est lu.

Les chemins relatifs

Un chemin relatif des fichiers que le serveur lit (host_keys, users_file, roles_file, public_key_file, les persist_file, la paire et le repertoire de [admin.tls]) part du repertoire de config.toml, pas du repertoire de lancement : une configuration et ses fichiers voyagent ensemble, y compris dans un conteneur. Les autres chemins (root d’un backend local, log.dir, les fichiers d’un backend WebHDFS) partent du repertoire de lancement : ecrivez-les absolus.

L’environnement

Une variable CRAFT_FILE_GATE_* remplace la cle qu’elle surcharge, apres la lecture du fichier, au demarrage comme a chaque rechargement : la liste est dans Variables d’environnement. Pour un secret, preferez la forme _FILE : un fichier lu une fois, juge comme un fichier de confiance.

Les outils du binaire

hash-password et verify-password ne lisent ni la configuration ni les secrets ; healthcheck lit les ecouteurs de --config, rien d’autre.

Ce que vous verrez

Verifier une configuration

config check applique a un fichier la validation du demarrage, sans demarrer : ni port ouvert, ni fichier cree, ni secret lu, ni reseau joint.

craft-file-gate config check /etc/craft-file-gate/config.toml
craft-file-gate config check config.toml --format json
craft-file-gate config schema > config.schema.json
craft-file-gate config explain sftp.ban.max_failures
craft-file-gate config effective /etc/craft-file-gate/config.toml

config check

Les variables d’environnement comptent comme au demarrage. Un secret (cle d’hote, _FILE, password_file, variable) est juge present, avec son proprietaire et son mode ; son contenu n’est pas lu. Restent au demarrage, dits en info : le JWKS, l’API Kubernetes, la sonde d’un stockage, l’amont SFTP, les fichiers de log, l’exporteur OTLP.

Une CI ou un assistant IA ecrit la configuration, lance config check --format json, corrige chaque error a l’aide de key et doc, recommence jusqu’a la sortie 0.

config schema

Le schema JSON (draft 2020-12) de config.toml, de users_file et de roles_file : types, defauts, bornes, valeurs permises, description de chaque cle, x-reload (rechargement), x-env (variables), x-doc (lien). Une cle inconnue y est refusee ; aucune n’y est exigee.

Une premiere ligne #:schema ./config.schema.json le donne a Taplo (Even Better TOML) : completion et soulignement dans l’editeur, comme dans config.example.toml. Le schema est a la racine du depot, joint a chaque release, et dans les images a /usr/share/craft-file-gate/config.schema.json ; config schema > config.schema.json l’ecrit a cote de la configuration.

config explain <cle>

Une cle : type, defaut, valeurs permises, rechargement (⟳), variables, effet, spec, lien vers sa section. --format json pour une machine ; une cle inconnue sort en 2 avec les plus proches.

config effective <fichier>

La configuration appliquee : le fichier, ses fichiers lies, les variables d’environnement, les defauts de la reference ; --format toml (par defaut) ou json. Chaque secret et chaque empreinte de mot de passe s’affichent ***, comme l’identifiant qui va avec un secret (access_key_id) et toute valeur d’une cle nommee comme un secret ou sous headers. Hors ligne comme config check, lance d’abord : une configuration refusee sort en 1 avec son constat.

Authentification

Deux sources, trois portes

Une connexion est authentifiee par une seule source, dont viennent ses roles. Un compte local alice et le sub alice d’un jeton sont deux utilisateurs distincts.

Choisir les methodes

[auth.methods]
jwt   = { enabled = false }
local = { enabled = true, password = true, pubkey = true }

Un deploiement en cles seules coupe le mot de passe :

local = { enabled = true, password = false, pubkey = true }

Les cles : [auth.methods].

Les comptes locaux

[[users]]
username = "alice"
password_hash = "$argon2id$v=19$m=19456,t=2,p=1$..."   # craft-file-gate hash-password
authorized_keys = ["ssh-ed25519 AAAA... alice@poste"]
authorities = ["utilisateurs"]                         # ses roles

Les cles : [[users]]. Dans users_file, ils se modifient sans redemarrer.

Les hashes

echo -n "mot-de-passe" | craft-file-gate hash-password              # le hash seul
echo -n "mot-de-passe" | craft-file-gate hash-password --user alice # un bloc [[users]]

Le mot de passe se lit sur stdin, jamais en argument. Le hash sort sur stdout, ses parametres sur stderr. L’onglet Hash tools de la console fait de meme dans le navigateur, sans envoyer le mot de passe.

Une verification coute ce que dit le hash stocke : le serveur ne re-hache jamais. Gardez un seul profil par fichier : un nom inconnu coute alors exactement le temps d’un mauvais mot de passe, et ne se devine pas au temps de reponse.

Les formats argon2 ($argon2id$, $argon2i$, $argon2d$) sont acceptes. Pour migrer d’un autre serveur sans connaitre les mots de passe, allow_sha512_crypt = true ou allow_bcrypt = true sous [auth.methods] local accepte aussi ces formats : Reference [auth.methods].

A chaque chargement du fichier, la ligne password hashes in use compte les comptes par format, et la metrique craftfilegate_local_users{hash_format} aussi : quand un format tombe a zero, retirez son drapeau. local.max_argon2_memory_kib (19456 : le m du profil owasp-min) nomme au chargement tout compte dont le hash demande plus, qui se connecte toujours : le re-hacher au profil par defaut le ramene sous le budget.

La verification se fait sur un pool de fils borne, hors du runtime : voir Verification des mots de passe.

La cle publique

Le client propose une cle, puis signe si elle est dans ses authorized_keys. Les cles proposees ne comptent pas : un agent SSH qui en essaie cinq avant la bonne ne se fait pas bannir ; une connexion qui finit sans s’authentifier, apres une cle declinee, compte un echec.

Les algorithmes de signature d’une cle

[sftp.algorithms] user_key dit les algorithmes permis a tous (voir Porte SFTP) ; ssh-rsa (SHA-1) n’y est pas par defaut. Un role peut en permettre d’autres a ses utilisateurs :

[[roles]]
name = "partenaire-ancien"
user_key_algorithms = ["ssh-rsa"]   # en plus de user_key

[[roles.mounts]]
backend = "disque"
home_dir = "/partenaire"

L’exception vaut pour tout utilisateur qui porte ce role, jamais pour un utilisateur seul. Seuls les roles des fichiers du serveur la donnent, pas ceux qu’atteint le service d’autorisation.

JWT

La methode jwt est active par defaut.

[auth.jwt]
secret = "remplacez-moi"     # ou CRAFT_FILE_GATE_JWT_SECRET_FILE
algorithm = "HS256"
username_path = "/sub"       # le nom de l'utilisateur
authorities_path = "/groups" # ses roles

Une source de cle, au choix : secret (HS256, HS384, HS512), public_key_file (la cle publique PEM de l’emetteur : RS256, RS384, RS512, ES256, ES384) ou jwks_url (le jeu de cles d’un fournisseur d’identite, chaque cle disant son algorithme). Les cles : [auth.jwt].

Un jeton est accepte si sa signature verifie, si exp est present et a venir, et si nbf, quand il est la, est passe (60 s de tolerance pour les deux). Avec issuer ou audience, la claim iss ou aud doit etre presente et egale. Le nom de l’utilisateur est lu a username_path, ses roles a authorities_path (un tableau de chaines).

Brancher un fournisseur d’identite (jwks_url)

[auth.jwt]
jwks_url = "https://idp.example.com/.well-known/jwks.json"
algorithm = "RS256"
jwks_refresh_interval_secs = 3600
issuer = "https://idp.example.com/"

L’age du cache est la jauge craftfilegate_jwks_cache_age_seconds : alertez dessus (voir Metriques).

Ce que vous verrez

Porte SFTP et algorithmes SSH

Un exemple

[sftp]
listen = "0.0.0.0:2222"
host_keys = ["/etc/craft-file-gate/host_ed25519"]

[server]
max_sessions_per_user = 10

[sftp] est optionnelle : sans elle, la porte SFTP est eteinte.

La cle d’hote se cree une fois, avant le premier demarrage :

ssh-keygen -t ed25519 -f /etc/craft-file-gate/host_ed25519 -N ""

Les cles de [sftp]

Toutes les cles : Reference [sftp] ; les delais : Delais.

[sftp.ban], [sftp.rate_limit] : Bans. Dans [server], communes a toutes les portes : max_sessions_per_user (sessions simultanees d’un meme nom, de toutes les instances avec [cluster]), shutdown_grace_period_secs (Arret), [server.hidden_stores] (Uploads).

La porte annonce les methodes password et publickey. Elle sert le seul sous-systeme sftp, une fois par connexion : ni shell, ni exec, ni renvoi de port.

Cles d’hote

Chaque cle chargee est annoncee avec son empreinte SHA256:..., celle que donne ssh-keygen -l et que voit un client a sa premiere connexion. GET /admin/config et l’onglet Configuration de la console donnent les memes.

generate_host_key cree la cle seulement si son fichier est absent, en 0600, et donne son empreinte. Un fichier present est relu tel quel : la cle ne change pas d’un demarrage a l’autre. Reservez-le a une instance unique sur un stockage persistant ; en Kubernetes, montez un Secret (voir Secrets).

Une entree en table choisit les algorithmes qu’une cle annonce, avec la syntaxe de [sftp.algorithms] appliquee a la liste host_key :

[sftp]
listen = "0.0.0.0:2222"
host_keys = [
  "/etc/craft-file-gate/host_ed25519",
  { path = "/etc/craft-file-gate/host_rsa", algorithms = ["rsa-sha2-512", "rsa-sha2-256"] },
]

Un algorithme n’est annonce que si une cle chargee sait le signer.

Algorithmes

[sftp.algorithms] regle les algorithmes proposes, par categorie. Chaque liste part d’un defaut moderne et s’edite comme dans OpenSSH :

Les defauts, liste par liste : Reference [sftp.algorithms].

• kex, ciphers, macs et host_key se negocient avant que l’utilisateur soit connu : ils valent pour tout le serveur.
• user_key dit les algorithmes avec lesquels une cle d’utilisateur peut signer sa connexion (le PubkeyAcceptedAlgorithms d’OpenSSH). Un role peut en permettre d’autres a ses seuls utilisateurs (user_key_algorithms, voir Authentification).
• Les marqueurs ext-info-* et kex-strict-* sont toujours ajoutes a kex.
• L’extension server-sig-algs annonce au client la liste host_key en vigueur, puis les algorithmes de user_key qu’aucune cle d’hote ne signe.

Les algorithmes faibles

diffie-hellman-group1-sha1, diffie-hellman-group14-sha1, diffie-hellman-group-exchange-sha1, aes*-cbc, hmac-sha1, hmac-sha1-etm@openssh.com et ssh-rsa (RSA signe en SHA-1) ne sont dans aucun defaut. Ajoutes avec +, ils sont proposes. diffie-hellman-group-exchange-sha256 s’ajoute aussi, hors defaut.

Un vieux client

# Un client JSch ancien : ni curve25519 ni ML-KEM
[sftp.algorithms]
kex = ["+diffie-hellman-group14-sha1"]

La liste des sessions de la console montre, pour chaque session, les algorithmes negocies et ceux qui sont faibles (weak_algorithms).

Ce que vous verrez

Uploads et ecritures atomiques

Ecritures atomiques (hidden stores)

Par defaut, un upload ecrit dans le fichier de destination, comme HiddenStores off dans ProFTPD : un lecteur peut y voir un fichier partiel tant que le transfert dure.

Avec enabled = true, l’upload ecrit dans un fichier en cours de transfert du meme repertoire, puis le renomme en destination a la fin. La destination n’apparait, ou ne change, qu’une fois le fichier complet.

[server.hidden_stores]
enabled = true
prefix = ".in."
extension = "."

Toutes les cles : Reference [server.hidden_stores].

Le fichier en cours de transfert s’appelle <prefix><nom>.<jeton><extension> : .in.rapport.csv.3f9a1c04b7e25d68. avec les defauts. Le jeton, 16 caracteres hexadecimaux, est propre a chaque upload. Un motif .in.* les reconnait tous.

Les fichiers en cours de transfert se listent et se lisent comme les autres. Ils concernent les backends local et sftp (proxy) ; un objet S3 n’apparait qu’une fois son upload termine, sans fichier a cote.

Par backend, par montage

La meme table se pose a trois niveaux. Chaque cle se resout a part : le montage l’emporte sur le backend, qui l’emporte sur [server.hidden_stores], qui l’emporte sur les defauts. SFTP et REST resolvent la meme valeur.

[server.hidden_stores]            # tout le serveur
enabled = true

[[backends]]
name = "disque"
type = "local"
root = "/srv/sftp"
hidden_stores = { enabled = false }   # ce backend ecrit en place

[[roles]]
name = "depot"

[[roles.mounts]]
backend = "disque"
mount_path = "/depot"
home_dir = "/depot"
hidden_stores = { enabled = true }    # sauf ce montage
acl = [{ path = "/", rights = ["write", "list"], recursive = true }]

Restes d’un transfert interrompu

Un processus tue en plein upload laisse son fichier en cours de transfert. Le serveur le supprime plus tard, quand un upload passe dans le meme repertoire, une fois le fichier plus vieux que grace_secs.

[uploads.stale_partials]
grace_secs = 900
age_check = true

Toutes les cles : Reference [uploads.stale_partials].

La meme table se pose par backend (stale_partials = { grace_secs = 1800 } dans son [[backends]]), cle par cle au-dessus de [uploads.stale_partials]. Sur un backend S3, elle regle le menage des uploads multipart abandonnes (voir S3).

Un reste n’est supprime que si son nom a la forme exacte que le serveur ecrit, si personne ne tient son verrou, et si son age depasse grace_secs sur l’horloge du stockage. Au moindre doute, il reste. Chaque suppression laisse une ligne INFO.

Les instances qui partagent un stockage ont le meme uploads.idle_timeout_secs

le seuil se calcule sur celui de l’instance qui balaie.

Deux uploads vers la meme destination

Le premier upload a s’ouvrir garde la destination jusqu’a sa fin. Un second, du meme compte ou d’un autre, par la meme porte ou une autre, est refuse des son ouverture, avant d’envoyer un octet.

Un upload bloque (client suspendu par Ctrl+Z) est repris par une relance du meme compte sur la meme instance, passe uploads.takeover_idle_secs sans donnees.

Entre plusieurs instances, un verrou pose sur le stockage, a cote de la destination, porte la meme regle. Il est rafraichi toutes les 20 s ; celui d’un processus disparu est repris passe 2 x idle_timeout_secs + 60 s (120 s par defaut). cross_instance_reservation et lock_prefix : Reference [[backends]].

Ce qu’est le verrou sur chaque type : Local, S3, Proxy SFTP. Les noms qui commencent par .craftfilegate-upload ou par le lock_prefix appartiennent au serveur : on les liste et on les lit, on n’y ecrit pas. Avec une seule instance, cross_instance_reservation = false suffit.

Plafonner la taille d’un fichier

max_file_mb, sur un montage, plafonne la taille de chaque fichier envoye (1 Mo = 1 048 576 octets). Ce n’est pas un compteur d’espace.

[[roles.mounts]]
backend = "disque"
home_dir = "/{username}"
max_file_mb = 500

Ce que vous verrez

Bans et limites de debit

Un exemple

[sftp.ban]
max_failures = 5
window_secs = 300
ban_duration_secs = 600
whitelist_ips = ["10.0.0.0/8"]

[admin]
listen = "0.0.0.0:8080"

[admin.ban]
max_failures = 10
trusted_proxies = ["10.0.0.5"]   # le reverse proxy devant l'API

[api]
enabled = true

[api.ban]
max_failures = 5
trusted_proxies = ["10.0.0.5"]   # le meme : un seul ecouteur

Sans la section, la porte ne bannit rien.

Une liste par porte

Les trois listes sont independantes : une adresse bannie sur l’API de fichiers ouvre toujours la console, et inversement.

Les cles d’un ban

Les memes sous [sftp.ban], [api.ban] et [admin.ban], lues au demarrage.

Toutes les cles : Reference [sftp.ban], [api.ban], [admin.ban].

Ce qui compte comme un echec

Un echec est une credential presentee et jugee fausse, quel que soit le compte essaye.

Ne comptent pas : une methode coupee, un jeton expire ou pas encore valide, un ticket de telechargement refuse, quel qu’il soit, un refus apres une credential acceptee (aucun role, limite de sessions), un refus du limiteur de debit, le refus d’une adresse deja bannie. Une connexion reussie ne remet pas le compteur a zero.

Avec [api] cors_origins = ["*"], toute page web peut faire envoyer par le navigateur d’un visiteur des credentials fausses, qui comptent pour le ban de son adresse : listez les origines de vos applications.

La vie d’un ban

Une adresse IPv4 mappee (::ffff:10.1.2.3) est la meme que 10.1.2.3, pour le ban, la liste blanche et les proxies.

Lever un ban

GET /admin/bans (onglet Bans de la console) les liste ; la levee demande la permission unban, {protocol} est sftp, api ou admin :

curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  http://localhost:8080/admin/bans/sftp/203.0.113.7

Une levee est une decision datee : elle annule les verdicts decides avant elle, jamais un verdict posterieur. Elle ne remet pas le compteur a zero.

Partager les bans entre instances

Les trois listes peuvent partager un fichier ou un ConfigMap. La fusion garde, par adresse, le ban le plus long et le verdict le plus recent ; un ban appris d’un pair coupe les sessions SFTP de l’adresse, sans ligne ip_banned (celle de l’instance qui l’a decide suffit). A l’arret, chaque liste est publiee, 5 s au plus chacune.

L’adresse d’un client HTTP : trusted_proxies

Les portes HTTP prennent le pair TCP pour adresse. Quand ce pair est dans le trusted_proxies de leur liste ([api.ban] pour l’API de fichiers, [admin.ban] pour l’API d’administration), elles prennent l’adresse la plus a droite de X-Forwarded-For qui n’est pas un proxy de confiance, a defaut X-Real-IP. Le ban, le limiteur, la part de la file de hachage et l’audit utilisent cette adresse. La porte SFTP ne lit que le pair TCP.

Sans [admin] control_listen, l’API de fichiers et l’API d’administration partagent un ecouteur : [api.ban] et [admin.ban] portent alors les memes trusted_proxies.

Limites de debit

Un seau a jetons par adresse : burst connexions ou requetes d’affilee, puis le debit par minute. Sans la section, aucune limite.

[sftp.rate_limit]
connections_per_minute = 30
burst = 10

[api.rate_limit]
requests_per_minute = 600

Toutes les cles : Reference [sftp.rate_limit], [api.rate_limit].

L’API d’administration n’a pas de limite de debit. Un refus de debit ne compte pas pour le ban.

Ce que vous verrez

Delais

Ce que chaque delai detecte

Uploads : [uploads]

[uploads]
idle_timeout_secs = 30
min_rate_bytes_per_sec = 1024   # 1 Kio/s en moyenne ; absent ou 0 : desactive
min_rate_grace_secs = 60

Toutes les cles : Reference [uploads].

Le delai d’inactivite

Le chronometre ne court que quand le serveur attend le client. Le temps passe par le serveur sur son stockage (S3 lent, NFS qui cale) ne compte jamais.

Au bout du delai, le partiel est jete (fichier en cours de transfert supprime, multipart S3 annule) et rien n’est publie.

Un upload vivant atteint son fichier au moins toutes les 2 x idle_timeout_secs : le menage des restes et la reprise des verrous s’y fient, donnez la meme valeur a toutes les instances qui partagent un stockage. Relevez-la pour les clients qui gardent un fichier ouvert sans ecrire (sshfs, client graphique qui demande une confirmation, lien tres lent : au defaut, un paquet de 32 Kio demande ~1,1 Ko/s).

Le debit minimal

Passe min_rate_grace_secs d’attente, un upload doit avoir recu en moyenne au moins min_rate_bytes_per_sec, comme RequestReadTimeout ... MinRate d’Apache. La moyenne court depuis le debut : un client en rafales garde le credit de ses rafales, un goutte-a-goutte est coupe a la fin de la grace. Les octets comptes sont ceux des WRITE acceptes, pas l’offset atteint.

En dessous, l’upload est coupe comme pour l’inactivite. 1 Kio/s coupe un goutte-a-goutte et laisse passer un lien de 10 Kio/s qui cale.

Keepalive TCP : [tcp_keepalive]

Pose sur chaque connexion acceptee, sur le port SFTP et sur le port HTTP.

Toutes les cles : Reference [tcp_keepalive].

Coupure du reseau en plein transfert : TCP_USER_TIMEOUT

Le keepalive ne sonde qu’une connexion sans rien en vol. Quand le serveur envoie quelque chose a un client disparu (les reponses aux WRITE d’un upload SFTP, un telechargement), c’est TCP_USER_TIMEOUT qui coupe.

La connexion est ainsi coupee 5 s apres l’abandon de l’upload. Sous Linux, ce delai remplace count : une connexion inoccupee dont le pair a disparu est coupee a la premiere sonde qui le depasse (vers 70 s en SFTP). Il vaut aussi pour un client qui ne lit plus : un telechargement REST dont le client est suspendu est coupe a 35 s. Une coupure reseau plus longue (perte de couverture, VPN qui se reconnecte) tue le transfert ; relevez user_timeout_secs si vos clients en traversent.

Hors Linux, rien n’est pose.

SSH : [sftp]

login_grace_secs et inactivity_timeout_secs coupent la connexion (0 : jamais) ; keepalive_interval_secs (0 : aucun) sonde le client, keepalive_max (3) coupe apres autant de sondes sans reponse. Les cles : [sftp].

La reponse a un keepalive SSH compte comme de l’activite : avec un keepalive plus court que inactivity_timeout_secs, une session vivante mais inoccupee n’est plus coupee par l’inactivite, seul un client qui ne repond plus l’est. C’est pourquoi le keepalive SSH est desactive par defaut.

HTTP : delai de lecture des en-tetes

admin.header_read_timeout_secs (10 s, de 1 a 300, CRAFT_FILE_GATE_ADMIN_HEADER_READ_TIMEOUT_SECS) borne, sur le port de l’API d’administration et de l’API de fichiers, l’attente des en-tetes d’une requete : depuis la connexion, la poignee de main TLS ou la reponse precedente en keep-alive. Au-dela, la connexion est fermee sans reponse. Il ne borne ni un corps ni une reponse.

Le port ne sert que HTTP/1.1 ; en HTTPS, l’ALPN n’offre que http/1.1, et les clients HTTP/2 s’y rabattent.

Ce que vous verrez

Journaux

Deux flux

Les deux vont sur stdout. Avec log.dir, ils vont aussi dans deux fichiers separes.

[log]

[log]
level = "info"
format = "json"
audit = "all"
dir = "/var/log/craft-file-gate"

Toutes les cles : Reference [log].

Le volume de la piste : log.audit

log.audit ne retire que des succes. Un refus, une erreur ou une issue inconnue est toujours ecrit.

Toujours ecrits, quel que soit log.audit : connection_rejected, connection_rejected_summary, ip_banned, tout ce qu’ecrit l’API d’administration, et les session_end d’une session coupee (administrateur, arret, ban, erreur interne).

Le niveau de log ne touche pas la piste : le target audit reste a info quel que soit log.level.

Fichiers de log : log.dir

• Rotation : au premier ecrit d’un nouveau jour UTC, et avant une ecriture qui depasserait max_file_size_mb. L’archive porte l’instant de son ouverture, craft-file-gate.2026-09-27T00-00-00Z.log.gz, et ne contient que des lignes de ce jour UTC.
• Retention : une archive part une fois son jour plus la retention ecoule, jugee sur son nom. Les autres fichiers du repertoire ne sont pas touches.
• Fichiers en 0640, archives .gz toujours completes ; un repertoire par processus.

En conteneur, stdout et la rotation de la plateforme (kubelet, journald, Docker) restent la voie normale ; dir y demande un volume. Le chart Helm le propose : logFiles.enabled: true.

Refus repetes : une ligne resumee

Un client anonyme qui insiste (scanner, client mal configure) produirait une ligne par tentative. Par porte, adresse, reason et result, les refusal_summary_threshold premiers refus d’une fenetre de refusal_summary_window_secs gardent leur ligne ; les suivants sont comptes, puis resumes en une ligne connection_rejected_summary a la fin de la fenetre, avec suppressed, threshold et window_secs.

Seuls les refus qui n’ont juge aucune credential sont resumes : missing credential, empty credential, malformed credential, method disabled, verifier unavailable, banned, rate limit, password checks saturated, password checks saturated for address, shutting down. Un mot de passe faux garde toujours sa ligne.

Au-dela de refusal_summary_max_addresses cles suivies, les refus de plus sont resumes ensemble (overflow=true).

Fins de session SFTP

La ligne applicative de fin d’une session dit sa cause :

La piste porte une ligne session_end par session, avec la meme cause dans reason.

Une connexion qui finit avant la session (client qui ne parle pas SSH, negociation sans algorithme commun) ecrit INFO SSH session ended: <raison>, avec peer et client_version. Ce sont des fins ordinaires : alertez sur leur nombre, pas sur chacune.

Ce que vous verrez

Niveau de log et diagnostic

Changer le niveau a chaud

[log]
level = "debug"

Enregistrer le fichier suffit : le niveau change en quelques instants, sans redemarrage, comme pour les fichiers d’utilisateurs et de roles. Sous Unix, kill -HUP applique l’edition sans attendre la surveillance du fichier.

level prend une seule valeur, pas une chaine de directives. La piste d’audit n’en depend pas : elle reste a info.

Dans [log], seuls level, audit et les refusal_summary_* s’appliquent a chaud ; le reste attend un redemarrage (voir Rechargement).

Qui decide du niveau

La premiere ligne du journal dit le filtre en vigueur et sa source :

INFO log filter in force  filter="info,craft_file_gate=info,audit=info,opentelemetry_sdk=off" source="config [log] level"

RUST_LOG, pour aller plus loin

RUST_LOG donne le detail d’une dependance, par exemple le trace de russh. Il remplace la chaine entiere, y compris le audit=info que le serveur ajoute toujours : ecrivez-le vous-meme.

RUST_LOG=warn,russh=trace,audit=info

Comprendre un refus d’authentification

La ligne d’audit d’un mot de passe refuse ne dit pas pourquoi : distinguer « utilisateur inconnu » de « mot de passe faux » revelerait quels comptes existent, et les journaux voyagent loin. Le detail est au niveau debug, pour l’exploitant seul.

DEBUG local password authentication rejected  username=alice reason="password does not match the stored hash"
DEBUG local password authentication rejected  username=bob reason="no such user in the users file"

debug donne aussi les comptes charges (local user store contents, champ usernames) ; info n’en dit que le nombre (local user store loaded).

Pour verifier un hash sans serveur :

echo -n "mot-de-passe" | craft-file-gate verify-password '$argon2id$v=19$...'

Revenez a info une fois le diagnostic fait. Les autres refus portent leur cause dans reason : Depannage.

Un changement a chaud ecrit INFO log level reloaded (level, source, filter). Sous level = "warn" ou plus severe, ces annonces partent sur stderr, prefixees craft-file-gate: : l’annonce d’un filtre n’est jamais etouffee par lui.

Telemetrie

Un exemple

[telemetry]
enabled = true
otlp_endpoint = "http://otel-collector:4318"
protocol = "http"
service_name = "craft-file-gate"
metrics = true

[telemetry]

Toutes les cles : Reference [telemetry].

Le point d’acces

• https:// est chiffre dans les deux protocoles ; le certificat du collecteur est verifie contre les racines du systeme (voir Racines de confiance TLS).
• protocol fait autorite : OTEL_EXPORTER_OTLP_PROTOCOL et OTEL_EXPORTER_OTLP_TRACES_PROTOCOL, qu’injectent certains operateurs, ne le changent pas.
• L’exporteur lit OTEL_EXPORTER_OTLP_HEADERS (en-tetes d’authentification) et OTEL_EXPORTER_OTLP_TIMEOUT (10 s par defaut).

Ce qui est exporte

L’export recoit les spans et les evenements de CraftFileGate et de la piste d’audit a partir de info, quel que soit le niveau du journal : un serveur regle en warn exporte toujours ses spans.

La ligne d’audit d’une operation est un evenement de son span ; un echec passe le span en status=error.

Pour un panneau Tempo ou Jaeger :

• un transfert qui va jusqu’a close a deux spans sftp_operation du meme operation (upload, download) : l’ouverture, puis la validation, qui seule porte bytes. Comptez les spans qui portent bytes ;
• un rmdir d’un repertoire non vide a un span rmdir puis un span rmdir_recursive, pour une seule ligne d’audit rmdir_recursive ;
• les lectures et ecritures n’ont pas de span par paquet.

Un path ou un username qui contient un caractere de controle ou un separateur Unicode (U+2028, controles bidirectionnels) arrive echappe, sous une forme visible (\u{2028}). La valeur exacte est dans la ligne d’audit.

Les metriques en OTLP

Avec metrics = true, le serveur pousse ses metriques toutes les metrics_interval_secs, en plus de GET /metrics, qui reste servi ; la correspondance des noms : Metriques.

Envois, relances et arret

Les spans perdus se comptent sur /metrics :

ended - exported - export_failed est ce qui est encore en route (jusqu’a 2560 spans : la file et le lot en cours), plus ce qu’une file pleine a rejete. Un ecart qui croit au-dela, ce sont des spans perdus.

increase(craftfilegate_otel_spans_ended_total[5m])
  - increase(craftfilegate_otel_spans_exported_total[5m])

Ce que vous verrez

Fichiers de confiance et TLS

Les fichiers de confiance

Ces fichiers decident de qui entre et de ce qu’il peut faire : quiconque peut les ecrire peut se donner l’acces. Le serveur les juge au demarrage, et au rechargement pour ceux qui se rechargent.

Le fichier, et chaque repertoire traverse depuis / pour l’atteindre (liens symboliques compris), est juge sur ses bits de mode, son proprietaire et son groupe. Le serveur lit ensuite le fichier par le descripteur qu’il a juge.

Les poser

La pose recommandee :

chown root:root /etc/craft-file-gate /etc/craft-file-gate/*
chmod 755 /etc/craft-file-gate
chmod 644 /etc/craft-file-gate/config.toml /etc/craft-file-gate/roles.toml
chmod 640 /etc/craft-file-gate/users.toml /etc/craft-file-gate/host_ed25519
chgrp craft-file-gate /etc/craft-file-gate/users.toml /etc/craft-file-gate/host_ed25519

En conteneur, montez la configuration en lecture seule (readOnly: true, :ro)

un Secret Kubernetes en 0440 avec le fsGroup du pod convient tel quel.

[security]

Toutes les cles : Reference [security].

Lue au demarrage. A reserver a un deploiement ou le groupe du serveur ne contient que lui.

Ce que le serveur cree lui-meme

Le processus pose umask(077) au demarrage.

Les instances qui partagent un volume de bans tournent sous le meme uid.

Les chemins des clients

Un chemin client est juge sur sa forme virtuelle, puis le backend le resout sous sa racine. Sur un backend local, un lien symbolique ne sort jamais de la racine : voir Local.

Racines de confiance TLS

Il s’agit du TLS sortant : backend S3 en HTTPS, jwks_url, service d’autorisation, collecteur OTLP en https://, backend WebHDFS. Le TLS entrant de la console se regle dans [admin.tls] (voir Console et API).

Le serveur n’embarque aucune racine : il lit le magasin du systeme.

Posee, l’une de ces variables remplace le magasin du systeme, elle ne s’y ajoute pas. Pour faire confiance a une autorite interne et aux racines publiques, concatenez :

cat /etc/ssl/certs/ca-certificates.crt ca-interne.pem > bundle.pem

Sans variable, le premier fichier trouve parmi les chemins usuels l’emporte (/etc/ssl/certs/ca-certificates.crt, /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem, /etc/pki/tls/certs/ca-bundle.crt, /etc/ssl/ca-bundle.pem, /etc/ssl/cert.pem), puis les repertoires /etc/ssl/certs et /etc/pki/tls/certs. Les images :latest et :alpine portent un magasin ; l’image :scratch n’en a pas.

Monter un jeu de racines

Le bundle Mozilla que maintient le projet curl convient :

curl -fsSLo bundle.pem https://curl.se/ca/cacert.pem

Montez-le au chemin par defaut (/etc/ssl/certs/ca-certificates.crt, en lecture seule), ou n’importe ou avec SSL_CERT_FILE ; en Kubernetes, un ConfigMap suffit, ce n’est pas un secret.

Un deploiement sans connexion TLS sortante (backend local ou proxy SFTP, comptes locaux ou cle JWT statique, pas d’OTLP) n’a besoin d’aucune racine.

Recommandations de deploiement

Exploiter

Docker

ssh-keygen -t ed25519 -f ./host_ed25519 -N ""   # la cle d'hote
sudo chown 65532 host_ed25519                   # lisible par l'utilisateur de l'image
docker run -d --name craft-file-gate \
  -v ./config.toml:/config/config.toml:ro \
  -v ./host_ed25519:/config/host_ed25519:ro \
  -v ./roles.toml:/config/roles.toml:ro -v ./users.toml:/config/users.toml:ro \
  -v data:/data \
  -p 2222:2222 -p 8080:8080 -p 8081:8081 \
  craftogether/craft-file-gate:latest

config.toml reprend le demarrage rapide avec ce qu’un conteneur change : des ecoutes sur 0.0.0.0, un chemin de cle relatif au repertoire de config.toml, la console par compte et mot de passe (les portes sont publiees), stockage et comptes dans leurs propres fichiers. docker run --rm craftogether/craft-file-gate:latest config schema > config.schema.json ecrit a cote le schema que nomme #:schema (Verifier une configuration) ; l’image le porte a /usr/share/craft-file-gate/config.schema.json.

#:schema ./config.schema.json
[sftp]
listen = "0.0.0.0:2222"
host_keys = ["host_ed25519"]        # /config/host_ed25519

[auth.methods]
local = { enabled = true }          # les comptes de users.toml
jwt = { enabled = false }           # sans fournisseur d'identite

[admin]
listen = "0.0.0.0:8080"             # API de fichiers, explorateur
control_listen = "0.0.0.0:8081"     # console, /admin, sondes, /metrics

[[admin.roles]]                     # un compte [[users]] avec authorities = ["admins"]
name = "admins"
permissions = ["overview", "sessions", "kick", "bans", "unban", "config", "logs", "audit", "revoke", "grant"]

[admin.ban]
max_failures = 5

[api]
enabled = true

[api.ban]
max_failures = 5

[api.ui]
enabled = true

Le premier montage et son ACL : roles.toml ([[backends]], [[roles]]) et users.toml ([[users]]), a cote de config.toml, sont pris sans etre declares.

#:schema ./config.schema.json
[[backends]]                        # roles.toml
name = "donnees"
type = "local"
root = "/data"                      # le volume data:/data

[[roles]]
name = "utilisateurs"

[[roles.mounts]]
backend = "donnees"
home_dir = "/{username}"            # alice voit /data/alice comme sa racine /
create_home = true

[[roles.mounts.acl]]
path = "/"
rights = ["read", "write", "list", "delete", "rename"]
recursive = true

#:schema ./config.schema.json
[[users]]                           # users.toml
username = "alice"
password_hash = "$argon2id$..."     # sortie de hash-password (plus bas)
authorities = ["utilisateurs", "admins"]   # ses fichiers, et la console

La console : http://hote:8081/, l’explorateur : http://hote:8080/files (Session de console, Explorateur).

L’image expose 2222 (SFTP) et 8080 ; control_listen en publie un troisieme. Le HEALTHCHECK lance craft-file-gate healthcheck sur /config/config.toml. ENTRYPOINT est le binaire seul, la commande --config /config/config.toml ; le binaire traite SIGTERM en PID 1.

• Montez en lecture seule (:ro) les fichiers auxquels le serveur se fie : configuration, utilisateurs, roles, cle d’hote, paire TLS (Securite).
• /data appartient dans l’image a son utilisateur, et un volume nomme en herite ; un repertoire de l’hote monte a sa place doit lui appartenir : sudo chown 65532 data (65534 pour :alpine).
• :scratch n’a aucune racine de certificats : une connexion TLS sortante (S3, JWKS, OTLP, Knox) demande un bundle monte et SSL_CERT_FILE.
• Les sous-commandes passent telles quelles : echo -n 'mot-de-passe' | docker run -i --rm craftogether/craft-file-gate hash-password.
• Gardez le delai d’arret de Docker au-dessus de celui du serveur : docker stop -t 90. Voir Arret.

Docker Compose

services:
  craft-file-gate:
    image: craftogether/craft-file-gate:latest
    restart: unless-stopped
    stop_grace_period: 90s
    ports:
      - "2222:2222"   # SFTP
      - "8080:8080"   # API de fichiers, explorateur
      - "8081:8081"   # console, /admin, sondes, metriques
    volumes:
      - ./config.toml:/config/config.toml:ro
      - ./roles.toml:/config/roles.toml:ro
      - ./users.toml:/config/users.toml:ro
      - ./host_ed25519:/config/host_ed25519:ro
      - data:/data

volumes:
  data:

Les features du binaire

Chaque type de backend et chaque porte est une feature Cargo, toutes actives par defaut. Les binaires et les images publies les portent toutes, et k8s. Un binaire construit avec moins de features refuse au demarrage la table d’une porte ou le type d’un backend qu’il ne porte pas, en nommant la feature.

La console, les sondes et /metrics n’ont pas de feature : tout binaire les porte.

Sous-commandes (hash-password, verify-password, healthcheck) : Le fichier de configuration.

Kubernetes

Le parcours de Docker sous le chart : le stockage local sur un volume, les comptes dans un Secret, les roles dans config.toml.

kubectl create secret generic sftp-host-keys --from-file=host_ed25519
kubectl create secret generic sftp-users --from-file=users.toml
kubectl apply -f - <<'EOF'
apiVersion: v1
kind: PersistentVolumeClaim
metadata: { name: sftp-data }
spec: { accessModes: [ReadWriteOnce], resources: { requests: { storage: 10Gi } } }
EOF
helm install sftp deploy/helm/craft-file-gate -f sftp-values.yaml \
  --set-file config.inline=config.toml

# sftp-values.yaml
hostKeys:
  existingSecret: sftp-host-keys                         # /keys/host_ed25519
extraVolumes:
  - name: data
    persistentVolumeClaim: { claimName: sftp-data }
  - name: users
    secret: { secretName: sftp-users, defaultMode: 0440 }
extraVolumeMounts:
  - { name: data, mountPath: /data }                     # root = "/data" du backend
  - { name: users, mountPath: /secrets/users, readOnly: true }

config.toml est celui de Docker suivi du contenu de son roles.toml (le chart ne monte que config.toml), avec host_keys = ["/keys/host_ed25519"] sous [sftp] et users_file = "/secrets/users/users.toml" sous [auth]. Les ecoutes restent sur 0.0.0.0 (les sondes joignent le pod par son IP) et [[admin.roles]] ouvre la console, puisque le chart ecarte le jeton statique. Le volume est au groupe du pod (fsGroup 65532) : create_home y cree alice/. Au-dela d’un pod, le volume est ReadWriteMany.

Le chart

• Un Service par exposition : publier SFTP par un LoadBalancer (service.sftp.type) ne publie ni la console, ni /metrics, ni les sondes.
• Les sondes du kubelet viennent du noeud du pod, que la plupart des CNI laissent passer malgre la NetworkPolicy ; sinon, ajoutez le CIDR des noeuds en ipBlock a networkPolicy.controlFrom. Pour restreindre Prometheus et l’ingress, listez leurs namespaces dans networkPolicy.controlFrom.

Les sondes

/livez et /readyz (Sondes et sante) sont sondes sur le port des sondes quand il est donne, sinon sur le port de controle, sinon sur le port admin.

Un port pour les sondes

service.probes.port: 9090 pose [server] probes_listen : les sondes et /metrics ont un port a eux, en HTTP simple, meme sous [admin.tls] (Une porte ou deux). Le kubelet et Prometheus (par pod : PodMonitor ou annotations) n’ont plus besoin du certificat ni du port de la console ; le port n’est sur le Service <release>-control qu’avec service.probes.expose: true. Un pod SFTP sans [admin] a ainsi ses sondes, /readyz pret des que la porte SFTP ecoute.

Durcissement du pod

Le chart applique le profil restricted des Pod Security Standards. Chaque champ se surcharge dans podSecurityContext et securityContext ; null retire un champ ou un bloc.

La racine d’un backend local est un volume de extraVolumes. Cles d’hote et paire TLS viennent d’un Secret (cert-manager pour le TLS), jamais d’un emptyDir : auto_generate de [admin.tls] ne sert pas sous ce chart.

Plusieurs pods

Chaque Role porte sur un seul nom, sans create : get, update sur le Secret ; get, update, patch sur chaque ConfigMap, watch sur leur collection pour les bans (helm template ... --show-only templates/rbac.yaml).

Le partage par ConfigMap

Feature k8s (dans les images publiees). Le pod lit la ConfigMap avant de servir ; chaque publication est conditionnee a la resourceVersion lue, et un data.bans efface par kubectl edit est republie a la suivante. Sans watch, la propagation tombe a une relecture toutes les 30 s ; un deploiement qui ne cree pas la ConfigMap ajoute create sur la collection.

[sftp.ban]           # de meme sous [api.ban] et [admin.ban] ; le chart en donne le nom
backend = "configmap"

inotify sur un noeud partage

fs.inotify.max_user_instances (128 par defaut) se compte par UID, sur tout le noeud. Le serveur n’en prend qu’une. Quand d’autres pods l’ont epuise et que vous ne pouvez pas regler le noeud :

[reload]
watch = "poll"   # aucune instance inotify ; une mise a jour de Secret est vue en 5 s

Voir Rechargement.

Secrets en Kubernetes

• Un Secret monte en volume est mis a jour par Kubernetes, qui repointe le lien ..data : configuration, utilisateurs, roles et paire TLS sont recharges a chaud. Voir Rechargement.
• Un Secret monte avec subPath n’est jamais mis a jour : evitez subPath.
• Montez Secrets et ConfigMaps readOnly: true, comme le chart, jamais sur un emptyDir ou un hostPath inscriptible (Fichiers de confiance et TLS).
• Un Secret passe par envFrom (extraEnvFrom) n’est lu qu’au demarrage : kubectl rollout restart pour une nouvelle valeur.
• Le serveur ne lit pas les Secrets par l’API Kubernetes : montez-les. Seule exception, le Secret partage des pods (ci-dessous).

Un fichier plutot qu’une variable

Montez le Secret en fichier par les valeurs du chart, et nommez-le par la variable _FILE (le jeton d’administration de meme, avec config.allowStaticToken: true) :

extraVolumes:
  - name: jwt
    secret: { secretName: sftp-jwt, defaultMode: 0440 }
extraVolumeMounts:
  - { name: jwt, mountPath: /secrets/jwt, readOnly: true }
extraEnv:
  - { name: CRAFT_FILE_GATE_JWT_SECRET_FILE, value: /secrets/jwt/jwt-secret }

Le fichier est lu une fois, au demarrage ; /proc/<pid>/environ ne montre qu’un chemin. Voir Variables d’environnement. users.toml se monte de meme, nomme par users_file : voir Kubernetes.

Le Secret partage des pods

Les pods d’une meme release partagent la cle qui signe les sessions de la console, pour qu’un pod accepte le jeton qu’un autre a emis. Le chart cree un Secret vide et donne aux pods get et update sur ce seul nom ; le premier pod qui n’y trouve pas l’entree admin-session.key la genere et l’ecrit, les autres la lisent. Chaque entree a sa propre vie : le certificat du canal entre pods y vit aussi (tls.crt, tls.key).

Avec replicaCount au-dela de 1, clusterSecret.enabled: false demande un key_file sous [admin.session] dans config.inline, et une cle partagee demande des revocations partagees (adminRevocations.backend: configmap, ou persist_file sous [admin.session]).

Pour changer la cle : supprimer l’entree (kubectl patch secret ... --type=json -p '[{"op":"remove","path":"/data/admin-session.key"}]') puis redemarrer les pods ; les sessions ouvertes sont perdues.

Cle d’hote SSH

Creez la cle une fois, gardez-la dans un Secret, montez-la. Ne laissez pas le serveur la generer (generate_host_key) dans un pod : chaque pod, ou chaque redemarrage sans volume, aurait sa cle, et les clients verraient « host key changed ».

ssh-keygen -t ed25519 -f host_ed25519 -N ""
ssh-keygen -l -f host_ed25519.pub          # l'empreinte a donner aux clients
kubectl create secret generic sftp-host-keys --from-file=host_ed25519

hostKeys.existingSecret: sftp-host-keys la monte dans /keys (Le chart), la configuration pointe dessus : host_keys = ["/keys/host_ed25519"]. L’empreinte du demarrage (loaded host key, champ fingerprint) et de GET /admin/config est celle de ssh-keygen -l.

Plusieurs instances

Les instances d’un deploiement se trouvent et se parlent sur un port a elles, en TLS 1.3 dans les deux sens, admises par le certificat qu’elles partagent. Le chart Kubernetes pose tout cela des que replicaCount depasse 1.

[cluster]
listen = "0.0.0.0:8083"
peers = "dns:craft-file-gate-cluster:8083"
cert_file = "/var/lib/craft-file-gate/cluster/tls.crt"
key_file = "/var/lib/craft-file-gate/cluster/tls.key"

Toutes les cles : Reference [cluster].

Le certificat partage

Son empreinte SHA-256 est l’identite du cluster : ni nom ni date ne sont verifies, l’expiration est dite par craftfilegate_cluster_cert_not_after_seconds. Pour le changer, retirez la paire et redemarrez toutes les instances ; pendant le roulement, un pair a l’ancien certificat est certificate_mismatch.

kubectl patch secret sftp-cluster --type=json \
  -p '[{"op":"remove","path":"/data/tls.crt"},{"op":"remove","path":"/data/tls.key"}]'
kubectl rollout restart deployment/sftp

Detecteurs et retrait du service

Apres chaque tour, chaque instance juge trois detecteurs : storage_alone (un backend down ici qu’un pair joignable voit up : une panne que tous voient ne compte pas), isolated (moins de min_peers pairs joignables depuis isolated_after_secs) et isolated_and_storage_down (isolee, et chaque backend non local down ici ; un backend local, le disque du pod, ne compte pas : sans backend non local, il ne se declenche jamais). Par defaut ils alertent seulement : WARN cluster detector active, craftfilegate_unready_detector{detector}, craftfilegate_cluster_isolated, checks.cluster de /admin/health.

Nommes dans unready_when, ils retirent l’instance du service : /readyz non pret apres unready_after_secs d’un detecteur actif, pret de nouveau apres ready_after_secs sans aucun ; /livez ne bouge pas. storage_alone ne retire un pod que si un autre pod, en service et sans aucun backend en panne, voit chacun de ses backends en panne disponible, et un seul pod a la fois : si chaque pod a une panne quelque part, aucun ne part.

[cluster]
min_peers = 1                    # le chart : floor(replicaCount / 2)
unready_when = ["storage_alone", "isolated_and_storage_down"]  # le chart : auto

isolated seul peut retirer chaque pod : coupure du port du cluster, perte d’une majorite de noeuds, partage en deux moities egales, reduction manuelle du nombre de replicas. Ne le nommez qu’en connaissance de cause, et ne descendez jamais sous 2 × min_peers + 1 replicas sans helm upgrade.

Avec les defauts, une panne de stockage est vue en 35 s au pire, le retrait suit 60 s plus tard, et Kubernetes sort le pod du Service apres 3 sondes de readiness a 10 s : environ 2 min.

Ce que vous verrez

Au demarrage, INFO cluster channel listening (TLS 1.3, pinned on the shared certificate) ; a chaque pair qui repond, INFO cluster peer reachable ; par statut : craftfilegate_cluster_peers{status}. Les onglets Instances, Sessions et Bans de la console lisent chaque pair avec votre credential, qu’il juge lui-meme (scope=cluster) ; un kick va au seul pair qui tient la session, une levee a chaque pair, sauf sur une liste ConfigMap ; par appel : craftfilegate_cluster_relay_total{route,result}.

Un ban y est un garde contre les essais, pas un retrait d’acces : une adresse bannie sur un pair le lit encore a travers une autre instance avec une credential valide (une session revoquee reste refusee).

Console et API d’administration

[admin]
listen = "0.0.0.0:8080"           # API de fichiers, explorateur
control_listen = "0.0.0.0:8081"   # console, /admin, /metrics, sondes
bearer_token = "changez-moi-en-production"

[api]
enabled = true
prefix = "/api/v1/files"

Les cles : reference.

Une porte ou deux

Avec l’API de fichiers, posez control_listen : bans, kicks, /metrics et sondes restent joignables quand les transferts saturent le serveur. Le chart Helm le fait (service.control.port). probes_listen donne aux sondes et a Prometheus un port sans TLS ni console ; sans [admin], c’est le seul ecouteur HTTP (Kubernetes). La console lit sa sante sur /admin/health, servi a cote d’elle dans tous les cas.

S’authentifier

Chaque route protegee demande Authorization: Bearer <jeton>.

Un role admin nomme des permissions ; une authority qui porte son nom les donne.

[[admin.roles]]
name = "support"
permissions = ["overview", "sessions", "logs"]

[[admin.roles]]
name = "admins"
permissions = ["overview", "sessions", "kick", "bans", "unban", "config", "logs", "audit", "revoke", "grant"]

Les noms des roles admin et ceux de [[roles]] sont distincts. Un compte qui porte les deux sortes ouvre la console et les portes de fichiers ; un compte qui ne porte que des roles admin n’ouvre que la console. Le service d’autorisation ne recoit jamais un nom de role admin, et aucun jeton d’administration n’ouvre un fichier. Les echecs comptent dans [admin.ban] (Bans).

Sessions

{"total": 1, "offset": 0, "limit": 50, "server_time": "2026-10-07T14:42:10.125Z", "inactivity_timeout_secs": 600,
 "sessions": [{"session_id": "550e8400-e29b-41d4-a716-446655440000", "username": "alice", "remote_addr": "192.168.1.42:54321", "auth_method": "password",
   "mounts": [{"mount_path": "/", "backend": "disque", "home_dir": "/alice", "acl": [{"path": "/", "rights": ["read", "write", "list", "delete", "rename"], "recursive": true}]}],
   "connected_at": "2026-10-07T14:30:00Z", "idle_since": null, "last_sftp_op_at": "2026-10-07T14:41:25.402Z", "last_traffic_at": "2026-10-07T14:42:05.871Z",
   "bytes_read": 1048576, "bytes_written": 524288, "sftp_ops": 412, "has_active_transfer": false, "pod_name": "craft-file-gate-0", "authorities": ["utilisateurs"],
   "client_version": "SSH-2.0-OpenSSH_9.6", "algorithms": {"kex": "curve25519-sha256", "host_key": "ssh-ed25519", "cipher": "chacha20-poly1305@openssh.com",
     "mac_client_to_server": "hmac-sha2-256", "mac_server_to_client": "hmac-sha2-256"}, "user_key": null, "weak_algorithms": [], "type": "sftp"}]}

La liste porte aussi les transferts REST (upload, telechargement) en cours depuis long_request_threshold_secs (30 s par defaut, 0 : tous, applique a chaud) : "type": "rest" (une session SFTP a "sftp"), session_id, username, remote_addr, method (PUT, GET), direction (upload, download), path (le chemin vu par l’utilisateur), mounts (mount_path, backend), connected_at (son debut), bytes, bytes_read, bytes_written, bytes_per_sec (la moyenne depuis le debut).

Journaux et flux

Avec [log] dir, GET /admin/logs/{app|audit} rend les dernieres entrees du fichier courant, filtrees par le serveur. Voir Journaux.

Parametres : lines (500, 5000 au plus ; 4 Mio parcourus au plus), level (ERROR a TRACE), since et until (RFC 3339), q (texte, 256 octets), field=cle:valeur (16 au plus). 3 lectures simultanees au plus.

Les flux SSE (text/event-stream) suivent l’activite en direct :

Au plus 8 flux ouverts, 2 par identite ; un flux finit a l’exp de son jeton ou a sa revocation, au plus tard apres 15 minutes.

Sondes et sante

La console

http://serveur:8081/ : une page qui appelle /admin/*. Elle ne charge rien d’un tiers. Sa connexion : Session de console.

• Les filtres et tris (ip:, user:, role:, backend:, type:) vivent dans l’URL : /#sessions?q=user:bob&sort=-last_op. Le jeton n’y figure jamais.
• La page et ses fichiers (/ui/*) portent une CSP stricte (default-src 'none', tout de la meme origine, 'wasm-unsafe-eval') ; un reverse proxy qui pose la sienne permet au moins autant.

Ce que vous verrez

Session de console et revocations

Un compte local dont les authorities nomment un role admin se connecte a la console par identifiant et mot de passe ; le serveur lui rend un jeton de session qu’il signe lui-meme.

[auth.methods]
local = { enabled = true, password = true }

[[users]]
username = "eric"
password_hash = "$argon2id$..."
authorities = ["admins"]

[[admin.roles]]
name = "admins"
permissions = ["overview", "sessions", "kick", "bans", "unban", "config", "logs", "audit", "revoke", "grant"]

[admin.ban]
max_failures = 5

[admin.session]
key_file = "/secrets/admin-session.key"   # 32 octets au moins, la meme sur toutes les instances
ttl_secs = 3600
max_age_secs = 43200

La connexion compte ses echecs dans [admin.ban], qu’elle exige (Bans), et passe par la file de hachage des mots de passe (Verification des mots de passe).

Se connecter

Le jeton ne porte que le compte : chaque requete relit le compte en vigueur ([[users]] ou users_file) et recalcule ses permissions. Un rechargement de users_file qui retire un role, change le mot de passe ou retire le compte s’applique a la requete suivante.

La cle de session

La cle qui signe les jetons est la meme sur toutes les instances : key_file, ou sous Kubernetes secret_name (Secrets). Sans l’une ni l’autre, la cle est tiree au demarrage : les sessions vivent avec le processus, sur cette instance seule. Toutes les cles : Reference [admin.session].

Revoquer, se deconnecter

Les flux ouverts sous un jeton revoque (/admin/events, suivis de journaux) se ferment.

Partager les revocations

[admin.session]
persist_file = "/var/lib/craft-file-gate/admin-revocations.json"  # un fichier a elles
# ou, sous Kubernetes :
# backend = "configmap"                                  # le chart le pose avec le Secret partage
# revocation_configmap_name = "craft-file-gate-access"
reread_interval_secs = 5

Toutes les cles : Reference [admin.session].

Une cle partagee va avec des revocations partagees, et des horloges synchronisees (NTP) : une revocation est datee, et une instance dont l’horloge avance ou retarde l’applique avec cet ecart.

Dans la console

• Identifiant et mot de passe quand la porte connecte des comptes ; « Sign in with a token » prend le jeton statique ou un JWT du fournisseur, seul formulaire sinon.
• Le jeton vit dans la page : recharger, ouvrir un onglet ou fermer le navigateur redemande la connexion. Le navigateur ne garde que le theme et les vues des tableaux.
• La session est renouvelee tant que la page est ouverte, jusqu’a max_age_secs apres la connexion ; un onglet ferme la laisse finir a ttl_secs. L’en-tete dit le compte, ses roles admin et la fin du jeton.
• Logout appelle POST /admin/logout : une session deconnecte tous les onglets et appareils du compte.

Acces temporaire

Un acces temporaire donne un role de fichiers a un nom d’utilisateur jusqu’a une date, en plus des roles qu’il tient deja : un prestataire pour une livraison, un support pour une journee. Le nom peut etre un compte local ou une identite qu’apporte un JWT ou le service d’autorisation.

[[admin.roles]]
name = "support"
permissions = ["overview", "sessions", "grant"]

[admin.grants]
persist_file = "/var/lib/craft-file-gate/grants.json"   # ou backend = "configmap"
max_duration_secs = 604800                              # 7 jours

Toutes les cles : Reference [admin.grants].

• Qui accorde : un role admin qui tient la permission grant, depuis l’onglet « Temporary access » de la console ou POST /admin/grants (S’authentifier). Tout role de [[roles]] peut etre accorde, jamais un role admin. Un motif est obligatoire ; l’accord et sa revocation sont dans la piste (grant_add, grant_revoke).
• Le nom : la console propose les comptes locaux et les noms qu’une porte de fichiers a authentifies dans les 7 derniers jours, sur cette instance. Un nom jamais vu est accepte avec un avertissement : il n’ouvre rien tant que personne ne se connecte sous ce nom.
• La duree : 1 h, 8 h, 24 h, 48 h, 7 jours ou une date de fin, au plus max_duration_secs.
• A la fin (date atteinte ou revocation) : les sessions SFTP que l’acces a servies et les transferts REST en cours sous ses montages sont coupes, un upload en cours est abandonne ; chaque requete REST suivante est jugee sans lui. Une session ouverte avant l’accord ne le voit pas.
• Plusieurs instances : l’acces vit dans un fichier ou la ConfigMap <release>-access (l’un des deux avec [cluster]), relu toutes les reread_interval_secs ; une autre instance l’applique et le coupe a sa relecture suivante. Les horloges sont supposees synchronisees (NTP).

Explorateur de fichiers

[admin]
listen = "0.0.0.0:8080"
bearer_token = "changez-moi-en-production"

[api]
enabled = true
prefix = "/api/v1/files"

[api.ui]
enabled = true
path = "/files"

La page est sur http://serveur:8080/files.

Les options

Les deux cles sont lues au demarrage. Toutes les cles : Reference [api.ui].

Ce que fait la page

La page est un client de l’API REST de fichiers, et de rien d’autre. Elle n’a aucun droit propre : ce que l’ACL refuse, l’API le refuse, et la page affiche le detail du serveur.

• Un bouton dont le droit manque sur le dossier courant est grise.
• Les requetes partent une a une, plus le depot en cours, pour rester sous [auth] hash_per_address en Basic.
• Les depots partent un fichier apres l’autre, avec un panneau de progression (nom, pourcentage, debit, annulation).
• La liste est paginee par 200, triable par nom, taille ou date, dossiers d’abord.
• Le dossier courant est dans l’URL (#/rapports/2026) : precedent, suivant et liens fonctionnent.

Se connecter

Identifiant et mot de passe (Basic, utilisateur local), ou « Use a token instead » (Bearer, un JWT). La credential reste en memoire seulement : recharger la page deconnecte. Seul le theme est garde (craft-admin-theme). Les echecs comptent pour [api.ban].

Montages

La page commence a /, le home que rend GET ?rights. Un montage a / y montre son home_dir ; des montages sous des noms y montrent la racine synthetique qui les liste.

Telecharger : le ticket

Un lien du navigateur ne porte pas d’en-tete Authorization : la page demande un ticket (ce fichier, cet utilisateur, dix minutes ; voir L’API de fichiers), puis le navigateur telecharge en flux. Pendant ces dix minutes, « Reessayer » et la reprise du navigateur reutilisent la meme URL.

Les fichiers de la page sont publics, sous la meme CSP que la console ; les donnees passent par l’API.

Limites

Interface en anglais ou en francais (?lang=fr, sinon la langue du navigateur) ; sous 720 px, les actions passent dans un menu.

Audit : lire la piste

La piste d’audit dit qui a fait quoi, sur quel fichier, et si ca a marche ; refus et erreurs compris. Le vocabulaire des lignes (actions, champs, reason) est dans la reference.

{"timestamp":"2026-10-07T14:41:25.402Z","level":"INFO","target":"audit","fields":{"message":"audit: operation succeeded","source":"sftp","action":"upload","session_id":"550e8400-e29b-41d4-a716-446655440000","remote_addr":"192.168.1.42","username":"alice","path":"/in/rapport.csv","backend":"disque","new_path":"","count":524288,"replaced":"no","removed":"","result":"success"}}

Ou elle va

Rotation, retention et niveau : Journaux.

Ce qu’elle garde

log.audit (all, changes, failures) ne retire que des succes ; les refus anonymes repetes sont resumes en connection_rejected_summary. Voir Le volume de la piste et Refus repetes.

Severite

Une alerte sur les WARN de la piste ne se declenche donc pas pour un scanner anonyme.

Filtrer

Dans la console, onglet Logs, source audit (permission audit) : filtres par niveau, periode, texte et champ:valeur ; chaque lecture ecrit une ligne audit_read. Voir Console et API d’administration.

# l'API de la console
curl -H "Authorization: Bearer $TOKEN" \
  'http://serveur:8081/admin/logs/audit?field=username:alice&level=WARN&since=2026-10-07T00:00:00Z'

# les fichiers ; sans [log] dir : docker logs ... | jq -c 'select(.target == "audit")'
jq -c 'select(.fields.username == "alice")' /var/log/craft-file-gate/craft-file-gate-audit.log

Le texte d’une erreur du stockage n’est pas dans la piste : cherchez-le dans le journal applicatif, a la meme heure, avec le meme path.

Une piste incomplete

Une ligne que le serveur ne peut pas ecrire (pipe ferme, disque plein) est perdue : craftfilegate_log_write_errors_total le compte, stderr le dit au plus une fois par minute, et le serveur continue de servir. Alertez sur increase(craftfilegate_log_write_errors_total[5m]) > 0.

Metriques

curl http://serveur:8081/metrics          # texte Prometheus, sans credential

# prometheus.yml
scrape_configs:
  - job_name: craftfilegate
    static_configs:
      - targets: ['serveur:8081']   # probes_listen, sinon control_listen, sinon admin.listen

• Valeurs cumulees depuis le demarrage, par pod ; un debit se calcule entre deux lectures (rate()).
• Une valeur inconnue est absente (null en JSON, aucun point en OTLP), jamais 0 : la colonne « Absente quand » dit quand.
• Le nom OTLP est le nom Prometheus sans _total.

Catalogue

craftfilegate_connections_rejected_total compte par tentative, plusieurs par connexion : son rapport a craftfilegate_connections_total n’est pas un taux d’echec par connexion.

Seuils de la console

[admin.metrics_thresholds] decide seulement ou l’onglet Metrics marque une tuile ; le serveur n’alerte pas. Les cles et leurs defauts : reference.

Alertes

groups:
  - name: craftfilegate
    rules:
      - alert: CraftFileGateAdminCertExpiringSoon
        expr: craftfilegate_admin_tls_cert_not_after_seconds - time() < 30 * 86400
        for: 1h
      - alert: CraftFileGateAdminCertExpiryUnknown
        expr: craftfilegate_admin_tls_cert_expiry_unreadable == 1
      - alert: CraftFileGateBackendErrors
        expr: increase(craftfilegate_backend_errors_total[5m]) > 0
      - alert: CraftFileGateBackendDown
        expr: craftfilegate_backend_up == 0
      - alert: CraftFileGateStorageAlone
        expr: craftfilegate_unready_detector{detector="storage_alone"} == 1
      - alert: CraftFileGateIsolated
        expr: craftfilegate_cluster_isolated == 1

Alerter sur la peremption du cache JWKS

      - alert: CraftFileGateJwksStale
        expr: craftfilegate_jwks_cache_age_seconds > 2 * 3600   # 2 x jwks_refresh_interval_secs
        for: 5m
      - alert: CraftFileGateJwksNeverLoaded
        expr: absent(craftfilegate_jwks_cache_age_seconds) and on() craftfilegate_jwks_cached_keys >= 0
        for: 5m

Un cache perime garde ses cles : les jetons signes par une cle tournee depuis sont refuses. jwks_age_secs fait le meme jugement pour /admin/status.

Rechargement

vi /etc/craft-file-gate/users.toml          # le serveur voit l'edition et recharge
kill -HUP $(pidof craft-file-gate)          # ou : recharger tout de suite

[reload]
watch = "auto"            # auto | inotify | poll
poll_interval_secs = 5    # periode de la relecture periodique

Ce qui est surveille

config.toml toujours ; users_file, roles_file et la paire [admin.tls] quand ils sont configures. Le serveur surveille le repertoire de chaque fichier : un remplacement atomique (sed -i, mv) et la bascule du lien ..data d’un volume ConfigMap ou Secret sont vus. Les evenements sont regroupes par rafale de 200 ms, et une seule tache relit. SIGHUP declenche un rechargement, meme sans surveillance.

Ce qu’un rechargement fait

Il relit tous les fichiers surveilles, quel que soit celui qui a change.

Une authentification, ou une requete REST, lit les utilisateurs en vigueur a son arrivee. Un fichier relu est juge comme au demarrage. Une variable d’environnement definie garde le dernier mot.

Ce qu’un rechargement applique, cle par cle

Les cles marquees ⟳ dans la reference ; une cle sans marque est lue au demarrage. Les entrees [[users]], [[roles]] et [[backends]] sont rechargees quand elles vivent dans users_file ou roles_file ; ecrites dans config.toml, elles sont lues au demarrage. Les chemins de [admin.tls] demandent un redemarrage ; le contenu de la paire, lui, est relu a chaque rechargement.

inotify ou relecture periodique

Toutes les cles : Reference [reload].

Les deux cles sont lues au demarrage.

• Une seule instance inotify par processus, partagee avec les fichiers de bans ; poll convient la ou elles sont rares (fs.inotify.max_user_instances, par UID et pour tout le noeud).
• La relecture periodique compare date, taille, inode, ctime, proprietaire et mode ; un intervalle sans changement n’ecrit rien.
• Quand la file d’evenements du noyau deborde (fs.inotify.max_queued_events), tous les fichiers sont relus ; des debordements repetes disent qu’un voisin agite le repertoire de configuration : deplacez-la, ou montez la limite.

Ce que vous verrez

Arret

[server]
shutdown_grace_period_secs = 30   # attente du travail en cours, toutes portes

docker stop -t 90 craft-file-gate                  # Docker
# Kubernetes : terminationGracePeriodSeconds: 90

Les etapes

SIGTERM ou SIGINT (Ctrl-C) declenchent l’arret, le serveur fut-il PID 1.

Les etapes 5, 7 et 8 partagent un seul delai, compte depuis l’annonce. Sans transfert en cours, l’arret ne l’attend pas.

Regler l’orchestrateur

Le pire cas d’un arret :

Le delai d’arret de l’orchestrateur doit le depasser : docker stop -t 90, terminationGracePeriodSeconds: 90, que le chart pose (delai de grace plus 60 s). Un SIGKILL avant la fin coupe les transferts sans ligne d’audit, laisse les multipart S3 ouverts et perd les spans non exportes.

Ce que vous verrez

Chaque etape ecrit sa ligne INFO : shutdown signal received, ban files written out before the shutdown sequence, idle sessions disconnected (idle_kicked), waiting for active transfers to complete (seulement s’il y en a), remaining sessions disconnected (force_kicked, 0 compris), graceful shutdown complete. Les sessions coupees finissent en session_end reason=shutdown_idle (etape 4) ou shutdown (etape 6).

Performances et memoire

Memoire

La formule

pic ≈ 12 Mio                                  base (14,5 Mio en glibc)
    + 5,5 Mio                                 si un backend S3 sert
    + hash_workers × m + 2 Mio                verifications de mot de passe
    + sessions × 0,15 Mio
    + connexions en file de hachage × 70 Kio  au plus hash_queue
    + transferts locaux × 4 Mio
    + uploads S3 × 26 Mio + downloads S3 × 8 Mio
    + adresses suivies par les bans × 225 o

m est le plus grand m argon2 du fichier d’utilisateurs : 19 Mio au profil owasp-min (defaut de hash-password), 64 Mio au profil rfc9106-low-mem. La ligne de demarrage donne ce terme : peak_memory="1 thread × 19 MiB = 19 MiB". Voir Verification des mots de passe.

La formule est une borne haute : elle additionne des pics qui ne tombent pas tous au meme instant. Aucun cas mesure ne l’a depassee. La taille des fichiers n’y entre pas : les transferts sont en flux.

Les termes sont des mesures sur l’image publiee (binaire musl statique, x86_64), client OpenSSH ; une connexion en file de hachage pese ~42 Kio en Basic, un telechargement local 2,3 Mio. A grande echelle avec S3, les uploads dominent : 4 fils a m=65536 et 10 uploads S3 mesurent 415 Mio (formule : 537). Rien ne plafonne le nombre d’uploads S3 simultanes ; max_sessions_per_user borne par utilisateur.

Un petit deploiement sous 80 Mo

30 utilisateurs, ~900 fichiers par jour : quelques clients simultanes.

[auth]
hash_workers = 1      # une verification a la fois : 1 × 19 Mio
hash_queue = 32       # une file pleine : 32 × 70 Kio = 2,2 Mio

Avec des hashs hash-password (profil owasp-min), sans aucun hash rfc9106-low-mem dans le fichier :

Binaires glibc

Les images Docker (musl) rendent la memoire apres chaque pic ; un binaire glibc (releases, hote glibc) garde dans ses arenes la memoire des hashs : 95 Mio retenus apres une rafale (4 fils, m=19456), 19 Mio avec MALLOC_MMAP_THRESHOLD_=4194304. Posez cette variable (Environment= dans l’unite systemd) et ne reglez pas MALLOC_ARENA_MAX, qui monte le pic.

Kubernetes

Le chart livre requests.memory: 64Mi et limits.memory: 256Mi. Avec son defaut (1 fil, tire de requests.cpu: 100m), 1000 connexions SSH en file au profil rfc9106-low-mem montent a 146 Mio. Sur un noeud charge, montez la requete vers le pic attendu.

Un pod sans limits.cpu voit les CPU du noeud : voir Verification des mots de passe pour fixer le pool.

Suivre la memoire

/metrics expose process_resident_memory_bytes et process_peak_resident_memory_bytes (Linux seulement), et la console les trace en direct. Voir Metriques.

Non mesure : transferts REST, proxy SFTP, telemetrie active, milliers d’utilisateurs, aarch64 et Windows.

Verification des mots de passe

[auth]
hash_workers = 2         # fils qui calculent les hashs
hash_queue = 1024        # tentatives qui attendent un fil
hash_per_address = 4     # places qu'une adresse peut tenir a la fois

Les options

Les trois cles sont lues au demarrage ; un rechargement ne change pas la taille du pool. Toutes les cles : Reference [auth].

Comment ca marche

Un hash argon2id, bcrypt ou sha512-crypt est du calcul pur : de 16 ms (owasp-min) a plus d’une seconde (argon2 lourd). Les verifications tournent sur des fils dedies (craft-file-gate-hash-0, -1… dans ps -L), hors du runtime qui sert les transferts, l’API et les sondes.

Une tentative prend sa place avant la recherche du compte : un nom connu et un nom inconnu recoivent la meme reponse. Les limiteurs de debit et les bans (Bans) bornent ce qu’une rafale coute a la file.

Derriere un reverse proxy, declarez-le dans trusted_proxies : chaque client compte a sa propre adresse. Une adresse de NAT va dans whitelist_ips de la porte ([sftp.ban], [api.ban], [admin.ban]), qui n’est pas plafonnee. La connexion a la console (POST /admin/login) passe par le meme pool.

Choisir les tailles

Ce que vous verrez

Au demarrage, une ligne dit chaque nombre et sa source :

INFO password hashing pool started: passwords are checked on these threads, off the async runtime, ...
     workers=2 workers_source="detected (8 CPUs ...), capped at 2 by default: ..."
     queue=1024 queue_source="default (1024, ...)"
     per_address=4 per_address_source="default (4 per address, ...)"
     peak_memory="2 threads × 19 MiB = 38 MiB"
     tokio_workers=8 tokio_workers_source="detected (std::thread::available_parallelism)"

tokio_workers : les fils du runtime async, sur la meme detection sans plafond, ou TOKIO_WORKER_THREADS.

Un rechargement de users.toml qui change le plus grand m le dit : INFO password hashing peak memory changed with the users file.

Kubernetes

Un pod sans limits.cpu voit les CPU du noeud (32, 64). Le plafond a 2 protege le pool par defaut, pas le runtime tokio. Pour suivre ce que le pod demande, passez requests.cpu par l’API Downward (arrondi a l’entier superieur) :

env:
  - name: CRAFT_FILE_GATE_HASH_WORKERS
    valueFrom:
      resourceFieldRef:
        containerName: craft-file-gate
        resource: requests.cpu
        divisor: "1"
  # de meme pour TOKIO_WORKER_THREADS

Une valeur explicite n’a pas de plafond : requests.cpu: 8 donne 8 fils et 8 x m de memoire. Le chart Helm le fait par passwordHashing.workers (vide : requests.cpu) et passwordHashing.queue.

Depannage

Un index des erreurs : le mot exact que vous voyez (message au demarrage, reason d’une ligne d’audit, statut SFTP, code REST) mene a la page du guide qui definit l’option en cause, puis, entre parentheses, a sa table dans la reference, et a l’identifiant de la regle de comportement, a citer au support. <...> marque une partie variable. Le vocabulaire complet des lignes d’audit est dans la reference.

Demarrage et configuration

Un reglage casse refuse le demarrage ; un reglage sans effet demarre avec un WARN qui nomme la cle.

Rechargement

Un fichier refuse au rechargement garde ce qui est en vigueur. Voir Rechargement.

Connexion et authentification

reason des lignes connection_rejected, et ce que voit le client. Les portes HTTP repondent une erreur en application/problem+json, champ detail.

Operations sur fichiers

reason des lignes d’operation, statut SFTP et code REST.