backport to buster

[hcoop/debian/openafs.git] / doc / man-pages / pod1 / vos_offline.pod.in

=head1 NAME

vos_offline - Takes a volume offline

=head1 SYNOPSIS

=for html
<div class="synopsis">

B<vos offline> S<<< B<-server> <I<machine name>> >>>
    S<<< B<-partition> <I<partition name>> >>> 
    S<<< B<-id> <I<volume name or ID>> >>>
    S<<< [B<-sleep> <I<seconds to sleep>>] >>> 
    [B<-busy>] S<<< [B<-cell> <I<cell name>>] >>> 
    [B<-noauth>] B<-localauth>]
    [B<-verbose>] [B<-encrypt>] [B<-noresolve>]
    S<<< [B<-config> <I<config directory>>] >>>
    [B<-help>]

B<vos of> S<<< B<-se> <I<machine name>> >>>
    S<<< B<-p> <I<partition name>> >>> 
    S<<< B<-i> <I<volume name or ID>> >>>
    S<<< [B<-sl> <I<seconds to sleep>>] >>> 
    [B<-b>] S<<< [B<-c> <I<cell name>>] >>> 
    [B<-noa>] B<-l>]
    [B<-v>] [B<-e>] [B<-nor>]
    S<<< [B<-co> <I<config directory>>] >>>
    [B<-h>]

=for html
</div>

=head1 DESCRIPTION

The B<vos offline> command takes a volume offline on the 
B<fileserver>.  

=head1 CAUTIONS

Taking a volume offline that has existing 
callbacks will result in those callbacks being broken
and clients not being able to access the volume.

=head1 OPTIONS

=over 4

=item B<-server> <I<machine name>>

Identifies the file server machine where the 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<-partition> <I<partition name>>

Identifies the partition where the volume resides, on the
file server machine named by the B<-server> argument. Provide the
partition's complete name with preceding slash (for example, C</vicepa>)
or use one of the three acceptable abbreviated forms. For details, see
L<vos(1)>.

=item B<-id> <I<volume name or ID>>

Specifies either the complete name or volume ID number of the volume.

=item B<-sleep> <I<seconds to sleep>>

Specifies to sleep for a certain number of seconds after taking the
volume offline before bringing it online again. If this option is
specified, the volume will be online when B<vos offline> successfully
completes. If this option is not specified, B<vos online> must be run to
bring the volume online.

=item B<-busy>

Specifies to mark the volume as `busy' instead of `offline'. This
means that a program trying to access this volume will receive a VBUSY
error instead of a VOFFLINE error (until the volume is brought back
online).

Different programs may react differently when they see these two
different states, but in general a `busy' volume is only unavailable
for a short period of time and will become online soon. An `offline'
volume, on the other hand, is typically unavailable for longer periods
and may not come back online until an administrator intervenes.

As an example of when these states occur normally, a volume can be
`busy' when it is being cloned (perhaps as the result of a
B<vos backup> or B<vos release> operation). A volume can be `offline'
if a non-DAFS fileserver has detected a problem in the volume, and an
administrator must manually schedule a salvage for that volume before
it becomes available again.

If B<-busy> is specified, the B<-sleep> option must also be specified, to
indicate for how long to keep the volume busy.

=include fragments/vos-common.pod

=back

=head1 EXAMPLES

The following example takes an online volume offline:

   % vos offline -server sv7.example.org -partition /vicepb -id root.afs

=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_online(1)>,
L<bos_salvage(8)>,

=head1 COPYRIGHT

IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.

This man page was created by Steven Jenkins.