doc: Add 'fs nukenfscreds' manpage
[openafs.git] / doc / man-pages / pod1 / fs_nukenfscreds.pod
1 =head1 NAME
2
3 fs_nukenfscreds - Discard NFS translator tokens
4
5 =head1 SYNOPSIS
6
7 =for html
8 <div class="synopsis">
9
10 B<fs nukenfscreds> S<<< B<-addr> <I<host>> >>>
11     [B<-help>]
12
13 B<fs nu> S<<< B<-a> <I<host>> >>>
14     [B<-h>]
15
16 =for html
17 </div>
18
19 =head1 DESCRIPTION
20
21 When using the NFS translator, it is possible for clients to supply AFS tokens
22 that the NFS translator will use for NFS-originating accesses from a specific
23 host and uid. The B<fs nukenfscreds> command, when run on the translator host,
24 will destroy all tokens for all uids for a specific NFS client host. After this
25 command is run successfully, all accesses for all users from that host will be
26 unauthenticated until they provide AFS tokens again.
27
28 This command can be useful in the following scenario. Say you have an NFS
29 client machine accessing a translator, and the machine is decommissioned, and a
30 new machine is brought up with the same IP. If there are credentials associated
31 with certain uids from that host, it is possible that accesses from the new
32 host will use the same credentials from the old host, even if they haven't
33 authenticated. With the B<fs_nukenfscreds> command, you can destroy all
34 credentials associated with the machine when it is decommissioned, ensuring
35 that that situation cannot occur.
36
37 =head1 OPTIONS
38
39 =over 4
40
41 =item B<-addr> <I<host>>
42
43 Specifies which host to invalidate tokens for. Specify either a resolvable host
44 name or an IP address.
45
46 =item B<-help>
47
48 Prints the online help for this command. All other valid options are
49 ignored.
50
51 =back
52
53 =head1 OUTPUT
54
55 If the specified tokens were destroyed successfully, no output is generated.
56
57 =head1 EXAMPLES
58
59 The following example destroys credentials from all PAGs for the NFS translator
60 client host 198.51.100.20:
61
62    % fs nukenfscreds -addr 198.51.100.20
63
64 =head1 PRIVILEGE REQUIRED
65
66 The issuer must be logged in as the local superuser C<root>.
67
68 =head1 SEE ALSO
69
70 L<fs_exportafs(1)>,
71 L<klog(1)>,
72 L<knfs(1)>
73
74 =head1 COPYRIGHT
75
76 Copyright 2013 Sine Nomine Associates
77
78 This documentation is covered by the BSD License as written in the
79 doc/LICENSE file. This man page was written by Andrew Deason for
80 OpenAFS.