Backing Up and Restoring an Xi-Batch Configuration

Xi-BatchXi-Batchbackup-restoremigrationxb-backupxb-btuconvxb-ciconvxb-cjlistxb-cvlist

A backup of an Xi-Batch configuration is a set of shell scripts written by four conversion tools, and a restore is those scripts replayed in a fixed order. This article covers 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.

The conversion tools write the backup

The scheduler keeps its state in binary files that are raw dumps of its internal structures. A copy of those files restores only onto a compatible installation, and holds the queue as it stood at the moment of the copy.

Xi-Batch 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 can be read, edited and replayed selectively, and it remains valid across a change of release, of word size and of machine.

What	Binary file	Tool	The script it writes contains
Jobs	btsched_jfile.xbjl6	xb-cjlist	btr commands, plus a copy of each job's script
Variables	btsched_vfile.xbvl6	xb-cvlist	btvar commands
Command interpreters	cifile	xb-ciconv	btcichange commands
User permissions	btufile6	xb-btuconv	btuchange commands

All four are in the user path on every distribution format. They need read access to the spool directory and no other privilege, and they run whether or not the scheduler is running.

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 where the installation has been relocated or built as a variant:

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 required. Give the plain name and the command stops with:

Sorry cannot open btsched_jfile

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

ls -l /var/spool/xi/batch

The other files in that directory: 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. The file names carry the release number, and a major upgrade changes them.

What the export leaves behind

Four things sit outside the export, 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. A package removal deletes it. See the holiday article for the format and for what a removal or a migration does to 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 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 are exported; the accumulated output is 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 kinds of entry are dropped from the export itself:

• 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 before an export you will restore from

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.

Stop the scheduler first:

systemctl stop xibatch

or, where there is no service unit:

btquit -y

Stopping has two further effects:

• 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 the five-minute window does not matter, and the scheduler can stay up.

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.

-I suits 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, so 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 apply:

• 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"

The date is computed once and held in a variable: computing it twice can straddle midnight and write into a directory that was never created.

Scheduled as an Xi-Batch job, 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. 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: two of the four scripts need the scheduler stopped and two need it running.

Step	Script	Command it replays	Scheduler
1	userlist.sh	btuchange	writes btufile6 directly; does not need one
2	cilist.sh	btcichange	writes cifile directly; does not need one
3	-	start the scheduler	-
4	varlist.sh	btvar	must be running
5	joblist.sh	btr	must be 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 reassigned to the first entry, with no message, and saved that way. Restoring the interpreter list afterwards restores the list, and leaves the jobs' assignments as they are.

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 can drop without reporting it:

• 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.

A stale export, dropped jobs, empty logging variables and the interpreter ordering all leave a backup that looks complete. A restore into a spare installation is the check that catches them.

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 \ 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, edit a copy of joblist.sh and delete the lines you do not want.

Related articles

All articles · Release notes · Contact support