Renewing an Xi-Batch Licence Without an Operator

What Can and Cannot Be Automated

Xi-Batch can fetch licence codes from the Xi Software licence server and install them without anyone typing them in, so a renewal can be driven from a script. The options that make this possible were added in 2024, so an older installation may not have them; the check is below.

What cannot be automated away is the stop. xb-vwrite refuses to run while the product is running - it looks for the scheduler's request socket and exits with status 10 and the message "It looks like the scheduler is running, please stop first". An automated renewal is therefore an automated outage: the script stops Xi-Batch, writes the licence and starts it again. Stopping kills running jobs, so the renewal has to be scheduled in a window that can absorb that.

The codes are checked against the machine's clock when they are applied, so they are fetched and applied in the same run. Fetching them in advance and applying them later does not work.

To confirm your build has the non-interactive options, run this as an ordinary user - it refuses to do anything either way:

xb-vwrite -q

A build that has the options answers "You have to be superuser to run this". A build that does not answers with an invalid-option message first.

The xb-vwrite Options for Unattended Renewal

Non-interactive mode (-q)

Ask no questions. Requires -o, -s and -I as well; without any one of them xb-vwrite exits 20, 21 or 22 respectively.

Organisation name (-o)

The name as it should appear on your output, up to 79 characters. Quote it if it contains spaces. It is recorded with the request and written into the licence file; it is a label, not a credential, and nothing checks it against your registration.

Serial number (-s)

The serial for Xi-Batch. Xi-Batch and Xi-Text are separate entitlements with separate serials; xb-checklic reports Xi-Batch's own.

Fetch the codes over the network (-I)

Contact the licence server rather than expecting the codes to be typed in. The opposite is -n, which is the default.

Networked or local licence (-N / -L)

Ask for a networked licence or a local one. With neither, xb-vwrite decides for itself from whether the hosts file and the product's service entries are present on the machine. Which one you get changes the exit status - see Error Handling.

Basic Usage

systemctl stop xibatch
/usr/local/bin/xb-vwrite -q -I -s 87654321 -o "Your Organisation"
systemctl start xibatch

Replace "Your Organisation" with your organisation name and the serial with your own - the Xi-Batch serial, not Xi-Text's. On an installation with no systemd, stop and start Xi-Batch with btquit -y and btstart -j 2000 -v 500 -l 10000, which are the commands the shipped service unit runs.

Automated Renewal Script

A renewal script has three jobs beyond calling xb-vwrite: stop the product, start it again whatever happens, and interpret the exit status correctly. A successful write of a local (non-network) licence exits with status 2, so the obvious shell idioms - xb-vwrite && echo renewed or if xb-vwrite; then - report failure every time the renewal works.

#!/bin/sh
# renew-xibatch-licence.sh - renew the Xi-Batch licence and restart it.
# Run as root, from a directory that contains no README file.

SERIAL=87654321                 # the Xi-Batch serial
ORG="Example Corporation"

cd /var/tmp || exit 1

systemctl stop xibatch || {
    logger -t xi-renew "Xi-Batch would not stop - licence not renewed"
    exit 1
}

/usr/local/bin/xb-vwrite -q -I -s "$SERIAL" -o "$ORG"
status=$?

systemctl start xibatch

# 0 = networked licence written, 2 = local licence written.
if [ $status -eq 0 ] || [ $status -eq 2 ]; then
    logger -t xi-renew "Xi-Batch licence renewed"
    exit 0
fi

logger -t xi-renew "Xi-Batch licence renewal failed, xb-vwrite exit $status"
exit 1

The product is started again on every path, so a failed renewal leaves it running on the licence it had rather than stopped. That matters only while the old licence is still valid: once it has expired the scheduler exits at startup and the product will not come back, which is the reason to schedule the renewal comfortably before the end date rather than on it.

Schedule it from cron, remembering that the product is down for the duration of the run and that no job runs while it is:

# 03:00 on the first of each month - Xi-Batch is stopped while this runs
0 3 1 * * /usr/local/sbin/renew-xibatch-licence.sh

Choose an hour with no scheduled work in it. Cron starts the job in the invoking user's home directory: xb-vwrite reads a file called README in its current directory and, if a line in it mentions a serial, uses that number in preference to the one given with -s. The script above changes directory to /var/tmp for that reason.

Checking the Current Licence

Before automating renewal, verify the current licence details. The command takes no options and can be run while the product is running:

xb-checklic

A valid licence reports the organisation it is licensed to, the serial, and the start and end dates as dd/mm/yyyy - or "No limit" for a perpetual licence, which has nothing to renew. "Validated for networks" appears for a networked licence and "***Emergency licence***" for an emergency one.

Use the end date to decide the schedule. The "*** NOTE: Licence about to expire ***" line appears only within the last four days, which is too late to be a useful trigger for an automated job.

