2. Informazioni RPC (RPC Information)

2.1 Autenticazione (Authentication)

Il servizio NFS utilizza AUTH_NONE nella procedura NULL. AUTH_UNIX, AUTH_DES o AUTH_KERB sono utilizzati per tutte le altre procedure. Altri tipi di autenticazione potrebbero essere supportati in futuro.

2.2 Costanti (Constants)

Queste sono le costanti RPC necessarie per chiamare il servizio NFS versione 3. Sono fornite in decimale.

PROGRAM  100003
VERSION  3

2.3 Indirizzo di trasporto (Transport address)

Il protocollo NFS è normalmente supportato sui protocolli TCP e UDP. Utilizza la porta 2049, la stessa del protocollo NFS versione 2.

2.4 Dimensioni (Sizes)

Queste sono le dimensioni, espresse in byte decimali, di varie strutture XDR utilizzate nel protocollo NFS versione 3:

NFS3_FHSIZE 64

• La dimensione massima in byte dell'handle di file opaco.

NFS3_COOKIEVERFSIZE 8

• La dimensione in byte del verificatore di cookie opaco passato da READDIR e READDIRPLUS.

NFS3_CREATEVERFSIZE 8

• La dimensione in byte del verificatore opaco utilizzato per CREATE esclusivo.

NFS3_WRITEVERFSIZE 8

• La dimensione in byte del verificatore opaco utilizzato per WRITE asincrono.

2.5 Tipi di dati di base (Basic Data Types)

Le seguenti definizioni XDR sono definizioni di base utilizzate in altre strutture.

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
};

Il tipo nfsstat3 viene restituito con i risultati di ogni procedura, eccetto la procedura NULL. Un valore di NFS3_OK indica che la chiamata è stata completata con successo. Qualsiasi altro valore indica che si è verificato un errore nella chiamata, identificato dal codice di errore. Si noti che deve essere seguita la codifica numerica precisa. Nessun altro valore può essere restituito da un server. I server sono tenuti a fare il miglior sforzo possibile per mappare le condizioni di errore all'insieme di codici di errore definiti. Inoltre, questa specifica non specifica alcuna precedenza di errore. Le precedenze di errore determinano il valore di errore che dovrebbe essere restituito quando più errori si applicano in una determinata situazione. La precedenza di errore sarà determinata dall'implementazione individuale del server. Se il client richiede precedenze di errore specifiche, dovrebbe controllare autonomamente gli errori specifici.

2.6 Numeri di errore definiti (Defined Error Numbers)

Segue una descrizione di ciascun errore definito:

NFS3_OK

• Indica che la chiamata è stata completata con successo.

NFS3ERR_PERM

• Non proprietario. L'operazione non è stata consentita perché il chiamante non è un utente privilegiato (root) o non è il proprietario del target dell'operazione.

NFS3ERR_NOENT

• File o directory inesistente. Il nome del file o della directory specificato non esiste.

NFS3ERR_IO

• Errore di I/O. Si è verificato un errore hardware (ad esempio, un errore del disco) durante l'elaborazione dell'operazione richiesta.

NFS3ERR_NXIO

• Errore di I/O. Nessun dispositivo o indirizzo di questo tipo.

NFS3ERR_ACCES

• Permesso negato. Il chiamante non ha il permesso corretto per eseguire l'operazione richiesta. Confronta questo con NFS3ERR_PERM, che si limita ai fallimenti di permesso del proprietario o dell'utente privilegiato.

NFS3ERR_EXIST

• Il file esiste. Il file specificato esiste già.

NFS3ERR_XDEV

• Tentativo di creare un hard link tra dispositivi diversi.

NFS3ERR_NODEV

• Nessun dispositivo di questo tipo.

NFS3ERR_NOTDIR

• Non è una directory. Il chiamante ha specificato una non-directory in un'operazione di directory.

NFS3ERR_ISDIR

• È una directory. Il chiamante ha specificato una directory in un'operazione non-directory.

NFS3ERR_INVAL

• Argomento non valido o argomento non supportato per un'operazione. Due esempi sono il tentativo di eseguire un READLINK su un oggetto diverso da un link simbolico o il tentativo di eseguire un SETATTR di un campo temporale su un server che non supporta questa operazione.

NFS3ERR_FBIG

• File troppo grande. L'operazione avrebbe causato la crescita di un file oltre il limite del server.

NFS3ERR_NOSPC

• Nessuno spazio rimasto sul dispositivo. L'operazione avrebbe causato il superamento del limite del file system del server.

NFS3ERR_ROFS

• File system di sola lettura. È stata tentata un'operazione di modifica su un file system di sola lettura.

NFS3ERR_MLINK

• Troppi hard link.

NFS3ERR_NAMETOOLONG

• Il nome del file in un'operazione era troppo lungo.

NFS3ERR_NOTEMPTY

