Job resource

Configuration directives for the Job resource. Every directive is listed; value types and defaults are noted where the source provides them.

Add Prefix

Add Prefix = <directory>

This directive applies only to a Restore job and specifies a prefix to the directory name of all files being restored. This will use File Relocation feature implemented in NGBackup 2.1.8 or later.

Add Suffix

Add Suffix = <extention>

This directive applies only to a Restore job and specifies a suffix to all files being restored. This will use File Relocation feature implemented in NGBackup 2.1.8 or later. Using Add Suffix=.old, /etc/passwd will be restored to /etc/passwsd.old

Allow Duplicate Jobs

Allow Duplicate Jobs = <yes|no>

A duplicate job in the sense we use it here means a second or subsequent job with the same name starts. This happens most frequently when the first job runs longer than expected because no tapes are available. The default is yes. Allow Duplicate Jobs usage

If this directive is enabled duplicate jobs will be run. If the directive is set to no then only one job of a given name may run at one time, and the action that NGBackup takes to ensure only one job runs is determined by the other directives (see below).

If Allow Duplicate Jobs is set to no and two jobs are present and none of the three directives given below permit cancelling a job, then the current job (the second one started) will be cancelled.

Allow Higher Duplicates

Allow Higher Duplicates = <yes|no>

This directive was implemented in version 5.0.0, but does not work as expected. If used, it should always be set to no. In later versions of NGBackup the directive is disabled (disregarded).

Allow Incomplete Jobs

Allow Incomplete Jobs = <yes|no>

If this directive is disabled, and the job terminates in incomplete status, the data of the job will be discarded and the job will be marked in error. NGBackup will treat this job like a regular job in error. The default is yes.

Allow Mixed Priority

Allow Mixed Priority = <yes|no>

This directive is only implemented in version 2.5 and later. When set to yes (default no), this job may run even if lower priority jobs are already running. This means a high priority job will not have to wait for other jobs to finish before starting. The scheduler will only mix priorities when all running jobs have this set to true. Note that only higher priority jobs will start early. Suppose the director will allow two concurrent jobs, and that two jobs with priority 10 are running, with two more in the queue. If a job with priority 5 is added to the queue, it will be run as soon as one of the running jobs finishes. However, new priority 10 jobs will not be run until the priority 5 job has finished.

BackupsToKeep

BackupsToKeep = <number>

When this directive is present during a Virtual Full (it is ignored for other Job types), it will look for a Full backup that has more subsequent backups than the value specified. In the example below, the Job will simply terminate unless there is a Full back followed by at least 31 backups of either level Differential or Incremental.

`

Job { Name = “VFull” Type = Backup Level = VirtualFull Client = “my-fd” File Set = “FullSet” Accurate = Yes Backups To Keep = 30 }

`

Assuming that the last Full backup is followed by 32 Incremental backups, a Virtual Full will be run that consolidates the Full with the first two Incrementals that were run after the Full. The result is that you will end up with a Full followed by 30 Incremental backups.

Base

Base = <job-resource-name, ...>

The Base directive permits to specify the list of jobs that will be used during Full backup as base. This directive is optional. See the Base Job chapter for more information.

Bootstrap

Bootstrap = <bootstrap-file>

The Bootstrap directive specifies a bootstrap file that, if provided, will be used during Restore Jobs and is ignored in other Job types. The <bootstrap-file> contains the list of tapes to be used in a Restore Job as well as which files are to be restored. Specification of this directive is optional, and if specified, it is used only for a restore job. In addition, when running a Restore job from the console, this value can be changed. If you use the restore command in the backup-console program, to start a Restore job, the <bootstrap-file> will be created automatically from the files you select to be restored.

For additional details of the bootstrap directive, please see Restoring Files with the Bootstrap File chapter of this manual.

Cancel Lower Level Duplicates

Cancel Lower Level Duplicates = <yes|no>

If Allow Duplicate Jobs is set to no and this directive is set to yes, NGBackup will choose between duplicated jobs the one with the highest level. For example, it will cancel a previous Incremental to run a Full backup. It works only for Backup jobs. The default is no. If the levels of the duplicated jobs are the same, nothing is done and the other Cancel XXX Duplicate directives will be examined.

Cancel Queued Duplicates

Cancel Queued Duplicates = <yes|no>

If Allow Duplicate Jobs is set to no and if this directive is set to yes any job that is already queued to run but not yet running will be canceled. The default is no.

Cancel Running Duplicates

Cancel Running Duplicates = <yes|no>

If Allow Duplicate Jobs is set to no and if this directive is set to yes any job that is already running will be canceled. The default is no.

Client

Client = <client-resource-name>

The Client directive specifies the Client (File daemon) that will be used in the current Job. Only a single Client may be specified in any one Job. The Client runs on the machine to be backed up, and sends the requested files to the Storage daemon for backup, or receives them when restoring. For additional details, see the Client Resource section of this chapter. This directive is required.

