doc: fs manpage fixes
[openafs.git] / doc / man-pages / pod1 / fs_exportafs.pod
1 =head1 NAME
2
3 fs_exportafs - Configures export of AFS to clients of other file systems
4
5 =head1 SYNOPSIS
6
7 =for html
8 <div class="synopsis">
9
10 B<fs exportafs> S<<< B<-type> <I<exporter name>> >>>
11     S<<< [B<-start> <I<start/stop translator (on | off)>>] >>>
12     S<<< [B<-convert> <I<convert from afs to unix mode (on | off)>>] >>>
13     S<<< [B<-uidcheck> <I<run on strict 'uid check' mode (on | off)>>] >>>
14     S<<< [B<-submounts> <I<allow nfs mounts to subdirs of /afs/.. (on | off)>>] >>>
15     S<<< [B<-clipags> <I<use client-assigned PAGs (on | off)>>] >>>
16     S<<< [B<-pagcb> <I<callback clients to get creds (on | off)>>] >>>
17     [B<-help>]
18
19 B<fs exp> S<<< B<-t> <I<exporter name>> >>>
20     S<<< [B<-st> <I<start/stop translator (on | off)>>] >>>
21     S<<< [B<-co> <I<convert from afs to unix mode (on | off)>>] >>>
22     S<<< [B<-u> <I<run on strict 'uid check' mode (on | off)>>] >>>
23     S<<< [B<-su> <I<allow nfs mounts to subdirs of /afs/.. (on | off)>>] >>>
24     S<<< [B<-cl> <I<use client-assigned PAGs (on | off)>>] >>>
25     S<<< [B<-p> <I<callback clients to get creds (on | off)>>] >>>
26     [B<-h>]
27
28 =for html
29 </div>
30
31 =head1 DESCRIPTION
32
33 The B<fs exportafs> command sets (if the B<-start> argument is provided)
34 or reports (if it is omitted) whether the machine can reexport the AFS
35 filespace to clients of a non-AFS file system. To control certain features
36 of the translation protocol, use the following arguments:
37
38 =over 4
39
40 =item *
41
42 To control whether the UNIX group and other mode bits on an AFS file or
43 directory are set to match the owner mode bits when it is exported to the
44 non-AFS file system, use the B<-convert> argument.
45
46 =item *
47
48 To control whether tokens can be placed in a credential structure
49 identified by a UID that differs from the local UID of the entity that is
50 placing the tokens in the structure, use the B<-uidcheck> argument. The
51 most common use is to control whether issuers of the B<knfs> command can
52 specify a value for its B<-id> argument that does not match their local
53 UID on the NFS/AFS translator machine.
54
55 =item *
56
57 To control whether users can create mounts in the non-AFS filespace to an
58 AFS directory other than F</afs>, use the B<-submounts> argument.
59
60 =back
61
62 =head1 OPTIONS
63
64 =over 4
65
66 =item B<-type> <I<exporter name>>
67
68 Names the alternate file system to which to reexport the AFS
69 filespace. The only acceptable value is C<nfs>, in lowercase letters only.
70
71 =item B<-start> <on | off>
72
73 Enables the local machine to reexport the AFS filespace if the value is
74 C<on>, or disables it if the value is C<off>. Omit this argument to report
75 the current setting for all of the configurable parameters.
76
77 =item B<-convert> <on | off>
78
79 Controls the setting of the UNIX group and other mode bits on AFS files
80 and directories exported to the non-AFS file system. If the value is
81 C<on>, they are set to match the B<owner> mode bits. If the value is
82 C<off>, the bits are not changed. If this argument is omitted, the default
83 value is C<on>.
84
85 =item B<-uidcheck> <on | off>
86
87 Controls whether tokens can be placed in a credential structure identified
88 by a UID that differs from the local UID of the entity that is placing the
89 tokens in the structure.
90
91 =over 4
92
93 =item *
94
95 If the value is on, the UID that identifies the credential structure must
96 match the local UID.
97
98 With respect to the B<knfs> command, this value means that the value of
99 B<-id> argument must match the issuer's local UID on the translator
100 machine. In practice, this setting makes it pointless to include the
101 B<-id> argument to the B<knfs> command, because the only acceptable value
102 (the issuer's local UID) is already used when the B<-id> argument is
103 omitted.
104
105 Enabling UID checking also makes it impossible to issue the B<klog> and
106 B<pagsh> commands on a client machine of the non-AFS file system even
107 though it is a system type supported by AFS. For an explanation, see
108 L<klog(1)>.
109
110 =item *
111
112 If the value is off (the default), tokens can be assigned to a local UID
113 in the non-AFS file system that does not match the local UID of the entity
114 assigning the tokens.
115
116 With respect to the B<knfs> command, it means that the issuer can use the
117 B<-id> argument to assign tokens to a local UID on the NFS client machine
118 that does not match his or her local UID on the translator machine. (An
119 example is assigning tokens to the MFS client machine's local superuser
120 C<root>.) This setting allows more than one issuer of the B<knfs> command
121 to make tokens available to the same user on the NFS client machine. Each
122 time a different user issues the B<knfs> command with the same value for
123 the B<-id> argument, that user's tokens overwrite the existing ones. This
124 can result in unpredictable access for the user on the NFS client machine.
125
126 =back
127
128 =item B<-submounts> <on | off>
129
130 Controls whether a user of the non-AFS filesystem can mount any directory
131 in the AFS filespace other than the top-level F</afs> directory. If the
132 value is C<on>, such submounts are allowed. If the value is C<off>, only
133 mounts of the F</afs> directory are allowed. If this argument is omitted,
134 the default value is C<off>.
135
136 =item B<-clipags> <on | off>
137
138 Turning on this option enables support for "client-assigned PAGs". With
139 client-assigned PAGs, an NFS client can manage its own AFS pags, and inform the
140 NFS translator machine what PAG we are using, instead of the NFS translator
141 machine keeping track of PAGs. An NFS client machine can do this if it has the
142 "afspag" kernel module loaded, which tracks PAGs but otherwise does not
143 implement AFS functionality, and forwards all requests to the NFS translator
144 machine.
145
146 You should only turn on this option if you are making use of client-assigned
147 PAGs, and you trust the NFS client machines making use of the translator. This
148 option is off by default.
149
150 =item B<-pagcb> <on | off>
151
152 Turning on this option means that the NFS translator machine will contact new
153 NFS clients in order to obtain their credentials and sysnames. This option can
154 be useful so that client credentials are not lost if the translator machine is
155 rebooted, or if an NFS client is "moved" to using a different translator. This
156 functionality will only work with NFS clients that are also running the
157 "afspag" kernel module.
158
159 Using this option with NFS clients not running with the "afspag" kernel module
160 would cause long timeouts when the translator machine attempts to contact the
161 client to obtain its credentials and sysname list. This option is off by
162 default.
163
164 =item B<-help>
165
166 Prints the online help for this command. All other valid options are
167 ignored.
168
169 =back
170
171 =head1 OUTPUT
172
173 If the machine is not even configured as a server of the non-AFS file
174 system, the following message appears:
175
176    Sorry, the <file_system>-exporter type is currently not supported on
177    this AFS client
178
179 If the machine is configured as a server of the non-AFS file system but is
180 not currently enabled to reexport AFS to it (because the B<-start>
181 argument to this command is not set to C<on>), the message is as follows:
182
183    '<file_system>' translator is disabled
184
185 If the machine is enabled to reexport AFS, the following message precedes
186 messages that report the settings of the other parameters.
187
188    '<file_system>' translator is enabled with the following options:
189
190 The following messages indicate that the B<-convert> argument is set to
191 C<on> or C<off> respectively:
192
193    Running in convert owner mode bits to world/other mode
194    Running in strict unix mode
195
196 The following messages indicate that the B<-uidcheck> argument is set to
197 C<on> or C<off> respectively:
198
199    Running in strict 'passwd sync' mode
200    Running in no 'passwd sync' mode
201
202 The following messages indicate that the B<-submounts> argument is set to
203 C<on> or C<off> respectively:
204
205    Allow mounts of /afs/.. subdirs
206    Only mounts to /afs allowed
207
208 =head1 EXAMPLES
209
210 The following example shows that the local machine can export AFS to NFS
211 client machines.
212
213    % fs exportafs nfs
214    'nfs' translator is enabled with the following options:
215         Running in convert owner mode bits to world/other mode
216         Running in no 'passwd sync' mode
217         Only mounts to /afs allowed
218
219 The following example enables the machine as an NFS server and converts
220 the UNIX group and other mode bits on exported AFS directories and files
221 to match the UNIX owner mode bits.
222
223    % fs exportafs -type nfs -start on -convert on
224
225 The following example disables the machine from reexporting AFS to NFS
226 client machines:
227
228    % fs exportafs -type nfs -start off
229
230 =head1 PRIVILEGE REQUIRED
231
232 The issuer must be logged in as the local superuser root.
233
234 =head1 SEE ALSO
235
236 L<klog(1)>,
237 L<knfs(1)>
238
239 =head1 COPYRIGHT
240
241 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
242
243 This documentation is covered by the IBM Public License Version 1.0.  It was
244 converted from HTML to POD by software written by Chas Williams and Russ
245 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.