From 62e3f2cfbe0e76eab03cf024c6fc8152ea41eb8d Mon Sep 17 00:00:00 2001 From: Joerg Steffens Date: Thu, 17 Nov 2016 17:07:55 +0100 Subject: [PATCH] added bconsole truncate command --- manuals/en/main/bconsole.tex | 106 +++++++++++------- manuals/en/main/dirdconf.tex | 59 ++++------ .../director-resource-job-definitions.tex | 22 ++-- .../director-resource-pool-definitions.tex | 22 ++-- 4 files changed, 109 insertions(+), 100 deletions(-) diff --git a/manuals/en/main/bconsole.tex b/manuals/en/main/bconsole.tex index 218b1d0..c6c32a4 100644 --- a/manuals/en/main/bconsole.tex +++ b/manuals/en/main/bconsole.tex @@ -1026,20 +1026,19 @@ \section{Console Commands} device. It is a way to tell Bareos that you have mounted a tape and that Bareos should examine the tape. This command is normally used only after there was no Volume in a drive and Bareos requests you to mount a new - Volume or when you have specifically unmounted a Volume with the {\bf - unmount} console command, which causes Bareos to close the drive. If + Volume or when you have specifically unmounted a Volume with the \bcommand{unmount}{} + console command, which causes Bareos to close the drive. If you have an autoloader, the mount command will not cause Bareos to operate the autoloader unless you specify a {\bf slot} and possibly a {\bf drive}. The various forms of the mount command are: \begin{bconsole}{mount} -mount storage= [slot=] [ - drive= ] +mount storage= [slot=] [drive=] mount [jobid= | job=] \end{bconsole} - If you have specified {\bf Automatic Mount = yes} in the Storage daemon's - Device resource, under most circumstances, Bareos will automatically access + If you have specified \linkResourceDirectiveValue{Sd}{Device}{Automatic Mount}{yes}, + under most circumstances, Bareos will automatically access the Volume unless you have explicitly \bcommand{unmount}{}ed it in the Console program. @@ -1074,45 +1073,46 @@ \section{Console Commands} records from specified Volumes. \begin{bconsole}{prune} -prune files|jobs|volume|stats client= volume= +prune files [client=] [pool=] [yes] | + jobs [client=] [pool=] [jobtype=] [yes] | + volume [=volume] [pool=] [yes] | + stats [yes] \end{bconsole} - For a Volume to be pruned, the {\bf VolStatus} must be Full, Used, or - Append, otherwise the pruning will not take place. + For a Volume to be pruned, the volume status must be \volumestatus{Full}, \volumestatus{Used} or + \volumestatus{Append} otherwise the pruning will not take place. \item [purge] \index[general]{Console!Command!purge} - The Purge command will delete associated Catalog database records from - Jobs and Volumes without considering the retention period. {\bf Purge} - works only on the Catalog database and does not affect data written to - Volumes. This command can be dangerous because you can delete catalog + \label{bcommandPurge} + The Purge command will delete associated catalog database records from + Jobs and Volumes without considering the retention period. + This command can be dangerous because you can delete catalog records associated with current backups of files, and we recommend that you do not use it unless you know what you are doing. The permitted - forms of {\bf purge} are: + forms of \bcommand{purge}{} are: \begin{bconsole}{purge} -purge files jobid=|job= | client= -purge jobs client= (of all jobs) -purge volume|volume= (of all jobs) +purge [files [job= | jobid= | client= | volume=]] | + [jobs [client= | volume=]] | + [volume [=] [storage=] [pool=] [devicetype=] [drive=] [action=]] | + [quota [client=]] \end{bconsole} -For the {\bf purge} command to work on Volume Catalog database records the -{\bf VolStatus} must be Append, Full, Used, or Error. +For the \bcommand{purge}{} command to work on volume catalog database records the +volume status must be \volumestatus{Append}, \volumestatus{Full}, \volumestatus{Used} or \volumestatus{Error}. The actual data written to the Volume will be unaffected by this command unless -you are using the \texttt{ActionOnPurge=Truncate} option on those Media. +you are using the \linkResourceDirectiveValue{Dir}{Pool}{Action On Purge}{Truncate} option. -To ask Bareos to truncate your \texttt{Purged} volumes, you need to use the -following command in interactive mode or in a RunScript: +To ask Bareos to truncate your \volumestatus{Purged} volumes, you need to use the +following command in interactive mode: \begin{bconsole}{purge example} -*purge volume action=truncate storage=File allpools -# or by default, action=all -*purge volume action storage=File pool=Default +*purge volume action=truncate storage=File pool=Full \end{bconsole} -It is possible to specify the volume name, the media type, the pool, the -storage, etc\dots (see \bcommand{help}{purge}). -Be sure that your storage device is idle when you decide to run this command. +However, normally you should use the \bcommand{purge}{} command only to purge a volume from the catalog +and use the \bcommand{truncate}{} command to truncate the volume on the \bareosSd. \item [resolve] \index[general]{Console!Command!resolve} @@ -1120,7 +1120,7 @@ \section{Console Commands} As the different components of Bareos will establish network connections to other Bareos components, it is important that DNS name resolution works on involved components and delivers the same results. The \bcommand{resolve}{} command can be used to test DNS resolution of a given hostname - on director, storage daemonm or client. + on director, storage daemon or client. \begin{bconsole}{resolve example} *resolve www.bareos.com @@ -1158,14 +1158,14 @@ \section{Console Commands} The full form of this command is: \begin{bconsole}{relabel} -relabel storage= oldvolume= volume=} +relabel storage= oldvolume= volume= pool= [encrypt] \end{bconsole} If you leave out any part, you will be prompted for it. In order for the Volume (old-volume-name) to be relabeled, it must be in the catalog, - and the volume status must be marked {\bf Purged} or {\bf Recycle}. - This happens automatically as a result of applying retention periods, or - you may explicitly purge the volume using the {\bf purge} command. + and the volume status must be marked \volumestatus{Purged} or \volumestatus{Recycle}. + This happens automatically as a result of applying retention periods or + you may explicitly purge the volume using the \bcommand{purge}{} command. Once the volume is physically relabeled, the old data previously written on the Volume is lost and cannot be recovered. @@ -1181,12 +1181,12 @@ \section{Console Commands} \end{bconsole} After a release command, the device is still kept open by Bareos (unless - \linkResourceDirective{Sd}{Device}{Always Open}=No) so it + \linkResourceDirectiveValue{Sd}{Device}{Always Open}{no}) so it cannot be used by another program. However, with some tape drives, the operator can remove the current tape and to insert a different one, and when the next Job starts, Bareos will know to re-read the tape label to find out what tape is mounted. If you want to be able to use the drive - with another program (e.g. \command{mt}), you must use the \bcommand{unmount} + with another program (e.g. \command{mt}), you must use the \bcommand{unmount}{} command to cause Bareos to completely release (close) the device. \item [reload] @@ -1571,7 +1571,7 @@ \section{Console Commands} ==== \end{bconsole} -\bcommand{status scheduler}{} accepts the following parameters: +\bcommand{status}{scheduler} accepts the following parameters: \begin{description} \item[client=clientname] shows only the schedules that affect the given client. \item[job=jobname] shows only the schedules that affect the given job. @@ -1580,13 +1580,11 @@ \section{Console Commands} \end{description} In case you are running a maintained version of Bareos, -the command \bcommand{status subscriptions}{} (\sinceVersion{console}{status subscriptions}{12.4.4}) can help you to keep the overview over the subscriptions +the command \bcommand{status}{subscriptions} (\sinceVersion{console}{status subscriptions}{12.4.4}) can help you to keep the overview over the subscriptions that are used. -To enable this functionality, just add the configuration directive subscriptions to the director configuration in the director resource: - -The number of subscribed clients can be set in -the director resource, for example: +To enable this functionality, just add the configuration \linkResourceDirective{Dir}{Director}{Subscriptions} directive +and specify the number of subscribed clients, for example: \begin{bconfig}{enable subscription check} Director { ... @@ -1594,7 +1592,7 @@ \section{Console Commands} } \end{bconfig} -Using the console command \bcommand{status subscriptions}{}, the status of +Using the console command \bcommand{status}{subscriptions}, the status of the subscriptions can be checked any time interactively: \begin{bconsole}{status subscriptions} @@ -1612,7 +1610,7 @@ \section{Console Commands} Please note: Nothing else than the warning is issued, no enforcement on backup, restore or any other operation will happen. -Setting the value for \configdirective{Subscriptions} to 0 disables this functionality: +Setting the value for \linkResourceDirectiveValue{Dir}{Director}{Subscriptions}{0} disables this functionality: \begin{bconfig}{disable subscription check} Director { ... @@ -1630,6 +1628,28 @@ \section{Console Commands} \index[general]{Console!Command!trace} Turn on/off trace to file. +\item [truncate] + \index[general]{Console!Command!truncate} + \index[general]{Disk!Freeing disk space} + \index[sd]{Disk!Freeing disk space} + \label{bcommandTruncate} + + If the status of a volume is \volumestatus{Purged}, + it normally still contains data, even so it can not easily be accessed. + +\begin{bconsole}{truncate} +truncate volstatus=Purged [storage=] [pool=] [volume=] [yes] +\end{bconsole} + + + When using a disk volume (and other volume types also) the volume file still resides on the \bareosSd. + If you want to reclaim disk space, you can use the \bcommand{truncate}{volstatus=Purged} command. + When used on a volume, it rewrites the header and by this frees the rest of the disk space. + + If the volume you want to get rid of has not the \volumestatus{Purged} status, + you first have to use the \bcommand{prune}{volume} or even the \bcommand{purge}{volume} command + to free the volume from all remaining jobs. + \item [umount] \index[general]{Console!Command!umount} Alias for \bcommand{unmount}{}. diff --git a/manuals/en/main/dirdconf.tex b/manuals/en/main/dirdconf.tex index 07dacc2..fcabe89 100644 --- a/manuals/en/main/dirdconf.tex +++ b/manuals/en/main/dirdconf.tex @@ -419,78 +419,61 @@ \section{Pool Resource} (Maximum Jobs, Retention Period, Recycle flag, ...) that will be given to a Volume when it is created. This avoids the need for you to answer a large number of questions when labeling a new Volume. Each of these attributes can -later be changed on a Volume by Volume basis using the {\bf update} command in +later be changed on a Volume by Volume basis using the \bcommand{update}{} command in the console program. Note that you must explicitly specify which Pool Bareos is to use with each Job. Bareos will not automatically search for the correct Pool. -Most often in Bareos installations all backups for all machines (Clients) go -to a single set of Volumes. In this case, you will probably only use the {\bf -Default} Pool. If your backup strategy calls for you to mount a different tape -each day, you will probably want to define a separate Pool for each day. For -more information on this subject, please see the -\ilink{Backup Strategies}{StrategiesChapter} chapter of this -manual. - To use a Pool, there are three distinct steps. First the Pool must be defined -in the Director's configuration file. Then the Pool must be written to the +in the Director's configuration. Then the Pool must be written to the Catalog database. This is done automatically by the Director each time that it -starts, or alternatively can be done using the {\bf create} command in the -console program. Finally, if you change the Pool definition in the Director's +starts. Finally, if you change the Pool definition in the Director's configuration file and restart Bareos, the pool will be updated alternatively -you can use the {\bf update pool} console command to refresh the database +you can use the \bcommand{update}{pool} console command to refresh the database image. It is this database image rather than the Director's resource image that is used for the default Volume attributes. Note, for the pool to be automatically created or updated, it must be explicitly referenced by a Job resource. -Next the physical media must be labeled. The labeling can either be done with -the {\bf label} command in the {\bf console} program or using the {\bf btape} -program. The preferred method is to use the {\bf label} command in the {\bf -console} program. +If automatic labeling is not enabled (see \nameref{AutomaticLabeling}) +the physical media must be manually labeled. +The labeling can either be done with +the \bcommand{label}{} command in the console program or using the \command{btape} +program. The preferred method is to use the \bcommand{label}{} command in the console program. +Generally, automatic labeling is enabled for \linkResourceDirectiveValue{Sd}{Device}{Device Type}{File} +and disabled for \linkResourceDirectiveValue{Sd}{Device}{Device Type}{Tape}. Finally, you must add Volume names (and their attributes) to the Pool. For -Volumes to be used by Bareos they must be of the same {\bf Media Type} as the +Volumes to be used by Bareos they must be of the same \linkResourceDirective{Sd}{Device}{Media Type} as the archive device specified for the job (i.e. if you are going to back up to a DLT device, the Pool must have DLT volumes defined since 8mm volumes cannot be -mounted on a DLT drive). The {\bf Media Type} has particular importance if you +mounted on a DLT drive). The \linkResourceDirective*{Sd}{Device}{Media Type} has particular importance if you are backing up to files. When running a Job, you must explicitly specify which Pool to use. Bareos will then automatically select the next Volume to use from -the Pool, but it will ensure that the {\bf Media Type} of any Volume selected +the Pool, but it will ensure that the \linkResourceDirective*{Sd}{Device}{Media Type} of any Volume selected from the Pool is identical to that required by the Storage resource you have specified for the Job. -If you use the {\bf label} command in the console program to label the +If you use the \bcommand{label}{} command in the console program to label the Volumes, they will automatically be added to the Pool, so this last step is not normally required. It is also possible to add Volumes to the database without explicitly labeling -the physical volume. This is done with the {\bf add} console command. +the physical volume. This is done with the \bcommand{add}{} console command. As previously mentioned, each time Bareos starts, it scans all the Pools associated with each Catalog, and if the database record does not already -exist, it will be created from the Pool Resource definition. {\bf Bareos} -probably should do an {\bf update pool} if you change the Pool definition, but -currently, you must do this manually using the {\bf update pool} command in -the Console program. +exist, it will be created from the Pool Resource definition. +If you change the Pool definition, you manually have to call \bcommand{update}{pool} command in +the console program to propagate the changes to existing volumes. -The Pool Resource defined in the Director's configuration file -(\file{bareos-dir.conf}) may contain the following directives: +The Pool Resource defined in the Director's configuration +may contain the following directives: \input{autogenerated/bareos-dir-resource-pool-table.tex} \input{director-resource-pool-definitions.tex} \input{autogenerated/bareos-dir-resource-pool-description.tex} -In order for a Pool to be used during a Backup Job, the Pool must have at -least one Volume associated with it. Volumes are created for a Pool using -the {\bf label} or the {\bf add} commands in the {\bf Bareos Console}, -program. In addition to adding Volumes to the Pool (i.e. putting the -Volume names in the Catalog database), the physical Volume must be labeled -with a valid Bareos software volume label before {\bf Bareos} will accept -the Volume. This will be automatically done if you use the {\bf label} -command. Bareos can automatically label Volumes if instructed to do so, -but this feature is not yet fully implemented. - The following is an example of a valid Pool resource definition: \begin{bconfig}{Pool resource example} diff --git a/manuals/en/main/director-resource-job-definitions.tex b/manuals/en/main/director-resource-job-definitions.tex index c1886bb..71d10a7 100644 --- a/manuals/en/main/director-resource-job-definitions.tex +++ b/manuals/en/main/director-resource-job-definitions.tex @@ -785,24 +785,24 @@ \defDirective{Dir}{Job}{Prune Files}{}{}{% Normally, pruning of Files from the Catalog is specified on a Client by -Client basis in the Client resource with the {\bf AutoPrune} directive. -If this directive is specified (not normally) and the value is {\bf -yes}, it will override the value specified in the Client resource. +Client basis in \linkResourceDirective{Dir}{Client}{Auto Prune}. +If this directive is specified and the value is \argument{yes}, +it will override the value specified in the Client resource. } \defDirective{Dir}{Job}{Prune Jobs}{}{}{% Normally, pruning of Jobs from the Catalog is specified on a Client by -Client basis in the Client resource with the {\bf AutoPrune} directive. -If this directive is specified (not normally) and the value is {\bf -yes}, it will override the value specified in the Client resource. +Client basis in \linkResourceDirective{Dir}{Client}{Auto Prune}. +If this directive is specified and the value is \argument{yes}, +it will override the value specified in the Client resource. } \defDirective{Dir}{Job}{Prune Volumes}{}{}{% Normally, pruning of Volumes from the Catalog is specified on a Pool by -Pool basis in the Pool resource with the {\bf AutoPrune} directive. +Pool basis in \linkResourceDirective{Dir}{Pool}{Auto Prune} directive. Note, this is different from File and Job pruning which is done on a -Client by Client basis. If this directive is specified (not normally) -and the value is {\bf yes}, it will override the value specified in the +Client by Client basis. If this directive is specified +and the value is \argument{yes}, it will override the value specified in the Pool resource. } @@ -982,7 +982,7 @@ program is executed on the Client side like in \texttt{ClientRunXXXJob}. \textbf{Console} options are special commands that are sent to the director instead -of the OS. At this time, console command ouputs are redirected to log with +of the OS. At this time, console command outputs are redirected to log with the jobid 0. You can use following console command: \texttt{delete}, \texttt{disable}, @@ -990,7 +990,7 @@ \texttt{memory}, \texttt{prune}, \texttt{purge}, \texttt{reload}, \texttt{status}, \texttt{setdebug}, \texttt{show}, \texttt{time}, \texttt{trace}, \texttt{update}, \texttt{version}, \texttt{.client}, -\texttt{.jobs}, \texttt{.pool}, \texttt{.storage}. +\texttt{.jobs}, \texttt{.pool}, \texttt{.storage}. See \nameref{sec:bconsole} for more information. You need to specify needed information on command line, nothing will be prompted. Example: diff --git a/manuals/en/main/director-resource-pool-definitions.tex b/manuals/en/main/director-resource-pool-definitions.tex index 59c9db4..676b60b 100644 --- a/manuals/en/main/director-resource-pool-definitions.tex +++ b/manuals/en/main/director-resource-pool-definitions.tex @@ -1,16 +1,22 @@ \defDirective{Dir}{Pool}{Action On Purge}{}{}{% -This directive \configline{Action On Purge=Truncate} instructs Bareos to truncate the +% DEPRECATED: +% because it does not do what is expected by the name. +% Is only has an influence, +% when using the command "purge volume action=truncate" +% but did do nothing automatically. + +The directive \configline{Action On Purge=Truncate} instructs Bareos to truncate the volume when it is purged with the \bcommand{purge}{volume action=truncate} command. It is useful to prevent disk based volumes from consuming too much space. -\bconfigInput{config/DirPoolActionOnPurge1.conf} - - -You can schedule the truncate operation at the end of your \job{BackupCatalog} job -like in this example: - -\bconfigInput{config/DirPoolActionOnPurge2.conf} +% \bconfigInput{config/DirPoolActionOnPurge1.conf} +% +% THIS DOES NOT WORK: +% You can schedule the truncate operation at the end of your \job{BackupCatalog} job +% like in this example: +% +% \bconfigInput{config/DirPoolActionOnPurge2.conf} } \defDirective{Dir}{Pool}{Auto Prune}{}{}{%