Client Run After Job

Client Run After Job = <Command>

The specified <Command> is run on the client machine as soon as data spooling is complete in order to allow restarting applications on the client as soon as possible. ClientRunBeforeJob can be used with Backup and Restore jobs. Note, please see the notes above in RunScript concerning Windows clients.

Client Run Before Job

Client Run Before Job = <Command>

This directive is the same as Run Before Job except that the program is run on the client machine. The same restrictions apply to Unix systems as noted above for the RunScript. ClientRunBeforeJob can be used with Backup and Restore jobs.

DeleteConsolidatedJobs

DeleteConsolidatedJobs = <yes/no>

If set to yes, it will cause any old Job that is consolidated during a Virtual Full to be deleted. In the example above we saw that a Full plus one other job (either an Incremental or Differential) were consolidated into a new Full backup. The original Full plus the other Job consolidated will be deleted. The default value is no.

Differential Backup Pool

Differential Backup Pool = <pool-resource-name>

The Differential Backup Pool specifies a Pool to be used for Differential backups. It will override any Pool specification during a Differential backup. This directive is optional.

Differential Max Run Time

Differential Max Run Time = <time>

The time specifies the maximum allowed time that a Differential backup job may run, counted from when the job starts, (not necessarily the same as when the job was scheduled).

Enabled

Enabled = <yes|no>

This directive allows you to enable or disable a Job resource. When the resource of the Job is disabled, the Job will no longer be scheduled and it will not be available in the list of Jobs to be run. To be able to use the Job you must enable it.

FileSet

FileSet = <FileSet-resource-name>

The FileSet directive specifies the FileSet that will be used in the current Job. The FileSet specifies which directories (or files) are to be backed up, and what options to use (e.g. compression, …). Only a single FileSet resource may be specified in any one Job. For additional details, see the FileSet Resource section of this chapter. This directive is required.

Full Backup Pool

Full Backup Pool = <pool-resource-name>

The Full Backup Pool specifies a Pool to be used for Full backups. It will override any Pool specification during a Full backup. This directive is optional.

Incremental Backup Pool

Incremental Backup Pool = <pool-resource-name>

The Incremental Backup Pool specifies a Pool to be used for Incremental backups. It will override any Pool specification during an Incremental backup. This directive is optional.

Incremental Max Run Time

Incremental Max Run Time = <time>

The time specifies the maximum allowed time that an Incremental backup job may run, counted from when the job starts, (not necessarily the same as when the job was scheduled).

Incremental|Differential Max Wait Time

Incremental|Differential Max Wait Time = <time>

Theses directives have been deprecated in favor of Incremental|Differential Max Run Time since bacula 2.3.18.

Job

Start of the Job resource. At least one Job resource is required.

JobDefs

JobDefs = <JobDefs-Resource-Name>

If a <JobDefs-Resource-Name> is specified, all the values contained in the named JobDefs resource will be used as the defaults for the current Job. Any value that you explicitly define in the current Job resource, will override any defaults specified in the JobDefs resource. The use of this directive permits writing much more compact Job resources where the bulk of the directives are defined in one or more JobDefs. This is particularly useful if you have many similar Jobs but with minor variations such as different Clients. A simple example of the use of JobDefs is provided in the default backup-dir.conf file.

Max Full Interval

Max Full Interval = <time>

The time specifies the maximum allowed age (counting from start time) of the most recent successful Full backup that is required in order to run Incremental or Differential backup jobs. If the most recent Full backup is older than this interval, Incremental and Differential backups will be upgraded to Full backups automatically. If this directive is not present, or specified as 0, then the age of the previous Full backup is not considered.

Max Run Sched Time

Max Run Sched Time = <time>

The time specifies the maximum allowed time that a job may run, counted from when the job was scheduled. This can be useful to prevent jobs from running during working hours. We can see it like Max Start Delay + Max Run Time.

Max Run Time

Max Run Time = <time>

The time specifies the maximum allowed time that a job may run, counted from when the job starts, (not necessarily the same as when the job was scheduled). By default, the the watchdog thread will kill any Job that has run more than 200 days. The maximum watchdog timeout is independent of MaxRunTime and cannot be changed.

Max Start Delay

Max Start Delay = <time>

The time specifies the maximum delay between the scheduled time and the actual start time for the Job. For example, a job can be scheduled to run at 1:00am, but because other jobs are running, it may wait to run. If the delay is set to 3600 (one hour) and the job has not begun to run by 2:00am, the job will be canceled. This can be useful, for example, to prevent jobs from running during day time hours. The default is 0 which indicates no limit.

Max VirtualFull Interval

Max VirtualFull Interval = <time>

