jobstart JOBNAME...
jobstart ( -e | fun | distribute )
jobstart ( -l | list | time | timeline ) [ query ]
jobstart ( runs | runs-days | stats | stats-days ) [ query ]
jobstart
(
enable
|
disable
|
unlock
|
lock
)
JOBNAME...
jobstart
(
enable
|
disable
|
unlock
|
lock
)
all
jobstart print JOBNAME
jobstart log [ begin [ end ]]
jobstart logswitch
The jobstart command can be called manually as user root from the command line, but running it scheduled (i.e. from cron or at) is the main purpose.
The
jobstart
command can be started on any system where it is available.
However, the
JOBNAME
is started from the system that is configured in the
JOBSTART_SYSTEM=system
setting
(e.g.
JOBSTART_SYSTEM="root@acme301.acme.ch")
in the
jobstart.cfg
configuration file.
If a job runs on a target system different to the JOBSTART_SYSTEM, the job needs to connect to the related target system (using ssh-exec for example).
Therefore the JOBSTART_SYSTEM acts like a hub to execute all jobs.
This to simplify jobs writing, understanding the job start mechanism and to consolidate the log output centrally.
The intention is to implement the job commands in the jobstart.cfg file to fulfill a specific task. The user then can start those (probably more complex) tasks using the JOBNAME without the need to remember command line options or dependencies.
The output of stderr and stdout is logged to the logfile, therefore it is not necessarily needed to write to a dedicated logfile from the job.
The JOBNAME should be in upper case and only the underscore (_) character should be used as separator.
Add additional jobs to the jobstart.cfg file between the
# v-------------- JOBS FOLLOW ---------------v # : : # ^--------------- JOBS END -----------------^ #
markers.
See section EXAMPLES for example job definitions.
Running jobs are not affected by the editing of the jobstart.cfg file.
Be aware, that the configuration file is saved automatically before editing using the vsav(1) command internally. Therefore when a messed-up file was saved, or to check changes, the vls(1), vdiff(1), vrestore(1) etc. commands can be used to verify changes or revert to a previous version.
The name, description and the job documentation reference is extracted from the configuration file if the job is defined as:
JOBNAME) # description of the job
or
JOBNAME) # description of the job / [REF]
in the jobstart.cfg file.
Only job RUNS that are not skipped (due to jobstart.cfg configuration file syntax errors (EXITCODE = 2) or are disabled/locked (ACTIVE = False)) are COUNTed for job runtime statistics calculations.
Starts of jobs that are not defined are not listed.
The host_list is a comma separated list of hosts (as returned by the hostlist -l command).
A space separated list of JOBNAMEs can be defined to execute several jobs in sequence. The jobstart command stops executing a JOBNAME sequence as soon as a JOBNAME has an exit code different to 0 (success) and 98 (deactivated).
A disabled JOBNAME is listed as ACTIVE False when listing all jobs using jobstart list.
lock provides a second level of disabling jobs from being started beside of the jobstart disable JOBNAME command.
jobstart lock JOBNAME is used to rather permanently prevent a job from being started where jobstart disable JOBNAME is used to rather temporarily prevent a job from being started.
A locked JOBNAME is listed as ACTIVE False when listing all jobs using jobstart list.
After a logswitch the runs, stats and log options can still be used to query information of all jobstart log files (the current jobstart.log and all available jobstart.<TIMESTAMP>.log files) without the need to know in which file the information is stored.
A log switch can significantly improve performance for queries of more recent events without loosing information as a normal log rotate would.
The jobstart logswitch command should probably be scheduled (using ecrontab(1) for example).
This functions could also be added to the jobstart.cfg config file, but when defining the functions in jobstart.lib the functions are listed when jobstart fun is used and the comment format is:
# myfunction opt1 opt2 -- description
A job is a shell case structure, which is
JOBNAME) # job description
echo "job code goes here ..."
;;
or with a reference to additional job documentation:
JOBNAME) # job description / [REF]
echo "job code goes here ..."
;;
The example below shows the definition of the jobs SYS2HTML and CRONTAB:
# v------------------------------------- JOBS FOLLOW --------------------------------------v #
CRONTAB) # list JOBSTART_SYSTEM crontab / crond(3)
#
echo "# ========== system root crontab =========="
crontab -l
echo "# =========== edrc root crontab ==========="
ecrontab -l
set_exitcode 0
;;
SYS2HTML) # system configuration HTML
#
collect=`hostlist`
outputdir=$REPORTDIR/SYS2HTML/$TODAY
# job workload
#
mkdir $outputdir >/dev/null 2>&1; chmod 755 $outputdir
sys2html -o $outputdir $collect
set_exitcode 0
;;
# ^--------------------------------------- JOBS END ---------------------------------------^ #
To list all defined jobs, output correlates to example 1):
[ / ] [ root@acme301 ][*edrc*/bash]: jobstart -l ACTIVE JOBNAME CRON HOUR MINUTE DAY MONTH WEEKDAY QUEUE DESCRIPTION DOCREF ------ -------- ----- ---- ------ --- ----- ------- ------- ---------------------------- -------- True CRONTAB list JOBSTART_SYSTEM crontab crond(3) True PUBLISH YES 08 00 * * 1,3 Q02-J01 publish documentation files True SYS2HTML YES 12 00 * * 7 Q01-J01 system configuration HTML True WEBSYNC YES 12 00 * * 7 Q01-J02 synchronize webserver data [DLD] (2)
The scheduling information is resolved from the ecrontab and crontab definition on the JOBSTART_SYSTEM:
[ / ] [ root@acme301 ][*edrc*/bash]: ecrontab -l # # acme301:~edrc/var/spool/cron/root - root crontab # # [000] 06.07.2021 CWa Initial Version # SHELL=/bin/bash PATH=~edrc/bin:/usr/bin:/bin #------ ------ ------ ------ -------------- ------------------------------------------ #MINUTE HOUR DAY MONTH WEEKDAY COMMAND #(0-59) (0-23) (1-31) (1-12) (1=Mon, 7=Sun) #------ ------ ------ ------ -------------- ------------------------------------------ 00 12 * * 7 jobrun SYS2HTML WEBSYNC 00 08 * * 1,3 jobrun PUBLISH #------ ------ ------ ------ -------------- ------------------------------------------
To use jobstart in an application, create a symlink to the edrc/bin/jobstart command with a different name:
Example:
ln -s ~edrc/bin/jobstart /opt/myApp/bin/jobctl
The FILES of such a jobstart instance are: /opt/myApp/etc/jobctl.cfg, /opt/myApp/etc/jobctl.lib, /opt/myApp/log/jobctl.log, /opt/myApp/var/jobctl.disabled, /opt/myApp/var/jobctl.locked, and edrc/var/cache/jobstart/jobctl.cache.
The setting JOBRUN_SYSTEM=system defines the system from where the jobs are started for an instance with any name of jobstart (jobctl in this example), as the JOBSTART_SYSTEM=system does for jobstart.
This is free software; see https://www.gnu.org/licenses/gpl-2.0.html for copying conditions. There is ABSOLUTELY NO WARRANTY; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.