dd5a1208032387ff6dae81abade841a9fccbe461
[openafs.git] / doc / man-pages / pod8 / backup_jobs.pod
1 =head1 NAME
2
3 backup jobs - Lists pending and running operations in interactive mode
4
5 =head1 SYNOPSIS
6
7 B<jobs>  [-help]
8
9 B<j> [-h]
10
11 =head1 DESCRIPTION
12
13 The (backup) jobs command lists the job ID number and status of
14 each B<backup> operation running or pending in the current interactive
15 session.
16
17 This command can be issued in interactive mode only. If the issuer
18 of the B<backup (interactive)> command included the
19 B<-localauth> flag, the B<-cell> argument, or both, those
20 settings apply to this command also.
21
22 To terminate operations that appear in the output, issue the (backup)
23 kill command and identify the operation to cancel with the job ID number
24 from this command's output.
25
26 To check the status of a Tape Coordinator, rather than of a certain
27 operation, use the B<backup status> command.
28
29 =head1 OPTIONS
30
31 =over 4
32
33 =item -help
34
35 Prints the online help for this command. All other valid options
36 are ignored.
37
38 =back
39
40 =head1 OUTPUT
41
42 The output always includes the expiration date and time of the tokens that
43 the B<backup> command interpreter is using during the current
44 interactive session, in the following format: 
45
46    I<date>   I<time>: TOKEN EXPIRATION
47
48 If the execution date and time specified for a scheduled dump operation is
49 later than I<date time>, then its individual line (as described in the
50 following paragraphs) appears below this line to indicate that the current
51 tokens will not be available to it.
52
53 If the issuer of the backup command included the
54 B<-localauth> flag when entering interactive mode, the line instead
55 reads as follows:
56
57    :  TOKEN NEVER EXPIRES
58
59 The entry for a scheduled dump operation has the following format:
60
61    Job I<job_ID>:  I<timestamp>:  dump  I<volume_set>  I<dump_level>
62
63 where
64
65 =over 4
66
67 =item I<job_ID
68 >
69
70 Is a job identification number assigned by the Backup System.
71
72 =item I<timestamp
73 >
74
75 Indicates the date and time the dump operation is to begin, in the format
76 I<month>/I<date>/I<year>
77 I<hours>:I<minutes> (in 24-hour format)
78
79 =item I<volume_set
80 >
81
82 Indicates the volume set to dump.
83
84 =item I<dump_level
85 >
86
87 Indicates the dump level at which to perform the dump operation.
88
89 =back
90
91 The line for a pending or running operation of any other type has the
92 following format:
93
94    Job I<job_ID>:  I<operation>  I<status>
95
96 where
97
98 =over 4
99
100 =item I<job_ID
101 >
102
103 Is a job identification number assigned by the Backup System.
104
105 =item I<operation
106 >
107
108 Identifies the operation the Tape Coordinator is performing, which is
109 initiated by the indicated command:
110
111 =over 4
112
113 =item C<Dump C<(>I<dump name>C<)>
114 >
115
116 Initiated by the backup dump command. The I<dump
117 name> has the following format: 
118
119 I<volume_set_name>.I<dump_level_name>
120
121 =item C<Restore
122 >
123
124 Initiated by the B<backup diskrestore>, backup
125 volrestore, or B<backup volsetrestore> command.
126
127 =item C<Labeltape C<(>I<tape_label>C<)>
128 >
129
130 Initiated by the backup labeltape command. The
131 I<tape_label> is the name specified by the B<backup labeltape>
132 command's B<-name> or B<-pname> argument.
133
134 =item C<Scantape
135 >
136
137 Initiated by the backup scantape command.
138
139 =item C<SaveDb
140 >
141
142 Initiated by the backup savedb command.
143
144 =item C<RestoreDb
145 >
146
147 Initiated by the backup restoredb command.
148
149 =back
150
151 =item I<status
152 >
153
154 Indicates the job's current status in one of the following
155 messages. If no message appears, the job is either still pending or has
156 finished.
157
158 =over 4
159
160 =item I<number C<Kbytes, volume> I<volume_name>
161 >
162
163 For a running dump operation, indicates the number of kilobytes copied to
164 tape or a backup data file so far, and the volume currently being
165 dumped.
166
167 =item I<number C<Kbytes, restore.volume>
168 >
169
170 For a running restore operation, indicates the number of kilobytes copied
171 into AFS from a tape or a backup data file so far.
172
173 =item C<[abort requested]
174 >
175
176 The (backup) kill command was issued, but the termination
177 signal has yet to reach the Tape Coordinator.
178
179 =item C<[abort sent]
180 >
181
182 The operation is canceled by the (backup) kill command.
183 Once the Backup System removes an operation from the queue or stops it from
184 running, it no longer appears at all in the output from the command.
185
186 =item C<[butc contact lost]
187 >
188
189 The backup command interpreter cannot reach the Tape
190 Coordinator. The message can mean either that the Tape Coordinator
191 handling the operation was terminated or failed while the operation was
192 running, or that the connection to the Tape Coordinator timed out.
193
194 =item C<[done]
195 >
196
197 The Tape Coordinator has finished the operation.
198
199 =item C<[drive wait]
200 >
201
202 The operation is waiting for the specified tape drive to become
203 free.
204
205 =item C<[operator wait]
206 >
207
208 The Tape Coordinator is waiting for the backup operator to insert a tape
209 in the drive.
210
211 =back
212
213 =back
214
215 =head1 EXAMPLES
216
217 The following example shows that two restore operations and one dump
218 operation are running (presumably on different Tape Coordinators) and that the
219 B<backup> command interpreter's tokens expire on 22 April 1999 at
220 10:45 am:
221
222    backup> jobs
223    Job 1: Restore, 1306 Kbytes, restore.volume
224    Job 2: Dump (user.sunday1), 34 Kbytes, volume user.pat.backup
225    Job 3: Restore, 2498 Kbytes, restore.volume
226           04/22/1999 10:45: TOKEN EXPIRATION
227
228 =head1 PRIVILEGE REQUIRED
229
230 None. However, queuing any operation requires privilege, and it is
231 possible to issue this command only within the interactive session in which
232 the jobs are queued.
233
234 =head1 SEE ALSO
235
236 L<backup(1)>,
237 L<backup_interactive(1)>,
238 L<backup_kill(1)>,
239 L<backup_quit(1)>
240
241 =head1 COPYRIGHT
242
243 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
244
245 This documentation is covered by the IBM Public License Version 1.0.  It was
246 converted from HTML to POD by software written by Chas Williams and Russ
247 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.