• È stato tentato di rimuovere una directory che non era vuota.

NFS3ERR_DQUOT

• Limite rigido della risorsa (quota) superato. Il limite di risorse dell'utente sul server è stato superato.

NFS3ERR_STALE

• Handle di file non valido. L'handle di file fornito negli argomenti non era valido. Il file a cui fa riferimento quell'handle di file non esiste più o l'accesso ad esso è stato revocato.

NFS3ERR_REMOTE

• Troppi livelli di remoto nel percorso. L'handle di file fornito negli argomenti faceva riferimento a un file su un file system non locale sul server.

NFS3ERR_BADHANDLE

• Handle di file NFS illegale. L'handle di file ha fallito i controlli di coerenza interna.

NFS3ERR_NOT_SYNC

• Rilevata mancata corrispondenza della sincronizzazione dell'aggiornamento durante un'operazione SETATTR.

NFS3ERR_BAD_COOKIE

• Il cookie READDIR o READDIRPLUS è obsoleto.

NFS3ERR_NOTSUPP

• L'operazione non è supportata.

NFS3ERR_TOOSMALL

• Il buffer o la richiesta è troppo piccola.

NFS3ERR_SERVERFAULT

• Si è verificato un errore sul server che non corrisponde a nessuno dei valori di errore legali del protocollo NFS versione 3. Il client dovrebbe tradurlo in un errore appropriato. I client UNIX possono scegliere di tradurlo in EIO.

NFS3ERR_BADTYPE

• È stato tentato di creare un oggetto di un tipo non supportato dal server.

NFS3ERR_JUKEBOX

• Il server ha avviato la richiesta, ma non è stato in grado di completarla in modo tempestivo. Il client dovrebbe attendere e quindi riprovare la richiesta con un nuovo ID di transazione RPC. Ad esempio, questo errore dovrebbe essere restituito da un server che supporta l'archiviazione gerarchica e riceve una richiesta di elaborazione di un file che è stato migrato. In questo caso, il server dovrebbe avviare il processo di immigrazione e rispondere al client con questo errore.

ftype3

enum ftype3 {
   NF3REG    = 1,
   NF3DIR    = 2,
   NF3BLK    = 3,
   NF3CHR    = 4,
   NF3LNK    = 5,
   NF3SOCK   = 6,
   NF3FIFO   = 7
};

L'enumerazione ftype3 fornisce il tipo di un file. Il tipo NF3REG è un file regolare, NF3DIR è una directory, NF3BLK è un file dispositivo a blocchi speciale, NF3CHR è un file dispositivo a caratteri speciale, NF3LNK è un link simbolico, NF3SOCK è un socket e NF3FIFO è una pipe con nome. Si noti che deve essere seguita la codifica enum precisa.

specdata3

struct specdata3 {
     uint32     specdata1;
     uint32     specdata2;
};

L'interpretazione delle due parole dipende dal tipo di oggetto del file system. Per un file speciale a blocchi (NF3BLK) o a caratteri (NF3CHR), specdata1 e specdata2 sono rispettivamente i numeri di dispositivo major e minor. (Questa è ovviamente un'interpretazione specifica di UNIX.) Per tutti gli altri tipi di file, questi due elementi dovrebbero essere impostati su 0 oppure i valori dovrebbero essere concordati tra client e server. Se il client e il server non concordano sui valori, il client dovrebbe trattare questi campi come se fossero impostati su 0. Questo campo dati viene restituito come parte della struttura fattr3 ed è quindi disponibile da tutte le risposte che restituiscono attributi. Poiché questi campi sono altrimenti inutilizzati per oggetti che non sono dispositivi, informazioni fuori banda possono essere passate dal server al client. Tuttavia, ancora una volta, sia il server che il client devono concordare sui valori passati.

nfs_fh3

struct nfs_fh3 {
   opaque       data<NFS3_FHSIZE>;
};

Il nfs_fh3 è l'oggetto opaco a lunghezza variabile restituito dal server nelle operazioni LOOKUP, CREATE, SYMLINK, MKNOD, LINK o READDIRPLUS, che viene utilizzato dal client nelle operazioni successive per fare riferimento al file. L'handle di file contiene tutte le informazioni di cui il server ha bisogno per distinguere un singolo file. Per il client, l'handle di file è opaco. Il client memorizza gli handle di file per l'uso in una richiesta successiva e può confrontare due handle di file dallo stesso server per l'uguaglianza eseguendo un confronto byte per byte, ma non può interpretare altrimenti il contenuto degli handle di file. Se due handle di file dallo stesso server sono uguali, devono fare riferimento allo stesso file, ma se non sono uguali, non si possono trarre conclusioni. I server dovrebbero cercare di mantenere una corrispondenza uno-a-uno tra handle di file e file, ma questo non è richiesto. I client dovrebbero utilizzare i confronti di handle di file solo per migliorare le prestazioni, non per un comportamento corretto.

