Backing Up and Restoring an Xi-Batch Configuration

What a Backup of Xi-Batch Consists Of

The scheduler keeps its state in binary files that are raw dumps of its internal structures. Copying those files is a backup of the machine's bytes, not of its configuration: they can only be restored onto a compatible installation, they cannot be read or edited, and they carry no protection against the queue having moved on while the copy was taken.

Xi-Batch therefore ships four conversion tools. Each reads one binary file and writes a shell script of ordinary Xi-Batch commands that recreates its contents. That script is the backup: it is readable, it can be edited, it can be replayed selectively, and it survives a change of release, of word size and of machine.

All four are in the user path on every distribution format, and none of them needs the scheduler to be running or any special privilege beyond being able to read the spool directory.

This article covers backing up and restoring one machine. Moving a configuration to a different machine is the same export plus a licensing step, and is covered by the Xi-Batch migration article.

Where the Files Are, and What They Are Called

The default spool directory is:

/var/spool/xi/batch

Read the real one off the master configuration if yours differs - a relocated or custom-blend installation will:

grep SPOOLDIR /etc/xi/batchconfig

The job and variable file names carry a suffix. Every shipped package and tarball is built against libxml2, and on such a build the saved files are:

btsched_jfile.xbjl6
btsched_vfile.xbvl6

The conversion tools choose which reader to use from the file name, so the suffix is not optional. Give the plain name and the command stops with:

Sorry cannot open btsched_jfile

and exit status 2. List the directory before you start rather than assuming:

ls -l /var/spool/xi/batch

The other files in that directory matter too. btufile6 holds every user's privileges and limits, cifile the command interpreter list, holfile the holiday calendar, and the SP files are the job scripts themselves. The licence is not there: it is .xibatch.lic in the internal programs directory, /usr/libexec/xi by default.

What the Export Does Not Carry

Four things a reader expects to be in the backup are not, and none of the omissions is reported.

• The holiday calendar. There is no holiday conversion tool - the four above are the whole set. The calendar is a bitmap in holfile and the only way to back it up is to copy that file, with the scheduler stopped. See the holiday article for the format and for what a removal or a migration costs it.
• The system variables. xb-cvlist skips every variable the scheduler created for itself, which is exactly LOADLEVEL, CLOAD, LOGJOBS and LOGVARS. After a restore, LOADLEVEL is back at its startup value and the two logging variables are empty, so job and variable logging is silently off until you set them again.
• Job numbers, job output and error files. The restored jobs are new jobs with new numbers. The redirection settings survive; the accumulated output does not.
• The licence. It is bound to the machine, so it is neither exported nor portable. Backing up on one machine and restoring on another is a re-licensing event.

Two silent losses inside the export itself are worth knowing about:

• A job whose script file has gone is dropped without a message and without a non-zero exit status. Compare the number of btr lines in the output with the number of jobs btjlist reports.
• A job or variable whose owner or group does not resolve to the recorded numeric id is dropped for the same reason. This is the common failure on a host whose accounts live in NIS or LDAP rather than in /etc/passwd. The -u option turns the check off and keeps the entries.

Stop the Scheduler First, or Accept a Stale Backup

The scheduler holds the job and variable queues in shared memory and writes them out at most every 300 seconds. An export taken from a running system can therefore be up to five minutes behind, and nothing indicates that it is.

For a backup you intend to restore from, stop the scheduler first:

systemctl stop xibatch

or, where there is no service unit:

btquit -y

Two things to know before you do:

• Stopping SIGKILLs every running job. There is no SIGTERM first and no grace period. Choose a moment when the queue is idle.
• btquit needs the "stop scheduler" privilege and blocks for at least nine seconds while the scheduler halts the queue, shuts the network side down and writes the files out. It returns when the scheduler has finished exiting, so no sleep afterwards is needed.

For a routine reference copy - "what did the schedule look like last Tuesday" - the five-minute window does not matter and there is no reason to interrupt production.

Exporting

The order the four exports run in makes no difference. The order they are restored in does; see below.

Jobs

mkdir -p /var/tmp/xibackup/scripts
xb-cjlist -D /var/spool/xi/batch btsched_jfile.xbjl6 \
          /var/tmp/xibackup/joblist.sh /var/tmp/xibackup/scripts

The full usage is:

xb-cjlist [-S env] [-D dir] [-u] [-s] [-f] [-e n] [-v n] [-I delim] jfile outfile [workdir]

The work directory must already exist - the command stops with Cannot find directory and exit status 4 if it does not. Each job's script is copied into it under its SP name, and the btr line in joblist.sh names that copy as its last argument.

The emitted lines look like this:

#! /bin/sh
# Conversion from XML Job list6

# Conversion of job number 1234

