Volumes : le stockage que crée fileshare

Depuis la v0.21.0, l’API d’administration peut créer le stockage qu’un partage sert — un jeu de données ZFS, un sous-volume btrfs, un répertoire XFS ou ext4 sous quota de projet — dimensionné, attribué et suivi, et servir un partage à partir de celui-ci. Linux seulement. Ceph n’est pas encore pris en charge.

Créer ce stockage exige CAP_SYS_ADMIN (quotactl, les ioctl de quota btrfs, /dev/zfs, mount(2)). fileshare serve analyse cinq protocoles réseau pour le compte d’inconnus et ne détient aucun privilège : la partie qui en a besoin est donc un second rôle du même binaire, fileshare provisioner (l’approvisionneur, provisioner), derrière un socket unix et un petit protocole fermé :

                         admin gRPC (unix socket 0600 + peer uid, or mTLS)
  operator ─────────────────────────────────────────────▶  fileshare serve
                                                             (unprivileged)
                                                                  │
                     provision gRPC (unix socket, SO_PEERCRED = fileshare's uid)
                                                                  ▼
                                                    fileshare provisioner
                                                    (CAP_SYS_ADMIN, CAP_CHOWN, CAP_FOWNER)
                                                                  │
                                    go-fsctl: zfs · btrfs · projquota (ioctls, no CLI)

Un binaire plutôt que deux démons : une seule version à déployer, une seule définition de protocole. Le stockage lui-même est géré par go-fsctl (pur Go, sans commande zfs ni btrfs). La conception, et ce qui a changé en cours de construction, se trouvent dans le docs/volumes.md du dépôt fileshare.

Les deux processus, configurés

fileshare serve, en tant qu’utilisateur fileshare (uid 990) :

# /etc/fileshare/fileshare.hcl
admin {
  listen          = "unix:///run/fileshare/admin.sock"
  state_file      = "/var/lib/fileshare/shares.json"
  source_roots    = ["/srv/fileshare/volumes"]
  provisioner     = "unix:///run/fileshare-provisioner/provisioner.sock"
  provisioner_uid = 0          # who must answer on that socket; 0 is the default
  allowed_uids    = [990]      # who may call this API
}

Le chemin d’un volume doit se trouver sous source_roots, comme toute autre source.

fileshare provisioner, en tant que root :

# /etc/fileshare-provisioner.hcl
provisioner {
  listen     = "unix:///run/fileshare-provisioner/provisioner.sock"
  client_uid = 990
  group      = "fileshare"
  max_volume = "10T"
  state_file = "/var/lib/fileshare-provisioner/volumes.json"

  parent "tank" {
    zfs  = "tank/fileshare"
    root = "/srv/fileshare/volumes/tank"
  }
  parent "fast" { btrfs = "/srv/fileshare/volumes/fast" }
  parent "plain" {
    xfs         = "/srv/fileshare/volumes/plain"
    project_ids = "100000-199999"
  }
}

Le fichier de l’approvisionneur ne contient rien d’autre que son bloc provisioner : le propre fichier de fileshare qui lui serait remis par erreur est refusé plutôt qu’à moitié lu.

Un volume est toujours <parent root>/<name> : le jeu de données tank/fileshare/<name> monté sur /srv/fileshare/volumes/tank/<name> (avec refquota), un sous-volume btrfs limité par son qgroup, un répertoire XFS ou ext4 avec un identifiant de projet pris dans la plage et une limite stricte de blocs. XFS et ext4 exigent l’option de montage prjquota (ext4 aussi les fonctionnalités project,quota).

La paire systemd

L’approvisionneur :

# fileshare-provisioner.service
[Service]
ExecStart=/usr/local/bin/fileshare provisioner -c /etc/fileshare-provisioner.hcl
RuntimeDirectory=fileshare-provisioner
RuntimeDirectoryMode=0755
StateDirectory=fileshare-provisioner
StateDirectoryMode=0700
CapabilityBoundingSet=CAP_SYS_ADMIN CAP_CHOWN CAP_FOWNER
# Run as root, or as a dedicated user with:
# AmbientCapabilities=CAP_SYS_ADMIN CAP_CHOWN CAP_FOWNER
NoNewPrivileges=yes
SystemCallFilter=@system-service @mount quotactl quotactl_fd
SystemCallArchitectures=native
LockPersonality=yes
RestrictRealtime=yes
# NOT ProtectSystem= nor ReadWritePaths=: they give the service its own
# mount namespace, and the ZFS volumes it mounts would be seen by nobody
# else. And no Landlock: a Landlock-restricted thread cannot mount(2).

Le serveur, sans aucune capacité :

# fileshare.service
[Unit]
Requires=fileshare-provisioner.service
After=fileshare-provisioner.service

[Service]
User=fileshare
Group=fileshare
ExecStart=/usr/local/bin/fileshare serve -c /etc/fileshare/fileshare.hcl
RuntimeDirectory=fileshare
StateDirectory=fileshare
# No capability at all: CAP_SYS_RESOURCE would let it past an ext4 quota,
# and fileshare refuses to serve volumes with it.
CapabilityBoundingSet=
AmbientCapabilities=
NoNewPrivileges=yes
ProtectSystem=strict
ReadWritePaths=/srv/fileshare/volumes /var/lib/fileshare

ProtectSystem= convient au serveur : c’est l’approvisionneur qui monte, et les montages se propagent vers l’espace de noms du serveur, pas dans l’autre sens : un volume ZFS monté après le démarrage du serveur lui est donc visible.

Les appels de l’API d’administration sur les volumes

fileshare serve les relaie à l’approvisionneur (admin.proto) :

DeleteShare ne supprime jamais un volume. « Les partages qui l’utilisent » sont les partages créés à partir de lui et tout partage — y compris ceux des fichiers de configuration, servis, désactivés ou indisponibles — dont l’image ou le répertoire se trouve à l’intérieur.

Un nom correspond à ^[a-z0-9][a-z0-9_-]{0,62}$, et une requête ne porte jamais de chemin : elle nomme un parent de la propre configuration de l’approvisionneur.

Avec reflection = true dans le bloc admin, grpcurl peut faire les appels. Le socket est en 0600 et allowed_uids ci-dessus ne nomme que l’uid de fileshare : lancez-le donc sous cet utilisateur :

S=/run/fileshare/admin.sock
A=fileshare.admin.v1.AdminService

sudo -u fileshare grpcurl -plaintext -unix $S $A/ListParents

# a 32 GiB volume on the XFS parent
sudo -u fileshare grpcurl -plaintext -unix $S \
  -d '{"parent": "plain", "name": "projects", "quota_bytes": "34359738368"}' \
  $A/CreateVolume

# a share served from it
sudo -u fileshare grpcurl -plaintext -unix $S \
  -d '{"name": "projects",
       "volume": {"parent": "plain", "name": "projects"},
       "grants": [{"subject": {"group": "staff"}, "access": "ACCESS_WRITE"}]}' \
  $A/CreateShare

