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