Renewing an Xi-Batch Licence Without an Operator
Scheduling the stop, running xb-vwrite non-interactively, reading xb-checklic, and what the exit statuses mean
An Xi-Batch licence with an end date can be renewed from a script: the product fetches the codes from the licence server and installs them without anyone typing them in. This article says what the script has to do around that, and which exit statuses mean the renewal worked.
The renewal is an outage
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". The script therefore stops Xi-Batch, writes the licence and starts it again. Stopping kills running jobs, so schedule the renewal 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.
The options that drive this were added in 2024, so an older installation may not have them.
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 options an unattended renewal uses
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, 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 for the codes. 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.
The commands
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 Xi-Batch serial. 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.
The same run converts a trial licence to a full one. xb-vwrite opens the existing licence file and writes the new record over whatever is there, so a trial is replaced in one run with nothing to remove first.
The renewal script
The script stops the product, starts it again whatever happens, and reads the exit status. 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. Once that licence has expired the scheduler exits at startup and the product stays down, so schedule the renewal comfortably before the end date.
Schedule it from cron. The product is down for the duration of the run, and 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.
Reading the current licence
The command takes no options and runs 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, too late to trigger 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.
What the renewal requires
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.
Outbound network access to the licence server
The machine resolves licserv.xisl.com and opens a TCP connection to port 1999. The connection is direct TCP over IPv4, so a rule permitting outbound web traffic does not cover it, and no proxy is 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, 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.
Exit statuses
Treat 0 and 2 as success, and alert on the rest:
| Status | Meaning |
|---|---|
| 0 | Networked licence written |
| 2 | Local (non-network) licence written - also a success |
| 10 | Refused before doing anything: not root, the product still running, or the licence file could not be opened |
| 20 | -q given without -o |
| 21 | -q given without -s |
| 22 | -q given without -I |
| 23 | The codes could not be fetched - server unreachable, or the request refused |
| 109 | The codes were fetched but rejected: "Sorry - invalid codes." |
The write itself is the last thing xb-vwrite does, so any of these failures leaves the existing licence file untouched.
When a renewal suits automation
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 is a stop and a start, and the stop kills running jobs, so it belongs where a stop is already acceptable. Where the host also runs Xi-Text, cover both products in the one window.
Several installations
One reviewed script deployed to many hosts is more reliable than the same procedure typed repeatedly.
When to renew by hand
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.
What the failures mean
"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 condition is on the account or its cover. 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.
Related articles
Installing an Emergency Seven-Day Licence on Xi-Batch
Recovering a system whose licence has been lost or damaged with xb-emerglic, and replacing it with a permanent licence
Migrating Xi-Batch to Another System
Exporting the schedule, variables, interpreters and users, the restore order, and the holidays gap
Renewing an Xi-Text Licence Without an Operator
Scheduling the stop, running xt-vwrite non-interactively, reading xt-checklic, and what the exit statuses mean