From 83cb54c47c3022c0c00bdd14ad89a1f86bd170e9 Mon Sep 17 00:00:00 2001 From: Eric Bollengier Date: Sat, 27 May 2006 21:44:26 +0000 Subject: [PATCH] o add documentation about RunScript o cleanup other Run command --- docs/manual/dirdconf.tex | 231 ++++++++++++++++++++++++++------------- 1 file changed, 153 insertions(+), 78 deletions(-) diff --git a/docs/manual/dirdconf.tex b/docs/manual/dirdconf.tex index 4e01443d..fe18b9bd 100644 --- a/docs/manual/dirdconf.tex +++ b/docs/manual/dirdconf.tex @@ -863,21 +863,42 @@ For a {\bf Verify} Job, the Level may be one of the following: is {\bf yes}, it will override the value specified in the Client resource. The default is {\bf no}. -\item [Run Before Job = \lt{}command\gt{}] -\index[dir]{Run Before Job} -\index[dir]{Directive!Run Before Job} -\index[dir]{Directive!Run Before Job} - The specified {\bf command} is run as an external program prior to - running the current Job. Any output sent by the command to standard output - will be included in the Bacula job report. The command string must be a - valid program name or name of a shell script. This directive is not - required, but if it is defined, and if the exit code of the program run - is non-zero, the current Bacula job will be canceled. In addition, the - command string is parsed then fed to the execvp() function, 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. +\item [RunScript \{...\}] + \index[dir]{RunScript} + \index[dir]{Directive!Run Script} + + The specified {\bf command} is run as an external program prior or after the + current Job. This directive is optional. + + You can use following options : +\begin{tabular}{|c|c|c|l} +Options & Value & Default & Informations \\ +\hline +\hline +Runs On Success & Yes/No & {\it Yes} & Run command if JobStatus is successful\\ +\hline +Runs On Failure & Yes/No & {\it No} & Run command if JobStatus isn't successful\\ +\hline +Runs On Client & Yes/No & {\it Yes} & Run command on client\\ +\hline +Runs When & Before|After|Always & {\it Never} & When run commands\\ +\hline +Abort Job On Error & Yes/No & {\it Yes} & Abort job if script return + something different from 0 \\ +\hline +Command & & & Path to your script\\ +\hline +\end{tabular} + + Any output sent by the command to standard output will be included in the + Bacula 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 execvp() function, + 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, Bacula performs character substitution of the following characters: @@ -913,65 +934,42 @@ The Job Exit Status code \%e edits the following values: Thus if you edit it on a command line, you will need to enclose it within some sort of quotes. - - Bacula checks the exit status of the RunBeforeJob program. If it is - non-zero, the job will be error terminated. Lutz Kittler has pointed - out that using the RunBeforJob 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. -\item [Run After Job = \lt{}command\gt{}] -\index[dir]{Run After Job} -\index[dir]{Directive!Run After Job} - The specified {\bf command} is run as an external program if the current - job terminates normally (without error or without being canceled). 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, Bacula will print a warning message. Before submitting the - specified command to the operating system, Bacula performs character - substitution as described above for the {\bf Run Before Job} directive. - - An example of the use of this directive is given in the - \ilink{Tips Chapter}{JobNotification} of this manual. - See the {\bf Run After Failed Job} if you - want to run a script after the job has terminated with any - non-normal status. - -\item [Run After Failed Job = \lt{}command\gt{}] -\index[dir]{Run After Job} -\index[dir]{Directive!Run After Job} - The specified {\bf 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, Bacula will print a - warning message. Before submitting the specified command to the - operating system, Bacula performs character substitution as described above - for the {\bf Run Before Job} directive. Note, if you wish, you may - specify the same script as for {\bf Run After Job} so that your script - will run regardless of the exit status of the Job. - - An example of the use of this directive is given in the - \ilink{Tips Chapter}{JobNotification} of this manual. - -\item [Client Run Before Job = \lt{}command\gt{}] -\index[dir]{Client Run Before Job} -\index[dir]{Directive!Client Run Before Job} - This directive is the same as {\bf 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 {\bf Run Before Job}. +You can use these following shortcuts : +\begin{tabular}{|c|c|c|c|c|c} +Keyword & RunsOnSuccess & RunsOnFailure & AbortJobOnError & Runs On Client & RunsWhen \\ +\hline +Run Before Job & & & Yes & No & Before \\ +\hline +Run After Job & Yes & No & & No & After \\ +\hline +Run After Failed Job & No & Yes & & No & After \\ +\hline +Client Run Before Job & & & Yes & Yes & Before \\ +\hline +Client Run After Job & Yes & No & & Yes & After \\ +\hline +Client Run After Failed Job & No & Yes & & Yes & After \\ +\end{tabular} + +Example : +\begin{verbatim} +RunScript { + RunsWhen = Before + AbortJobOnError = No + Command = "/etc/init.d/apache stop" +} - When specifying a full path to an executable if the path or executable - name contains whitespace or special characters they will need to be - quoted. Arguments containing whitespace or special characters will also - have to be quoted. +RunScript { + RunsWhen = After + RunsOnFailure = yes + Command = "/etc/init.d/apache start" +} +\end{verbatim} {\bf Special Windows Considerations} + In addition, for a Windows client on version 1.33 and above, please take careful note that you must ensure a correct path to your script. The script or program can be a .com, .exe or a .bat file. However, if you @@ -1049,14 +1047,13 @@ The following line in the Job resource in the bacula-dir.conf file: '%l'\"" \end{verbatim} \normalsize - 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. + +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 +To remedy this situation, the "db2 BACKUP DATABASE" line should be changed to the following: \footnotesize @@ -1069,13 +1066,91 @@ the following: It is important to redirect the input and outputs of a backgrounded command to /dev/null to prevent the script from blocking. +\item [Run Before Job = \lt{}command\gt{}] +\index[dir]{Run Before Job} +\index[dir]{Directive!Run Before Job} +\index[dir]{Directive!Run Before Job} +The specified {\bf 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 Bacula job will be +canceled. + +\begin{verbatim} +Run Before Job = "echo test" +\end{verbatim} + it's equivalent to : +\begin{verbatim} +RunScript { + Command = "echo test" + RunsOnClient = No + RunsWhen = Before +} +\end{verbatim} + + Lutz Kittler has pointed out that using the RunBeforJob 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. + +\item [Run After Job = \lt{}command\gt{}] +\index[dir]{Run After Job} +\index[dir]{Directive!Run After Job} + The specified {\bf 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, Bacula will print a warning message. Before submitting the + specified command to the operating system, Bacula performs character + substitution as described above for the {\bf RunScript} directive. + + An example of the use of this directive is given in the + \ilink{Tips Chapter}{JobNotification} of this manual. + + See the {\bf Run After Failed Job} if you + want to run a script after the job has terminated with any + non-normal status. + +\item [Run After Failed Job = \lt{}command\gt{}] +\index[dir]{Run After Job} +\index[dir]{Directive!Run After Job} + The specified {\bf 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, Bacula will print a + warning message. Before submitting the specified command to the + operating system, Bacula performs character substitution as described above + for the {\bf RunScript} directive. Note, if you wish that your script + will run regardless of the exit status of the Job, you can use this : +\begin{verbatim} +RunScript { + Command = "echo test" + RunsWhen = After + RunsOnFailure = yes + RunsOnClient = no + RunsOnSuccess = yes # default, you can drop this line +} +\end{verbatim} + + An example of the use of this directive is given in the + \ilink{Tips Chapter}{JobNotification} of this manual. + + +\item [Client Run Before Job = \lt{}command\gt{}] +\index[dir]{Client Run Before Job} +\index[dir]{Directive!Client Run Before Job} + This directive is the same as {\bf 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 {\bf RunScript}. \item [Client Run After Job = \lt{}command\gt{}] \index[dir]{Client Run After Job} \index[dir]{Directive!Client Run After Job} This directive is the same as {\bf Run After Job} except that it is run on - the client machine. Note, please see the notes above in {\bf Client Run - Before Job} concerning Windows clients. + the client machine. Note, please see the notes above in {\bf RunScript} + concerning Windows clients. \item [Rerun Failed Levels = \lt{}yes|no\gt{}] \index[dir]{Rerun Failed Levels} -- 2.39.5