doc/man-pages/pod1/vos_changeloc.pod

   1 =head1 NAME
   2
   3 vos_changeloc - Change a volume's entry in the VLDB
   4
   5 =head1 SYNOPSIS
   6
   7 =for html
   8 <div class="synopsis">
   9
  10 B<vos changeloc> S<<< [B<-server>] <I<new server name>> >>>
  11    S<<< [B<-partition>] <I<new partition location>> >>>
  12    S<<< [B<-id>] <I<volume name or ID>> >>>
  13    S<<< [B<-cell> <I<cell name>>] >>> [B<-noauth>] [B<-localauth>]
  14    [B<-verbose>] [B<-encrypt>] [B<-noresolve>] [B<-help>]
  15
  16 B<vos changel> S<<< [B<-s>] <I<new server name>> >>>
  17    S<<< [B<-p>] <I<new partition location>> >>>
  18    S<<< [B<-i>] <I<volume name or ID>> >>>
  19    S<<< [B<-c> <I<cell name>>] >>>
  20    [B<-noa>] [B<-l>] [B<-v>] [B<-e>] [B<-nor>] [B<-h>]
  21
  22 =for html
  23 </div>
  24
  25 =head1 DESCRIPTION
  26
  27 The B<vos changeloc> command changes the location of a volume in the
  28 Volume Location Database (VLDB) without needing to contact the original
  29 file server on which the volume was hosted. This is useful when a file
  30 server has gone down permanently and the data that was stored on that
  31 server has been moved to a new file server with a different name and IP
  32 address (perhaps by mounting the same /vicepX partitions on a different
  33 host). After moving the data and running B<vos changeloc>, run B<vos
  34 syncvldb> and then B<vos syncserv> against the new server to ensure full
  35 synchronization of the VLDB with the file server.
  36
  37 In essence, B<vos changeloc> performs the same operations on the VLDB as
  38 B<vos move>, but it does NOT move the data from one server's file system
  39 to another.
  40
  41 =head1 CAUTIONS
  42
  43 Using B<vos changeloc> changes the VLDB without modifying the file server
  44 data, so it inherently causes the VLDB to be out of sync with the data on
  45 the servers. It should only be used when recovering from server failure.
  46 If the servers are on-line, B<vos move> should be used instead. It is
  47 highly recommended that B<vos syncvldb> and B<vos syncserv> be run after
  48 using the B<vos changeloc> command to ensure properly synchronization of
  49 the VLDB with the file servers.
  50
  51 =head1 OPTIONS
  52
  53 B<vos changeloc> takes the following options:
  54
  55 =over 4
  56
  57 =item B<-server> <I<new server name>>
  58
  59 Specifies the new server where the VLDB should believe the volume resides.
  60 Provide the machine's IP address or its host name (either fully qualified
  61 or using an unambiguous abbreviation). For details, see L<vos(1)>.
  62
  63 =item B<-partition> <I<partition name>>
  64
  65 Specifies the partition where the VLDB should believe the volume resides.
  66 Provide the B<-server> argument along with this one. Provide the
  67 partition's complete name with preceding slash (for example, C</vicepa>)
  68 or use one of the three acceptable abbreviated forms. For details, see
  69 L<vos(1)>.
  70
  71 =item B<-id> <I<volume name or ID>>
  72
  73 Specifies the name or volume ID number on which to operate.
  74
  75 =item B<-cell> <I<cell name>>
  76
  77 Names the cell in which to run the command. Do not combine this argument
  78 with the B<-localauth> flag. For more details, see L<vos(1)>.
  79
  80 =item B<-noauth>
  81
  82 Assigns the unprivileged identity C<anonymous> to the issuer. Do not
  83 combine this flag with the B<-localauth> flag. For more details, see
  84 L<vos(1)>.
  85
  86 =item B<-localauth>
  87
  88 Constructs a server ticket using a key from the local
  89 F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents it
  90 to the Volume Server and Volume Location Server during mutual
  91 authentication. Do not combine this flag with the B<-cell> argument or
  92 B<-noauth> flag. For more details, see L<vos(1)>.
  93
  94 =item B<-verbose>
  95
  96 Produces on the standard output stream a detailed trace of the command's
  97 execution. If this argument is omitted, only warnings and error messages
  98 appear.
  99
 100 =item B<-encrypt>
 101
 102 Encrypts the command so that the operation's results are not transmitted
 103 across the network in clear text. This option is available in OpenAFS
 104 versions 1.4.11 or later and 1.5.60 or later.
 105
 106 =item B<-noresolve>
 107
 108 Shows all servers as IP addresses instead of the DNS name. This is very
 109 useful when the server address is registered as 127.0.0.1 or when dealing
 110 with multi-homed servers. This option is available in OpenAFS
 111 versions 1.4.8 or later and 1.5.35 or later.
 112
 113 =item B<-help>
 114
 115 Prints the online help for this command. All other valid options are
 116 ignored.
 117
 118 =back
 119
 120 =head1 OUTPUT
 121
 122 B<vos changeloc> shows a brief message upon completion:
 123
 124    Changed location to server2 /vicepa for volume user.jdoe
 125
 126 =head1 EXAMPLES
 127
 128 The following command changes the location of the C<user.jdoe> volume to
 129 be F</vicepa> on the file server machine C<server2> while being verbose:
 130
 131    % vos changeloc server2 a user.jdoe -verbose
 132     done
 133    Changed location to server2 /vicepa for volume user.jdoe
 134
 135 The following command changes the location of the C<user.jdoe> volume to
 136 be F</vicepa> on C<server1> without being verbose:
 137
 138    % vos changeloc server1 a user.jdoe
 139    Changed location to server1 /vicepa for volume user.jdoe
 140
 141 =head1 PRIVILEGE REQUIRED
 142
 143 The issuer must be listed in the F</usr/afs/etc/UserList> file on each
 144 database server machine. If the B<-localauth> flag is included, the issuer
 145 must instead be logged on to a server machine as the local superuser
 146 C<root>.
 147
 148 =head1 SEE ALSO
 149
 150 L<vos(1)>,
 151 L<vos_move(1)>,
 152 L<vos_syncserv(1)>,
 153 L<vos_syncvldb(1)>
 154
 155 =head1 COPYRIGHT
 156
 157 Copyright 2007 Jason Edgecombe <jason@rampaginggeek.com>
 158
 159 This documentation is covered by the BSD License as written in the
 160 doc/LICENSE file. This man page was written by Jason Edgecombe for
 161 OpenAFS.