I server possono revocare l'accesso fornito da un handle di file in qualsiasi momento. Se l'handle di file passato in una chiamata fa riferimento a un oggetto del file system che non esiste più sul server o se l'accesso per quell'handle di file è stato revocato, deve essere restituito l'errore NFS3ERR_STALE.

nfstime3

struct nfstime3 {
   uint32   seconds;
   uint32   nseconds;
};

La struttura nfstime3 fornisce il numero di secondi e nanosecondi dalla mezzanotte del 1° gennaio 1970, ora media di Greenwich. Viene utilizzata per passare informazioni su data e ora. I tempi associati ai file sono tutti tempi del server, tranne nel caso di un'operazione SETATTR in cui il client può impostare esplicitamente l'ora del file. Un server converte da e verso l'ora locale durante l'elaborazione dei valori temporali, preservando la maggior precisione possibile. Se la precisione dei timestamp memorizzati per un file è inferiore a quella definita dal protocollo NFS versione 3, può verificarsi una perdita di precisione. Si raccomanda un protocollo ausiliario di manutenzione del tempo per ridurre lo scostamento temporale tra client e server.

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;
};

Questa struttura definisce gli attributi di un oggetto del file system. Viene restituita dalla maggior parte delle operazioni su un oggetto; nel caso di operazioni che influenzano due oggetti (ad esempio, un MKDIR che modifica gli attributi della directory di destinazione e definisce nuovi attributi per la directory appena creata), gli attributi di entrambi possono essere restituiti. In alcuni casi, gli attributi vengono restituiti nella struttura wcc_data, definita di seguito; in altri casi gli attributi vengono restituiti da soli. Le principali modifiche rispetto al protocollo NFS versione 2 sono che molti dei campi sono stati ampliati e le informazioni sul dispositivo major/minor sono ora presentate in una struttura distinta anziché essere impacchettate in una parola.

La struttura fattr3 contiene gli attributi di base di un file. Tutti i server dovrebbero supportare questo insieme di attributi anche se devono simulare alcuni dei campi. Type è il tipo del file. Mode sono i bit della modalità di protezione. Nlink è il numero di hard link al file, cioè il numero di nomi diversi per lo stesso file. Uid è l'ID utente del proprietario del file. Gid è l'ID del gruppo del file. Size è la dimensione del file in byte. Used è il numero di byte di spazio su disco che il file utilizza effettivamente (che può essere inferiore alla dimensione perché il file può avere buchi o può essere maggiore a causa della frammentazione). Rdev descrive il file del dispositivo se il tipo di file è NF3CHR o NF3BLK - vedi specdata3 a pagina 20. Fsid è l'identificatore del file system per il file system. Fileid è un numero che identifica univocamente il file all'interno del suo file system (su UNIX questo sarebbe l'inumber). Atime è il momento in cui i dati del file sono stati acceduti per l'ultima volta. Mtime è il momento in cui i dati del file sono stati modificati per l'ultima volta. Ctime è il momento in cui gli attributi del file sono stati modificati per l'ultima volta. La scrittura nel file modifica il ctime oltre al mtime.

I bit della modalità sono definiti come segue:

0x00800 Imposta ID utente all'esecuzione.
0x00400 Imposta ID gruppo all'esecuzione.
0x00200 Salva testo scambiato (non definito in POSIX).
0x00100 Permesso di lettura per il proprietario.
0x00080 Permesso di scrittura per il proprietario.
0x00040 Permesso di esecuzione per il proprietario su un file. O permesso di ricerca (lookup) per il proprietario nella directory.
0x00020 Permesso di lettura per il gruppo.
0x00010 Permesso di scrittura per il gruppo.
0x00008 Permesso di esecuzione per il gruppo su un file. O permesso di ricerca (lookup) per il gruppo nella directory.
0x00004 Permesso di lettura per altri.
0x00002 Permesso di scrittura per altri.
0x00001 Permesso di esecuzione per altri su un file. O permesso di ricerca (lookup) per altri nella directory.

post_op_attr

union post_op_attr switch (bool attributes_follow) {
case TRUE:
   fattr3   attributes;
case FALSE:
   void;
};

Questa struttura viene utilizzata per restituire attributi in quelle operazioni che non sono direttamente coinvolte nella manipolazione degli attributi. Uno dei principi di questa revisione del protocollo NFS è restituire il valore reale dall'operazione indicata e non un errore da un'operazione accessoria. La struttura post_op_attr è stata progettata per consentire al server di recuperare da errori riscontrati durante l'ottenimento degli attributi.

Questo sembra rendere opzionale la restituzione degli attributi. Tuttavia, gli implementatori di server sono fortemente incoraggiati a fare il miglior sforzo per restituire gli attributi quando possibile, anche quando si restituisce un errore.

wcc_attr

struct wcc_attr {
   size3       size;
   nfstime3    mtime;
   nfstime3    ctime;
};

Questo è il sottoinsieme di attributi di pre-operazione necessari per supportare meglio la semantica della coerenza della cache debole. Size è la dimensione del file in byte dell'oggetto prima dell'operazione. Mtime è il momento dell'ultima modifica dell'oggetto prima dell'operazione. Ctime è il momento dell'ultima modifica degli attributi dell'oggetto prima dell'operazione. Vedi la discussione in wcc_attr a pagina 24.

L'uso di mtime da parte dei client per rilevare le modifiche agli oggetti del file system che risiedono su un server dipende dalla granularità della base temporale sul server.

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;
};

