added bconsole truncate command

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=<storage-name> [slot=<num>] [
-       drive=<num> ]
+mount storage=<storage-name> [slot=<num>] [drive=<num>]
 mount [jobid=<id> | job=<job-name>]
 \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,53 +1073,54 @@ \section{Console Commands}
    records from specified Volumes.
 
 \begin{bconsole}{prune}
-prune files|jobs|volume|stats client=<client-name> volume=<volume-name>
+prune files [client=<client>] [pool=<pool>] [yes] |
+      jobs [client=<client>] [pool=<pool>] [jobtype=<jobtype>] [yes] |
+      volume [=volume] [pool=<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=<jobid>|job=<job-name> | client=<client-name>
-purge jobs client=<client-name> (of all jobs)
-purge volume|volume=<vol-name> (of all jobs)
+purge [files [job=<job> | jobid=<jobid> | client=<client> | volume=<volume>]] |
+      [jobs [client=<client> | volume=<volume>]] |
+      [volume [=<volume>] [storage=<storage>] [pool=<pool>] [devicetype=<type>] [drive=<drivenum>] [action=<action>]] |
+      [quota [client=<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}
-*<input>purge volume action=truncate storage=File allpools</input>
-# or by default, action=all
-*<input>purge volume action storage=File pool=Default</input>
+*<input>purge volume action=truncate storage=File pool=Full</input>
 \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}
     In the configuration files, Addresses can (and normally should) be specified as DNS names.
     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}
 *<input>resolve www.bareos.com</input>
@@ -1158,14 +1158,14 @@ \section{Console Commands}
    The full form of this command is:
 
 \begin{bconsole}{relabel}
-relabel storage=<storage-name> oldvolume=<old-volume-name> volume=<newvolume-name>}
+relabel storage=<storage-name> oldvolume=<old-volume-name> volume=<new-volume-name> pool=<pool-name> [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,21 +1580,19 @@ \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 {
    ...
    Subscriptions = 50
 }
 \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=<storage>] [pool=<pool>] [volume=<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}{}.

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}

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,15 +982,15 @@
 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},
 \texttt{enable}, \texttt{estimate}, \texttt{list}, \texttt{llist},
 \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: