1FEDFS-DOMAINROOT(8) System Manager's Manual FEDFS-DOMAINROOT(8)
3
7 fedfs-domainroot - set up FedFS domain root infrastructure
8
10 fedfs-domainroot [-h, --help] [--version]
11 fedfs-domainroot [--silent] [--statedir= statedir] add domainname
13 fedfs-domainroot [--silent] [--statedir= statedir] remove domainname
15 [--force]
16 fedfs-domainroot [--silent] [--statedir= statedir] status
18 fedfs-domainroot [--silent] [--statedir= statedir] clean [--force]
20
22 RFC 5716 introduces the Federated File System (FedFS, for short).
23 FedFS is an extensible standardized mechanism by which system adminis‐
24 trators construct a coherent namespace across multiple file servers
25 using file system referrals. For further details, see fedfs(7).
26 The top directory of a FedFS domain namespace is known as a domain root
28 directory. FedFS-enabled clients discover the fileserver that exports
29 a FedFS domain's root directory using a DNS SRV query. Using a well-
30 known export path, clients then mount the domain root directory on that
31 fileserver in the normal fashion.
32 After a filesystem client mounts a domain's root directory, applica‐
34 tions on that client descend into the domain's name space starting in
35 that directory, and are directed transparently to exports on other
36 fileservers.
37 Further information about domain roots is available in fedfs(7).
39
41 A single fileserver may host domain root directories for one or more
42 FedFS domains. The fedfs-domainroot(8) command is a convenient way to
43 securely manage domain root exports on a Linux NFS fileserver. FedFS
44 itself is agnostic about the underlying file-access protocol, but the
45 fedfs-domainroot(8) command supports only NFS at this time.
46 FedFS domain root directories are exported using a standard well-known
48 pathname to make it simple for clients to find them. The first compo‐
49 nent of the domain root's export pathname is always /.domainroot. The
50 second component is a FedFS domain name.
51 For instance, the export pathname of the domain root of the example.net
53 FedFS domain is /.domainroot/example.net.
54 Operation
56 The add subcommand creates a directory under /var/lib/fedfs/domainroots
57 where the contents of the domain root directory reside. A directory is
58 also set up under /.domainroot for each doman root directory. fedfs-
59 domainroot(8) bind-mounts the domain root directory under
60 /var/lib/fedfs/domainroots, then exports the directory under /.domain‐
61 root.
62 In this way, each domain root directory is exported via a well-known
64 pathname, and can have its own export settings separate from other
65 domain root directories, including security settings and client and
66 network designations. These can be modified by editing /etc/exports
67 after the domain root export is created.
68 The fedfs-domainroot(8) command must run as root in order to create and
70 remove NFS exports and entries in /etc/fstab.
71 Subcommands
73 Valid fedfs-domainroot(8) subcommands are:
74 clean Remove the /.domainroot directory and other infrastructure (as
76 long as it is empty). The user is asked to confirm before
77 action is taken.
78 By default, this process stops when a step encounters an error.
80 Adding the --force option forces the process to try each step
81 even if an error occurs, and bypasses the confirmation request.
82 status Display the status of the domain root infrastructure on the
84 local system. This includes whether NFSD is running, and what
85 domain root directories are currently configured and exported.
86 This subcommand takes no arguments.
87 add Create a new FedFS domain root directory under /.domainroot and
89 export it. This subcommand takes a FedFS domain name as an
90 argument.
91 remove Remove an existing FedFS domain root directory from /.domain‐
93 root. This subcommand takes a FedFS domain name as an argument.
94 The user is asked to confirm before action is taken.
95 By default, this process stops when a step encounters an error.
97 Adding the --force option forces the process to try each step
98 even if an error occurs, and bypasses the confirmation request.
99 Command line options
101 The following options are specified before the subcommand on the com‐
102 mand line.
103 -h, --help
105 Display usage and copyright information, then exit.
106 --version
108 Display fedfs-utils version information, then exit.
109 --silent
111 Process quietly.
112 --statedir=state-directory
114 Find FedFS domain root directories on the local system in the
115 domainroots subdirectory of the specified directory. By
116 default, the state directory is /var/lib/fedfs.
117
119 The fedfs-domainroot(8) command returns one of two values upon exit.
120 0 The requested subcommand succeeded.
122 1 The requested subcommand failed.
124
126 Suppose you are the FedFS administrator of the example.net FedFS
127 domain. After you have chosen a reliable NFS fileserver to serve your
128 FedFS domain root directory, log in on that fileserver as root and
129 ensure that NFSD is running.
130 To create a new FedFS domain root for the example.net domain, use:
132 # fedfs-domainroot --silent add example.net
134 Added domain root for FedFS domain "example.net"
135 #
136 To populate the new domain root, change your current directory to
138 /.domainroot/example.net, then add junctions with the nfsref(8) command
139 on the fileserver.
140 You can list the domain roots that are currently exported by your file‐
142 server with:
143 # fedfs-domainroot --silent status
145 FedFS domain roots:
146 example.net is exported with options
147 *(ro,subtree_check,mp,insecure,sec=sys:none)
148 #
149 When you want to remove this domain root (say, because you have moved
151 it to another fileserver), remove it's contents, then use:
152 # fedfs-domainroot remove example.net
154 Removed domain root for FedFS domain "example.net"
155 #
156
158 To enable discovery of new domain roots by FedFS-enabled file-access
159 clients, a DNS SRV record must be added to an appropriate authoritative
160 DNS server.
161 If you created your domain root on the fileserver named foo.exam‐
163 ple.net, a record for the above domain root should be added to the DNS
164 server authoritative for the example.net domain. Such a record might
165 look like
166 _nfs-domainroot._tcp IN SRV 0 0 2049 foo.example.net.
168 Adding DNS SRV records is outside the scope of the fedfs-domainroot(8)
170 command. Consult with your network administrator for details on how to
171 add appropriate DNS SRV records for your FedFS domain root.
172
174 FedFS domain root exports created by fedfs-domainroot(8) are exported
175 with *(ro,insecure,subtree_check,sec=sys:none). FedFS standards recom‐
176 mend that FedFS domain root directories should be globally readable.
177 Specific access restrictions typically occur lower in a domain's name
178 space.
179 However, fileserver administrators can alter a domain root export's
181 security settings by editing a domain root export's entry in
182 /etc/exports, and then refreshing the kernel's export cache with
183 exportfs -r.
184 For example, if the domain root fileserver has Kerberos configured, an
186 administrator might change a domain root export's sec= option to
187 sec=krb5p:krb5i:krb5:sys:none. Or, to restrict the range of clients
188 that can access the domain root, an administrator might replace the
189 leading * with a specific netgroup or IP network designation.
190 It is recommended to keep the subtree_check export option. Refer to
192 exports(5) for details.
193
195 /var/lib/fedfs/domainroots
196 directory containing domain root directories
197 /.domainroot
199 directory containing domain root exports
200
202 fedfs(7), nfsref(8), rpc.fedfsd(8), exportfs(8), exports(5)
203 RFC 6641 for the specification of FedFS DNS SRV records
205
207 This page is part of the fedfs-utils package. A description of the
208 project and information about reporting bugs can be found at
209 http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject.
210
212 Chuck Lever <chuck.lever@oracle.com>
213 3 February 2014 FEDFS-DOMAINROOT(8)