Quando un client esegue un'operazione che modifica lo stato di un file o di una directory sul server, non può determinare immediatamente dagli attributi di post-operazione se l'operazione appena eseguita è stata l'unica operazione sull'oggetto dall'ultima volta che il client ha ricevuto gli attributi per l'oggetto. Questo è importante, perché se un'operazione intermedia ha modificato l'oggetto, il client dovrà invalidare tutti i dati memorizzati nella cache per l'oggetto (tranne i dati che ha appena scritto).

Per gestire questo, viene introdotta la nozione di dati di coerenza della cache debole o wcc_data. Una struttura wcc_data consiste di alcuni campi chiave degli attributi dell'oggetto prima dell'operazione, insieme agli attributi dell'oggetto dopo l'operazione. Queste informazioni consentono al client di gestire la propria cache in modo più accurato rispetto alle implementazioni del protocollo NFS versione 2. Il termine coerenza della cache debole sottolinea il fatto che questo meccanismo non fornisce la stretta coerenza server-client che un protocollo di coerenza della cache fornirebbe.

Per supportare il modello di coerenza della cache debole, il server dovrà essere in grado di ottenere gli attributi di pre-operazione dell'oggetto, eseguire l'operazione di modifica prevista e quindi ottenere gli attributi di post-operazione in modo atomico. Se esiste una finestra per la modifica dell'oggetto tra l'operazione e una delle operazioni di ottenimento degli attributi, allora il client non sarà in grado di determinare se era l'unica entità a modificare l'oggetto. Alcune informazioni saranno andate perse, indebolendo così le garanzie di coerenza della cache debole.

post_op_fh3

union post_op_fh3 switch (bool handle_follows) {
case TRUE:
     nfs_fh3  handle;
case FALSE:
     void;
};

Uno dei principi di questa revisione del protocollo NFS è restituire il valore reale dall'operazione indicata e non un errore da un'operazione accessoria. La struttura post_op_fh3 è stata progettata per consentire al server di recuperare da errori riscontrati durante la costruzione di un handle di file.

Questa è la struttura utilizzata per restituire un handle di file dalle richieste CREATE, MKDIR, SYMLINK, MKNOD e READDIRPLUS. In ogni caso, il client può ottenere l'handle di file emettendo una richiesta LOOKUP dopo un ritorno riuscito da una delle operazioni elencate. La restituzione dell'handle di file è un'ottimizzazione in modo che il client non sia costretto a emettere immediatamente una richiesta LOOKUP per ottenere l'handle di file.

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 struttura sattr3 contiene gli attributi del file che possono essere impostati dal client. I campi sono gli stessi dei campi con nome simile nella struttura fattr3. Nel protocollo NFS versione 3, gli attributi impostabili sono descritti da una struttura contenente un insieme di unioni discriminate. Ogni unione indica se l'attributo corrispondente deve essere aggiornato e, in tal caso, come.

Vengono utilizzate due forme di unioni discriminate. Nell'impostazione di mode, uid, gid o size, l'unione discriminata viene commutata su un booleano, set_it; se è TRUE, viene quindi codificato un valore del tipo appropriato.

Nell'impostazione di atime o mtime, l'unione viene commutata su un tipo di enumerazione, set_it. Se set_it ha il valore DONT_CHANGE, l'attributo corrispondente rimane invariato. Se ha il valore SET_TO_SERVER_TIME, l'attributo corrispondente viene impostato dal server alla sua ora locale; nessun dato viene fornito dal client. Infine, se set_it ha il valore SET_TO_CLIENT_TIME, l'attributo viene impostato all'ora passata dal client in una struttura nfstime3. (Vedi FSINFO a pagina 86, che affronta la questione della granularità temporale).

diropargs3

struct diropargs3 {
   nfs_fh3     dir;
   filename3   name;
};

La struttura diropargs3 viene utilizzata nelle operazioni di directory. L'handle di file, dir, identifica la directory in cui manipolare o accedere al file, name. Vedi commenti aggiuntivi in Gestione dei componenti del nome file a pagina 101.

---