| 1 | =head1 NAME |
| 2 | |
| 3 | vos - Introduction to the vos command suite |
| 4 | |
| 5 | =head1 DESCRIPTION |
| 6 | |
| 7 | The commands in the B<vos> command suite are the administrative interface |
| 8 | to the Volume Server and Volume Location (VL) Server. System |
| 9 | administrators use B<vos> commands to create, move, delete, replicate, |
| 10 | back up and examine volumes, among other operations. The VL Server |
| 11 | automatically records in the Volume Location Database (VLDB) changes in |
| 12 | volume status and location that result from B<vos> commands. |
| 13 | |
| 14 | The operations invoked by most B<vos> commands are idempotent, meaning |
| 15 | that if an operation is interrupted by a network, server machine, or |
| 16 | process outage, then a subsequent attempt at the same operation continues |
| 17 | from the interruption point, rather than starting over at the beginning of |
| 18 | the operation. Before executing a command, the Volume and VL Servers check |
| 19 | the current state of the volumes and VLDB records to be altered by the |
| 20 | command. If they are already in the desired end state (or a consistent |
| 21 | intermediate state), there is no need to repeat the internal steps that |
| 22 | brought them there. Idempotency does not apply if the command issuer |
| 23 | explicitly interrupts the operation with the Ctrl-C command or another |
| 24 | interrupt signal. In that case, the volume is left locked and the |
| 25 | administrator must use the L<B<vos unlock>|vos_unlock(1)> command to |
| 26 | unlock it before proceeding. |
| 27 | |
| 28 | It is important that the VLDB accurately indicate the status of the |
| 29 | volumes on file server machines at all times. L<vldb.DB0(5)> and |
| 30 | L<afs_volume_header(5)> describe the information recorded in the VLDB and |
| 31 | volume headers, respectively. If a B<vos> command changes volume status, |
| 32 | it automatically records the change in the corresponding VLDB entry. The |
| 33 | most common cause of discrepancies between the VLDB and volume status on |
| 34 | file server machines is interrupted operations; to restore consistency, |
| 35 | use the L<B<vos syncserv>|vos_syncserv(1)> and |
| 36 | L<B<vos syncvldb>|vos_syncvldb(1)> commands. |
| 37 | |
| 38 | There are several categories of commands in the vos command suite: |
| 39 | |
| 40 | =over 4 |
| 41 | |
| 42 | =item * |
| 43 | |
| 44 | Commands to create, move, and rename volumes: |
| 45 | L<B<vos backup>|vos_backup(1)>, |
| 46 | L<B<vos backupsys>|vos_backupsys(1)>, |
| 47 | L<B<vos changeloc>|vos_changeloc(1)>, |
| 48 | L<B<vos create>|vos_create(1)>, |
| 49 | L<B<vos move>|vos_move(1)>, |
| 50 | and L<B<vos rename>|vos_rename(1)>. |
| 51 | |
| 52 | =item * |
| 53 | |
| 54 | Commands to remove VLDB volume records or volumes or both: |
| 55 | L<B<vos delentry>|vos_delentry(1)>, |
| 56 | L<B<vos remove>|vos_remove(1)>, |
| 57 | and L<B<vos zap>|vos_zap(1)>. |
| 58 | |
| 59 | =item * |
| 60 | |
| 61 | Commands to edit or display VLDB server entries: |
| 62 | L<B<vos changeaddr>|vos_changeaddr(1)>, |
| 63 | L<B<vos listaddrs>|vos_listaddrs(1)> |
| 64 | L<B<vos setaddrs>|vos_setaddrs(1)>, |
| 65 | and L<B<vos remaddrs>|vos_remaddrs(1)>. |
| 66 | |
| 67 | =item * |
| 68 | |
| 69 | Commands to create, size, and restore dump files: |
| 70 | L<B<vos dump>|vos_dump(1)>, |
| 71 | L<B<vos restore>|vos_restore(1)>, |
| 72 | and L<B<vos size>|vos_size(1)>. |
| 73 | |
| 74 | =item * |
| 75 | |
| 76 | Commands to administer replicated volumes: |
| 77 | L<B<vos addsite>|vos_addsite(1)>, |
| 78 | L<B<vos release>|vos_release(1)>, |
| 79 | and L<B<vos remsite>|vos_remsite(1)>. |
| 80 | |
| 81 | =item * |
| 82 | |
| 83 | Commands to display VLDB records, volume headers, or both: |
| 84 | L<B<vos examine>|vos_examine(1)>, |
| 85 | L<B<vos listvldb>|vos_listvldb(1)>, |
| 86 | and L<B<vos listvol>|vos_listvol(1)>. |
| 87 | |
| 88 | =item * |
| 89 | |
| 90 | Commands to display information about partitions that house volumes: |
| 91 | L<B<vos listpart>|vos_listpart(1)> |
| 92 | and L<B<vos partinfo>|vos_partinfo(1)>. |
| 93 | |
| 94 | =item * |
| 95 | |
| 96 | Commands to restore consistency between the VLDB and volume headers: |
| 97 | L<B<vos syncserv>|vos_syncserv(1)> |
| 98 | and L<B<vos syncvldb>|vos_syncvldb(1)>. |
| 99 | |
| 100 | =item * |
| 101 | |
| 102 | Commands to lock and unlock VLDB entries: |
| 103 | L<B<vos lock>|vos_lock(1)>, |
| 104 | L<B<vos unlock>|vos_unlock(1)>, |
| 105 | and L<B<vos unlockvldb>|vos_unlockvldb(1)>. |
| 106 | |
| 107 | =item * |
| 108 | |
| 109 | A command to report Volume Server status: |
| 110 | L<B<vos status>|vos_status(1)>. |
| 111 | |
| 112 | =item * |
| 113 | |
| 114 | A command to end Volume Server transactions: |
| 115 | L<B<vos endtrans>|vos_endtrans(1)>. |
| 116 | |
| 117 | =item * |
| 118 | |
| 119 | A command to change volume fields: |
| 120 | L<B<vos setfields>|vos_setfields(1)>. |
| 121 | |
| 122 | =item * |
| 123 | |
| 124 | Commands to obtain help: |
| 125 | L<B<vos apropos>|vos_apropos(1)> |
| 126 | and L<B<vos help>|vos_help(1)>. |
| 127 | |
| 128 | =back |
| 129 | |
| 130 | =head1 CAUTIONS |
| 131 | |
| 132 | =include fragments/volsize-caution.pod |
| 133 | |
| 134 | =head1 OPTIONS |
| 135 | |
| 136 | The following arguments and flags are available on many commands in the |
| 137 | B<vos> suite. The reference page for each command also lists them, but |
| 138 | they are described here in greater detail. |
| 139 | |
| 140 | =over 4 |
| 141 | |
| 142 | =item B<-cell> <I<cell name>> |
| 143 | |
| 144 | Names the cell in which to run the command. It is acceptable to abbreviate |
| 145 | the cell name to the shortest form that distinguishes it from the other |
| 146 | entries in the F</usr/vice/etc/CellServDB> file on the local machine. If |
| 147 | the B<-cell> argument is omitted, the command interpreter determines the |
| 148 | name of the local cell by reading the following in order: |
| 149 | |
| 150 | =over 4 |
| 151 | |
| 152 | =item * |
| 153 | |
| 154 | The value of the AFSCELL environment variable. |
| 155 | |
| 156 | =item * |
| 157 | |
| 158 | The local F</usr/vice/etc/ThisCell> file. |
| 159 | |
| 160 | =back |
| 161 | |
| 162 | Do not combine the B<-cell> and B<-localauth> options. A command on which |
| 163 | the B<-localauth> flag is included always runs in the local cell (as |
| 164 | defined in the server machine's local F</usr/afs/etc/ThisCell> file), |
| 165 | whereas a command on which the B<-cell> argument is included runs in the |
| 166 | specified foreign cell. |
| 167 | |
| 168 | =item B<-config> <I<config directory>> |
| 169 | |
| 170 | The location of the directory to use to obtain configuration information, |
| 171 | including the CellServDB. This is primarily provided for testing purposes. |
| 172 | |
| 173 | =item B<-help> |
| 174 | |
| 175 | Prints a command's online help message on the standard output stream. Do |
| 176 | not combine this flag with any of the command's other options; when it is |
| 177 | provided, the command interpreter ignores all other options, and only |
| 178 | prints the help message. |
| 179 | |
| 180 | =item B<-localauth> |
| 181 | |
| 182 | Constructs a server ticket using the server encryption key with the |
| 183 | highest key version number in the local F</usr/afs/etc/KeyFile> file. The |
| 184 | B<vos> command interpreter presents the ticket, which never expires, to |
| 185 | the Volume Server and VL Server during mutual authentication. |
| 186 | |
| 187 | Use this flag only when issuing a command on a server machine; client |
| 188 | machines do not usually have a F</usr/afs/etc/KeyFile> file. The issuer |
| 189 | of a command that includes this flag must be logged on to the server |
| 190 | machine as the local superuser C<root>. The flag is useful for commands |
| 191 | invoked by an unattended application program, such as a process controlled |
| 192 | by the UNIX B<cron> utility or by a cron entry in the machine's |
| 193 | F</usr/afs/local/BosConfig> file. It is also useful if an administrator is |
| 194 | unable to authenticate to AFS but is logged in as the local superuser |
| 195 | B<root>. |
| 196 | |
| 197 | Do not combine the B<-cell> and B<-localauth> options. A command on which |
| 198 | the B<-localauth> flag is included always runs in the local cell (as |
| 199 | defined in the server machine's local F</usr/afs/etc/ThisCell> file), |
| 200 | whereas a command on which the B<-cell> argument is included runs in the |
| 201 | specified foreign cell. Also, do not combine the B<-localauth> and |
| 202 | B<-noauth> flags. |
| 203 | |
| 204 | =item B<-noauth> |
| 205 | |
| 206 | Establishes an unauthenticated connection to the Volume Server and VL |
| 207 | Server, in which the servers treat the issuer as the unprivileged user |
| 208 | C<anonymous>. It is useful only when authorization checking is disabled on |
| 209 | the server machine (during the installation of a file server machine or |
| 210 | when the L<B<bos setauth>|bos_setauth(8)> command has been used during |
| 211 | other unusual circumstances). In normal circumstances, the servers allow |
| 212 | only privileged users to issue commands that change the status of a volume |
| 213 | or VLDB record, and refuses to perform such an action even if the |
| 214 | B<-noauth> flag is provided. Do not combine the B<-noauth> and |
| 215 | B<-localauth> flags. |
| 216 | |
| 217 | =item B<-partition> <I<partition name>> |
| 218 | |
| 219 | Identifies the AFS server partition on a file server machine that houses, |
| 220 | or is to house, the volumes of interest, or about which to list |
| 221 | information. The B<vos> command interpreter accepts any of the following |
| 222 | four name formats: |
| 223 | |
| 224 | /vicepa = vicepa = a = 0 |
| 225 | /vicepb = vicepb = b = 1 |
| 226 | |
| 227 | After /vicepz (for which the index is 25) comes |
| 228 | |
| 229 | /vicepaa = vicepaa = aa = 26 |
| 230 | /vicepab = vicepab = ab = 27 |
| 231 | |
| 232 | and so on through |
| 233 | |
| 234 | /vicepiv = vicepiv = iv = 255 |
| 235 | |
| 236 | The B<-frompartition> and B<-topartition> arguments to the |
| 237 | L<B<vos move>|vos_move(1)> command also accept this notation. |
| 238 | |
| 239 | =item B<-server> <I<machine name>> |
| 240 | |
| 241 | Identifies the file server machine that houses, or is to house, the |
| 242 | volumes or AFS server partitions of interest. Provide the machine's IP |
| 243 | address in dotted decimal format, its fully qualified host name (for |
| 244 | example, C<fs1.example.com>), or the shortest abbreviated form of its host |
| 245 | name that distinguishes it from other machines. Successful use of an |
| 246 | abbreviated form depends on the availability of a name resolution service |
| 247 | (such as the Domain Name Service or a local host table) at the time the |
| 248 | command is issued. |
| 249 | |
| 250 | The B<-fromserver> and B<-toserver> arguments to the |
| 251 | L<B<vos move>|vos_move(1)> command also accept these name formats. |
| 252 | |
| 253 | =item B<-noresolve> |
| 254 | |
| 255 | Shows all servers as IP addresses instead of the DNS name. This is very |
| 256 | useful when the server address is registered as 127.0.0.1 or when dealing |
| 257 | with multi-homed servers. The B<-noresolve> option is available in OpenAFS |
| 258 | versions 1.4.8 or later and 1.5.35 or later. |
| 259 | |
| 260 | =item B<-verbose> |
| 261 | |
| 262 | Produces on the standard output stream a detailed trace of the command's |
| 263 | execution. If this argument is omitted, only warnings and error messages |
| 264 | appear. |
| 265 | |
| 266 | =back |
| 267 | |
| 268 | =head1 PRIVILEGE REQUIRED |
| 269 | |
| 270 | To issue most vos commands, the issuer must be listed in the |
| 271 | F</usr/afs/etc/UserList> file on each server machine that houses or is to |
| 272 | house an affected volume, and on each database server machine. The most |
| 273 | predictable performance results if all database server and file server |
| 274 | machines in the cell share a common F<UserList> file. Alternatively, if |
| 275 | the B<-localauth> flag is included, the issuer must be logged on to a |
| 276 | server machine as the local superuser C<root>. |
| 277 | |
| 278 | To issue a vos command that only displays information, no privilege is |
| 279 | required. |
| 280 | |
| 281 | =head1 SEE ALSO |
| 282 | |
| 283 | L<vos_addsite(1)>, |
| 284 | L<vos_apropos(1)>, |
| 285 | L<vos_backup(1)>, |
| 286 | L<vos_backupsys(1)>, |
| 287 | L<vos_changeaddr(1)>, |
| 288 | L<vos_convertROtoRW(1)>, |
| 289 | L<vos_clone(1)>, |
| 290 | L<vos_copy(1)>, |
| 291 | L<vos_create(1)>, |
| 292 | L<vos_delentry(1)>, |
| 293 | L<vos_dump(1)>, |
| 294 | L<vos_endtrans(1)>, |
| 295 | L<vos_examine(1)>, |
| 296 | L<vos_help(1)>, |
| 297 | L<vos_listaddrs(1)>, |
| 298 | L<vos_listpart(1)>, |
| 299 | L<vos_listvldb(1)>, |
| 300 | L<vos_listvol(1)>, |
| 301 | L<vos_lock(1)>, |
| 302 | L<vos_move(1)>, |
| 303 | L<vos_partinfo(1)>, |
| 304 | L<vos_release(1)>, |
| 305 | L<vos_remove(1)>, |
| 306 | L<vos_remsite(1)>, |
| 307 | L<vos_rename(1)>, |
| 308 | L<vos_restore(1)>, |
| 309 | L<vos_setfields(1)>, |
| 310 | L<vos_shadow(1)>, |
| 311 | L<vos_size(1)>, |
| 312 | L<vos_status(1)>, |
| 313 | L<vos_syncserv(1)>, |
| 314 | L<vos_syncvldb(1)>, |
| 315 | L<vos_unlock(1)>, |
| 316 | L<vos_unlockvldb(1)>, |
| 317 | L<vos_zap(1)>, |
| 318 | L<CellServDB(5)>, |
| 319 | L<UserList(5)> |
| 320 | |
| 321 | =head1 COPYRIGHT |
| 322 | |
| 323 | IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved. |
| 324 | |
| 325 | This documentation is covered by the IBM Public License Version 1.0. It was |
| 326 | converted from HTML to POD by software written by Chas Williams and Russ |
| 327 | Allbery, based on work by Alf Wachsmann and Elizabeth Cassell. |