# grow it to 64 GiB
sudo -u fileshare grpcurl -plaintext -unix $S \
  -d '{"parent": "plain", "name": "projects", "quota_bytes": "68719476736"}' \
  $A/ResizeVolume

Codes de statut

Les codes de l’approvisionneur reviennent tels qu’il les a donnés : INVALID_ARGUMENT (un nom hors de la grammaire, un parent inconnu, un quota de 0), OUT_OF_RANGE (au-delà de max_volume), RESOURCE_EXHAUSTED (le quota, ou l’augmentation d’un redimensionnement, dépasse ce que le parent a de libre en ce moment ; ou la plage d’identifiants de projet est épuisée), ALREADY_EXISTS, NOT_FOUND, FAILED_PRECONDITION, UNIMPLEMENTED.

Trois sont propres à fileshare :

• aucun provisioner configuré : FAILED_PRECONDITION ;
• l’approvisionneur refuse l’uid de ce serveur : FAILED_PRECONDITION aussi — c’est une erreur de déploiement (son client_uid est faux), pas quelque chose que l’appelant d’administration n’a pas le droit de faire ;
• l’approvisionneur ne répond pas : UNAVAILABLE.

Ce qui est vérifié avant qu’un volume ne soit servi

fileshare demande à l’approvisionneur où se trouve le volume, puis vérifie, lui-même :