The time specifies the maximum allowed age (counting from start time) of the most recent successful Full backup that is required in order to run Incremental, Differential or Full backup jobs. If the most recent Full backup is older than this interval, Incremental, Differential and Full backups will be converted to a VirtualFull backup automatically. If this directive is not present, or specified as 0, then the age of the previous Full backup is not considered.

Please note that a VirtualFull job is not a real backup job. A VirtualFull will merge exiting jobs to create a new virtual Full job in the catalog and will copy the exiting data to new volumes.

The Client is not used in a VirtualFull job, so when using this directive, the Job that was supposed to run and save recently modified data on the Client will not run. Only the next regular Job defined in the Schedule will backup the data. It will not be possible to restore the data that was modified on the Client between the last Incremental/Differential and the VirtualFull.

Max Wait Time

Max Wait Time = <time>

The time specifies the maximum allowed time that a job may block waiting for a resource (such as waiting for a tape to be mounted, or waiting for the storage or file daemons to perform their duties), counted from the when the job starts, (not necessarily the same as when the job was scheduled). This directive works as expected since bacula 2.3.18. Job time control directives

Maximum Bandwidth

Maximum Bandwidth = <speed>

The speed parameter specifies the maximum allowed bandwidth in bytes that a job may use. You may specify the following speed parameter modifiers: kb/s (1,000 bytes per second), k/s (1,024 bytes per second), mb/s (1,000,000 bytes per second), or m/s (1,048,576 bytes per second).

The use of TLS, TLS PSK, CommLine compression and Deduplication can interfer with the value set with the Directive.

Maximum Concurrent Jobs

Maximum Concurrent Jobs = <number>

where <number> is the maximum number of Jobs from the current Job resource that can run concurrently. Note, this directive limits only Jobs with the same name as the resource in which it appears. Any other restrictions on the maximum concurrent jobs such as in the Director, Client, or Storage resources will also apply in addition to the limit specified here. The default is set to 1, but you may set it to a larger number. We strongly recommend that you read the WARNING documented under Maximum Concurrent Jobs in the Director’s resource.

Maximum Spawned Jobs

Maximum Spawned Jobs = <nb>

The Job resource now permits specifying a number of Maximum Spawn Jobs. The default is 600. This directive can be useful if you have big hardware and you do a lot of Migration/Copy jobs which start at the same time.

Messages

Messages = <messages-resource-name>

The Messages directive defines what Messages resource should be used for this job, and thus how and where the various messages are to be delivered. For example, you can direct some messages to a log file, and others can be sent by email. For additional details, see the Messages Resource Chapter of this manual. This directive is required.

Name

Name = <name>

The Job name. This name can be specified on the run command in the console program to start a job. If the name contains spaces, it must be specified between quotes. It is generally a good idea to give your job the same name as the Client that it will backup. This permits easy identification of jobs. When the job actually runs, the unique Job Name will consist of the name you specify here followed by the date and time the job was scheduled for execution. This directive is required.

Pool

Pool = <pool-resource-name>

The Pool directive defines the pool of Volumes where your data can be backed up. Many NGBackup installations will use only the Default pool. However, if you want to specify a different set of Volumes for different Clients or different Jobs, you will probably want to use Pools. For additional details, see the Pool Resource section of this chapter. This directive is required.

Prefer Mounted Volumes

Prefer Mounted Volumes = <yes|no>

If the Prefer Mounted Volumes directive is set to yes (default yes), the Storage daemon is requested to select either an Autochanger or a drive with a valid Volume already mounted in preference to a drive that is not ready. This means that all jobs will attempt to append to the same Volume (providing the Volume is appropriate - right Pool, … for that job), unless you are using multiple pools. If no drive with a suitable Volume is available, it will select the first available drive. Note, any Volume that has been requested to be mounted, will be considered valid as a mounted volume by another job. This if multiple jobs start at the same time and they all prefer mounted volumes, the first job will request the mount, and the other jobs will use the same volume. If the directive is set to no, the Storage daemon will prefer finding an unused drive, otherwise, each job started will append to the same Volume (assuming the Pool is the same for all jobs). Setting Prefer Mounted Volumes to no can be useful for those sites with multiple drive autochangers that prefer to maximize backup throughput at the expense of using additional drives and Volumes. This means that the job will prefer to use an unused drive rather than use a drive that is already in use.

Despite the above, we recommend against setting this directive to no since it tends to add a lot of swapping of Volumes between the different drives and can easily lead to deadlock situations in the Storage daemon. We will accept bug reports against it, but we cannot guarantee that we will be able to fix the problem in a reasonable time.

A better alternative for using multiple drives is to use multiple pools so that NGBackup will be forced to mount Volumes from those Pools on different drives.

Priority

Priority = <number>

