Migrating Xi-Batch to Another System

Xi-BatchXi-Batchbackup-restorelicensingmigrationxb-btuconvxb-checklicxb-ciconvxb-cjlistxb-cvlistxb-vwrite

Migration carries the configuration and the queued work of an existing Xi-Batch installation onto a different installation. This article gives the export and restore procedure, and says what the export leaves behind. The machine changes, and the licence is the first consequence to plan for.

The cases that call for a migration

Replacement hardware
Moving to a new server while keeping the schedule and the variables

A different operating system or architecture
The saved state files are raw C structures written by the running daemon, so they are readable only by a build for the same release on the same architecture. The conversion tools bridge that gap

Major release upgrades
Xi-Batch release 5 to release 6

Disaster recovery
Rebuilding a system from a backup taken with the same tools

The licence stays with the old machine

A migration puts Xi-Batch on a different machine, and the licence is tied to the machine it was issued on. The new host needs a licence of its own, and a licence file copied across is invalid there. Plan the licence step first: without a valid licence the scheduler exits at startup.

What the licence is bound to

The licence is a small binary block in a hidden file in the internal-programs directory, /usr/libexec/xi/.xibatch.lic by default. It is keyed to the machine's hardware signature. Register the new system with Xi: the entitlement is recorded per system, and support and downloads for the new machine depend on it being registered.

On a different machine the check fails and the product reports the licence as invalid:

xb-checklic
Licence is not valid

The scheduler makes the same check at startup and exits if it fails, with no warning and no grace period. The exit status is 107 for an invalid licence and 110 for an expired one.

Getting a licence for the new machine

Licence codes come from the Xi customer portal:

• Sign in with your account reference and the email address held on the account. A one-time code is sent to that address.
• Open the panel for the serial number the old machine used, and choose Register a new system. Give it a label and host name, and pick the architecture, operating system, version and blend of the new machine.
• The registration is confirmed by Xi as a separate step. Allow for that in the migration plan.
• Once the system is active, choose Generate licence codes. The codes are shown on screen, and can be emailed to you.

The codes are short-lived. They carry the time they were generated, and the licensing program compares it against the target machine's clock: codes more than twelve hours old are refused, and so are codes from a machine whose clock is more than six hours behind the moment of generation. Either case gives "Sorry - invalid codes." Generate them when you are ready to apply them, and check the date and time on the target machine first.

Apply them on the new machine, as root, with the scheduler stopped:

btquit -y
xb-vwrite

The program asks for the organisation name and serial number, then for the codes. It refuses to run for any user other than the superuser, and it refuses to run while the scheduler is up.

Where the machine can reach the licence server directly, the codes can be fetched rather than typed:

xb-vwrite -q -I -s 52210000 -o "Your Organisation"

With -q all three of -I (fetch over the network), -s (serial) and -o (organisation) are mandatory; the program exits 20, 21 or 22 if any is missing.

The trial licence buys you the confirmation window

A package installation on a machine with no licence file sets a temporary licence automatically - 45 days from an RPM install, 30 days from a Debian install. That is what covers the period between installing on the new machine and the portal registration being confirmed. It is set only when no licence file exists, so it cannot extend an existing licence and cannot be re-run over a valid one.

What the export carries

Jobs
Scheduled jobs, their scripts, timing, conditions, assignments and state

Variables
User-defined job control variables with current values and permissions

Command interpreters
Interpreter definitions with their load levels and argument settings

User permissions
Privileges, load levels, priorities and default modes, held in the user file

Holiday calendar
Days to avoid when calculating a schedule. There is no conversion tool for these - see step 5

System configuration
The master config and hosts files under /etc/xi

When the conversion tools are required

A different machine, always
The saved state files are raw structure dumps, and copying them between machines of different architecture, or between builds of different major releases, is unsupported. The conversion tools turn them into plain shell scripts, which are portable.

Major release changes
Release 5 to 6 on the same machine. The converters read the older formats and detect which one they have been given: xb-cjlist accepts job files from release 5 to 6, and xb-cvlist variable files from release 4 to 6. A -v option forces a particular release if detection picks the wrong one.

Minor version upgrades
Within the same major release, on the same machine - 6.400 to 6.451, say - stop the product, install the new binaries and restart. No conversion is needed.

File names carry the major release
The user file is named for the major version, btufile6 on a release 6 system, and the saved job and variable files carry the major version in their suffix as well. Look in the spool directory before typing a command that names them.

The procedure

Step 1: Stop the scheduler first

The saved job and variable files are rewritten at most every 300 seconds while the scheduler runs, so an export from a live system can be five minutes stale. Stopping writes them at the end of a clean shutdown.

# On a packaged Linux system
systemctl stop xibatch

