1FEDFS(7) Miscellaneous Information Manual FEDFS(7)
3
7 fedfs - The Linux Federated File System implementation
8
10 RFC 5716 introduces the Federated File System (FedFS, for short).
11 FedFS is an extensible standardized mechanism by which system adminis‐
12 trators construct a coherent namespace across multiple fileservers
13 using file system referrals.
14 A file system referral is like a symbolic link to another file system
16 share, but it is not visible to applications. It behaves like an auto‐
17 mounted directory where a mount operation is performed when an applica‐
18 tion first accesses that directory.
19 Today, file system referral mechanisms exist in several standard net‐
21 work file system protocols. Because FedFS uses a mechanism already
22 built in to standard network protocols, using it does not require any
23 change to file system protocols or file-access client implementations.
24 A sideband protocol, such as NIS, is also unnecessary. File-access
26 clients automatically share a common view of the network file system
27 namespace with no need for individual configuration on each client.
28 Currently, the Linux FedFS implementation supports only NFS version 4
30 referrals. More on NFS version 4 referrals can be found in RFC 5661.
31 FedFS may support other network file system protocols in the future.
32
34 A file system referral whose target is managed by FedFS is called a
35 FedFS junction. Junctions join separate fileserver shares into a sin‐
36 gle coherent FedFS namespace. On FedFS-enabled Linux fileservers, the
37 rpc.fedfsd(8) daemon and the nfsref(5) command create and remove FedFS
38 junctions.
39 An independently administered FedFS namespace is referred to as a FedFS
41 domain. FedFS domains are file namespaces only. They do not represent
42 authentication or ID-mapping realms, for example. FedFS-enabled file-
43 access clients and fileservers are not members of a particular FedFS
44 domain and do not have a priori knowledge of what FedFS domains exist.
45 The top-level directory of a FedFS domain is referred to as its domain
47 root. Domain roots typically contain nothing but FedFS junctions and a
48 few other directories. Useful data is contained in other shares which
49 file-access clients discover by following FedFS junctions in the domain
50 root directory.
51 Although FedFS junctions are stored on fileservers, they are light‐
53 weight objects that contain little actual data. The bulk of FedFS
54 junction information in a FedFS domain is stored on an LDAP server.
55 LDAP servers that store FedFS information are known as namespace data‐
56 bases, or NSDBs, for short. Any standard LDAP server can become an
57 NSDB if it knows the FedFS schema (the definitions of FedFS record
58 types).
59 Filesets
61 FedFS groups a set of directories in a server's physical file system
62 namespace into a single administrative unit called a fileset. For NFS,
63 a whole share might be considered a fileset. A FedFS domain consists
64 of one or more filesets, a domain root, and junction information stored
65 on an NSDB node.
66 To function as a FedFS fileset, a set of directories must have a name
68 unique in a FedFS domain, and a set of locations where the file data is
69 stored.
70 A FedFS fileset name is a UUID and an NSDB domainname and port. This
72 information is also maintained in an LDAP record on the NSDB node.
73 A FedFS fileset location is an LDAP record that describes the location
75 (the fileserver where it resides, and its export path) of a copy of a
76 fileset's data. These records are children of the fileset name record
77 for this fileset.
78 A fileset can have multiple replicas. Such a fileset has one FedFS
80 fileset name, and each replica of the fileset has an individual FedFS
81 fileset location record.
82 A FedFS junction contains only a FedFS fileset name. A fileserver
84 resolves a FedFS junction by performing an LDAP query on the NSDB node
85 named in the junction, using the UUID named in the junction. The NSDB
86 node returns location information stored in FedFS fileset location
87 records for that FedFS fileset name. The fileserver returns this loca‐
88 tion information to file-access clients it servers via a file system
89 referral.
90 On Linux NFS fileservers, rpc.mountd(8) is the gateway through which
92 the in-kernel NFS server performs FedFS junction resolution.
93 Discovering domain roots
95 As with other FedFS filesets, copies of a domain root can exist on mul‐
96 tiple fileservers. These copies are known as domain root replicas.
97 Rather than using junctions and information in an NSDB node, FedFS-
99 enabled file-access clients locate a domain's root by looking for DNS
100 SRV records that advertise fileservers exporting domain root replicas.
101 Such clients typically mount FedFS domain roots in a standard place so
103 that files residing in a FedFS domain appear at the same location in
104 the file namespace on all file-access clients. By convention, the top
105 of the global FedFS namespace looks like this:
106 /fstype/domainname
108 where fstype specifies a network file system protocol to use, and
110 domainname specifies a FedFS domain. Currently, the Linux FedFS imple‐
111 mentation recognizes only nfs4 as a valid fstype.
112 Globally Useful Names
114 On FedFS-enabled Linux file-access clients, the automounter (via a pro‐
115 gram map) or the mount.fedfs(8) command find and mount the root of a
116 FedFS domain.
117 Typically, file-access clients mount the FedFS namespace so that FedFS
119 pathnames appear the same on all clients. Such pathnames are referred
120 to as globally useful names, since a globally useful name refers to
121 exactly the same file object on every file-access client in a FedFS
122 domain.
123 For example, the FedFS globally useful name /nfs4/example.net would be
125 mounted on a local directory called /nfs4/example.net on all file-
126 access clients, so that applications have the same view of the exam‐
127 ple.net domain namespace on all FedFS-enabled file-access clients.
128 The Linux mount.fedfs(8) command can attach anywhere in a file-access
130 client's local file namespace any directory in the FedFS namespace that
131 client has permission to access. This can be useful to ensure local
132 namespace compatibility in some cases, or hide parts of the FedFS
133 namespace for security purposes.
134 However, it breaks cross-platform application interoperability by pre‐
136 senting applications with multiple pathnames to the same file object.
137 Therefore it should be avoided.
138
140 Each host in a FedFS domain plays one or more of the following roles,
141 each of which have different security requirements.
142 NSDB node
144 LDAP server that contains FedFS domain information
145 FedFS fileserver
147 stores data accessible via a FedFS domain name space
148 FedFS file-access client
150 accesses data in FedFS domain name spaces
151 FedFS admin client
153 manages FedFS domain information
154 The Linux FedFS implementation provides administrative tools to manage
156 FedFS fileset name and location records on an NSDB node. Junction res‐
157 olution uses anonymous LDAP search requests, and administration takes
158 place via authenticated LDAP modification requests.
159 Fileservers and administrative clients use plaintext or TLS-secured
161 transports to perform junction lookups and administrative requests.
162 The Linux FedFS implementation provides tools for managing x.509 cer‐
163 tificates required for LDAP over TLS.
164 FedFS junction objects are created on fileservers by a side-band RPC
166 protocol called the FedFS ADMIN protocol. This protocol is separate
167 from network file system protocols. This allows FedFS to operate with‐
168 out modification to network file system protocols. The protocol uses
169 RPCSEC GSS to secure administrative requests.
170 Since two separate protocols are involved when administering junctions
172 and filesets, junctions are created on fileservers and registered with
173 the domain's NSDB node in two separate steps.
174
176 nsdb-parameters(7), nsdbparams(8), fedfs-map-nfs4(8), mount.fedfs(8),
177 rpc.fedfsd(8), rpc.mountd(8), fedfs-create-junction(8), fedfs-create-
178 replication(8), fedfs-delete-junction(8), fedfs-delete-replication(8),
179 fedfs-get-limited-nsdb-params(8), fedfs-get-nsdb-params(8), fedfs-
180 lookup-junction(8), fedfs-lookup-replication(8), fedfs-null(8), fedfs-
181 set-nsdb-params(8), nsdb-simple-nce(8), nsdb-annotate(8), nsdb-create-
182 fsl(8), nsdb-create-fsn(8), nsdb-update-nci(8), nsdb-delete-fsl(8),
183 nsdb-delete-fsn(8), nsdb-remove-nci(8), nsdb-describe(8), nsdb-list(8),
184 nsdb-nces(8), nsdb-resolve-fsn(8), nsdb-update-fsl(8)
185 RFC 4510 for an introduction to LDAP
187 RFC 5661 for a description of NFS version 4 referrals
189 RFC 5716 for FedFS requirements and overview
191
193 This page is part of the fedfs-utils package. A description of the
194 project and information about reporting bugs can be found at
195 http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject.
196
198 Chuck Lever <chuck.lever@oracle.com>
199 3 February 2014 FEDFS(7)