This directive permits you to control the order in which your jobs will be run by specifying a positive non-zero number. The higher the number, the lower the job priority. Assuming you are not running concurrent jobs, all queued jobs of priority 1 will run before queued jobs of priority 2 and so on, regardless of the original scheduling order. The priority only affects waiting jobs that are queued to run, not jobs that are already running. If one or more jobs of priority 2 are already running, and a new job is scheduled with priority 1, the currently running priority 2 jobs must complete before the priority 1 job is run, unless Allow Mixed Priority is set.

The default priority is 10.

If you want to run concurrent jobs you should keep these points in mind:

• See Running Concurrent Jobs section on how to setup concurrent jobs in the NGBackup Problems Resolution guide.

• NGBackup concurrently runs jobs of only one priority at a time. It will not simultaneously run a priority 1 and a priority 2 job.

• If NGBackup is running a priority 2 job and a new priority 1 job is scheduled, it will wait until the running priority 2 job terminates even if the Maximum Concurrent Jobs settings would otherwise allow two jobs to run simultaneously.

• Suppose that bacula is running a priority 2 job and a new priority 1 job is scheduled and queued waiting for the running priority 2 job to terminate. If you then start a second priority 2 job, the waiting priority 1 job will prevent the new priority 2 job from running concurrently with the running priority 2 job. That is: as long as there is a higher priority job waiting to run, no new lower priority jobs will start even if the Maximum Concurrent Jobs settings would normally allow them to run. This ensures that higher priority jobs will be run as soon as possible.

If you have several jobs of different priority, it may not best to start them at exactly the same time, because NGBackup must examine them one at a time. If by NGBackup starts a lower priority job first, then it will run before your high priority jobs. If you experience this problem, you may avoid it by starting any higher priority jobs a few seconds before lower priority ones. This insures that NGBackup will examine the jobs in the correct order, and that your priority scheme will be respected.

Prune Files

Prune Files = <yes|no>

Normally, pruning of Files from the Catalog is specified on a Client by Client basis in the Client resource with the AutoPrune directive. If this directive is specified (not normally) and the value is yes, it will override the value specified in the Client resource. The default is no.

Prune Jobs

Prune Jobs = <yes|no>

Normally, pruning of Jobs from the Catalog is specified on a Client by Client basis in the Client resource with the AutoPrune directive. If this directive is specified (not normally) and the value is yes, it will override the value specified in the Client resource. The default is no.

Prune Volumes

Prune Volumes = <yes|no>

Normally, pruning of Volumes from the Catalog is specified on a Pool by Pool basis in the Pool resource with the AutoPrune 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 yes, it will override the value specified in the Pool resource. The default is no.

RegexWhere

RegexWhere = <expressions>

This directive applies only to a Restore job and specifies a regex filename manipulation of all files being restored. This will use File Relocation feature implemented in NGBackup 2.1.8 or later. For more informations about how use this option, see this.

Replace

Replace = <replace-option>

This directive applies only to a Restore job and specifies what happens when NGBackup wants to restore a file or directory that already exists. You have the following options for <replace-option>:

Rerun Failed Levels

Rerun Failed Levels = <yes|no>

If this directive is set to yes (default no), and NGBackup detects that a previous job at a higher level (i.e. Full or Differential) has failed, the current job level will be upgraded to the higher level. This is particularly useful for Laptops where they may often be unreachable, and if a prior Full save has failed, you wish the very next backup to be a Full save rather than whatever level it is started as. There are several points that must be taken into account when using this directive: first, a failed job is defined as one that has not terminated normally, which includes any running job of the same name (you need to ensure that two jobs of the same name do not run simultaneously); secondly, the Ignore FileSet Changes directive is not considered when checking for failed levels, which means that any FileSet change will trigger a rerun.

Reschedule Incomplete Jobs

Reschedule Incomplete Jobs = <yes|no>

If this directive is enabled, and the job terminates in incomplete status, the job will be rescheduled as determined by the Reschedule Interval and Reschedule Times directives. If you cancel the job, it will not be rescheduled. The default is yes (i.e. Incomplete jobs will be rescheduled).

Reschedule Interval

Reschedule Interval = <time-specification>

If you have specified Reschedule On Error = yes and the job terminates in error, it will be rescheduled after the interval of time specified by <time-specification>. See the time specification formats in the Configure chapter for details of time specifications. If no interval is specified, the job will not be rescheduled on error. The default Reschedule Interval is 30 minutes (1800 seconds).

Reschedule On Error

Reschedule On Error = <yes|no>

If this directive is enabled, and the job terminates in error, the job will be rescheduled as determined by the Reschedule Interval and Reschedule Times directives. If you cancel the job, it will not be rescheduled. The default is no (i.e. the job will not be rescheduled). This specification can be useful for portables, laptops, or other machines that are not always connected to the network or switched on.

Reschedule Times

Reschedule Times = <count>

This directive specifies the maximum number of times to reschedule the job. If it is set to zero (0, the default) the job will be rescheduled an indefinite number of times.

RestoreClient

RestoreClient = <client-resource-name>

