Migrating Xi-Batch to Another System

Understanding Xi-Batch Migration Scenarios

Migration carries the configuration and the queued work of an existing Xi-Batch installation onto a different installation. The cases that call for it:

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 exist to 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

Whatever the reason, the machine changes, and that has one consequence the rest of this article depends on.

The Licence Does Not Move With the System

A migration puts Xi-Batch on a different machine, and the licence is tied to the machine it was issued on. The existing licence will not work on the new host, and copying the licence file across does not help. Plan the licence step before you plan anything else: everything below can be done perfectly and the product will still refuse to start without it.

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. On Linux the block is encoded against the machine's hardware address - the address of the network interface carrying the most traffic. The binding works differently on the other supported platforms, and a licence there may survive a move that would break it on Linux. Register the new system with Xi in any case: the entitlement is recorded per system, and support and downloads for the new machine depend on it being registered.

The block is validated by decoding it with the local machine's key and comparing an embedded checksum. On a different machine the checksum does not match, the block is zeroed, and the product reports it as invalid:

xb-checklic
Licence is not valid

The scheduler makes the same check at startup and simply exits if it fails. There is no warning, no grace period, and the exit status is deliberately obscure (107 for an invalid licence, 110 for an expired one). A reader who has copied the licence file sees a product that will not start and no obvious reason why.

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, not granted on the spot. 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 if you are not 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 is not a way to extend an existing licence, and it cannot be re-run over a valid one.

What an Xi-Batch Migration 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. Copying them between machines of different architecture, or between builds of different major releases, is not supported. 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 Migration 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 the reader is left believing an export was taken when none was.

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

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.

What the Export Does Not Carry

The conversion tools cover the configuration and the queue. Several things a reader would expect to survive do not, and nothing warns them:

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 is broken by the migration.

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 silently 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 if 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 without a message and without affecting the exit status. Compare the job count before and after.

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 but the file is not as tidy as it looks. 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.

Common Migration Patterns

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 first and let new work be submitted to the new system, rather than restoring the old queue

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

Platform-Specific Considerations

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.

Verifying a Successful Migration

Licence

xb-checklic reports the organisation, serial and expiry. Do this first - nothing else can be verified until the product runs

Counts

Compare job, variable, interpreter and user counts against the old system, and account for any difference. A silently 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

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. Copying the licence file across cannot work

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