man8-editing-pass-20051213
[openafs.git] / doc / man-pages / pod8 / backup_kill.pod
1 =head1 NAME
2
3 backup kill - Terminates a pending or running operation
4
5 =head1 SYNOPSIS
6
7 B<kill> B<-id> <I<job ID or dump set name>> [B<-help>]
8
9 B<k -i> <I<job ID or dump set name>> [B<-h>]
10
11 =head1 DESCRIPTION
12
13 The B<backup kill> command dequeues a Backup System operation that is
14 pending, or terminates an operation that is running, in the current
15 interactive session. It is available only in interactive mode.  If the
16 issuer of the B<backup interactive> command included the B<-localauth>
17 flag, the B<-cell> argument, or both, then those settings apply to this
18 command also.
19
20 To terminate a dump operation, specify either the dump name
21 (I<volume_set_name>.I<dump_level_name>) or its job ID number, which
22 appears in the output from the B<backup jobs> command. To terminate any
23 other type of operation, provide the job ID number.
24
25 The effect of terminating an operation depends on the type and current
26 state of the operation:
27
28 =over 4
29
30 =item *
31
32 If an operation is still pending, the Tape Coordinator removes it from the
33 queue with no other lasting effects.
34
35 =item *
36
37 If the Tape Coordinator is unable to process the termination signal before
38 an operation completes, it simply confirms the operation's completion. The
39 operator must take the action necessary to undo the effects of the
40 incorrect operation.
41
42 =item *
43
44 If a tape labeling operation is running, the effect depends on when the
45 Tape Coordinator receives the termination signal. The labeling operation
46 is atomic, so it either completes or does not begin at all.  Use the
47 B<backup readlabel> command to determine if the labeling operation
48 completed, and reissue the B<backup labeltape> command to overwrite the
49 incorrect label if necessary.
50
51 =item *
52
53 If a tape scanning operation is running, it terminates with no other
54 effects unless the B<-dbadd> flag was included on the B<backup>
55 command. In that case, the Backup System possibly has already written new
56 Backup Database records to represent dumps on the scanned tape. If
57 planning to restart the scanning operation, first locate and remove the
58 records created during the terminated operation: a repeated B<backup
59 scantape> operation exits automatically when it finds that a record that
60 it needs to create already exists.
61
62 =item *
63
64 If a dump operation is running, all of the volumes written to the tape or
65 backup data file before the termination signal is received are complete
66 and usable. If the operation is restarted, the Backup System performs all
67 the dumps again from scratch, and assigns a new dump ID number. If writing
68 the new dumps to the same tape or file, the operator must relabel it first
69 if the interrupted dump is not expired. If writing the new dump to a
70 different tape or file, the operator can remove the dump record associated
71 with the interrupted dump to free up space in the database.
72
73 =item *
74
75 If a restore operation is running, completely restored volumes are online
76 and usable. However, it is unlikely that many volumes are completely
77 restored, given that complete restoration usually requires data from
78 multiple tapes. If the termination signal comes before the Backup System
79 has accessed all of the necessary tapes, each volume is only partially
80 written and is never brought online. It is best to restart the restore
81 operation from scratch to avoid possible inconsistencies. See also
82 L<CAUTIONS>.
83
84 =back
85
86 =head1 CAUTIONS
87
88 It is best not to issue the B<backup kill> command against restore
89 operations. If the termination signal interrupts a restore operation as
90 the Backup System is overwriting an existing volume, it is possible to
91 lose the volume entirely (that is, to lose both the contents of the volume
92 as it was before the restore and any data that was restored before the
93 termination signal arrived). The data being restored still exists on the
94 tape, but some data can be lost permanently.
95
96 =head1 OPTIONS
97
98 =over 4
99
100 =item B<-id> <I<job ID or dump set name>>
101
102 Identifies the backup operation to terminate. Provide one of two types of
103 values:
104
105 =over 4
106
107 =item *
108
109 The operation's job ID number, as displayed in the output of the B<backup
110 jobs> command.
111
112 =item *
113
114 For a dump operation, either the job ID number or a dump name of the form
115 I<volume_set_name>.I<dump_level_name>, where I<volume_set_name> is the
116 name of the volume set being dumped and I<dump_level_name> is the last
117 element in the dump level pathname at which the volume set is being
118 dumped. The dump name appears in the output of the B<backup jobs> command
119 along with the job ID number.
120
121 =back
122
123 =item B<-help>
124
125 Prints the online help for this command. All other valid options are
126 ignored.
127
128 =back
129
130 =head1 EXAMPLES
131
132 The following command terminates the operation with job ID 5:
133
134    backup> kill 5
135
136 The following command terminates the dump operation called
137 C<user.sunday1>:
138
139    backup> kill user.sunday1
140
141 =head1 PRIVILEGE REQUIRED
142
143 The issuer must have the privilege required to initiate the operation
144 being cancelled. Because this command can be issued only within the
145 interactive session during which the operation was initiated, the required
146 privilege is essentially guaranteed.
147
148 =head1 SEE ALSO
149
150 L<backup(8)>,
151 L<backup_interactive(8)>,
152 L<backup_jobs(8)>
153
154 =head1 COPYRIGHT
155
156 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
157
158 This documentation is covered by the IBM Public License Version 1.0.  It was
159 converted from HTML to POD by software written by Chas Williams and Russ
160 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.