The RestoreClient directive specifies the default Client (File Daemon) that will be used with the restore job. If this directive is not set then a default restore client will be set to a backup client as usual. It is possible to define a dedicated restore job and run an automatic (scheduled) restore tests of your backups which will be redirected to the restore test Client.

always when the file to be restored already exists, it is deleted and then replaced by the copy that was backed up. This is the default value.

Run

Run = <job-name>

The Run directive (not to be confused with the Run option in a Schedule) allows you to start other jobs or to clone jobs. By using the cloning keywords (see below), you can backup the same data (or almost the same data) to two or more drives at the same time. The <job-name> is normally the same name as the current Job resource (thus creating a clone). However, it may be any Job name, so one job may start other related jobs. The part after the equal sign must be enclosed in double quotes, and can contain any string or set of options (overrides) that you can specify when entering the run command from the console. For example storage=DDS-4 … In addition, there are two special keywords that permit you to clone the current job. They are level=%l and since=%s. The %l in the level keyword permits entering the actual level of the current job and the %s in the since keyword permits putting the same time for comparison as used on the current job. Note, in the case of the since keyword, the %s must be enclosed in double quotes, and thus they must be preceded by a backslash since they are already inside quotes. For example:

`

run = “Nightly-backup level=%l since=“%s” storage=DDS-4”

`

A cloned job will not start additional clones, so it is not possible to recurse.

Please note that all cloned jobs, as specified in the Run directives are submitted for running before the original job is run (while it is being initialized). This means that any clone job will actually start before the original job, and may even block the original job from starting until the original job finishes unless you allow multiple simultaneous jobs. Even if you set a lower priority on the clone job, if no other jobs are running, it will start before the original job.

If you are trying to prioritize jobs by using the clone feature (Run directive), you will find it much easier to do using a RunScript resource, or a RunBeforeJob directive.

Run After Failed Job

Run After Failed Job = <Command>

The specified <Command> is run as an external program after the current job terminates with any error status. This directive is not required. The command string must be a valid program name or name of a shell script. If the exit code of the program run is non-zero, NGBackup will print a warning message. Before submitting the specified command to the operating system, NGBackup performs character substitution as described above for the RunScript directive. Note, if you wish that your script will run regardless of the exit status of the Job, you can use this :

`

RunScript { Command = “echo test” RunsWhen = After RunsOnFailure = yes RunsOnClient = no RunsOnSuccess = yes # default, you can drop this line }

`

An example of the use of this directive is given in the Tips chapter of the NGBackup Problems Resolution guide.

Run After Job

Run After Job = <Command>

The specified <Command> is run as an external program if the current job terminates normally (without error or without being canceled). This directive is not required. If the exit code of the program run is non-zero, NGBackup will print a warning message. Before submitting the specified command to the operating system, NGBackup performs character substitution as described above for the RunScript directive. An example of the use of this directive is given in the Tips chapter of the NGBackup Problems Resolution guide.

See the Run After Failed Job if you want to run a script after the job has terminated with any non-normal status.

Run Before Job

Run Before Job = <command>

The specified <command> is run as an external program prior to running the current Job. This directive is not required, but if it is defined, and if the exit code of the program run is non-zero, the current NGBackup job will be canceled.

`

Run Before Job = “echo test”

`

it’s equivalent to :

`

RunScript { Command = “echo test” RunsOnClient = No RunsWhen = Before }

`

Lutz Kittler has pointed out that using the RunBeforeJob directive can be a simple way to modify your schedules during a holiday. For example, suppose that you normally do Full backups on Fridays, but Thursday and Friday are holidays. To avoid having to change tapes between Thursday and Friday when no one is in the office, you can create a RunBeforeJob that returns a non-zero status on Thursday and zero on all other days. That way, the Thursday job will not run, and on Friday the tape you inserted on Wednesday before leaving will be used.

RunScript {}

The RunScript directive behaves like a resource in that it requires opening and closing braces around a number of directives that make up the body of the runscript.

The specified Command (see below for details) is run as an external program prior or after the current Job. This is optional. By default, the program is executed on the Client side like in ClientRunXXXJob.

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 the jobid 0.

You can use following console command : delete, disable, enable, estimate, list, llist, memory, prune, purge, reload, status, setdebug, show, time, trace, update, version, .client, .jobs, .pool, .storage. See console chapter for more information. You need to specify needed information on command line, nothing will be prompted. Example :

`

Console = “prune files client=%c” Console = “update stats age=3”

`

You can specify more than one Command/Console option per RunScript.

You can use following options may be specified in the body of the runscript:

Options for Run Script

Options Value Default Information

Runs On Success Yes / No Yes Run command if JobStatus is successful

Runs On Failure Yes / No No Run command if JobStatus isn’t successful

