2. Informations RPC (RPC Information)
2.1 Authentification (Authentication)
Le service NFS utilise AUTH_NONE dans la procédure NULL. AUTH_UNIX, AUTH_DES ou AUTH_KERB sont utilisés pour toutes les autres procédures. D'autres types d'authentification pourront être pris en charge à l'avenir.
2.2 Constantes (Constants)
Voici les constantes RPC nécessaires pour appeler le service NFS Version 3. Elles sont données en décimal.
PROGRAM 100003
VERSION 3
2.3 Adresse de transport (Transport address)
Le protocole NFS est normalement pris en charge sur les protocoles TCP et UDP. Il utilise le port 2049, le même que le protocole NFS version 2.
2.4 Tailles (Sizes)
Voici les tailles, en octets décimaux, des différentes structures XDR utilisées dans le protocole NFS version 3 :
NFS3_FHSIZE 64
- La taille maximale en octets du descripteur de fichier opaque.
NFS3_COOKIEVERFSIZE 8
- La taille en octets du vérificateur de cookie opaque passé par READDIR et READDIRPLUS.
NFS3_CREATEVERFSIZE 8
- La taille en octets du vérificateur opaque utilisé pour CREATE exclusif.
NFS3_WRITEVERFSIZE 8
- La taille en octets du vérificateur opaque utilisé pour WRITE asynchrone.
2.5 Types de données de base (Basic Data Types)
Les définitions XDR suivantes sont des définitions de base utilisées dans d'autres structures.
uint64
typedef unsigned hyper uint64;
int64
typedef hyper int64;
uint32
typedef unsigned long uint32;
int32
typedef long int32;
filename3
typedef string filename3<>;
nfspath3
typedef string nfspath3<>;
fileid3
typedef uint64 fileid3;
cookie3
typedef uint64 cookie3;
cookieverf3
typedef opaque cookieverf3[NFS3_COOKIEVERFSIZE];
createverf3
typedef opaque createverf3[NFS3_CREATEVERFSIZE];
writeverf3
typedef opaque writeverf3[NFS3_WRITEVERFSIZE];
uid3
typedef uint32 uid3;
gid3
typedef uint32 gid3;
size3
typedef uint64 size3;
offset3
typedef uint64 offset3;
mode3
typedef uint32 mode3;
count3
typedef uint32 count3;
nfsstat3
enum nfsstat3 {
NFS3_OK = 0,
NFS3ERR_PERM = 1,
NFS3ERR_NOENT = 2,
NFS3ERR_IO = 5,
NFS3ERR_NXIO = 6,
NFS3ERR_ACCES = 13,
NFS3ERR_EXIST = 17,
NFS3ERR_XDEV = 18,
NFS3ERR_NODEV = 19,
NFS3ERR_NOTDIR = 20,
NFS3ERR_ISDIR = 21,
NFS3ERR_INVAL = 22,
NFS3ERR_FBIG = 27,
NFS3ERR_NOSPC = 28,
NFS3ERR_ROFS = 30,
NFS3ERR_MLINK = 31,
NFS3ERR_NAMETOOLONG = 63,
NFS3ERR_NOTEMPTY = 66,
NFS3ERR_DQUOT = 69,
NFS3ERR_STALE = 70,
NFS3ERR_REMOTE = 71,
NFS3ERR_BADHANDLE = 10001,
NFS3ERR_NOT_SYNC = 10002,
NFS3ERR_BAD_COOKIE = 10003,
NFS3ERR_NOTSUPP = 10004,
NFS3ERR_TOOSMALL = 10005,
NFS3ERR_SERVERFAULT = 10006,
NFS3ERR_BADTYPE = 10007,
NFS3ERR_JUKEBOX = 10008
};
Le type nfsstat3 est retourné avec les résultats de chaque procédure, sauf pour la procédure NULL. Une valeur de NFS3_OK indique que l'appel s'est terminé avec succès. Toute autre valeur indique qu'une erreur s'est produite lors de l'appel, identifiée par le code d'erreur. Notez que l'encodage numérique précis doit être suivi. Aucune autre valeur ne peut être retournée par un serveur. Les serveurs sont censés faire de leur mieux pour mapper les conditions d'erreur à l'ensemble des codes d'erreur définis. De plus, aucune priorité d'erreur n'est spécifiée par cette spécification. Les priorités d'erreur déterminent la valeur d'erreur qui doit être retournée lorsque plusieurs erreurs s'appliquent dans une situation donnée. La priorité d'erreur sera déterminée par l'implémentation individuelle du serveur. Si le client nécessite des priorités d'erreur spécifiques, il doit vérifier lui-même les erreurs spécifiques.
2.6 Numéros d'erreur définis (Defined Error Numbers)
Une description de chaque erreur définie suit :
NFS3_OK
- Indique que l'appel s'est terminé avec succès.
NFS3ERR_PERM
- Pas propriétaire. L'opération n'a pas été autorisée car l'appelant n'est pas un utilisateur privilégié (root) ou n'est pas le propriétaire de la cible de l'opération.
NFS3ERR_NOENT
- Fichier ou répertoire inexistant. Le nom de fichier ou de répertoire spécifié n'existe pas.
NFS3ERR_IO
- Erreur d'E/S. Une erreur matérielle (par exemple, une erreur disque) s'est produite lors du traitement de l'opération demandée.
NFS3ERR_NXIO
- Erreur d'E/S. Aucun périphérique ou adresse de ce type.
NFS3ERR_ACCES
- Permission refusée. L'appelant n'a pas la permission correcte pour effectuer l'opération demandée. Comparez ceci avec NFS3ERR_PERM, qui se limite aux échecs de permission du propriétaire ou de l'utilisateur privilégié.
NFS3ERR_EXIST
- Le fichier existe. Le fichier spécifié existe déjà.
NFS3ERR_XDEV
- Tentative de créer un lien physique inter-périphériques.
NFS3ERR_NODEV
- Aucun périphérique de ce type.
NFS3ERR_NOTDIR
- Pas un répertoire. L'appelant a spécifié un non-répertoire dans une opération de répertoire.
NFS3ERR_ISDIR
- Est un répertoire. L'appelant a spécifié un répertoire dans une opération non-répertoire.
NFS3ERR_INVAL
- Argument invalide ou argument non pris en charge pour une opération. Deux exemples sont la tentative d'un READLINK sur un objet autre qu'un lien symbolique ou la tentative d'un SETATTR d'un champ temporel sur un serveur qui ne prend pas en charge cette opération.
NFS3ERR_FBIG
- Fichier trop volumineux. L'opération aurait causé la croissance d'un fichier au-delà de la limite du serveur.
NFS3ERR_NOSPC
- Aucun espace restant sur le périphérique. L'opération aurait causé le dépassement de sa limite par le système de fichiers du serveur.
NFS3ERR_ROFS
- Système de fichiers en lecture seule. Une opération de modification a été tentée sur un système de fichiers en lecture seule.
NFS3ERR_MLINK
- Trop de liens physiques.
NFS3ERR_NAMETOOLONG
- Le nom de fichier dans une opération était trop long.
NFS3ERR_NOTEMPTY
- Une tentative a été faite pour supprimer un répertoire qui n'était pas vide.
NFS3ERR_DQUOT
- Limite dure de ressource (quota) dépassée. La limite de ressource de l'utilisateur sur le serveur a été dépassée.
NFS3ERR_STALE
- Descripteur de fichier invalide. Le descripteur de fichier donné dans les arguments était invalide. Le fichier référencé par ce descripteur de fichier n'existe plus ou l'accès à celui-ci a été révoqué.
NFS3ERR_REMOTE
- Trop de niveaux de remote dans le chemin. Le descripteur de fichier donné dans les arguments référençait un fichier sur un système de fichiers non local sur le serveur.
NFS3ERR_BADHANDLE
- Descripteur de fichier NFS illégal. Le descripteur de fichier a échoué aux vérifications de cohérence interne.
NFS3ERR_NOT_SYNC
- Une incompatibilité de synchronisation de mise à jour a été détectée lors d'une opération SETATTR.
NFS3ERR_BAD_COOKIE
- Le cookie READDIR ou READDIRPLUS est périmé.
NFS3ERR_NOTSUPP
- L'opération n'est pas prise en charge.
NFS3ERR_TOOSMALL
- Le tampon ou la demande est trop petit.
NFS3ERR_SERVERFAULT
- Une erreur s'est produite sur le serveur qui ne correspond à aucune des valeurs d'erreur légales du protocole NFS version 3. Le client doit traduire cela en une erreur appropriée. Les clients UNIX peuvent choisir de traduire cela en EIO.
NFS3ERR_BADTYPE
- Une tentative a été faite pour créer un objet d'un type non pris en charge par le serveur.
NFS3ERR_JUKEBOX
- Le serveur a initié la demande, mais n'a pas pu la terminer dans un délai opportun. Le client doit attendre puis réessayer la demande avec un nouvel ID de transaction RPC. Par exemple, cette erreur doit être retournée par un serveur qui prend en charge le stockage hiérarchique et reçoit une demande de traitement d'un fichier qui a été migré. Dans ce cas, le serveur doit démarrer le processus d'immigration et répondre au client avec cette erreur.
ftype3
enum ftype3 {
NF3REG = 1,
NF3DIR = 2,
NF3BLK = 3,
NF3CHR = 4,
NF3LNK = 5,
NF3SOCK = 6,
NF3FIFO = 7
};
L'énumération ftype3 donne le type d'un fichier. Le type NF3REG est un fichier régulier, NF3DIR est un répertoire, NF3BLK est un fichier périphérique bloc spécial, NF3CHR est un fichier périphérique caractère spécial, NF3LNK est un lien symbolique, NF3SOCK est un socket et NF3FIFO est un tube nommé. Notez que l'encodage enum précis doit être suivi.
specdata3
struct specdata3 {
uint32 specdata1;
uint32 specdata2;
};
L'interprétation des deux mots dépend du type d'objet du système de fichiers. Pour un fichier spécial bloc (NF3BLK) ou caractère spécial (NF3CHR), specdata1 et specdata2 sont respectivement les numéros de périphérique majeur et mineur. (Il s'agit évidemment d'une interprétation spécifique à UNIX.) Pour tous les autres types de fichiers, ces deux éléments doivent être définis sur 0 ou les valeurs doivent être convenues entre le client et le serveur. Si le client et le serveur ne s'accordent pas sur les valeurs, le client doit traiter ces champs comme s'ils étaient définis sur 0. Ce champ de données est retourné dans le cadre de la structure fattr3 et est donc disponible dans toutes les réponses retournant des attributs. Puisque ces champs sont par ailleurs inutilisés pour les objets qui ne sont pas des périphériques, des informations hors bande peuvent être transmises du serveur au client. Cependant, encore une fois, le serveur et le client doivent s'accorder sur les valeurs transmises.
nfs_fh3
struct nfs_fh3 {
opaque data<NFS3_FHSIZE>;
};
Le nfs_fh3 est l'objet opaque de longueur variable retourné par le serveur lors des opérations LOOKUP, CREATE, SYMLINK, MKNOD, LINK ou READDIRPLUS, qui est utilisé par le client lors des opérations ultérieures pour référencer le fichier. Le descripteur de fichier contient toutes les informations dont le serveur a besoin pour distinguer un fichier individuel. Pour le client, le descripteur de fichier est opaque. Le client stocke les descripteurs de fichier pour une utilisation dans une demande ultérieure et peut comparer deux descripteurs de fichier du même serveur pour l'égalité en effectuant une comparaison octet par octet, mais ne peut pas interpréter autrement le contenu des descripteurs de fichier. Si deux descripteurs de fichier du même serveur sont égaux, ils doivent faire référence au même fichier, mais s'ils ne sont pas égaux, aucune conclusion ne peut être tirée. Les serveurs doivent essayer de maintenir une correspondance un-à-un entre les descripteurs de fichier et les fichiers, mais cela n'est pas requis. Les clients doivent utiliser les comparaisons de descripteurs de fichier uniquement pour améliorer les performances, pas pour un comportement correct.
Les serveurs peuvent révoquer l'accès fourni par un descripteur de fichier à tout moment. Si le descripteur de fichier transmis dans un appel fait référence à un objet du système de fichiers qui n'existe plus sur le serveur ou si l'accès pour ce descripteur de fichier a été révoqué, l'erreur NFS3ERR_STALE doit être retournée.
nfstime3
struct nfstime3 {
uint32 seconds;
uint32 nseconds;
};
La structure nfstime3 donne le nombre de secondes et de nanosecondes depuis minuit le 1er janvier 1970, heure moyenne de Greenwich. Elle est utilisée pour transmettre des informations de date et d'heure. Les heures associées aux fichiers sont toutes des heures du serveur, sauf dans le cas d'une opération SETATTR où le client peut explicitement définir l'heure du fichier. Un serveur convertit vers et depuis l'heure locale lors du traitement des valeurs de temps, en préservant autant de précision que possible. Si la précision des horodatages stockés pour un fichier est inférieure à celle définie par le protocole NFS version 3, une perte de précision peut se produire. Un protocole de maintenance du temps adjoint est recommandé pour réduire le décalage temporel entre le client et le serveur.
fattr3
struct fattr3 {
ftype3 type;
mode3 mode;
uint32 nlink;
uid3 uid;
gid3 gid;
size3 size;
size3 used;
specdata3 rdev;
uint64 fsid;
fileid3 fileid;
nfstime3 atime;
nfstime3 mtime;
nfstime3 ctime;
};
Cette structure définit les attributs d'un objet du système de fichiers. Elle est retournée par la plupart des opérations sur un objet ; dans le cas d'opérations qui affectent deux objets (par exemple, un MKDIR qui modifie les attributs du répertoire cible et définit de nouveaux attributs pour le répertoire nouvellement créé), les attributs des deux peuvent être retournés. Dans certains cas, les attributs sont retournés dans la structure wcc_data, qui est définie ci-dessous ; dans d'autres cas, les attributs sont retournés seuls. Les principaux changements par rapport au protocole NFS version 2 sont que de nombreux champs ont été élargis et que les informations de périphérique majeur/mineur sont maintenant présentées dans une structure distincte plutôt que d'être empaquetées dans un mot.
La structure fattr3 contient les attributs de base d'un fichier. Tous les serveurs doivent prendre en charge cet ensemble d'attributs même s'ils doivent simuler certains des champs. Type est le type du fichier. Mode sont les bits de mode de protection. Nlink est le nombre de liens physiques vers le fichier, c'est-à-dire le nombre de noms différents pour le même fichier. Uid est l'ID utilisateur du propriétaire du fichier. Gid est l'ID de groupe du groupe du fichier. Size est la taille du fichier en octets. Used est le nombre d'octets d'espace disque que le fichier utilise réellement (qui peut être inférieur à la taille car le fichier peut avoir des trous ou il peut être plus grand en raison de la fragmentation). Rdev décrit le fichier périphérique si le type de fichier est NF3CHR ou NF3BLK - voir specdata3 page 20. Fsid est l'identifiant du système de fichiers pour le système de fichiers. Fileid est un nombre qui identifie de manière unique le fichier dans son système de fichiers (sur UNIX, ce serait le inumber). Atime est l'heure à laquelle les données du fichier ont été accédées pour la dernière fois. Mtime est l'heure à laquelle les données du fichier ont été modifiées pour la dernière fois. Ctime est l'heure à laquelle les attributs du fichier ont été modifiés pour la dernière fois. L'écriture dans le fichier modifie le ctime en plus du mtime.
Les bits de mode sont définis comme suit :
0x00800 Définir l'ID utilisateur à l'exécution.
0x00400 Définir l'ID de groupe à l'exécution.
0x00200 Enregistrer le texte échangé (non défini dans POSIX).
0x00100 Permission de lecture pour le propriétaire.
0x00080 Permission d'écriture pour le propriétaire.
0x00040 Permission d'exécution pour le propriétaire sur un fichier. Ou permission de recherche pour le propriétaire dans un répertoire.
0x00020 Permission de lecture pour le groupe.
0x00010 Permission d'écriture pour le groupe.
0x00008 Permission d'exécution pour le groupe sur un fichier. Ou permission de recherche pour le groupe dans un répertoire.
0x00004 Permission de lecture pour les autres.
0x00002 Permission d'écriture pour les autres.
0x00001 Permission d'exécution pour les autres sur un fichier. Ou permission de recherche pour les autres dans un répertoire.
post_op_attr
union post_op_attr switch (bool attributes_follow) {
case TRUE:
fattr3 attributes;
case FALSE:
void;
};
Cette structure est utilisée pour retourner des attributs dans les opérations qui ne sont pas directement impliquées dans la manipulation des attributs. L'un des principes de cette révision du protocole NFS est de retourner la valeur réelle de l'opération indiquée et non une erreur d'une opération accessoire. La structure post_op_attr a été conçue pour permettre au serveur de se remettre des erreurs rencontrées lors de l'obtention des attributs.
Cela semble rendre le retour des attributs facultatif. Cependant, les implémenteurs de serveurs sont fortement encouragés à faire de leur mieux pour retourner les attributs dans la mesure du possible, même lors du retour d'une erreur.
wcc_attr
struct wcc_attr {
size3 size;
nfstime3 mtime;
nfstime3 ctime;
};
Il s'agit du sous-ensemble des attributs de pré-opération nécessaires pour mieux prendre en charge la sémantique de cohérence de cache faible. Size est la taille du fichier en octets de l'objet avant l'opération. Mtime est l'heure de la dernière modification de l'objet avant l'opération. Ctime est l'heure du dernier changement des attributs de l'objet avant l'opération. Voir la discussion dans wcc_attr page 24.
L'utilisation de mtime par les clients pour détecter les changements des objets du système de fichiers résidant sur un serveur dépend de la granularité de la base de temps sur le serveur.
pre_op_attr
union pre_op_attr switch (bool attributes_follow) {
case TRUE:
wcc_attr attributes;
case FALSE:
void;
};
wcc_data
struct wcc_data {
pre_op_attr before;
post_op_attr after;
};
Lorsqu'un client effectue une opération qui modifie l'état d'un fichier ou d'un répertoire sur le serveur, il ne peut pas déterminer immédiatement à partir des attributs de post-opération si l'opération qui vient d'être effectuée était la seule opération sur l'objet depuis la dernière fois que le client a reçu les attributs de l'objet. Ceci est important, car si une opération intermédiaire a modifié l'objet, le client devra invalider toutes les données mises en cache pour l'objet (sauf les données qu'il vient d'écrire).
Pour gérer cela, la notion de données de cohérence de cache faible ou wcc_data est introduite. Une structure wcc_data se compose de certains champs clés des attributs de l'objet avant l'opération, ainsi que des attributs de l'objet après l'opération. Ces informations permettent au client de gérer son cache plus précisément que dans les implémentations du protocole NFS version 2. Le terme cohérence de cache faible souligne le fait que ce mécanisme ne fournit pas la cohérence stricte serveur-client qu'un protocole de cohérence de cache fournirait.
Pour prendre en charge le modèle de cohérence de cache faible, le serveur devra être capable d'obtenir les attributs de pré-opération de l'objet, d'effectuer l'opération de modification prévue, puis d'obtenir les attributs de post-opération de manière atomique. S'il existe une fenêtre pour que l'objet soit modifié entre l'opération et l'une ou l'autre des opérations d'obtention d'attributs, alors le client ne pourra pas déterminer s'il était la seule entité à modifier l'objet. Certaines informations auront été perdues, affaiblissant ainsi les garanties de cohérence de cache faible.
post_op_fh3
union post_op_fh3 switch (bool handle_follows) {
case TRUE:
nfs_fh3 handle;
case FALSE:
void;
};
L'un des principes de cette révision du protocole NFS est de retourner la valeur réelle de l'opération indiquée et non une erreur d'une opération accessoire. La structure post_op_fh3 a été conçue pour permettre au serveur de se remettre des erreurs rencontrées lors de la construction d'un descripteur de fichier.
Il s'agit de la structure utilisée pour retourner un descripteur de fichier à partir des demandes CREATE, MKDIR, SYMLINK, MKNOD et READDIRPLUS. Dans chaque cas, le client peut obtenir le descripteur de fichier en émettant une demande LOOKUP après un retour réussi de l'une des opérations répertoriées. Le retour du descripteur de fichier est une optimisation afin que le client ne soit pas forcé d'émettre immédiatement une demande LOOKUP pour obtenir le descripteur de fichier.
sattr3
enum time_how {
DONT_CHANGE = 0,
SET_TO_SERVER_TIME = 1,
SET_TO_CLIENT_TIME = 2
};
union set_mode3 switch (bool set_it) {
case TRUE:
mode3 mode;
default:
void;
};
union set_uid3 switch (bool set_it) {
case TRUE:
uid3 uid;
default:
void;
};
union set_gid3 switch (bool set_it) {
case TRUE:
gid3 gid;
default:
void;
};
union set_size3 switch (bool set_it) {
case TRUE:
size3 size;
default:
void;
};
union set_atime switch (time_how set_it) {
case SET_TO_CLIENT_TIME:
nfstime3 atime;
default:
void;
};
union set_mtime switch (time_how set_it) {
case SET_TO_CLIENT_TIME:
nfstime3 mtime;
default:
void;
};
struct sattr3 {
set_mode3 mode;
set_uid3 uid;
set_gid3 gid;
set_size3 size;
set_atime atime;
set_mtime mtime;
};
La structure sattr3 contient les attributs de fichier qui peuvent être définis à partir du client. Les champs sont les mêmes que les champs de nom similaire dans la structure fattr3. Dans le protocole NFS version 3, les attributs définissables sont décrits par une structure contenant un ensemble d'unions discriminées. Chaque union indique si l'attribut correspondant doit être mis à jour et, le cas échéant, comment.
Deux formes d'unions discriminées sont utilisées. Pour définir le mode, l'uid, le gid ou la taille, l'union discriminée est commutée sur un booléen, set_it ; s'il est TRUE, une valeur du type approprié est alors encodée.
Pour définir atime ou mtime, l'union est commutée sur un type d'énumération, set_it. Si set_it a la valeur DONT_CHANGE, l'attribut correspondant est inchangé. S'il a la valeur SET_TO_SERVER_TIME, l'attribut correspondant est défini par le serveur à son heure locale ; aucune donnée n'est fournie par le client. Enfin, si set_it a la valeur SET_TO_CLIENT_TIME, l'attribut est défini sur l'heure transmise par le client dans une structure nfstime3. (Voir FSINFO page 86, qui traite de la question de la granularité temporelle).
diropargs3
struct diropargs3 {
nfs_fh3 dir;
filename3 name;
};
La structure diropargs3 est utilisée dans les opérations de répertoire. Le descripteur de fichier, dir, identifie le répertoire dans lequel manipuler ou accéder au fichier, name. Voir les commentaires supplémentaires dans Gestion des composants de nom de fichier page 101.