man-page-vldb_convert-20080626
[openafs.git] / doc / man-pages / pod8 / vldb_convert.pod
1 =head1 NAME
2
3 vldb_convert - Convert the VLDB to/from Transarc AFS versions 3.1-3.4a
4
5 =head1 SYNOPSIS
6
7 =for html
8 <div class="synopsis">
9
10 B<vldb_convert> [B<initcmd>] S<<< [B<-to>] <I<AFS version goal>> >>>
11     S<<< [B<-from>] <I<current AFS version>> >>>
12     S<<< [B<-path>] <I<path to VLDB file>> >>> [B<-showversion>]
13     [B<-dumpvldb>] [B<-help>]
14
15 =for html
16 </div>
17
18 =head1 DESCRIPTION
19
20 The B<vldb_convert> command is used to convert legacy Transarc 3.1-3.4
21 VLDB database files between versions. This command is not needed when
22 using OpenAFS except in the case of preparing to migrate a pre-3.4 version
23 of Transarc AFS to OpenAFS.
24
25 In order to convert the VLDB file, do the following:
26
27 =over 4
28
29 =item 1.
30
31 Shutdown the B<vlserver> process on all server machines. B<vlserver> is
32 typically run only on the Cell servers, which must be listed in
33 F<CellServDB> or DNS.
34
35 =item 2.
36
37 Backup the VLDB file F</usr/afs/db/vldb.DB0> on the sync site to a safe
38 place. Typically, the sync site if the machine with the lowest IP address.
39
40 =item 3.
41
42 Remove the F</usr/afs/db/vldb.DBSYS1> file from all cell server machines.
43
44 =item 4.
45
46 Remove the F</usr/afs/db/vldb.DB0> file from the non-sync site server
47 machines.
48
49 =item 5.
50
51 Run the B<vldb_convert> command on the VLDB file using the following
52 command:
53
54    # vldb_convert -path /usr/afs/db/vldb.DB0
55
56 =item 6.
57
58 Copy the new version of the vlserver binaries to all Cell servers.
59
60 =item 7.
61
62 Restart the vlserver process on all Cell servers. The new VLDB will be
63 distributed to all of the Cell servers.
64
65 =item 8.
66
67 Confirm that all Cell servers are synchronized and that the vldb looks in
68 good shape.
69
70 =back
71
72 =head1 CAUTIONS
73
74 Backup the VLDB file to a different directory or machine before performing
75 the upgrade. Be sure that all vlserver processes are always running the
76 same version. This requires downtime, but for this conversion, all
77 vlserver instances must be at the same version. This restriction is
78 relaxed in OpenAFS.
79
80 =head1 OPTIONS
81
82 =over 4
83
84 =item [B<initcmd>]
85
86 This is an optional string that does nothing.
87
88 =item [B<-to>] <I<AFS version goal>>
89
90 This option is required when downgrading or when upgrading to a version
91 less than 3.4.  Specify 1, 2, 3, or 4 to choose version 3.1, 3.2, 3.3, or
92 3,4 respectively. This defaults to version 3.4.
93
94 =item [B<-from>] <I<current AFS version>>
95
96 This option is required when downgrading. Specify 1, 2, 3, or 4 to choose
97 version 3.1, 3.2, 3.3, or 3.4 respectively.
98
99 =item [B<-path>] <I<path to VLDB file>>
100
101 Specifies the path the VLDB file. This defaults to F</usr/afs/db/vldb.DB0>
102 and only needs to be used if the VLDB file is not in the default path..
103
104 =item B<-showversion>
105
106 Shows the current version of the VLDB. This option can only be used by itself.
107
108 =item B<-dumpvldb>
109
110 Produces verbose debugging output during the conversion process.
111
112 =item B<-help>
113
114 Prints the online help for this command. All other valid options are
115 ignored.
116
117 =back
118
119 =head1 PRIVILEGE REQUIRED
120
121 The issuer must have read and write access to the file
122 F</usr/afs/db/vldb.DB0>. This usually means that root access is required
123 on the cell server machines.
124
125 =head1 SEE ALSO
126
127 L<vlserver(8)>
128
129 =head1 COPYRIGHT
130
131 Copyright 2008 Jason Edgecombe <jason@rampaginggeek.com>
132
133 This documentation is covered by the BSD License as written in the
134 doc/LICENSE file. This man page was written by Jason Edgecombe for
135 OpenAFS.