Runs On Client Yes / No Yes Run command on clientnoteScripts will run on Client only with Jobs that use a Client. (Backup, Restore, some Verify jobs). For other Jobs (Copy, Migration, Admin, …) RunsOnClient should be set to No.

Runs When Before After Always AfterVSS AtJobCompletion Never When run commands

Fail Job On Error Yes/No Yes Fail job if script returns something different from 0

Command

Path to your script

Console

Console command

Any output sent by the command to standard output will be included in the NGBackup job report. The command string must be a valid program name or name of a shell script.

In addition, the command string is parsed then fed to the OS, which means that the path will be searched to execute your specified command, but there is no shell interpretation, as a consequence, if you invoke complicated commands or want any shell features such as redirection or piping, you must call a shell script and do it inside that script.

Before submitting the specified command to the operating system, NGBackup performs character substitution of the following characters:

`

%% = % %b = Job Bytes %c = Client’s name %C = If the job is a Cloned job (Only on director side) %d = Daemon’s name (Such as host-dir or host-fd) %D = Director’s name (Also valid on file daemon) %e = Job Exit Status %E = Non-fatal Job Errors %f = Job FileSet (Only on director side) %F = Job Files %h = Client address %i = JobId %I = Migration/Copy JobId (Only in Copy/Migrate Jobs) %j = Unique Job id %l = Job Level %n = Job name %o = Job Priority %p = Pool name (Only on director side) %P = Current PID process %R = Read Bytes %s = Since time %S = Previous Job name (Only on file daemon side) %t = Job type (Backup, …) %v = Volume name (Only on director side) %w = Storage name (Only on director side) %x = Spooling enabled? (“yes” or “no”)

`

Some character substitutions are not available in all situations. The Job Exit Status code %e edits the following values:

• OK

• Error

• Fatal Error

• Canceled

• Differences

• Unknown term code

Thus if you edit it on a command line, you will need to enclose it within some sort of quotes.

You can use these following shortcuts:

RunScript shortcuts

  Runs Runs FailJob Runs Runs

Keyword On On On On When

  Success Failure Error Client  

Run Before Job

Yes No Before

Run After Job Yes No

No After

Run After Failed Job No Yes

No After

Client Run Before Job

Yes Yes Before

Client Run After Job Yes No

Yes After

Examples:

`

RunScript { RunsWhen = Before FailJobOnError = No Command = “/etc/init.d/apache stop” }

RunScript { RunsWhen = After RunsOnFailure = yes Command = “/etc/init.d/apache start” }

`

Notes about ClientRunBeforeJob

For compatibility reasons, with this shortcut, the command is executed directly when the client recieve it. And if the command is in error, other remote runscripts will be discarded. To be sure that all commands will be sent and executed, you have to use RunScript syntax.

Special Shell Considerations

A “Command =” can be one of:

• The full path to an executable program

• The name of an executable program that can be found in the $PATH

• A complex shell command in the form of: “sh -c “your commands go here"" Special Windows Considerations

You can run scripts just after snapshots initializations with AfterVSS keyword.

In addition, for a Windows client, please take note that you must ensure a correct path to your script. The script or program can be a .com, .exe or a .bat file. If you just put the program name in then NGBackup will search using the same rules that cmd.exe uses (current directory, NGBackup bin directory, and PATH). It will even try the different extensions in the same order as cmd.exe. The command can be anything that cmd.exe or command.com will recognize as an executable file.

However, if you have slashes in the program name then NGBackup figures you are fully specifying the name, so you must also explicitly add the three character extension.

The command is run in a Win32 environment, so Unix like commands will not work unless you have installed and properly configured Cygwin in addition to and separately from NGBackup.

The System %Path% will be searched for the command. (under the environment variable dialog you have have both System Environment and User Environment, we believe that only the System environment will be available to backup-fd, if it is running as a service.)

System environment variables can be referenced with %var% and used as either part of the command name or arguments.

So if you have a script in the NGBackup \bin directory then the following lines should work fine:

`

Client Run Before Job = systemstate or Client Run Before Job = systemstate.bat or Client Run Before Job = “systemstate” or Client Run Before Job = “systemstate.bat” or ClientRunBeforeJob = ""C:/Program Files/NGBackup/systemstate.bat""

`

The outer set of quotes is removed when the configuration file is parsed. You need to escape the inner quotes so that they are there when the code that parses the command line for execution runs so it can tell what the program name is.

`

ClientRunBeforeJob = ""C:/Program Files/Software Vendor/Executable” /arg1 /arg2 “foo bar""

`

The special characters

`

&<>()@^|

`

will need to be quoted, if they are part of a filename or argument.

If someone is logged in, a blank “command” window running the commands will be present during the execution of the command.

Some Suggestions from Phil Stracchino for running on Win32 machines with the native Win32 File daemon:

• You might want the ClientRunBeforeJob directive to specify a .bat file which runs the actual client-side commands, rather than trying to run (for example) regedit /e directly.

