fs rxstatpeer
fs rxstatproc
fs setcbaddr
- read_tape
restorevol
rmtsysd
vldb_convert
vos clone
- vos convertROtoRW
- vos copy
+ vos setfields
vos shadow
vsys
L<vos_backup(1)>,
L<vos_backupsys(1)>,
L<vos_changeaddr(1)>,
-L<vos_changeloc(1)>,
+L<vos_convertROtoRW(1)>,
+L<vos_copy(1)>,
L<vos_create(1)>,
L<vos_delentry(1)>,
L<vos_dump(1)>,
--- /dev/null
+=head1 NAME
+
+vos_convertROtoRW - Converts a Read-Only volume into a Read/Write volume
+
+=head1 SYNOPSIS
+
+=for html
+<div class="synopsis">
+
+B<vos convertROtoRW> S<<< [B<-server>] <I<machine name>> >>>
+ S<<< [B<-partition>] <I<partition name>> >>>
+ S<<< [B<-id>] <I<volume name or ID>> >>> [B<-force>]
+ S<<< [B<-cell> <I<cell name>>] >>> [B<-noauth>] [B<-localauth>]
+ [B<-verbose>] [B<-encrypt>] [B<-help>]
+
+=for html
+</div>
+
+=head1 DESCRIPTION
+
+B<vos convertROtoRW> converts a Read-Only volume into a Read/Write volume
+when the original Read/Write volume is no longer available. It's normal use
+is to recover the Read/Write volume from a replica after a failed disk,
+failed server, or accidental deletion.
+
+=head1 CAUTIONS
+
+This command can only be used with namei AFS file servers. If used on an
+inode AFS file server (normally found only on Solaris or AIX systems), it
+will fail with an error.
+
+The command name is case-sensitive. It must be issued with the capital "RO"
+and "RW".
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> <I<server name>>
+
+Identifies the file server machine that houses the Read-Only volume which
+will be converted. Provide the machine's IP address or its host name
+(either fully qualified or using an unambiguous abbreviation). For details,
+see L<vos(1)>.
+
+=item B<-partition> <I<partition name>>
+
+Identifies the partition on the file server machine that houses the
+Read-Only volume which will be converted. Provide the full partition name
+(for, example, B</vicepa>) or one of the abbreviated forms described in
+L<vos(1)>.
+
+=item B<-id> <I<volume ID>>
+
+Specifies either the complete name or volume ID number of a Read/Write
+volume.
+
+=item B<-force>
+
+Don't ask for confirmation.
+
+=item B<-cell> <I<cell name>>
+
+Names the cell in which to run the command. Do not combine this argument
+with the B<-localauth> flag. For more details, see L<vos(1)>.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity C<anonymous> to the issuer. Do not
+combine this flag with the B<-localauth> flag. For more details, see
+L<vos(1)>.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents it
+to the Volume Server and Volume Location Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument or
+B<-noauth> flag. For more details, see L<vos(1)>.
+
+=item B<-verbose>
+
+Produces on the standard output stream a detailed trace of the command's
+execution. If this argument is omitted, only warnings and error messages
+appear.
+
+=item B<-encrypt>
+
+Encrypts the command so that the operation's results are not transmitted
+across the network in clear text.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following example converts the read-only volume test3.readonly in
+partition vicepb on server1 to a read-write volume:
+
+ % vos convertROtoRW server1 b test3.readonly
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the F</usr/afs/etc/UserList> file on the
+machines specified with the B<-toserver> and B<-fromserver> arguments and
+on each database server machine. If the B<-localauth> flag is included,
+the issuer must instead be logged on to a server machine as the local
+superuser C<root>.
+
+=head1 SEE ALSO
+
+L<vos(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.
--- /dev/null
+=head1 NAME
+
+vos_copy - Make a copy of a volume
+
+=head1 SYNOPSIS
+
+=for html
+<div class="synopsis">
+
+B<vos copy> S<<< [B<-id>] <I<volume name or ID of source>> >>>
+ S<<< [B<-fromserver>] <I<machine name for source>> >>>
+ S<<< [B<-frompartition>] <I<partition name for source>> >>>
+ S<<< [B<-toname>] <I<volume name for new copy>> >>>
+ S<<< [B<-toserver>] <I<machine name for destination>> >>>
+ S<<< [B<-topartition>] <I<partition name for destination>> >>>
+ [B<-offline>] [B<-readonly>] [B<-live>] S<<< [B<-cell> <I<cell name>>] >>>
+ [B<-noauth>] [B<-localauth>] [B<-verbose>] [B<-encrypt>] [B<-help>]
+
+=for html
+</div>
+
+=head1 DESCRIPTION
+
+The B<vos copy> command makes a copy of a volume with a new name. It is
+equivalent to B<vos dump> followed by B<vos restore>, but doesn't require
+the volume be stored locally by the client.
+
+=head1 OPTIONS
+
+=over 4
+
+=item [B<-id>] <I<volume name or ID>>
+
+Specifies either the complete name or volume ID number of a read/write
+volume.
+
+=item [B<-fromserver>] <I<machine name for source>>
+
+Identifies the file server machine where the source volume resides. Provide
+the machine's IP address or its host name (either fully qualified or using
+an unambiguous abbreviation). For details, see L<vos(1)>.
+
+=item [B<-frompartition>] <I<partition name for source>>
+
+Names the partition where the source volume resides. Provide the full
+partition name (for, example, B</vicepa>) or one of the abbreviated forms
+described in L<vos(1)>.
+
+=item [B<-toname>] <I<volume name for new copy>>
+
+The complete name of the new volume to create.
+
+=item [B<-toserver>] <I<machine name for destination>>
+
+Identifies the file server machine to which to copy the volume. Provide
+the machine's IP address or its host name (either fully qualified or using
+an unambiguous abbreviation). For details, see L<vos(1)>.
+
+=item [B<-topartition>] <I<partition name for destination>>
+
+Names the partition to which to copy the volume. Provide the full partition
+name (for, example, B</vicepa>) or one of the abbreviated forms described in
+L<vos(1)>.
+
+=item B<-offline>
+
+Leaves the new volume flagged as off-line in the volume database.
+
+=item B<-readonly>
+
+Flags the new volume as read-only in the volume database.
+
+=item B<-live>
+
+Copies the live volume without cloning. This is normally not necessary and
+causes the volume to be kept locked for longer than the normal copy
+mechanism.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents it to
+the Volume Server and Volume Location Server during mutual
+authentication. Do not combine this flag with the B<-cell> argument or
+B<-noauth> flag. For more details, see L<vos(1)>.
+
+=item B<-verbose>
+
+Produces on the standard output stream a detailed trace of the command's
+execution. If this argument is omitted, only warnings and error messages
+appear.
+
+=item B<-encrypt>
+
+Encrypts the command so that the operation's results are not transmitted
+across the network in clear text.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+This command has no output unless C<-verbose> is specified or there is
+an error.
+
+=head1 EXAMPLES
+
+The following example makes a verbose copy of the C<test> volume named
+C<test2> in the cell C<localcell>. The volume and copy both reside on
+C</vicepa> of C<server1>.
+
+ % vos copy test server1 a test2 server1 a -cell localcell -verbose
+ Starting transaction on source volume 536870921 ... done
+ Allocating new volume id for clone of volume 536870921 ... done
+ Allocating new volume id for copy of volume 536870921 ... done
+ Cloning source volume 536870921 ... done
+ Ending the transaction on the source volume 536870921 ... done
+ Starting transaction on the cloned volume 536870926 ... done
+ Setting flags on cloned volume 536870926 ... done
+ Getting status of cloned volume 536870926 ... done
+ Creating the destination volume 536870927 ... done
+ Setting volume flags on destination volume 536870927 ... done
+ Dumping from clone 536870926 on source to volume 536870927 on destination ... done
+ Ending transaction on cloned volume 536870926 ... done
+ Starting transaction on source volume 536870921 ... done
+ Doing the incremental dump from source to destination for volume 536870921 ... done
+ Setting volume flags on destination volume 536870927 ... done
+ Ending transaction on destination volume 536870927 ... done
+ Ending transaction on source volume 536870921 ... done
+ Starting transaction on the cloned volume 536870926 ... done
+ Deleting the cloned volume 536870926 ... done
+ Ending transaction on cloned volume 536870926 ... done
+ Created the VLDB entry for the volume test2 536870927
+ Volume 536870921 copied from server1 /vicepa to test2 on server1 /vicepa
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the F</usr/afs/etc/UserList> file on the
+machine specified with the B<-server> argument and on each database server
+machine. If the B<-localauth> flag is included, the issuer must instead be
+logged on to a server machine as the local superuser C<root>.
+
+=head1 SEE ALSO
+
+L<vos(1)>,
+L<vos_clone(1)>,
+L<vos_move(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.
S<<< [B<-cb> <I<number of call backs>>] >>> [B<-banner>] [B<-novbc>]
S<<< [B<-implicit> <I<admin mode bits: rlidwka>>] >>> [B<-readonly>]
S<<< [B<-hr> <I<number of hours between refreshing the host cps>>] >>>
- [B<-busyat> <I<< redirect clients when queue > n >>>]
+ S<<< [B<-busyat> <I<< redirect clients when queue > n >>>] >>>
[B<-nobusy>] S<<< [B<-rxpck> <I<number of rx extra packets>>] >>>
[B<-rxdbg>] [B<-rxdbge>] S<<< [B<-rxmaxmtu> <I<bytes>>] >>>
S<<< [B<-rxbind> <I<address to bind the Rx socket to>>] >>>
The File Server creates the F</usr/afs/logs/FileLog> log file as it
initializes, if the file does not already exist. It does not write a
-detailed trace by default, but use the B<-d> option to increase the amount
-of detail. Use the B<bos getlog> command to display the contents of the
-log file.
+detailed trace by default, but the B<-d> option may be used to
+increase the amount of detail. Use the B<bos getlog> command to
+display the contents of the log file.
The command's arguments enable the administrator to control many aspects
of the File Server's performance, as detailed in L<OPTIONS>. By default
The maximum number of lightweight processes (LWPs) the File Server uses to
handle requests for data; corresponds to the B<-p> argument. The File
-Server always uses a minimum of 32 KB for these processes.
+Server always uses a minimum of 32 KB of memory for these processes.
=item *
that it can take that long for changed group memberships to become
effective. To change this frequency, use the B<-hr> argument.
+The File Server stores volumes in partitions. A partition is a
+filesystem or directory on the server machine that is named C</vicepX>
+or C</vicepXX> where XX is "a" through "z" or "aa" though "zz". The
+File Server expects that the /vicepXX directories are each on a
+dedicated filesystem. The File Server will only use a /vicepXX if it's
+a mountpoint for another filesystem, unless the file
+C</vicepXX/AlwaysAttach> exists. The data in the partition is a
+special format that can only be access using OpenAFS commands or an
+OpenAFS client.
+
The File Server generates the following message when a partition is nearly
full:
=head1 CAUTIONS
-Do not use the B<-k> and -w arguments, which are intended for use by the
-AFS Development group only. Changing them from their default values can
-result in unpredictable File Server behavior. In any case, on many
-operating systems the File Server uses native threads rather than the LWP
-threads, so using the B<-k> argument to set the number of LWP threads has
-no effect.
+Do not use the B<-k> and B<-w> arguments, which are intended for use
+by the AFS Development group only. Changing them from their default
+values can result in unpredictable File Server behavior. In any case,
+on many operating systems the File Server uses native threads rather
+than the LWP threads, so using the B<-k> argument to set the number of
+LWP threads has no effect.
Do not specify both the B<-spare> and B<-pctspare> arguments. Doing so
causes the File Server to exit, leaving an error message in the
-cmd "/usr/afs/bin/fileserver -pctspare 10 \
-L" /usr/afs/bin/volserver /usr/afs/bin/salvager
+
+=head1 TROUBLESHOOTING
+
+Sending process signals to the File Server Process can change its
+behavior in the following ways:
+
+ Process Signal OS Result
+ ---------------------------------------------------------------------
+
+ File Server XCPU Unix Prints a list of client IP
+ Addresses.
+
+ File Server USR2 Windows Prints a list of client IP
+ Addresses.
+
+ File Server POLL HPUX Prints a list of client IP
+ Addresses.
+
+ Any server TSTP Any Increases Debug level by a power
+ of 5 -- 1,5,25,125, etc.
+ This has the same effect as the
+ -debug XXX command-line option.
+
+ Any Server HUP Any Resets Debug level to 0
+
+ File Server TERM Any Run minor instrumentation over
+ the list of descriptors.
+
+ Other Servers TERM Any Causes the process to quit.
+
+ File Server QUIT Any Causes the File Server to Quit.
+ Bos Server knows this.
+
+The basic metric of whether an AFS file server is doing well is the number
+of connections waiting for a thread,
+which can be found by running the following command:
+
+ % rxdebug <server> | grep waiting_for | wc -l
+
+Each line returned by C<rxdebug> that contains the text "waiting_for"
+represents a connection that's waiting for a file server thread.
+
+If the blocked connection count is ever above 0, the server is having
+problems replying to clients in a timely fashion. If it gets above 10,
+roughly, there will be noticable slowness by the user. The total number of
+connections is a mostly irrelevant number that goes essentially
+monotonically for as long as the server has been running and then goes back
+down to zero when it's restarted.
+
+The most common cause of blocked connections rising on a server is some
+process somewhere performing an abnormal number of accesses to that server
+and its volumes. If multiple servers have a blocked connection count, the
+most likely explanation is that there is a volume replicated between those
+servers that is absorbing an abnormally high access rate.
+
+To get an access count on all the volumes on a server, run:
+
+ % vos listvol <server> -long
+
+and save the output in a file. The results will look like a bunch of B<vos
+examine> output for each volume on the server. Look for lines like:
+
+ 40065 accesses in the past day (i.e., vnode references)
+
+and look for volumes with an abnormally high number of accesses. Anything
+over 10,000 is fairly high, but some volumes like root.cell and other
+volumes close to the root of the cell will have that many hits routinely.
+Anything over 100,000 is generally abnormally high. The count resets about
+once a day.
+
+Another approach that can be used to narrow the possibilities for a
+replicated volume, when multiple servers are having trouble, is to find all
+replicated volumes for that server. Run:
+
+ % vos listvldb -server <server>
+
+where <server> is one of the servers having problems to refresh the VLDB
+cache, and then run:
+
+ % vos listvldb -server <server> -part <partition>
+
+to get a list of all volumes on that server and partition, including every
+other server with replicas.
+
+Once the volume causing the problem has been identified, the best way to
+deal with the problem is to move that volume to another server with a low
+load or to stop any runaway programs that are accessing that volume
+unnecessarily. Often the volume will be enough information to tell what's
+going on.
+
+If you still need additional information about who's hitting that server,
+sometimes you can guess at that information from the failed callbacks in the
+F<FileLog> log in F</var/log/afs> on the server, or from the output of:
+
+ % /usr/afsws/etc/rxdebug <server> -rxstats
+
+but the best way is to turn on debugging output from the file server.
+(Warning: This generates a lot of output into FileLog on the AFS server.)
+To do this, log on to the AFS server, find the PID of the fileserver
+process, and do:
+
+ kill -TSTP <pid>
+
+where <pid> is the PID of the file server process. This will raise the
+debugging level so that you'll start seeing what people are actually doing
+on the server. You can do this up to three more times to get even more
+output if needed. To reset the debugging level back to normal, use (The
+following command will NOT terminate the file server):
+
+ kill -HUP <pid>
+
+The debugging setting on the File Server should be reset back to normal when
+debugging is no longer needed. Otherwise, the AFS server may well fill its
+disks with debugging output.
+
+The lines of the debugging output that are most useful for debugging load
+problems are:
+
+ SAFS_FetchStatus, Fid = 2003828163.77154.82248, Host 171.64.15.76
+ SRXAFS_FetchData, Fid = 2003828163.77154.82248
+
+(The example above is partly truncated to highlight the interesting
+information). The Fid identifies the volume and inode within the volume;
+the volume is the first long number. So, for example, this was:
+
+ % vos examine 2003828163
+ pubsw.matlab61 2003828163 RW 1040060 K On-line
+ afssvr5.Stanford.EDU /vicepa
+ RWrite 2003828163 ROnly 2003828164 Backup 2003828165
+ MaxQuota 3000000 K
+ Creation Mon Aug 6 16:40:55 2001
+ Last Update Tue Jul 30 19:00:25 2002
+ 86181 accesses in the past day (i.e., vnode references)
+
+ RWrite: 2003828163 ROnly: 2003828164 Backup: 2003828165
+ number of sites -> 3
+ server afssvr5.Stanford.EDU partition /vicepa RW Site
+ server afssvr11.Stanford.EDU partition /vicepd RO Site
+ server afssvr5.Stanford.EDU partition /vicepa RO Site
+
+and from the Host information one can tell what system is accessing that
+volume.
+
+Note that the output of L<vos_examine(1)> also includes the access count, so
+once the problem has been identified, vos examine can be used to see if the
+access count is still increasing. Also remember that you can run vos
+examine on the read-only replica (e.g., pubsw.matlab61.readonly) to see the
+access counts on the read-only replica on all of the servers that it's
+located on.
+
=head1 PRIVILEGE REQUIRED
The issuer must be logged in as the superuser C<root> on a file server
-machine to issue the command at a command shell prompt. It is conventional
+machine to issue the command at a command shell prompt. It is conventional
instead to create and start the process by issuing the B<bos create>
command.
L<bos_getlog(8)>,
L<fs_setacl(1)>,
L<salvager(8)>,
-L<volserver(8)>
+L<volserver(8)>,
+L<vos_examine(1)>
=head1 COPYRIGHT
--- /dev/null
+=head1 NAME
+
+read_tape - Reads volume dumps from a backup tape to a file
+
+=head1 SYNOPSIS
+
+=for html
+<div class="synopsis">
+
+B<read_tape> S<<< B<-tape> <I<tape device>> >>>
+ S<<< B<-restore> <I<# of volumes to restore>> >>>
+ S<<< B<-skip> <I<# of volumes to skip>> >>>
+ S<<< B<-file> <I<filename>> >>> [B<-scan>] [B<-noask>] [B<-label>]
+ [B<-vheaders>] [B<-verbose>] [B<-help>]
+
+=for html
+</div>
+
+=head1 DESCRIPTION
+
+B<read_tape> reads an OpenAFS backup tape and prompts for each dump file to
+save. This command does not require any OpenAFS infrastructure. This
+command does not need an OpenAFS client or server to be available, which is
+not the case with the L<backup(8)> command.
+
+The dump files will be named for the Read/Write name of the volume restored.
+After saving each dump file, B<vos restore> or B<restorevol> can be used to
+restore the volume into AFS and non-AFS space respectively.
+
+B<read_tape> reads the tape while skipping the specified number of volumes.
+After that, it restores the specified number of volumes. B<read_tape>
+doesn't rewind the tape so that it may be used multiple times in succession.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-tape> <I<tape device>>
+
+Specifies the tape device from which to restore.
+
+=item B<-restore> <I<# of volumes to restore>>
+
+Specifies the number of volumes to restore from tape.
+
+=item B<-skip> <I<# of volumes to skip>>
+
+Specifies the number of volumes to skip before starting the restore.
+
+=item B<-file> <I<filename>>
+
+Specifies an alternate name for the restored volume dump file rather than
+the default of the volume name.
+
+=item B<-scan>
+
+Scans the tape.
+
+=item B<-noask>
+
+Doesn't prompt for each volume.
+
+=item B<-label>
+
+Displays the full dump label.
+
+=item B<-vheaders>
+
+Displays the full volume headers.
+
+=item B<-verbose>
+
+Produces on the standard output stream a detailed trace of the command's
+execution. If this argument is omitted, only warnings and error messages
+appear.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command will read the third through fifth volumes from
+the tape device /dev/tape without prompting:
+
+ % read_tape -tape /dev/tape -skip 2 -restore 3 -noask
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must have access to read and write to the specified tape device.
+
+=head1 SEE ALSO
+
+L<backup(8)>,
+L<restorevol(8)>,
+L<vos_restore(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.