STABLE14-pod-man-fs-uuid-20071023

FIXES 75175

add man page for fs uuid


(cherry picked from commit 66a19a512e)

doc/man-pages/pod1/fs_uuid.pod

@@ -0,0 +1,82 @@
+=head1 NAME
+
+fs uuid - Prints the uuid of the client or generates a new one
+
+=head1 SYNOPSIS
+
+=for html
+<div class="synopsis">
+
+B<fs uuid> [B<-generate>] [B<-help>]
+
+=for html
+</div>
+
+=head1 DESCRIPTION
+
+B<fs uuid> prints the current uuid of an OpenAFS client. It can
+optionally force the generation of a new uuid, if needed. The client
+uuid is used by the B<fileserver> to differentiate clients with the
+same IP address.
+
+=head1 CAUTIONS
+
+The B<fs uuid> command is only available in OpenAFS versions after
+1.4.5 and 1.5.8. The behavior differs slightly between versions. In
+OpenAFS 1.4.5 and later, the B<-generate> option is required and the
+uuid for the client machine is never printed. OpenAFS versions 1.5.8
+and later will print the uuid.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-generate>
+
+Generates a new uuid for the cache manager. This is useful if two
+clients share the same uuid. B<-generate> is optional in OpenAFS
+versions 1.5.8 and later, but it is required in OpenAFS versions 1.4.5
+and later.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+B<fs uuid> prints out the current uuid for the client or the new uuid
+if the B<-generate> option is passed to it.
+
+=head1 EXAMPLES
+
+There are only two ways to invoke B<fs uuid> under 1.5.8 and later:
+
+   % fs uuid
+   UUID: 8ac66f9308a8e-47d7-80f7-50d0040cddc2
+
+   % fs uuid -generate
+   New UUID: 436bd660-1720-429508e470cff38f5c6fb0
+
+Here is the only way to invoke B<fs uuid> under OpenAFS 1.4.5 and later:
+
+   % fs uuid -generate
+   New uuid generated.
+
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be logged on as the local superuser C<root>.
+
+=head1 SEE ALSO
+
+L<fs(1)>
+
+=head1 COPYRIGHT
+
+Copyright 2007 Jason Edgecombe <jason@rampaginggeek.com>
+
+This documentation is covered by the IBM Public License Version 1.0. This
+man page was written by Jason Edgecombe for OpenAFS.