• The batch file should explicitly “exit 0” on successful completion.

• The path to the batch file should be specified in Unix form:

`

ClientRunBeforeJob = “c:/bacula/bin/systemstate.bat”

`

rather than DOS/Windows form:

`

ClientRunBeforeJob = “c:\bacula\bin\systemstate.bat” # INCORRECT

`

For Win32, please note that there are certain limitations:

`

ClientRunBeforeJob = “C:/Program Files/NGBackup/bin/pre-exec.bat”

`

Lines like the above do not work because there are limitations of cmd.exe that is used to execute the command. NGBackup prefixes the string you supply with cmd.exe /c . To test that your command works you should type cmd /c “C:/Program Files/test.exe” at a cmd prompt and see what happens. Once the command is correct insert a backslash () before each double quote (”), and then put quotes around the whole thing when putting it in the director’s configuration file. You either need to have only one set of quotes or else use the short name and don’t put quotes around the command path.

Below is the output from cmd’s help as it relates to the command line passed to the /c option.

If /C or /K is specified, then the remainder of the command line after the switch is processed as a command line, where the following logic is used to process quote (”) characters:

• If all of the following conditions are met, then quote characters on the command line are preserved:

• no /S switch.

• exactly two quote characters.

• no special characters between the two quote characters, where special is one of:

`

&<>()@^|

`

• there are one or more whitespace characters between the the two quote characters.

• the string between the two quote characters is the name of an executable file.

• Otherwise, old behavior is to see if the first character is a quote character and if so, strip the leading character and remove the last quote character on the command line, preserving any text after the last quote character.

The following example of the use of the Client Run Before Job directive was submitted by a user:

You could write a shell script to back up a DB2 database to a FIFO. The shell script is:

`

#!/bin/sh

===== backupdb.sh

DIR=/u01/mercuryd

mkfifo $DIR/dbpipe db2 BACKUP DATABASE mercuryd TO $DIR/dbpipe WITHOUT PROMPTING & sleep 1

`

The following line in the Job resource in the backup-dir.conf file:

`

Client Run Before Job = “su - mercuryd -c “/u01/mercuryd/backupdb.sh ‘%t’ ‘%l’""

`

When the job is run, you will get messages from the output of the script stating that the backup has started. Even though the command being run is backgrounded with &, the job will block until the db2 BACKUP DATABASE command, thus the backup stalls.

To remedy this situation, the “db2 BACKUP DATABASE” line should be changed to the following:

`

db2 BACKUP DATABASE mercuryd TO $DIR/dbpipe WITHOUT PROMPTING > $DIR/backup.log 2>&1 < /dev/null &

`

It is important to redirect the input and outputs of a backgrounded command to /dev/null to prevent the script from blocking.

Schedule

Schedule = <schedule-name>

The Schedule directive defines what schedule is to be used for the Job. The schedule in turn determines when the Job will be automatically started and what Job level (i.e. Full, Incremental, …) is to be run. This directive is optional, and if left out, the Job can only be started manually using the Console program. Although you may specify only a single Schedule resource for any one job, the Schedule resource may contain multiple Run directives, which allow you to run the Job at many different times, and each Run directive permits overriding the default Job Level Pool, Storage, and Messages resources. This gives considerable flexibility in what can be done with a single Job. For additional details, see the Schedule Resource chapter of this manual.

Snapshot Retention

Snapshot Retention = <time-period-specification>

The Snapshot Retention directive defines the length of time that NGBackup will keep Snapshots in the Catalog database and on the Client after the Snapshot creation. When this time period expires, and if using the snapshot prune command, NGBackup will prune (remove) Snapshot records that are older than the specified Snapshot Retention period and will contact the FileDaemon to delete Snapshots from the system.

The Snapshot retention period is specified as seconds, minutes, hours, days, weeks, months, quarters, or years. See the Configuration chapter of this manual for additional details of time specification.

The default is 0 seconds, Snapshots are deleted at the end of the backup. The Job SnapshotRetention directive overwrites the Client SnapshotRetention directive.

Spool Attributes

Spool Attributes = <yes|no>

The default is set to yes, the Storage daemon will buffer the File attributes and Storage coordinates to a temporary file in the Working Directory, then when writing the Job data to the tape is completed, the attributes and storage coordinates will be sent to the Director. If set to no the File attributes are sent by the Storage daemon to the Director as they are stored on tape.

NOTE: When Spool Data is set to yes, Spool Attributes is also automatically set to yes.

Spool Data

Spool Data = <yes|no>

If this directive is set to yes (default no), the Storage daemon will be requested to spool the data for this Job to disk rather than write it directly to the Volume (normally a tape).

Thus the data is written in large blocks to the Volume rather than small blocks. This directive is particularly useful when running multiple simultaneous backups to tape. Once all the data arrives or the spool files’ maximum sizes are reached, the data will be despooled and written to tape.

