Removing Xi-Batch from a System

Xi-BatchXi-Batchbackup-restorelicensingpackagingremoval

Removing Xi-Batch takes a different amount of the installation with it depending on how it was installed. This article says what each route removes, what to copy out first, and how to confirm the removal afterwards.

What a packaged removal takes with it

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 and asks no questions. Take the backup described below before you start.

Both packaged routes delete /usr/libexec/xi/.xibatch.lic, and a later reinstallation writes a trial licence in its place. Copy the licence file out of the installation before you remove anything, and put it back after any reinstallation: it stays valid on the same machine, and restoring it returns the installation to its own licence.

A tarball installation differs in both respects: its de-installer keeps the licence file, and keeps the spool directory with all your saved state in it. What each removal route removes, below, sets the three routes side by side.

Stopping the scheduler halts the queue and sends SIGKILL to the process group of every job running on this machine, with 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

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 been killed, so an unprivileged attempt still loses the work in progress.
• 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 - the one 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 remain only as the files an upgrade reads once and replaces.

The holiday calendar has no conversion tool, 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 overwrites 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 default 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 # says the default is in force.

Which format the installation came from

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_<variant>
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.

Removing an RPM installation

Step 1: clear leftover IPC resources

Do this before removing the package: xb-ripc, the tool for the job, is part of the package and goes with it. After a clean stop there is normally nothing to clear, and Clearing leftover IPC resources below says how to check.

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_<variant>-gtk3 xibatch_<variant>-motif xibatch_<variant>

# Verify
rpm -qa | grep xibatch

Expected output: nothing.

What the removal has already done

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. Confirm with getent group batch before reaching for groupdel.

Removing a Debian package installation

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

dpkg -r xibatch

# Verify
dpkg -l | grep xibatch

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

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.

Removing 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-<variant>-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.

It reads your master configuration first, so it follows the directories your installation uses.

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 is what makes this route differ from the packaged ones.

What the tarball route leaves behind

• The licence file. .xibatch.lic is left in the internal programs directory, and that directory remains because the file is in it.
• 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 removes

Item	RPM	Debian package	Tarball
Programs, help files, libraries	removed	removed	removed
Saved job queue and variables	deleted	deleted	kept
User permissions, interpreters, holidays	deleted	deleted	kept
Job scripts and scheduler report file	deleted	deleted	kept
Licence file	deleted	deleted	kept
Master config and hosts file	deleted	deleted	deleted
Other files under /etc/xi	deleted with the directory, unless Xi-Text is installed	deleted with the directory, unless Xi-Text is installed	deleted individually
/etc/services entries	removed	left behind	removed if you agree
batch system account	removed	removed	left behind
systemd unit	stopped, disabled, removed	stopped, disabled, removed	disabled and removed
Other startup integration	none installed	none installed	removed, all platforms
Follows relocated directories	standard paths only	standard paths only	yes, from the master config

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, or that a stop timed out part way through, so this is a check rather than 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 for leftovers

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.

Xi-Batch creates no message queues, and creates a semaphore set only when the licence permits networking, so ipcs -q and ipcs -s normally show nothing for Xi-Batch.

Clearing them

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

Confirming the removal

Processes

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

Expected: no results other than the grep itself.

IPC resources

ipcs -m | grep 0x5869b

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

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.

Configuration

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

Expected: no results on every route.

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.

The batch account

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. A site may have given batch other work, so check before deleting it by hand.

On Solaris, AIX and HP-UX

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:

Platform	Command
Linux	userdel batch
Solaris	/usr/sbin/userdel batch
HP-UX	/usr/sbin/userdel batch
AIX	rmuser batch

What goes wrong

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: where systemd gives up and kills the scheduler part way through, the job and variable files are never written and shared memory is left behind.

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.

Related articles

All articles · Release notes · Contact support