Removing Xi-Batch from a System

Before You Begin

⚠️ WARNING: Removing a package destroys your data

Removing the RPM or the Debian package deletes the whole spool directory and everything in it - the saved job queue, the variables, the user permissions file, the command interpreter table and the holiday calendar - together with the licence file, the master configuration, the hosts file and the batch system account. The removal takes no backup, keeps nothing back for safety and asks no questions. Take the backup described below before you start.

⚠️ WARNING: The packaged routes delete your licence

The RPM and the Debian package both delete /usr/libexec/xi/.xibatch.lic on removal. If you install Xi-Batch again afterwards, the installation finds no licence file and quietly writes a trial licence in its place, so the system appears to work and stops weeks later when the trial expires. Copy the licence file out of the installation before you remove anything, and put it back after any reinstallation.

A tarball installation is different in both respects: its de-installer keeps the licence file and keeps the spool directory with all your saved state in it. See What Each Removal Route Destroys below - the difference is large enough that an administrator who has removed Xi-Batch by the other route, or who has removed Xi-Text before, will have the wrong expectation in both directions.

⚠️ WARNING: Stopping Xi-Batch kills running jobs

Stopping the scheduler halts the queue and sends SIGKILL to the process group of every job running on this machine. There is no SIGTERM first and no grace period, so work in progress is lost where it stands, and a job that writes a file leaves that file half written. Check what is running with btjlist first, and schedule the removal for a window in which the queue is idle.

Stop Xi-Batch First

Stop the scheduler before you take the backup. The saved job and variable files are rewritten at most every 300 seconds while the scheduler runs, so an export taken from a live system can be five minutes behind the real queue; the stop flushes both files as its last act.

# On a packaged Linux installation, stop the service rather than the scheduler,
# so that systemd does not restart it underneath you
systemctl stop xibatch

# On every other installation, and wherever the scheduler was started by hand
btquit -y

# Verify
ps -ef | grep btsched

btquit accepts only -y (or -Y), which confirms the stop without prompting. It does not return until the scheduler has finished shutting down, which takes at least nine seconds: the queue is halted, running jobs are killed, operator connections and the network side are closed, and only then are the job and variable files written.

Two things to know before you run it:

• The caller needs the scheduler-stop privilege, which root and the batch account hold by default and an ordinary user does not. The refusal arrives after the running jobs have already been killed, so an unprivileged attempt still costs you the work in progress - treat btquit as an operation only an administrator performs.
• Removing the package stops the service itself, but only a scheduler that systemd started. A scheduler started by hand with btstart is left running while the package removal deletes the spool tree out from under it.

Back Up What You Need to Keep

Take the backup after the stop, and write it somewhere outside /var/spool/xi and outside /usr/libexec/xi - a packaged removal deletes both.

The licence file first. This is the item you cannot recreate yourself:

BACKUP_DIR=/var/tmp/xibatch-final-$(date +%Y%m%d-%H%M%S)
mkdir -p "$BACKUP_DIR/Scripts"

cp -p /usr/libexec/xi/.xibatch.lic "$BACKUP_DIR"

Then export the saved state. Xi-Batch ships four conversion tools that turn the binary spool files into replayable shell scripts. They are installed in /usr/local/bin by all three distribution formats, so they are already on the path.

The job and variable file names carry a suffix on every packaged installation - btsched_jfile.xbjl6 and btsched_vfile.xbvl6 - and the converters select their input format from that suffix. A command naming the plain btsched_jfile will fail or produce nothing. List the directory first and use the names you find:

ls -l /var/spool/xi/batch

cd "$BACKUP_DIR"

# Jobs: the third argument is the directory the saved job scripts are written to,
# and the generated joblist.sh refers to it
xb-cjlist /var/spool/xi/batch/btsched_jfile.xbjl6 joblist.sh "$BACKUP_DIR/Scripts"

# Variables
xb-cvlist /var/spool/xi/batch/btsched_vfile.xbvl6 varlist.sh

# Command interpreters
xb-ciconv -D /var/spool/xi/batch cifile cilist.sh

# User permissions
xb-btuconv -D /var/spool/xi/batch btufile6 userlist.sh

Restore them in the order variables, users, command interpreters, jobs - a job definition can refer to all three.

Then the configuration files. The current names are:

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

# These three exist only where the site uses them
cp -p /etc/xi/batch-env /etc/xi/pwfile /etc/xi/usermap "$BACKUP_DIR" 2>/dev/null