btr -N -F -j -p 150 -i sh -l 1000 -P 0022 -L -1 -t 0 -Y 0 -2 0 -W 15
    -h 'Nightly report' -D '/home/jsmith' -X N0:0 -X E1:255
    -M U:RWSMPD,G:RS,O:RS -u jsmith -g users
    -K -c 'extract_done=Yes' -f SREN -B -s 'report_state=Running'
    -T 26/08/13,03:00 -r Days:1 -A -,Sat,Sun,Hday -S
    /var/tmp/xibackup/scripts/SP00001234

(One line per job in the real file; broken here to fit.) The time is written as yy/mm/dd,hh:mm, the avoided days as a -A list beginning with a bare - so that it replaces rather than adds to the site defaults, and the permissions as -M with one letter per right.

Every job record produces its own #! /bin/sh line, so the file contains many of them. That is expected and harmless.

-I is worth knowing about for an unattended backup. Given a delimiter word it writes each job's script inline as a here-document instead of into a work directory, so the whole export is a single self-contained file and the third argument is omitted:

xb-cjlist -D /var/spool/xi/batch -I XBJOB btsched_jfile.xbjl6 \
          /var/tmp/xibackup/joblist.sh

Variables

xb-cvlist -D /var/spool/xi/batch btsched_vfile.xbvl6 \
          /var/tmp/xibackup/varlist.sh

xb-cvlist [-S env] [-D dir] [-u] [-s] [-f] [-e n] [-v n] vfile outfile

The emitted lines are complete btvar creations - the value is the argument to -s and the variable name is positional:

#! /bin/sh
# Conversion from XML Var list
btvar -C -k -E -c 'Status of nightly backup' -U jsmith -G users -M U:RWSMPD,G:RS,O:RS -s 'Not Started' backup_status
btvar -C -k -L -c 'Run counter' -U batch -G daemon -M U:RWSMPD,G:RS,O: -s 0 counter

-k or -K records whether the variable is a cluster variable and -L or -E whether it is exported, so the export state is preserved. There is no option that selects only exported variables; filter the output file if you want a subset.

Command Interpreters

xb-ciconv -D /var/spool/xi/batch cifile /var/tmp/xibackup/cilist.sh

xb-ciconv [-S env] [-D dir] [-u] [-s] [-f] [-e n] [-v n] vfile outfile

The usage line calls the input vfile. That is a defect in the message; the input is cifile.

The output renames the first entry and adds the rest:

#! /bin/sh
# Conversion from release 5 up
btcichange -n sh -iu -N 24 -L 1000 -p /bin/sh -a '-s' sh
btcichange -Aiu -N 24 -L 1000 -p /bin/ksh -a '-s' ksh
btcichange -Atu -N 30 -L 2000 -p /usr/bin/perl -a '-' perl

The interpreter's name is the trailing positional argument. -A adds a new entry, -L is the load level, -N the nice value, and -i/-t and -u/-e carry the two flags. The first entry cannot be added or deleted, only changed, which is why the converter renames it rather than creating it.

User Permissions

xb-btuconv -D /var/spool/xi/batch btufile6 /var/tmp/xibackup/userlist.sh

xb-btuconv [-D dir] [-s] [-f] [-e n] [-v n] vfile outfile

The output begins with the site defaults and then carries one line per user:

#! /bin/sh
# Conversion from release 5 up
# Converted from vn 6

btuchange -DA -l 1 -d 150 -m 255 -M 20000 -T 20000 -S 1000 -p 0x5 -J 0x7,0x5,0x1 -V 0x7,0x5,0x1
btuchange -l 1 -d 200 -m 255 -M 20000 -T 20000 -S 5000 -p 0x1f -J 0x7,0x7,0x1 -V 0x7,0x7,0x1 jsmith

The user name is positional and the privileges are a hexadecimal mask. btuchange also accepts privileges by name - RA, WA, CR, SPC, ST, Cdft, UG, UO, GO, or all - but they must be given as one comma-separated list, because each -p starts again from nothing and the last one wins.

Users whose settings are identical to the site defaults are omitted, which is correct and means the file is usually much shorter than the user list.

The Supplied Backup Script

Xi-Batch ships an interactive wrapper, xb-backup, which asks what to save and where, runs all four tools with the right arguments and file names, and remembers the destination for next time. It works out the suffixes for you.

Three limits decide whether it is the right tool:

• It is installed only by the tarball distribution. Neither the RPM nor the Debian package ships it.
• It must be run as root and it is interactive, so it cannot be scheduled.
• It does not stop the scheduler and does not cover the holiday calendar.

On a packaged installation, or for anything unattended, drive the four tools yourself.

A Complete Backup Script

#! /bin/sh
# backup-xibatch.sh - run as root

SPOOL=/var/spool/xi/batch
ROOT=/var/tmp/xibatch-backup
DEST=$ROOT/`date +%Y-%m-%d`

set -e
mkdir -p "$DEST/scripts"