# Or directly
btquit -y

# Verify
ps -ef | grep btsched

Stopping kills every running job outright, with SIGKILL to the whole process group and no grace period. btquit also blocks for at least nine seconds, and requires the stop-scheduler privilege.

Step 2: Create the backup directory

BACKUP_DIR=/var/tmp/batchsave
mkdir -p "$BACKUP_DIR/Scripts"

The scripts directory must exist before the job converter is run - the converter checks for it and refuses to start if it is missing.

Step 3: Check the saved file names before you type them

On any build with libxml2 - which is every packaged installation - the saved job and variable files carry an XML suffix:

ls /var/spool/xi/batch/btsched_[jv]file*
/var/spool/xi/batch/btsched_jfile.xbjl6
/var/spool/xi/batch/btsched_vfile.xbvl6

The converters choose their input format from that suffix. Naming the plain btsched_jfile on such a system produces "Sorry cannot open btsched_jfile" and exit status 2, and no export is written.

Step 4: Export jobs, variables, interpreters and users

xb-cjlist  -D /var/spool/xi/batch btsched_jfile.xbjl6 "$BACKUP_DIR/joblist.sh" "$BACKUP_DIR/Scripts"
xb-cvlist  -D /var/spool/xi/batch btsched_vfile.xbvl6 "$BACKUP_DIR/varlist.sh"
xb-ciconv  -D /var/spool/xi/batch cifile   "$BACKUP_DIR/cilist.sh"
xb-btuconv -D /var/spool/xi/batch btufile6 "$BACKUP_DIR/userlist.sh"

Drop the suffixes on a build without libxml2, where the plain names are the real ones. xb-btuconv has no default source directory, so it needs -D or a full path.

What each produces:

• joblist.sh - btr commands, one per job, and Scripts/ holding a copy of each job's script
• varlist.sh - btvar commands recreating the user-defined variables
• cilist.sh - btcichange commands recreating the command interpreters
• userlist.sh - btuchange commands recreating the user permissions

The scripts call the commands by their plain names, so the restoring system needs the user command directory on its PATH.

There is a tarball-only wrapper, xb-backup, that drives all four. It is not installed by the RPM or the deb, so on a packaged system run the converters directly.

Step 5: Deal with the holiday calendar separately

There is no conversion tool for holidays. On a system where bthols is available it will print a year's holidays as plain text and read them back:

# On the old system
bthols 2026 > "$BACKUP_DIR/hols2026.txt"

# On the new system
bthols -s -C 2026 "$BACKUP_DIR/hols2026.txt"

bthols is not installed by the RPM or the deb. On a packaged system the holiday list is reachable only through the holidays screen in btq, so it has to be copied out and re-entered by hand, or the holfile carried across as bytes - which is subject to the same architecture and release constraints as any other state file.

Step 6: Copy the configuration files

cp /etc/xi/batchconfig "$BACKUP_DIR/"
cp /etc/xi/batch-hosts "$BACKUP_DIR/"

Also under /etc/xi: batch-env, usermap and pwfile, if your installation uses them.

Take care with batchconfig: it records the directories this installation was built and installed with, so overwriting the new machine's copy with the old machine's copy is only right when the two installations are laid out identically.

Step 7: Install and licence the new system

Install Xi-Batch on the target by the normal route for that platform. A package installation sets a temporary licence at this point, which is what gives you working software while the portal registration is confirmed. Then register the machine in the portal, generate codes and apply them with xb-vwrite. Confirm before going further - xb-checklic reports the organisation, serial and expiry, and nothing else can be verified until the product runs:

xb-checklic

Step 8: Restore in the correct order

Two of these scripts need the scheduler stopped and two need it running:

# 1. Users. btuchange edits the user file directly.
sh "$BACKUP_DIR/userlist.sh"

# 2. Command interpreters. btcichange edits cifile directly, and a
#    running scheduler picks up a change without a restart. Restore
#    them BEFORE starting it all the same: the scheduler loads the
#    job file straight after the interpreter list, and any saved job
#    naming an interpreter missing at that moment is silently reset
#    to the first entry.
sh "$BACKUP_DIR/cilist.sh"

# 3. Holidays, if you have them.
bthols -s -C 2026 "$BACKUP_DIR/hols2026.txt"

# 4. Start the scheduler.
systemctl start xibatch

# 5. Variables. btvar talks to the scheduler and fails with
#    "Scheduler not running" without it. Variables must precede
#    jobs, because job conditions and assignments reference them.
sh "$BACKUP_DIR/varlist.sh"

# 6. Jobs, last. btr also requires a running scheduler.
sh "$BACKUP_DIR/joblist.sh"

Step 9: Verify

# Jobs
btjlist -H

# Variables
btvlist

