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
A term licence for Xi-Text has to be replaced before its end date. Xi-Text can fetch the replacement codes from the Xi Software licence server and install them without anyone typing them in, so the renewal can be driven from a script. This article gives the options, a renewal script, and the exit statuses the script has to test.
The renewal is an outage
xt-vwrite refuses to run while the product is running - it looks for the spooler's request socket and exits with status 10 and the message "It looks like the scheduler is running, please stop first". The script stops Xi-Text, writes the licence and starts it again. Stopping aborts whatever is printing, 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 fetch and apply them in the same run.
Hosts with no route to the licence server
Where the machine cannot reach the licence server, generate the codes in the customer portal and run xt-vwrite interactively to type them in.
Confirming the build has the non-interactive options
The options were added in 2024, so an older installation may not have them. Run this as an ordinary user - it refuses to do anything either way:
xt-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 xt-vwrite options for an unattended renewal
Non-interactive mode (-q)
Ask no questions. Requires -o, -s and -I as well; without any one of them xt-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. Nothing checks it against your registration.
Serial number (-s)
The serial for Xi-Text. Xi-Text and Xi-Batch are separate entitlements with separate serials; xt-checklic reports Xi-Text'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, xt-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 The exit statuses.
Renewing in one run
systemctl stop xitext
/usr/local/bin/xt-vwrite -q -I -s 12345678 -o "Your Organisation"
systemctl start xitext
Replace "Your Organisation" with your organisation name and the serial with your own. On an installation with no systemd, stop and start Xi-Text with sstop -y and spstart 2000 50, which are the commands the shipped service unit runs.
The same run converts a trial licence to a full one. xt-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.
A renewal script
The script stops the product, starts it again on every path, and tests the exit status against both of its success values. A successful write of a local (non-network) licence exits with status 2, so the shell idioms xt-vwrite && echo renewed and if xt-vwrite; then report failure every time the renewal works.
#!/bin/sh
# renew-xitext-licence.sh - renew the Xi-Text licence and restart it.
# Run as root, from a directory that contains no README file.
SERIAL=12345678 # the Xi-Text serial
ORG="Example Corporation"
cd /var/tmp || exit 1
systemctl stop xitext || {
logger -t xi-renew "Xi-Text would not stop - licence not renewed"
exit 1
}
/usr/local/bin/xt-vwrite -q -I -s "$SERIAL" -o "$ORG"
status=$?
systemctl start xitext
# 0 = networked licence written, 2 = local licence written.
if [ $status -eq 0 ] || [ $status -eq 2 ]; then
logger -t xi-renew "Xi-Text licence renewed"
exit 0
fi
logger -t xi-renew "Xi-Text licence renewal failed, xt-vwrite exit $status"
exit 1
A failed renewal therefore leaves the product running on the licence it had. Once that licence has expired the spooler exits at startup and the product will not come back, so schedule the renewal comfortably before the end date.
Schedule it from cron. The product is down for the duration of the run:
# 03:00 on the first of each month - Xi-Text is stopped while this runs
0 3 1 * * /usr/local/sbin/renew-xitext-licence.sh
Cron starts the job in the invoking user's home directory: xt-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.
Run xt-checklic after a renewal: the new end date confirms the write.
Reading the current licence
The command takes no options and runs while the product is running:
xt-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.
Schedule from the end date. The "*** NOTE: Licence about to expire ***" line appears only within the last four days.
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 a renewal needs
Root
xt-vwrite exits 10 with "You have to be superuser to run this" for any other user.
The product stopped
xt-vwrite exits 10 while the spooler is up.
Outbound network access to the licence server
The machine resolves licserv.xisl.com and opens a direct IPv4 TCP connection to port 1999. A rule permitting outbound web traffic does not cover it, and no proxy is used.
The Xi-Text serial
Held against your account at Xi.
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 xt-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.
Where the host also runs Xi-Batch, one maintenance window covers both products.
The exit statuses
Treat both 0 and 2 as success:
| 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 xt-vwrite does, so any of these failures leaves the existing licence file untouched.
What the failure messages 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 xt-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-Batch's serial. Compare it with the output of xt-checklic.
"Network licence error: On credit hold ..." or "... Contract expired ..." (status 23)
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-Text
Recovering a system whose licence has been lost or damaged with xt-emerglic, and replacing it with a permanent licence
Migrating Xi-Text to Another System
Exporting the print queue, printers and users with xt-backup, and restoring them on a newly licensed machine
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