xb-btuconv -D "$SPOOL" btufile6           "$DEST/userlist.sh"
xb-ciconv  -D "$SPOOL" cifile             "$DEST/cilist.sh"
xb-cvlist  -D "$SPOOL" btsched_vfile.xbvl6 "$DEST/varlist.sh"
xb-cjlist  -D "$SPOOL" btsched_jfile.xbjl6 "$DEST/joblist.sh" "$DEST/scripts"

# The holiday calendar has no conversion tool - copy it raw.
cp -p "$SPOOL/holfile" "$DEST/holfile"

# The licence is bound to this machine and cannot be restored elsewhere,
# but keep a copy so a reinstall on the same machine does not overwrite it
# with a trial licence.
cp -p /usr/libexec/xi/.xibatch.lic "$DEST/xibatch.lic"

cd "$ROOT"
tar cf - "`basename $DEST`" | gzip > "xibatch-`date +%Y-%m-%d`.tar.gz"

Note the single date substitution held in a variable: computing the date twice can straddle midnight and write into a directory that was never created.

Scheduling it as an Xi-Batch job is possible, and means the export is taken from a running scheduler and can be five minutes stale:

btr -T '02:00' -r Days:1 -h 'Xi-Batch configuration backup' \
    /usr/local/sbin/backup-xibatch.sh

The run time option is -T and the title option is -h. Note also that btr copies the contents of the file into the queue at submission and hands them to the job's command interpreter on standard input - the #! line is a comment, and later edits to the file on disk do not change the job.

Restoring

The order matters, and it is not simply the reverse of the backup, because two of the four scripts need the scheduler stopped and two need it running.

Running the whole set with the scheduler down fails at step 4 with Scheduler not running on every line of both remaining scripts. Steps 1 and 2 will have succeeded, so btulist and btcilist afterwards look right and only btvlist and btjlist show that half the restore did nothing.

Why the interpreters must precede the start. As the scheduler loads a saved job file, every job naming an interpreter that is not in cifile at that instant is silently reassigned to the first entry and saved that way. Restoring the interpreter list afterwards restores the list but not the jobs' assignments.

Why the variables must precede the jobs. btr resolves the variables named in a job's conditions and assignments at submission, so a job restored before its variables is refused.

The full sequence:

systemctl stop xibatch

cd /var/tmp/xibatch-backup/2026-08-13

sh userlist.sh
sh cilist.sh

# The calendar, if you are restoring it, goes back with the scheduler stopped
cp -p holfile /var/spool/xi/batch/holfile
chown batch /var/spool/xi/batch/holfile

systemctl start xibatch

sh varlist.sh
sh joblist.sh

Use sh rather than bash: the generated scripts declare #! /bin/sh and use nothing outside it, and bash is not present on a stock Solaris, AIX or HP-UX system.

Nothing in the generated scripts checks whether an item already exists. Replaying a job script twice creates a second copy of every job; replaying a variable script over live variables overwrites their values. Restore into a scheduler you have deliberately emptied, or edit the script first.

Verifying a Restore

btulist                       # users and their privileges
btcilist                      # command interpreters
btvlist -H -F '%N %U %V %E %K'
btjlist -H -F '%N %U %H %I %t %P'

btulist and btcilist read their files directly and work whether or not the scheduler is running. btvlist and btjlist read shared memory and need a running scheduler.

Then check the three things the export could have dropped in silence:

• Count the jobs. Fewer than you started with means job scripts had gone missing, or owners did not resolve.
• Set LOGJOBS and LOGVARS again if you use them. They come back empty on every restore.
• Check LOADLEVEL. It is back at whatever value the scheduler was started with, and any value you had set since is gone.

Selective Restore

The scripts are ordinary text, one command per job or variable, so a subset is a matter of filtering. The owner appears as -u <name> in each btr line:

grep -- "-u jsmith " joblist.sh > jsmith-jobs.sh
sh jsmith-jobs.sh

Keep the scripts directory alongside, because each line names a file in it.

For a single job it is usually easier to edit a copy of joblist.sh and delete the lines you do not want. Take a copy rather than editing the backup.

Practices

Export rather than copy. A copy of the binary files restores only onto a compatible installation and tells you nothing. The scripts restore across releases and machines, and can be read.

Keep the holiday calendar with the backup. It is the one piece of configuration with no tool, and a package removal deletes it outright.

Keep a copy of the licence file. It is useless on any other machine, but a reinstall on the same machine writes a fresh trial licence over the gap and the loss surfaces weeks later.

Test a restore, not just the backup. The failure modes above - a stale export, dropped jobs, empty logging variables, the interpreter ordering - all produce a backup that looks complete and a restore that is not. A restore into a spare installation is the only check that catches them.

Keep the backup script in version control and record which release it was written against; the file names carry the release number, and a major upgrade changes them.