The exit status is 0 when the licence is valid, including during those last four days. It is 107 with "Licence is not valid" when the licence file does not decode on this machine, 110 with "Licence expired, expiry date was ..." when the end date has passed, 10 when there is no licence file at all, and 11 when the file is too short to be one.

Requirements

Root

xb-vwrite exits 10 with "You have to be superuser to run this" for any other user.

The product stopped

xb-vwrite exits 10 while the scheduler is up. Renewal is an outage.

Outbound network access to the licence server

The machine resolves licserv.xisl.com and opens a TCP connection to port 1999. This is a direct connection over IPv4, not HTTPS, so a rule permitting outbound web traffic does not cover it and a proxy is not used.

The Xi-Batch serial

Held against your account at Xi. Xi-Batch and Xi-Text have separate serials.

An organisation name

Up to 79 characters; it appears on your output.

A correct machine clock

The codes carry the time they were generated and are rejected if the machine's clock differs from it by more than a few hours.

What the Licence Server Checks

A request is answered with codes only when the serial is known and held by exactly one account, that account is not on credit hold, and - where a support contract covers the serial - cover is in force. A refusal comes back as text, which xb-vwrite prints as "Network licence error: ..." before exiting 23. The wordings are "Unknown serial", "Duplicate serial", "On credit hold", "Contract expired" and, at some sites, "No contract", each naming the serial or the account. These are commercial conditions rather than faults on your machine, and a retry will not clear them.

Every issue is recorded against the serial together with the machine that asked for it. One serial has one live machine: issuing codes registers the requesting machine against the serial and retires any other machine currently registered as live on it. Run the renewal only on the machine that is meant to be running that serial - a test system renewing against a production serial takes the production machine's registration with it.

Best practices:

• Schedule the renewal against the end date reported by xb-checklic, with enough margin to notice a failure and act on it
• Where the host also runs Xi-Text, use one maintenance window covering both products rather than two separate outages
• Point a test system at its own serial, never at a production one
• Alert on the script's own exit status rather than retrying in a loop - the failures that matter are commercial or network faults that a retry cannot fix

Error Handling

Automated scripts must check the exit status, and must treat both 0 and 2 as success:

The write itself is the last thing xb-vwrite does, so any of these failures leaves the existing licence file untouched.

When Automation Is Appropriate

Licences with an end date

A term licence that has to be replaced on a known date. A perpetual licence reports "No limit" and needs nothing.

Hosts with outbound access to the licence server

Port 1999 open outbound, and DNS working.

An existing maintenance window

The renewal costs a stop and a start, and the stop kills running jobs, so it belongs where a stop is already acceptable.

Several installations

One reviewed script deployed to many hosts is more reliable than the same procedure typed repeatedly.

When Manual Renewal Is Preferred

Perpetual licences

Nothing expires, so there is nothing to schedule.

Air-gapped systems

With no route to the licence server the codes are generated in the customer portal and typed in, and xb-vwrite is run interactively.

Systems that cannot be stopped unattended

If nobody can confirm the scheduler came back and the schedule resumed, do it by hand.

High-security environments

Where a change to a production host needs approval before it happens.

Trial and evaluation systems

A trial licence is a one-off; converting it to a full licence is a single supervised run of xb-vwrite, not a recurring job.

Troubleshooting

"It looks like the scheduler is running, please stop first" (status 10)

The product was still up. Check that the stop in the script succeeded before xb-vwrite ran.

"You have to be superuser to run this" (status 10)

Run the job as root.

"Must specify site/organisation name with non-interactive" (20), "Must specify seral with non-interactive" (21), "Must specify network fetch with non-interactive" (22)

-q was given without -o, without -s, or without -I. The misspelling in the second message is the product's own.

"Cannot locate licence server" (status 23)

The name licserv.xisl.com did not resolve. Check DNS on the host.

"Cannot connect to licence server" (status 23)

The name resolved but the connection failed. Check that outbound TCP to port 1999 is permitted - a rule that allows HTTPS does not.

"Network licence error: Unknown serial ..." (status 23)

The serial is not one Xi holds for your account, or it is Xi-Text's serial. Compare it with the output of xb-checklic.

"Network licence error: On credit hold ..." or "... Contract expired ..." (status 23)

The account or its cover, rather than the machine. Contact Xi Software; retrying will not help.

"Sorry - invalid codes." (status 109)

The codes did not match the machine's clock. Check the date and time on the host and run the renewal again.

The renewal reports failure every time although the licence is written

The script is treating the exit status as a boolean. A local licence exits 2 on success.

A serial other than the one in the script was used

There is a README file in the directory the job ran from and it mentions a serial. Run from a directory that has none.

xb-checklic says "Licence is not valid" straight after a successful renewal

The licence is encoded against the hardware address of the machine's busiest network interface, so a change in which interface that is - a failover, a new bonded or virtual interface - invalidates it. Re-run the renewal on the machine in its settled state.