If your system instead has /etc/Xibatch-config and /etc/Xibatch-hosts, it predates the move to /etc/xi; those names survive only as the files an upgrade reads once and replaces.

What cannot be preserved: the holiday calendar. Every other part of an Xi-Batch configuration has a conversion tool. The holiday file has none, and bthols, the command that edits it, is installed by no distribution format. The file itself, holfile in the spool directory, is a binary the next installation will overwrite with an empty one. Before a packaged removal, print the calendar from the holidays screen in btq and keep the printout, or copy holfile byte for byte and accept that it can only be restored to a matching installation on matching hardware. A tarball removal leaves the file in place.

Finding Your Own Directories

The paths above are the standard ones. A custom build, or a tarball installation where different directories were chosen at install time, puts them elsewhere. The master configuration is the authority:

grep -E '^[ 	]*(SPOOLDIR|SPROGDIR|SPHELPDIR|SPUDSOCKS|USERPATH)' /etc/xi/batchconfig

A setting still at its built-in default is written into that file commented out, so a line beginning with # is telling you the default is in force rather than telling you nothing.

Determine Installation Type

Xi-Batch installs from an RPM, a Debian package or a tarball, and the three are removed by different means with different consequences. The package databases give the answer directly:

# RPM-based systems. The package name is the product and the build variant,
# for example xibatch_standard
rpm -qa | grep xibatch

# Debian-based systems. The package name is xibatch
dpkg -l | grep xibatch

# Which package, if any, owns an installed command
rpm -qf /usr/local/bin/btr
dpkg -S /usr/local/bin/btr

If the commands are present and no package owns them, the installation came from a tarball. Xi-Batch's tarball installer records no file manifest, so the unpacked distribution directory is the only inventory of what was installed - which is also what its de-installer has to be run from.

Uninstalling an RPM Installation

Step 1: Clear Leftover IPC Resources

Do this before removing the package, because xb-ripc - the tool for the job - is part of the package and will have been deleted by the time the removal finishes. After a clean stop there is normally nothing to clear; see Clearing Leftover IPC Resources below for how to check and what to do.

Step 2: Remove the RPM Package

The Motif and GTK3 desktop packages each require the main package at the same version, so remove all three in one command if they are installed:

# Find the exact names first
rpm -qa | grep xibatch

# Remove them together
rpm -e xibatch_standard-gtk3 xibatch_standard-motif xibatch_standard

# Verify
rpm -qa | grep xibatch

Expected output: nothing.

What the Removal Has Already Done

There are no optional clean-up steps after an RPM removal. Before the files are unpacked away the package stops and disables the xibatch service, deletes its unit file, and removes the Xi-Batch entries from /etc/services. It then deletes:

• /usr/libexec/xi/.xibatch.lic - the licence.
• /etc/xi/batchconfig and /etc/xi/batch-hosts, and the whole of /etc/xi if Xi-Text is not also installed - which takes batch-env, pwfile and usermap with it.
• /var/spool/xi/batch and /var/spool/xi/btuds outright, and /var/spool/xi itself if nothing else is left in it.
• The batch account.

The account's group is one the system already had - daemon, bin or root - so there is no batch group to remove. Run getent group batch if you want to confirm before reaching for groupdel.

Uninstalling a Debian Package Installation

The Debian package uses the same removal logic as the RPM, so it destroys the same things, with two differences noted below.

dpkg -r xibatch

# Verify
dpkg -l | grep xibatch

dpkg -r removes as much as dpkg --purge does. Contrary to the usual Debian convention, the ordinary removal deletes the spool tree, the licence, the configuration and the batch account; there is no data-preserving removal on Debian. Treat apt remove xibatch as destructive.

The two differences from the RPM:

• The Xi-Batch entries in /etc/services - xibatch, btq, xbnetsrv and xbapi - are added at installation but are left behind at removal. Delete them by hand if you are decommissioning the host.
• The systemd unit is written to /lib/systemd/system/xibatch.service rather than /usr/lib/systemd/system/xibatch.service. The removal deletes its own copy either way.

Uninstalling a Tarball Installation

Step 1: Find the Unpacked Distribution Directory

The de-installer lives in the directory the distribution archive was unpacked into, alongside the installer, and it reads the installation modules that sit beside it there. It is not copied into the installed system, so if that directory has been deleted you must unpack the same archive again before you can use it.