Spooling data prevents interleaving date from several job and reduces or eliminates tape drive stop and start commonly known as “shoe-shine”.

We don’t recommend using this option if you are writing to a disk file using this option will probably just slow down the backup jobs.

NOTE: When this directive is set to yes, Spool Attributes is also automatically set to yes.

SpoolSize

SpoolSize=bytes

where the bytes specify the maximum spool size for this job. The default is take from Device Maximum Spool Size limit. This directive is available only in NGBackup version 2.3.5 or later.

Storage

Storage = <storage-resource-name>

The Storage directive defines the name of the storage services where you want to backup the FileSet data. For additional details, see the Storage Resource Chapter of this manual. The Storage resource may also be specified in the Job’s Pool resource, in which case the value in the Pool resource overrides any value in the Job. This Storage resource definition is not required by either the Job resource or in the Pool, but it must be specified in one or the other, if not an error will result. Storage can be either specified by an single item or it can be specified as a comma separated list of storages to use according to StorageGroupPolicy. If some number of first storage daemons on the list are unavailable due to network problems, broken or unreachable for some other reason, NGBackup will take first available one from the list (which is sorted according to the policy used) which is network reachable and healthy.

StorageGroupPolicy

StorageGroupPolicy = <Storage Group Policy Name>

Storage Group Policy determines how Storage resources (from the ‘Storage’ directive) are being choosen from the Storage list. If no StoragePolicy is specified NGBackup always tries to use first available Storage from the provided list. Currently supported policies are: ListedOrder

• This is the default policy, which uses first available storage from the list provided

Strip Prefix

Strip Prefix = <directory>

This directive applies only to a Restore job and specifies a prefix to remove from the directory name of all files being restored. This will use the File Relocation feature implemented in NGBackup 2.1.8 or later. Using Strip Prefix=/etc, /etc/passwd will be restored to /passwd

Under Windows, if you want to restore c:/files to d:/files, you can use :

`

Strip Prefix = c: Add Prefix = d:

`

Tag

Tag = <string, string2, string3>

The Tag directive specifies a list of tags to create when creating a new Job record. This directive is optional.

Type

Type = <job-type>

The Type directive specifies the Job type, which may be one of the following: Backup, Restore, Verify, or Admin. This directive is required. Within a particular Job Type, there are also Levels as discussed in the next item.

Backup Run a backup Job. Normally you will have at least one Backup job for each client you want to save. Normally, unless you turn off cataloging, most all the important statistics and data concerning files backed up will be placed in the catalog.

Verify Job

Verify Job = <Job-Resource-Name>

If you run a verify job without this directive, the last job run will be compared with the catalog, which means that you must immediately follow a backup by a verify command. If you specify a Verify Job NGBackup will find the last job with that name that ran. This permits you to run all your backups, then run Verify jobs on those that you wish to be verified (most often a VolumeToCatalog) so that the tape just written is re-read.

VirtualFull Backup Pool

VirtualFull Backup Pool = <pool-resource-name>

The VirtualFull Backup Pool specifies a Pool to be used for VirtualFull backups. It will override any Pool specification during an VirtualFull backup. This directive is optional.

Where

Where = <directory>

This directive applies only to a Restore job and specifies a prefix to the directory name of all files being restored. This permits files to be restored in a different location from which they were saved. If Where is not specified or is set to slash (/), the files will be restored to their original location. By default, we have set Where in the example configuration files to be /tmp/bacula-restores. This is to prevent accidental overwriting of your files.

Write Bootstrap

Write Bootstrap = <bootstrap-file-specification>

The writebootstrap directive specifies a file name where NGBackup will write a bootstrap file for each Backup job run. This directive applies only to Backup Jobs. If the Backup job is a Full save, NGBackup will erase any current contents of the specified file before writing the bootstrap records. If the Job is an Incremental or Differential save, NGBackup will append the current bootstrap record to the end of the file. Using this feature, permits you to constantly have a bootstrap file that can recover the current state of your system. Normally, the file specified should be a mounted drive on another machine, so that if your hard disk is lost, you will immediately have a bootstrap record available. Alternatively, you should copy the bootstrap file to another machine after it is updated. Note, it is a good idea to write a separate bootstrap file for each Job backed up including the job that backs up your catalog database.

If the <bootstrap-file-specification> begins with a vertical bar (|), NGBackup will use the specification as the name of a program to which it will pipe the bootstrap record. It could for example be a shell script that emails you the bootstrap record.

On versions 1.39.22 or greater, before opening the file or executing the specified command, NGBackup performs character substitution like in RunScript directive. To automatically manage your bootstrap files, you can use this in your JobDefs resources:

`

JobDefs { Write Bootstrap = “%c_%n.bsr” … }

`

For more details on using this file, please see the chapter entitled The Bootstrap File of this manual.