• que le chemin est propre, absolu et — une fois résolu — sous source_roots ;
• que c’est un répertoire ;
• que statfs signale le système de fichiers du type (ZFS_SUPER_MAGIC, BTRFS_SUPER_MAGIC, XFS_SUPER_MAGIC, EXT4_SUPER_MAGIC) ;
• ZFS : que c’est un point de montage — son périphérique n’est pas celui de son parent. Le répertoire d’un jeu de données non monté accepterait des écritures hors de tout quota. (Le jeu de données qui y est monté n’est pas vérifié : la réponse de l’approvisionneur ne le dit pas.)
• btrfs : que c’est la racine d’un sous-volume — un simple répertoire sous le parent n’a pas de qgroup ;
• XFS et ext4 : qu’il porte un identifiant de projet non nul dont héritent ses nouveaux fichiers — un répertoire hors de tout projet est servi sans limite.

Le fichier d’état conserve le nom du volume, pas son chemin, et chaque démarrage redemande et revérifie. Un volume disparu, qui échoue à une vérification, ou dont l’approvisionneur ne répond pas en 10 s laisse son partage défini et non servi — c’est signalé au démarrage, par fileshare check, et dans le champ unavailable du partage — pendant que le reste du serveur démarre. EnableShare le retente.

Un partage plein

XFS signale un projet plein avec ENOSPC ; ext4, btrfs et ZFS avec EDQUOT. Depuis la v0.21.1, tous les protocoles répondent « plein » :

En v0.21.0, SMB répondait STATUS_ACCESS_DENIED et NFS répondait à un quota par NFS3ERR_NOSPC.

Cela s’applique à tout partage de répertoire, pas seulement aux volumes — voir la note de mise à jour.

La taille que voit un client

Chaque protocole demande au serveur la taille d’un partage à chaque requête : FSSTAT pour NFS, FileFsFullSizeInformation pour SMB et les propriétés de quota de la RFC 4331 pour WebDAV.

• ZFS, XFS et ext4 : la taille est ce que dit statfs à l’intérieur du volume, auquel le noyau répond par le quota (refquota pour ZFS, le quota de projet pour XFS et ext4).
• btrfs (depuis fileshare v0.23.0) : le statfs de btrfs ignore les qgroups et annonce le système de fichiers entier, donc le serveur prend les chiffres de l’approvisionneur. La taille est le quota du volume, et l’espace libre est le quota moins les octets référencés du qgroup, ou l’espace libre du système de fichiers s’il est plus petit. Le serveur interroge l’approvisionneur en arrière-plan, au plus une fois toutes les 5 secondes tant que des clients demandent, et répond entre-temps avec les derniers chiffres. btrfs met à jour le compte d’un qgroup quand il valide une transaction (toutes les 30 secondes par défaut) : l’espace libre vu par un client peut donc avoir ce retard sur les écritures. Avant la v0.23.0, un volume btrfs affichait le système de fichiers entier ; le quota s’appliquait quand même.

L’espace utilisé vient de l’approvisionneur (used_bytes) : lire l’utilisation d’un projet XFS ou ext4 exige CAP_SYS_ADMIN, que fileshare n’a pas.

Ce que promet l’approvisionneur

• Un seul uid, lu depuis le noyau. Le pair est identifié par SO_PEERCRED à sa connexion, et quiconque n’est pas client_uid — root compris — reçoit PERMISSION_DENIED avant qu’un seul octet de la requête ne soit décodé.
• Un ensemble fermé de verbes. Une méthode hors de son service, ou un message qui ne se décode pas ou porte un champ qu’il ne définit pas, ne reçoit aucune réponse : la connexion est fermée.
• Il ne touche jamais à ce qu’il n’a pas créé. ZFS : la propriété fileshare:volume propre au jeu de données — posée sur le jeu de données, puisque les propriétés utilisateur sont héritées et qu’une marque héritée n’est pas la sienne. btrfs : l’identifiant et l’uuid du sous-volume consignés dans state_file. XFS/ext4 : un identifiant de projet dans la plage du parent et consigné. Vérifié avant chaque redimensionnement, instantané et suppression.
• La suppression refuse les données et les instantanés sauf si destroy_data est défini, et est journalisée avant d’avoir lieu.

Mesuré

Dans la CI de fileshare, en tant que root sur de vrais pools et des systèmes de fichiers adossés à des périphériques loop, avec fileshare serve tournant en tant que nobody et piloté par l’API d’administration : les écritures en WebDAV et en SFTP s’arrêtent au quota d’un volume de 32 Mio sur les quatre types.

Pas encore

• Ceph. Les quotas CephFS et RBD viendront dans une phase ultérieure.