# Command interpreters
btcilist

# Users
btulist

btjlist and btvlist need the scheduler running; btcilist and btulist read their files directly and do not.

Then check the following:

Counts
Compare job, variable, interpreter and user counts against the old system, and account for any difference. A dropped job shows up here and nowhere else

User access
Check that ordinary users can submit work and view the queue

Scheduling
Confirm jobs run at the right times with their conditions satisfied, and that LOGJOBS and LOGVARS have been set again if you use them

Network operation
If networked, check remote submission

What stays with the old machine

The conversion tools cover the configuration and the queue. These remain on the old system:

The licence
Covered above. Nothing in the export touches it.

Job numbers
Nothing in the generated commands sets a job number. The destination allocates new ones, so any external record that refers to a job by number refers to the old numbering.

Job output and error files
Only the redirection settings are carried. Output already produced on the old system stays there.

System variables
LOADLEVEL, CLOAD, LOGJOBS and LOGVARS are skipped by xb-cvlist - it exports user-defined variables only. On the new machine they come back at their defaults, LOADLEVEL at 20000 unless btstart is given -l, and LOGJOBS and LOGVARS empty, which turns job and variable logging off. Set them again after the migration.

Logs and report files
btsched_reps and any job or variable log are not exported. Keep them with the old system where you need the history.

Holidays
No conversion tool exists - see step 5 above.

Jobs whose script file has gone
The job converter copies each job's script into the scripts directory. A queue entry whose file has already been removed is dropped from the export with no message and with the exit status unchanged. Comparing the job count before and after is what surfaces them.

Editing the generated scripts

The generated scripts are plain text and can be edited before they are replayed. Common changes:

Selective restoration
Delete or comment out the lines for jobs or variables you do not want

Parameter changes
Edit a command in place to change an owner, a priority or a path

Filtering
Cut the file down with grep. The job owner is set with -u and the group with -g:

# Only restore jobs owned by jsmith
grep '^btr .*-u jsmith' joblist.sh > joblist-jsmith.sh

Two things to watch when editing. The job script repeats its #! /bin/sh header once per job rather than once per file; the repeats are harmless. And each btr line ends with the path of the job's script file in the scripts directory, so moving or renaming that directory breaks every line in the file.

Ways to stage the move

Test migration before production
Restore to a test system first and verify, then migrate production. A test system needs its own licence - register it in the portal as a separate system

Selective migration
Carry the users, interpreters and variables and start with an empty job queue

Incremental migration
Restore users and interpreters, then let new work be submitted to the new system while the old queue stays where it is

Parallel operation
Run both systems during the transition and let the old one finish its existing work. Both need a valid licence for as long as they run

Where the two machines differ

Run the converters on the source machine
The state files are raw structure dumps, and a file written by a big-endian build is not reliably readable by a little-endian one. The shell scripts the converters produce are plain text and cross the gap safely.

Directory differences
The current default spool directory is /var/spool/xi/batch. Older installations used paths under /usr/spool. Edit the scripts if the two installations differ.

User and group IDs
The generated commands name users and groups by name, so the accounts must exist on the target. Where they do not, the affected lines fail.

Command interpreters
Interpreter definitions name a path to a shell, and the paths differ between platforms - /bin/ksh on one system, /usr/bin/ksh on another. Correct the table with btcichange on the target before restoring jobs that use them; every job naming that interpreter is corrected with it.

Network addressing
Update /etc/xi/batch-hosts if hostnames or addresses change.

Troubleshooting

"Licence is not valid" or the scheduler exits at startup
The licence was issued for the old machine. Register the new system in the portal and generate fresh codes

"Sorry - invalid codes." from xb-vwrite
The codes have gone stale or the machine clock is wrong. Check the date and time, then generate the codes again

"Sorry cannot open btsched_jfile"
The file name given to xb-cjlist is missing its .xbjl6 suffix. List the spool directory and use the name that is there

"Scheduler not running" during restore
btvar and btr both need the scheduler running. Start it before running those scripts

Jobs restored with the wrong interpreter
The command interpreters were restored after the scheduler was started, so it never saw them. Restore them first, or restart the scheduler and restore the jobs again

"Variable does not exist" errors
Variables must be restored before the jobs whose conditions and assignments reference them

Permission denied errors
The restore scripts assume the privileges of whoever runs them. Run them as root or as an account holding the relevant Xi privileges

Jobs do not execute after migration
Check the scheduler is running, then check LOADLEVEL - it is not carried across and comes back at its default

Users appear by number rather than by name
Xi-Batch reads /etc/passwd directly rather than through the system's name service, so an account that exists only in a directory service is exported and displayed by number. Add the accounts locally on the machine running the product

Related articles

All articles · Release notes · Contact support