This repository has been archived by the owner on Mar 19, 2021. It is now read-only.
/
bconsole.tex
1966 lines (1622 loc) · 80.1 KB
/
bconsole.tex
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
\chapter{Bareos Console}
\label{sec:bconsole}
\index[general]{Bareos Console}
\index[general]{bconsole}
\index[general]{Command!bconsole}
The {\bf Bareos Console} (\command{bconsole}) is a program that
allows the user or the System Administrator, to interact with the Bareos
Director daemon while the daemon is running.
The current Bareos Console comes as a shell interface (TTY
style). It permit the administrator or
authorized users to interact with Bareos. You can determine the status of a
particular job, examine the contents of the Catalog as well as perform certain
tape manipulations with the Console program.
Since the Console program interacts with the Director through the network, your
Console and Director programs do not necessarily need to run on the same
machine.
In fact, a certain minimal knowledge of the Console program is needed in order
for Bareos to be able to write on more than one tape, because when Bareos
requests a new tape, it waits until the user, via the Console program,
indicates that the new tape is mounted.
\section{Console Configuration}
\index[general]{Configuration!Console}
\index[general]{Configuration!bconsole}
When the Console starts, it reads a standard Bareos configuration file
named {\bf bconsole.conf} unless you specify the {\bf {-}c}
command line option (see below). This file allows default configuration
of the Console, and at the current time, the only Resource Record defined
is the Director resource, which gives the Console the name and address of
the Director. For more information on configuration of the Console
program, please see the \ilink{Console Configuration}{ConsoleConfChapter} chapter of this document.
\section{Running the Console Program}
The console program can be run with the following options:
\index[console]{Command Line Options}
\begin{commandOut}{bconsole command line options}{}{bconsole -?}
Usage: bconsole [-s] [-c config_file] [-d debug_level]
-D <dir> select a Director
-l list Directors defined
-c <file> set configuration file to file
-d <nn> set debug level to <nn>
-dt print timestamp in debug output
-n no conio
-s no signals
-u <nn> set command execution timeout to <nn> seconds
-t test - read configuration and exit
-? print this message.
\end{commandOut}
After launching the Console program (bconsole), it will prompt you for the next
command with an asterisk (*). Generally, for all commands, you can simply
enter the command name and the Console program will prompt you for the
necessary arguments. Alternatively, in most cases, you may enter the command
followed by arguments. The general format is:
\footnotesize
\begin{verbatim}
<command> <keyword1>[=<argument1>] <keyword2>[=<argument2>] ...
\end{verbatim}
\normalsize
where {\bf command} is one of the commands listed below; {\bf keyword} is one
of the keywords listed below (usually followed by an argument); and {\bf
argument} is the value. The command may be abbreviated to the shortest unique
form. If two commands have the same starting letters, the one that will be
selected is the one that appears first in the {\bf help} listing. If you want
the second command, simply spell out the full command. None of the keywords
following the command may be abbreviated.
For example:
\footnotesize
\begin{verbatim}
list files jobid=23
\end{verbatim}
\normalsize
will list all files saved for JobId 23. Or:
\footnotesize
\begin{verbatim}
show pools
\end{verbatim}
\normalsize
will display all the Pool resource records.
The maximum command line length is limited to 511 characters, so if you
are scripting the console, you may need to take some care to limit the
line length.
\subsection{Exit the Console Program}
\index[general]{Command!bconsole!exit}
Normally, you simply enter {\bf quit} or {\bf exit} and the Console program
will terminate. However, it waits until the Director acknowledges the command.
If the Director is already doing a lengthy command (e.g. prune), it may take
some time. If you want to immediately terminate the Console program, enter the
{\bf .quit} command.
There is currently no way to interrupt a Console command once issued (i.e.
Ctrl-C does not work). However, if you are at a prompt that is asking you to
select one of several possibilities and you would like to abort the command,
you can enter a period ({\bf .}), and in most cases, you will either be
returned to the main command prompt or if appropriate the previous prompt (in
the case of nested prompts). In a few places such as where it is asking for a
Volume name, the period will be taken to be the Volume name. In that case, you
will most likely be able to cancel at the next prompt.
\subsection{Running the Console from a Shell Script}
\index[general]{Console!Running from a Shell}
\label{scripting}
You can automate many Console tasks by running the console program from a
shell script. For example, if you have created a file containing the following
commands:
\footnotesize
\begin{verbatim}
bconsole -c ./bconsole.conf <<END_OF_DATA
unmount storage=DDS-4
quit
END_OF_DATA
\end{verbatim}
\normalsize
when that file is executed, it will unmount the current DDS-4 storage device.
You might want to run this command during a Job by using the {\bf
RunBeforeJob} or {\bf RunAfterJob} records.
It is also possible to run the Console program from file input where the file
contains the commands as follows:
\footnotesize
\begin{verbatim}
bconsole -c ./bconsole.conf <filename
\end{verbatim}
\normalsize
where the file named {\bf filename} contains any set of console commands.
As a real example, the following script is part of the Bareos regression
tests. It labels a volume (a disk volume), runs a backup, then does a restore
of the files saved.
\footnotesize
\begin{verbatim}
bconsole <<END_OF_DATA
@output /dev/null
messages
@output /tmp/log1.out
label volume=TestVolume001
run job=Client1 yes
wait
messages
@#
@# now do a restore
@#
@output /tmp/log2.out
restore current all
yes
wait
messages
@output
quit
END_OF_DATA
\end{verbatim}
\normalsize
The output from the backup is directed to /tmp/log1.out and the output from
the restore is directed to /tmp/log2.out. To ensure that the backup and
restore ran correctly, the output files are checked with:
\footnotesize
\begin{verbatim}
grep "^ *Termination: *Backup OK" /tmp/log1.out
backupstat=$?
grep "^ *Termination: *Restore OK" /tmp/log2.out
restorestat=$?
\end{verbatim}
\normalsize
\section{Console Keywords}
\index[general]{Console!Keywords}
Unless otherwise specified, each of the following keywords
takes an argument, which is specified after the keyword following
an equal sign. For example:
\begin{verbatim}
jobid=536
\end{verbatim}
\begin{description}
\item [all]
Permitted on the status and show commands to specify all components or
resources respectively.
\item [allfrompool]
Permitted on the update command to specify that all Volumes in the
pool (specified on the command line) should be updated.
\item [allfrompools]
Permitted on the update command to specify that all Volumes in all
pools should be updated.
\item [before]
Used in the restore command.
\item [bootstrap]
Used in the restore command.
\item [catalog]
Allowed in the use command to specify the catalog name
to be used.
\item [catalogs]
Used in the show command. Takes no arguments.
\item [client \textbar\ fd]
\item [clients]
Used in the show, list, and llist commands. Takes no arguments.
\item [counters]
Used in the show command. Takes no arguments.
\item [current]
Used in the restore command. Takes no argument.
\item [days]
Used to define the number of days the \bcommand{list}{nextvol} command
should consider when looking for jobs to be run. The days keyword
can also be used on the \bcommand{status}{dir} command so that it will display
jobs scheduled for the number of days you want. It can also be used on the \bcommand{rerun}{} command, where it will automatically select all failed jobids in the last number of days for rerunning.
\item [devices]
Used in the show command. Takes no arguments.
\item [director \textbar\ dir]
\item [directors]
Used in the show command. Takes no arguments.
\item [directory]
Used in the restore command. Its argument specifies the directory
to be restored.
\item [enabled]
This keyword can appear on the \bcommand{update}{volume} as well
as the \bcommand{update}{slots} commands, and can
allows one of the following arguments: yes, true, no, false, archived,
0, 1, 2. Where 0 corresponds to no or false, 1 corresponds to yes or true, and
2 corresponds to archived. Archived volumes will not be used, nor will
the Media record in the catalog be pruned. Volumes that are not enabled,
will not be used for backup or restore.
\item [done]
Used in the restore command. Takes no argument.
\item [file]
Used in the restore command.
\item [files]
Used in the list and llist commands. Takes no arguments.
\item [fileset]
\item [filesets]
Used in the show command. Takes no arguments.
\item [help]
Used in the show command. Takes no arguments.
\item [hours]
Used on the \bcommand{rerun}{} command to select all failed jobids in the last number of hours for rerunning.
\item [jobs]
Used in the show, list and llist commands. Takes no arguments.
\item [jobmedia]
Used in the list and llist commands. Takes no arguments.
\item [jobtotals]
Used in the list and llist commands. Takes no arguments.
\item [jobid]
The JobId is the numeric jobid that is printed in the Job
Report output. It is the index of the database record for the
given job. While it is unique for all the existing Job records
in the catalog database, the same JobId can be reused once a
Job is removed from the catalog. Probably you will refer
specific Jobs that ran using their numeric JobId.
JobId can be used on the \bcommand{rerun} command to select all jobs failed after and including the given jobid for rerunning.
\item [job \textbar\ jobname]
The Job or Jobname keyword refers to the name you specified
in the Job resource, and hence it refers to any number of
Jobs that ran. It is typically useful if you want to list
all jobs of a particular name.
\item [level]
\item [listing]
Permitted on the estimate command. Takes no argument.
\item [limit]
\item [messages]
Used in the show command. Takes no arguments.
\item [media]
Used in the list and llist commands. Takes no arguments.
\item [nextvolume \textbar\ nextvol]
Used in the list and llist commands. Takes no arguments.
\item [on]
Takes no keyword.
\item [off]
Takes no keyword.
\item [pool]
\item [pools]
Used in the show, list, and llist commands. Takes no arguments.
\item [select]
Used in the restore command. Takes no argument.
\item[limit]
Used in the setbandwidth command. Takes integer in KB/s unit.
\item [schedules]
Used in the show command. Takes no arguments.
\item [storage \textbar\ store \textbar\ sd]
\item [storages]
Used in the show command. Takes no arguments.
\item [ujobid]
The ujobid is a unique job identification that is printed
in the Job Report output. At the current time, it consists
of the Job name (from the Name directive for the job) appended
with the date and time the job was run. This keyword is useful
if you want to completely identify the Job instance run.
\item [volume]
\item [volumes]
Used in the list and llist commands. Takes no arguments.
\item [where]
Used in the restore command.
\item [yes]
Used in the restore command. Takes no argument.
\end{description}
\section{Console Commands}
\label{sec:ConsoleCommands}
The following commands are currently implemented:
\begin{description}
\item [add]
\index[general]{Console!Command!add|textbf}
This command is used to add Volumes to an existing Pool. That is,
it creates the Volume name in the catalog and inserts into the Pool
in the catalog, but does not attempt to access the physical Volume.
Once added, Bareos expects that Volume to exist and to be labeled.
This command is not normally used since Bareos will
automatically do the equivalent when Volumes are labeled. However,
there may be times when you have removed a Volume from the catalog
and want to later add it back.
The full form of this command is:
\begin{bconsole}{add}
add [pool=<pool-name>] [storage=<storage>] [jobid=<JobId>]
\end{bconsole}
Normally, the \bcommand{label}{} command is used rather than this command
because the \bcommand{label}{} command labels the physical media (tape, disk,, ...)
and does the equivalent of the \bcommand{add}{} command.
The \bcommand{add}{} command affects only the Catalog and not the physical media (data
on Volumes). The physical media must exist and be labeled before use
(usually with the \bcommand{label}{} command). This command can, however, be
useful if you wish to add a number of Volumes to the Pool that will be
physically labeled at a later time. It can also be useful if you are
importing a tape from another site. Please see the \bcommand{label}{} command
for the list of legal characters in a Volume name.
\item [autodisplay]
\index[general]{Console!Command!autodisplay on/off}
This command accepts {\bf on} or {\bf off} as an argument, and turns
auto-display of messages on or off respectively. The default for the
console program is {\bf off}, which means that you will be notified when
there are console messages pending, but they will not automatically be
displayed.
When autodisplay is turned off, you must explicitly retrieve the
messages with the {\bf messages} command. When autodisplay is turned
on, the messages will be displayed on the console as they are received.
\item [automount]
\index[general]{Console!Command!automount on/off}
This command accepts {\bf on} or {\bf off} as the argument, and turns
auto-mounting of the Volume after a {\bf label} command on or off
respectively. The default is {\bf on}. If {\bf automount} is turned
off, you must explicitly {\bf mount} tape Volumes after a label command to
use it.
\item [cancel]
\index[general]{Console!Command!cancel jobid}
This command is used to cancel a job and accepts {\bf jobid=nnn} or {\bf
job=xxx} as an argument where nnn is replaced by the JobId and xxx is
replaced by the job name. If you do not specify a keyword, the Console
program will prompt you with the names of all the active jobs allowing
you to choose one.
The full form of this command is:
\begin{bconsole}{cancel}
cancel [jobid=<number> job=<job-name> ujobid=<unique-jobid>]
\end{bconsole}
Once a Job is marked to be cancelled, it may take a bit of time
(generally within a minute but up to two hours) before the Job actually
terminates, depending on what operations it is doing.
Don't be surprised that you receive a Job not found message. That just
means that one of the three daemons had already canceled the job.
Messages numbered in the 1000's are from the Director, 2000's are from
the File daemon and 3000's from the Storage daemon.
It is possible to cancel multiple jobs at once. Therefore, the following extra options are available for the job-selection:
\begin{itemize}
\item all jobs
\item all jobs with a created state
\item all jobs with a blocked state
\item all jobs with a waiting state
\item all jobs with a running state
\end{itemize}
Usage:
\begin{bconsole}{cancel all}
cancel all
cancel all state=<created|blocked|waiting|running>
\end{bconsole}
Sometimes the Director already removed the job from its running queue, but the storage daemon still thinks it is doing a backup (or another job) - so you cannot cancel the job from within a console anymore. Therefore it is possible to cancel a job by JobId on the storage daemon. It might be helpful to execute a \bcommand{status storage}{} on the Storage Daemon to make sure what job you want to cancel.
Usage:
\begin{bconsole}{cancel on Storage Daemon}
cancel storage=<Storage Daemon> Jobid=<JobId>
\end{bconsole}
This way you can also remove a job that blocks any other jobs from running without the need to restart the whole storage daemon.
\item [create]
\index[general]{Console!Command!create pool}
This command is not normally used as the Pool records are automatically
created by the Director when it starts based on what it finds in
the configuration. If needed, this command can be used,
to create a Pool record in the database using the
Pool resource record defined in the Director's configuration file. So
in a sense, this command simply transfers the information from the Pool
resource in the configuration file into the Catalog. Normally this
command is done automatically for you when the Director starts providing
the Pool is referenced within a Job resource. If you use this command
on an existing Pool, it will automatically update the Catalog to have
the same information as the Pool resource. After creating a Pool, you
will most likely use the {\bf label} command to label one or more
volumes and add their names to the Media database.
The full form of this command is:
\begin{bconsole}{create}
create [pool=<pool-name>]
\end{bconsole}
When starting a Job, if Bareos determines that there is no Pool record
in the database, but there is a Pool resource of the appropriate name,
it will create it for you. If you want the Pool record to appear in the
database immediately, simply use this command to force it to be created.
\item[configure]
\label{sec:bcommandConfigure}
Configures director resources during runtime.
The first configure subcommands are \bcommand{configure}{add} and \bcommand{configure}{export}.
Other subcommands may follow in later releases.
\begin{description}
\item [configure add]
\label{sec:bcommandConfigureAdd}
\index[general]{Console!Command!configure add}
This command allows to add resources during runtime.
Usage:
\begin{bconsole}{}
configure add <resourcetype> name=<resourcename> <directive1>=<value1> <directive2>=<value2> ...
\end{bconsole}
The command generates and loads a new, valid resource.
As the new resource is also stored at
\file{<CONFIGDIR>/bareos-dir.d/<resourcetype>/<resourcename>.conf}
(see \nameref{sec:ConfigurationResourceFileConventions}) it is persistent upon reload and restart.
This feature requires \nameref{sec:ConfigurationSubdirectories}.
All kinds of resources can be added.
When adding a client resource, the \nameref{ClientResourceDirector} for the \bareosFd is also created
and stored at:
\file{<CONFIGDIR>/bareos-dir-export/client/<clientname>/bareos-fd.d/director/<clientname>.conf}
\begin{bconsole}{Example: adding a client and a job resource during runtime}
*<input>configure add client name=client2-fd address=192.168.0.2 password=secret</input>
Created resource config file "/etc/bareos/bareos-dir.d/client/client2-fd.conf":
Client {
Name = client2-fd
Address = 192.168.0.2
Password = secret
}
*<input>configure add job name=client2-job client=client2-fd jobdefs=DefaultJob</input>
Created resource config file "/etc/bareos/bareos-dir.d/job/client2-job.conf":
Job {
Name = client2-job
Client = client2-fd
JobDefs = DefaultJob
}
\end{bconsole}
These two commands create three resource configuration files:
\begin{itemize}
\item \file{/etc/bareos/bareos-dir.d/client/client2-fd.conf}
\item \file{/etc/bareos/bareos-dir-export/client/client2-fd/bareos-fd.d/director/bareos-dir.conf} (assuming your director resource is named \name{bareos-dir})
\item \file{/etc/bareos/bareos-dir.d/job/client2-job.conf}
\end{itemize}
The files in \directory{bareos-dir-export/client/} directory are not used by the \bareosDir.
However, they can be copied to new clients to configure these clients for the \bareosDir.
\warning{Don't be confused by the extensive output of \bcommand{help}{configure}. As \bcommand{configure}{add} allows configuring arbitrary resources, the output of \bcommand{help}{configure} lists all the resources, each with all valid directives. The same data is also used for \command{bconsole} command line completion.}
Available since Bareos \sinceVersion{console}{configure add}{16.2.4}.
\item [configure export]
\label{sec:bcommandConfigureExport}
\index[general]{Console!Command!configure export}
This command allows to export the \resourcetype{Fd}{Director} resource for clients already configured in the \bareosDir.
Usage:
\begin{bconsole}{Export the bareos-fd Director resource for the client bareos-fd}
configure export client=bareos-fd
Exported resource file "/etc/bareos/bareos-dir-export/client/bareos-fd/bareos-fd.d/director/bareos-dir.conf":
Director {
Name = bareos-dir
Password = "[md5]932d1d3ef3c298047809119510f4bee6"
}
\end{bconsole}
To use it, copy the \resourcetype{Fd}{Director} resource file to the client machine
(on Linux: to \directory{/etc/bareos/bareos-fd.d/director/}) and restart the \bareosFd.
Available since Bareos \sinceVersion{console}{configure export}{16.2.4}.
\end{description}
\item [delete]
\index[general]{Console!Command!delete}
The delete command is used to delete a Volume, Pool or Job record from
the Catalog as well as all associated catalog Volume records that were
created. This command operates only on the Catalog database and has no
effect on the actual data written to a Volume. This command can be
dangerous and we strongly recommend that you do not use it unless you
know what you are doing.
If the keyword {\bf Volume} appears on the command line, the named
Volume will be deleted from the catalog, if the keyword {\bf Pool}
appears on the command line, a Pool will be deleted, and if the keyword
{\bf Job} appears on the command line, a Job and all its associated
records (File and JobMedia) will be deleted from the catalog.
The full form of this command is:
\begin{bconsole}{delete}
delete pool=<pool-name>
delete volume=<volume-name> pool=<pool-name>
delete JobId=<job-id> JobId=<job-id2> ...
delete Job JobId=n,m,o-r,t ...
\end{bconsole}
The first form deletes a Pool record from the catalog database. The
second form deletes a Volume record from the specified pool in the
catalog database. The third form deletes the specified Job record from
the catalog database. The last form deletes JobId records for JobIds
n, m, o, p, q, r, and t. Where each one of the n,m,... is, of course, a
number. That is a "delete jobid" accepts lists and ranges of
jobids.
\item [disable]
\index[general]{Console!Command!disable}
This command permits you to disable a Job for automatic scheduling.
The job may have been previously enabled with the Job resource
{\bf Enabled} directive or using the console {\bf enable} command.
The next time the Director is reloaded or restarted,
the Enable/Disable state will be set to the value in the Job resource
(default enabled) as defined in the \bareosDir configuration.
The full form of this command is:
\begin{bconsole}{disable}
disable job=<job-name>
\end{bconsole}
\item [enable]
\index[general]{Console!Command!enable}
This command permits you to enable a Job for automatic scheduling.
The job may have been previously disabled with the Job resource
{\bf Enabled} directive or using the console {\bf disable} command.
The next time the Director is reloaded or restarted,
the Enable/Disable state will be set to the value in the Job resource
(default enabled) as defined in the \bareosDir configuration.
The full form of this command is:
\begin{bconsole}{enable}
enable job=<job-name>
\end{bconsole}
\label{estimate}
\item [estimate]
\index[general]{Console!Command!estimate}
Using this command, you can get an idea how many files will be backed
up, or if you are unsure about your Include statements in your FileSet,
you can test them without doing an actual backup. The default is to
assume a Full backup. However, you can override this by specifying a
{\bf level=Incremental} or {\bf level=Differential} on the command line.
A Job name must be specified or you will be prompted for one, and
optionally a Client and FileSet may be specified on the command line.
It then contacts the client which computes the number of files and bytes
that would be backed up. Please note that this is an estimate
calculated from the number of blocks in the file rather than by reading
the actual bytes. As such, the estimated backup size will generally be
larger than an actual backup.
The \texttt{estimate} command can use the accurate code to detect changes
and give a better estimation. You can set the accurate behavior on command
line using \texttt{accurate=yes/no} or use the Job setting as default value.
Optionally you may specify the keyword {\bf listing} in which case, all the
files to be backed up will be listed. Note, it could take quite some time to
display them if the backup is large. The full form is:
The full form of this command is:
\begin{bconsole}{estimate}
estimate job=<job-name> listing client=<client-name> accurate=<yes|no> fileset=<fileset-name> level=<level-name>
\end{bconsole}
Specification of the {\bf job} is sufficient, but you can also override the
client, fileset, accurate and/or level by specifying them on the estimate
command line.
As an example, you might do:
\begin{bconsole}{estimate: redirected output}
@output /tmp/listing
estimate job=NightlySave listing level=Incremental
@output
\end{bconsole}
which will do a full listing of all files to be backed up for the Job {\bf
NightlySave} during an Incremental save and put it in the file {\bf
/tmp/listing}. Note, the byte estimate provided by this command is
based on the file size contained in the directory item. This can give
wildly incorrect estimates of the actual storage used if there are
sparse files on your systems. Sparse files are often found on 64 bit
systems for certain system files. The size that is returned is the size
Bareos will backup if the sparse option is not specified in the FileSet.
There is currently no way to get an estimate of the real file size that
would be found should the sparse option be enabled.
\item [exit]
\index[general]{Console!Command!exit}
This command terminates the console program.
\item [export]
\index[general]{Console!Command!export}
The export command is used to export tapes from an autochanger. Most Automatic
Tapechangers offer special slots for importing new tape cartridges or
exporting written tape cartridges. This can happen without having to set
the device offline.
The full form of this command is:
\begin{bconsole}{export}
export storage=<storage-name> srcslots=<slot-selection> [dstslots=<slot-selection> volume=<volume-name> scan]
\end{bconsole}
The export command does exactly the opposite of the import command. You
can specify which slots should be transferred to import/export slots. The
most useful application of the export command is the possibility to
automatically transfer the volumes of a certain backup into the import/export
slots for external storage.
To be able to to this, the export command also accepts a list of volume names
to be exported.
Example:
\begin{bconsole}{export volume}
export volume=A00020L4|A00007L4|A00005L4
\end{bconsole}
Instead of exporting volumes by names you can also select a number of slots via
the srcslots keyword and export those to the slots you specify in dstslots. The export
command will check if the slots have content (e.g. otherwise there is not much to
export) and if there are enough export slots and if those are really import/export slots.
Example:
\begin{bconsole}{export slots}
export srcslots=1-2 dstslots=37-38
\end{bconsole}
To automatically export the Volumes used by a certain backup job, you can use the following RunScript in that job:
\begin{bconsole}{automatic export}
RunScript {
Console = "export storage=TandbergT40 volume=%V"
RunsWhen = After
RunsOnClient = no
}
\end{bconsole}
To send an e-mail notification via the Messages resource regarding export tapes you can use the Variable \%V substitution in the Messages resource, which is implemented in Bareos 13.2. However, it does also work in earlier releases inside the job resources. So in versions prior to Bareos 13.2 the following workaround can be used:
\begin{bconsole}{e-mail notification via messages resource regarding export tapes}
RunAfterJob = "/bin/bash -c \"/bin/echo Remove Tape %V | \
/usr/sbin/bsmtp -h localhost -f root@localhost -s 'Remove Tape %V' root@localhost \""
\end{bconsole}
\item [gui]
\index[general]{Console!Command!gui}
Invoke the non-interactive gui mode.
This command is only used when \command{bconsole} is commanded by an external program.
\item [help]
\index[general]{Console!Command!help}
This command displays the list of commands available.
\item [import]
\index[general]{Console!Command!import}
The import command is used to import tapes into an autochanger. Most Automatic
Tapechangers offer special slots for importing new tape cartridges or
exporting written tape cartridges. This can happen without having to set
the device offline.
The full form of this command is:
\begin{bconsole}{import}
import storage=<storage-name> [srcslots=<slot-selection> dstslots=<slot-selection> volume=<volume-name> scan]
\end{bconsole}
To import new tapes into the autochanger, you only have to load the new
tapes into the import/export slots and call import from the cmdline.
The import command will automatically transfer the new tapes into free
slots of the autochanger. The slots are filled in order of the slot numbers.
To import all tapes, there have to be enough free slots to load all tapes.
Example with a Library with 36 Slots and 3 Import/Export Slots:
\begin{bconsole}{import example}
*import storage=TandbergT40
Connecting to Storage daemon TandbergT40 at bareos:9103 ...
3306 Issuing autochanger "slots" command.
Device "Drive-1" has 39 slots.
Connecting to Storage daemon TandbergT40 at bareos:9103 ...
3306 Issuing autochanger "listall" command.
Connecting to Storage daemon TandbergT40 at bareos:9103 ...
3306 Issuing autochanger transfer command.
3308 Successfully transfered volume from slot 37 to 20.
Connecting to Storage daemon TandbergT40 at bareos:9103 ...
3306 Issuing autochanger transfer command.
3308 Successfully transfered volume from slot 38 to 21.
Connecting to Storage daemon TandbergT40 at bareos:9103 ...
3306 Issuing autochanger transfer command.
3308 Successfully transfered volume from slot 39 to 25.
\end{bconsole}
You can also import certain slots when you don't have enough free slots
in your autochanger to put all the import/export slots in.
Example with a Library with 36 Slots and 3 Import/Export Slots importing one slot:
\begin{bconsole}{import example}
*import storage=TandbergT40 srcslots=37 dstslots=20
Connecting to Storage daemon TandbergT40 at bareos:9103 ...
3306 Issuing autochanger "slots" command.
Device "Drive-1" has 39 slots.
Connecting to Storage daemon TandbergT40 at bareos:9103 ...
3306 Issuing autochanger "listall" command.
Connecting to Storage daemon TandbergT40 at bareos:9103 ...
3306 Issuing autochanger transfer command.
3308 Successfully transfered volume from slot 37 to 20.
\end{bconsole}
\item [label]
\index[general]{Console!Command!label}
\index[general]{Console!Command!relabel}
This command is used to label physical volumes.
The full form of this command is:
\begin{bconsole}{label}
label storage=<storage-name> volume=<volume-name> slot=<slot>
\end{bconsole}
If you leave out any part, you will be prompted for it. The media type
is automatically taken from the Storage resource definition that you
supply. Once the necessary information is obtained, the Console program
contacts the specified Storage daemon and requests that the Volume be
labeled. If the Volume labeling is successful, the Console program will
create a Volume record in the appropriate Pool.
The Volume name is restricted to letters, numbers, and the special
characters hyphen ({\bf -}), underscore ({\bf \_}), colon ({\bf :}), and
period ({\bf .}). All other characters including a space are invalid.
This restriction is to ensure good readability of Volume names to reduce
operator errors.
Please note, when labeling a blank tape, Bareos will get {\bf read I/O
error} when it attempts to ensure that the tape is not already labeled. If
you wish to avoid getting these messages, please write an EOF mark on
your tape before attempting to label it:
\footnotesize
\begin{verbatim}
mt rewind
mt weof
\end{verbatim}
\normalsize
The label command can fail for a number of reasons:
\begin{enumerate}
\item The Volume name you specify is already in the Volume database.
\item The Storage daemon has a tape or other Volume already mounted on the
device, in which case you must {\bf unmount} the device, insert a blank
tape, then do the {\bf label} command.
\item The Volume in the device is already a Bareos labeled Volume. (Bareos will
never relabel a Bareos labeled Volume unless it is recycled and you use the
{\bf relabel} command).
\item There is no Volume in the drive.
\end{enumerate}
There are two ways to relabel a volume that already has a Bareos label. The
brute force method is to write an end of file mark on the tape using the
system {\bf mt} program, something like the following:
\footnotesize
\begin{verbatim}
mt -f /dev/st0 rewind
mt -f /dev/st0 weof
\end{verbatim}
\normalsize
For a disk volume, you would manually delete the Volume.
Then you use the {\bf label} command to add a new label. However, this could
leave traces of the old volume in the catalog.
The preferable method to relabel a Volume is to first purge the volume,
either automatically, or explicitly with the \bcommand{purge}{} command,
then use the \bcommand{relabel}{} command described below.
If your autochanger has barcode labels, you can label all the Volumes in
your autochanger one after another by using the \bcommand{label}{barcodes}
command. For each tape in the changer containing a barcode, Bareos will
mount the tape and then label it with the same name as the barcode. An
appropriate Media record will also be created in the catalog. Any barcode
that begins with the same characters as specified on the
"CleaningPrefix=xxx" (default is "CLN") directive in the Director's Pool resource, will be
treated as a cleaning tape, and will not be labeled. However, an entry for
the cleaning tape will be created in the catalog. For example with:
\begin{bconfig}{Cleaning Tape}
Pool {
Name ...
Cleaning Prefix = "CLN"
}
\end{bconfig}
Any slot containing a barcode of CLNxxxx will be treated as a cleaning tape
and will not be mounted. Note, the full form of the command is:
\begin{bconsole}{label}
label storage=xxx pool=yyy slots=1-5,10 barcodes
\end{bconsole}
\item [list]
\index[general]{Console!Command!list}
The list command lists the requested contents of the Catalog. The
various fields of each record are listed on a single line. The various
forms of the list command are:
\begin{bconsole}{list}
list jobs
list jobid=<id> (list jobid id)
list ujobid=<unique job name> (list job with unique name)
list job=<job-name> (list all jobs with "job-name")
list jobname=<job-name> (same as above)
In the above, you can add "limit=nn" to limit the output to nn jobs.
list joblog jobid=<id> (list job output if recorded in the catalog)
list jobmedia
list jobmedia jobid=<id>
list jobmedia job=<job-name>
list files jobid=<id>
list files job=<job-name>
list pools
list clients
list jobtotals
list volumes
list volumes jobid=<id>
list volumes pool=<pool-name>
list volumes job=<job-name>
list volume=<volume-name>
list nextvolume job=<job-name>
list nextvol job=<job-name>
list nextvol job=<job-name> days=nnn
\end{bconsole}
What most of the above commands do should be more or less obvious. In
general if you do not specify all the command line arguments, the
command will prompt you for what is needed.
The \bcommand{list}{nextvol} command will print the Volume name to be used by
the specified job. You should be aware that exactly what Volume will be
used depends on a lot of factors including the time and what a prior job
will do. It may fill a tape that is not full when you issue this
command. As a consequence, this command will give you a good estimate
of what Volume will be used but not a definitive answer. In addition,
this command may have certain side effect because it runs through the
same algorithm as a job, which means it may automatically purge or
recycle a Volume. By default, the job specified must run within the
next two days or no volume will be found. You can, however, use the
{\bf days=nnn} specification to specify up to 50 days. For example,
if on Friday, you want to see what Volume will be needed on Monday,
for job MyJob, you would use \bcommand{list}{nextvol job=MyJob days=3}.
If you wish to add specialized commands that list the contents of the
catalog, you can do so by adding them to the \file{query.sql} file.
However, this takes some knowledge of programming SQL. Please see the
\bcommand{query}{} command below for additional information. See below for
listing the full contents of a catalog record with the \bcommand{llist}{}
command.
As an example, the command {\bf list pools} might produce the following
output:
\begin{bconsole}{list pools}
*<input>list pools</input>
+------+---------+---------+---------+----------+-------------+
| PoId | Name | NumVols | MaxVols | PoolType | LabelFormat |
+------+---------+---------+---------+----------+-------------+
| 1 | Default | 0 | 0 | Backup | * |
| 2 | Recycle | 0 | 8 | Backup | File |
+------+---------+---------+---------+----------+-------------+
\end{bconsole}
As mentioned above, the {\bf list} command lists what is in the
database. Some things are put into the database immediately when Bareos
starts up, but in general, most things are put in only when they are
first used, which is the case for a Client as with Job records, etc.
Bareos should create a client record in the database the first time you
run a job for that client. Doing a {\bf status} will not cause a
database record to be created. The client database record will be
created whether or not the job fails, but it must at least start. When
the Client is actually contacted, additional info from the client will
be added to the client record (a "uname -a" output).
If you want to see what Client resources you have available in your conf
file, you use the Console command {\bf show clients}.
\item [llist]
\index[general]{Console!Command!llist}
The llist or "long list" command takes all the same arguments that the
list command described above does. The difference is that the llist
command list the full contents of each database record selected. It
does so by listing the various fields of the record vertically, with one
field per line. It is possible to produce a very large number of output
lines with this command.
If instead of the {\bf list pools} as in the example above, you enter
{\bf llist pools} you might get the following output:
\begin{bconsole}{llist pools}
*<input>llist pools</input>
PoolId: 1
Name: Default
NumVols: 0
MaxVols: 0
UseOnce: 0
UseCatalog: 1
AcceptAnyVolume: 1
VolRetention: 1,296,000
VolUseDuration: 86,400
MaxVolJobs: 0
MaxVolBytes: 0
AutoPrune: 0
Recycle: 1
PoolType: Backup
LabelFormat: *
PoolId: 2
Name: Recycle
NumVols: 0
MaxVols: 8