bd10f08fd5fb3faac33bdcf16df45fd1a676726f
[openafs.git] / doc / man-pages / pod1 / vos_rename.pod
1 =head1 NAME
2
3 vos_rename - Renames a volume
4
5 =head1 SYNOPSIS
6
7 =for html
8 <div class="synopsis">
9
10 B<vos rename> S<<< B<-oldname> <I<old volume name>> >>>
11     S<<< B<-newname> <I<new volume name>> >>>
12     S<<< [B<-cell> <I<cell name>>] >>>
13     [B<-noauth>] [B<-localauth>]
14     [B<-verbose>] [B<-encrypt>] [B<-noresolve>]
15     S<<< [B<-config> <I<config directory>>] >>>
16     [B<-help>]
17
18 B<vos ren> S<<< B<-o> <I<old volume name>> >>>
19     S<<< B<-ne> <I<new volume name>> >>>
20     [-c <I<cell name>>] [B<-noa>] [B<-l>] [B<-v>] [B<-e>] [B<-nor>]
21     S<<< [B<-co> <I<config directory>>] >>>
22     [B<-h>]
23
24 =for html
25 </div>
26
27 =head1 DESCRIPTION
28
29 The B<vos rename> command changes the name of the read/write volume
30 specified with the B<-oldname> argument to the name specified with the
31 B<-newname> argument. The names of the read/write's read-only copies and
32 backup copy, if any, change automatically to match.
33
34 After issuing this command, remember to correct any mount points that
35 refer to the old volume name, by removing the old mount point with the
36 B<fs rmmount> command and creating a new one with the B<fs mkmount>
37 command.
38
39 =head1 OPTIONS
40
41 =over 4
42
43 =item B<-oldname> <I<old volume name>>
44
45 Is the current name of the read/write volume.
46
47 =item B<-newname> <I<new volume name>>
48
49 Is the desired new name for the volume.
50
51 =item B<-cell> <I<cell name>>
52
53 Names the cell in which to run the command. Do not combine this argument
54 with the B<-localauth> flag. For more details, see L<vos(1)>.
55
56 =item B<-noauth>
57
58 Assigns the unprivileged identity C<anonymous> to the issuer. Do not
59 combine this flag with the B<-localauth> flag. For more details, see
60 L<vos(1)>.
61
62 =item B<-localauth>
63
64 Constructs a server ticket using a key from the local
65 F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents it
66 to the Volume Server and Volume Location Server during mutual
67 authentication. Do not combine this flag with the B<-cell> argument or
68 B<-noauth> flag. For more details, see L<vos(1)>.
69
70 =item B<-verbose>
71
72 Produces on the standard output stream a detailed trace of the command's
73 execution. If this argument is omitted, only warnings and error messages
74 appear.
75
76 =item B<-encrypt>
77
78 Encrypts the command so that the operation's results are not transmitted
79 across the network in clear text. This option is available in OpenAFS
80 versions 1.4.11 or later and 1.5.60 or later.
81
82 =item B<-noresolve>
83
84 Shows all servers as IP addresses instead of the DNS name. This is very
85 useful when the server address is registered as 127.0.0.1 or when dealing
86 with multi-homed servers. This option is available in OpenAFS
87 versions 1.4.8 or later and 1.5.35 or later.
88
89 =item B<-help>
90
91 Prints the online help for this command. All other valid options are
92 ignored.
93
94 =back
95
96 =head1 OUTPUT
97
98 The B<vos rename> command produces no output if the command succeeds.
99
100 If the volume named by the B<-oldname> argument does not exist, the
101 following message appears:
102
103    vos: Could not find entry for volume <old volume name>.
104
105 =head1 EXAMPLES
106
107 The following example changes the mistaken volume name C<sun4x_56.afsws>
108 to the correct alternative C<sun4x_56.usr.afsws>.
109
110    % vos rename -oldname sun4x_56.afsws -newname sun4x_56.usr.afsws
111
112 =head1 PRIVILEGE REQUIRED
113
114 The issuer must be listed in the F</usr/afs/etc/UserList> file on the
115 machine specified with the B<-server> argument and on each database server
116 machine. If the B<-localauth> flag is included, the issuer must instead be
117 logged on to a server machine as the local superuser C<root>.
118
119 =head1 SEE ALSO
120
121 L<vos(1)>
122
123 =head1 COPYRIGHT
124
125 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
126
127 This documentation is covered by the IBM Public License Version 1.0.  It was
128 converted from HTML to POD by software written by Chas Williams and Russ
129 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.