cd /path/to/xibatch_legacy-standard-1.9.1

ls -l DEINSTALL.sh DEINSTALL.pl

The archive ships DEINSTALL.sh and DEINSTALL.pl. There is no file called UNINSTALL and no bare DEINSTALL.

Step 2: Run the De-installer

./DEINSTALL.sh

DEINSTALL.sh checks that Perl 5 or later is available and then hands over to DEINSTALL.pl, which is an interactive program. It requires:

• root. It refuses otherwise.
• Perl version 5 or above on the path. It reports which of the two conditions failed and exits.
• A terminal. It asks questions, and F1 or ? gives help on each, ENTER accepts the default, and F8 aborts.

It offers to stop Xi-Batch if it finds it running, using btquit -y - which kills running jobs, as above - and gives up entirely if you decline or if the stop fails. Then it asks two questions:

• Delete the entries in the services file as well - answer yes to remove the four /etc/services entries.
• Do you want to delete the system user - see the note under What the Tarball Route Leaves Behind.

Unlike the packaged routes, it reads your master configuration first, so it follows the directories your installation actually uses rather than the standard ones.

What the De-installer Removes

• The user commands from the user programs directory, the internal programs and daemons from the internal programs directory, the help files and screen-help files, and the Motif and GTK3 desktop programs if they are installed.
• The API library and header, and the shared libraries.
• The system startup integration, for whichever mechanism this platform uses - systemd, upstart, LSB, System V, an AIX inittab entry or an HP-UX /etc/rc function. All of them are handled.
• The master configuration /etc/xi/batchconfig, and the hosts, environment, password and user-map files it points at.
• The installation's own helper directories under the internal programs directory.

It then attempts to remove the installation directories, but only with rmdir - which succeeds only on a directory that is already empty. That single detail is what makes this route so different from the packaged ones.

What the Tarball Route Leaves Behind

• The licence file. .xibatch.lic is never touched. It survives in the internal programs directory, and because it is there that directory survives too.
• The whole spool directory and everything in it - the saved job queue, the variables, btufile6, cifile, holfile, the scheduler report file and the SP job scripts. The rmdir fails against a directory with files in it, so nothing in it is lost. Delete it by hand once you are certain the backup is good.
• The batch account. The de-installer asks about it, and on the shipped version the answer has no effect - the account is left in place either way. Remove it yourself if you want it gone; see Platform-Specific Considerations for the command on each platform.
• The /etc/services entries, if you answered no to that question.
• Leftover sockets and lock files if the scheduler was killed rather than stopped - see the IPC section below.

What Each Removal Route Destroys

Clearing Leftover IPC Resources

A clean stop releases everything the scheduler holds: both shared memory segments, the request socket and the two lock files. Leftovers mean the scheduler was killed rather than stopped, or that a stop timed out part way through. So this is a check, not a routine step.

Run it before you remove the package, because xb-ripc is installed with the product and a package removal deletes it.

Checking

ipcs -m | grep 0x5869b

0x5869b is the Xi-Batch prefix and it must be matched in full. Xi-Text's keys begin 0x58691, and the two products share the first four digits. A pattern of 0x5869 matches both, so on a machine carrying both products it will delete Xi-Text's live shared memory. Always include the fifth character.

Two further points about the keys:

• The job and variable segments move as the queue grows, so the digits after the prefix are different on different days. Match on the prefix, not on a whole key you saw once.
• If this host runs Xi-Batch under more than one runtime environment, each environment's keys are offset from the others; a plain grep for the standard range will miss some of them. Give xb-ripc the environment number with -S and let it work them out.
• Two entries in the range, currently 0x5869b200 and 0x5869b201, belong to the file monitor rather than to the scheduler and are cleaned up by that program when its last user exits. Leave them alone.

A shipped Xi-Batch build creates no message queues, and creates a semaphore set only when the licence permits networking, so ipcs -q and ipcs -s will normally show nothing for Xi-Batch and an empty result there means nothing is wrong.

Clearing

# The tool for the job. Run it as root or as the batch account, and never
# against a running scheduler
xb-ripc -d

# On a host running several Xi-Batch environments, name the one you mean
xb-ripc -S 2 -d

xb-ripc -d removes the shared memory segments and the leftover request socket. The socket is the part that matters most: while it exists, a new scheduler treats the address as already in use and exits without starting, so a restart appears to do nothing.

If the package has already gone and xb-ripc with it, remove the segments by key. This works on Linux, Solaris, AIX and HP-UX alike:

ipcs -m | grep 0x5869b

# For each key listed, with the fifth character checked
ipcrm -M 0x5869b002

Then delete the leftover socket, btsched_req, from the sockets directory - by default /var/spool/xi/btuds.

Verification Steps

Check Processes

ps -ef | grep -E 'btsched|xbnetserv'

Expected: no results other than the grep itself.

Check IPC Resources

ipcs -m | grep 0x5869b

Expected: no results, apart from the file monitor's two entries if a file monitor is running.

Check Files

# User commands and tools
ls -l /usr/local/bin/bt* /usr/local/bin/xb-* 2>/dev/null

# Internal programs
ls -l /usr/libexec/xi/btsched /usr/libexec/xi/xbnetserv 2>/dev/null

# Spool directories
ls -d /var/spool/xi/batch /var/spool/xi/btuds 2>/dev/null

Expected after an RPM or Debian removal: all of them report no such file or directory.

Expected after a tarball removal: the programs are gone, and the spool directory and the licence file are still there. That is the correct outcome, not a failed removal.

Check Configuration

ls -l /etc/xi/batchconfig /etc/xi/batch-hosts 2>/dev/null

Expected: no results on every route.

Check Services

systemctl status xibatch

grep -E '^(xibatch|btq|xbnetsrv|xbapi)' /etc/services

Expected: the service is not found; and the /etc/services entries are gone after an RPM or tarball removal, and still present after a Debian removal.

Check User

id batch

Expected: no such user after an RPM or Debian removal, and the account still present after a tarball removal. Xi-Text runs as spooler, so a co-installed Xi-Text has no claim on this account - but a site may have given batch other work, so check before deleting it by hand.

Platform-Specific Considerations

The RPM and the Debian package are Linux formats. On Solaris, AIX and HP-UX the tarball procedure is the only one that applies, and there the de-installer removes the platform's own startup integration for you - the AIX inittab entry, the HP-UX /etc/rc function, or the System V run-level links.

The account is the one thing you may need to remove by hand after a tarball removal, and the command differs:

Troubleshooting

The RPM removal fails on dependencies

the Motif and GTK3 packages each require the main package at exactly the installed version. Remove all three in one rpm -e command rather than reaching for --nodeps, which would leave the desktop packages installed and broken.

btquit does not return

a clean stop takes at least nine seconds and longer on a busy queue. On a systemd installation, check that the unit's stop timeout is long enough for it - if systemd gives up and kills the scheduler part way through, the job and variable files are never written and shared memory is left behind. That is the usual cause of the leftovers this article's IPC section deals with.

The de-installer refuses to start

it needs root and Perl 5 or later, and it must be run from the directory the distribution archive was unpacked into, because it loads its installation modules from beside itself.

Files remain after a tarball removal

that is expected. The de-installer removes directories with rmdir, so any directory containing a file it does not know about is left alone - which is what preserves the spool directory and the licence.

A command still runs after the removal

search by name rather than by owner, since the account may already be gone:

find / -name 'bt*' -path '*bin*' 2>/dev/null
find / -name 'xb-*' 2>/dev/null
find / -name '.xibatch.lic' 2>/dev/null

The licence is gone after a reinstallation

restore the copy taken before the removal into the internal programs directory, and confirm it with xb-checklic. If no copy was taken, the licence has to be reissued.

Complete Removal Checklist

Before:

• Confirm the queue is idle with btjlist - stopping kills running jobs
• Notify users of the outage
• Stop Xi-Batch
• Copy the licence file out of the installation
• Export jobs, variables, command interpreters and user permissions
• Record the holiday calendar, which has no export tool
• Copy the configuration files
• Verify the backup is readable and outside /var/spool/xi

Removal:

• Establish which format the installation came from
• Check for and clear leftover IPC resources, before the package goes
• Remove the package, or run DEINSTALL.sh from the unpacked archive

After:

• No btsched or xbnetserv processes
• No Xi-Batch shared memory and no leftover socket
• Programs gone from the user and internal programs directories
• Spool directory: gone after a package removal, still present after a tarball removal
• Licence file: gone after a package removal, still present after a tarball removal
• /etc/services entries removed by hand if this was a Debian package
• batch account removed by hand if this was a tarball
• Backups verified and their location recorded