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
The machine's licence has been lost or overwritten, the scheduler will not start, and a permanent licence cannot be obtained in time. This article covers xb-emerglic, which writes a seven-day licence to keep the site running until the permanent one arrives.
What the emergency licence is
xb-emerglic writes a seven-day emergency licence into the product's licence file, /usr/libexec/xi/.xibatch.lic. Every packaging format - RPM, Debian package and portable archive - installs the command on the PATH, in /usr/local/bin on a packaged system.
An emergency licence is a licence record in the same format as any other, keyed to its machine's hardware signature in the same way. Copied to a second machine it is invalid there, and a permanent licence installed over it replaces it.
The two cases it covers
- The licence file was lost or overwritten by a restore or a disc recovery, and the scheduler will not start.
- Production work must run now, and a permanent licence cannot be obtained and installed in time.
A new installation from an RPM or Debian package carries a 30-day trial licence, installed at install time; a portable-archive installation carries a 45-day trial. Licence a test or development machine as you would any other. Replace an emergency licence with a permanent one as the first available action afterwards.
What it requires before it will run
The program checks three things and refuses on any of them.
- You must be root. The command is not installed set-user-id, so it needs a genuine root shell or sudo. Otherwise it prints You have to be superuser to run this and exits 10.
- The scheduler must be stopped. Otherwise it prints It looks like the scheduler is running, please stop first and exits 10.
- The licence file must be readable, or absent. If it is absent the program creates it, so no previous licence is needed. If it exists but is too short to hold a complete licence record, the program prints Cannot read val code??? and exits 4 without writing anything.
A stopped scheduler is detected by the absence of its request socket. After a crash or a SIGKILL the socket file can be left behind, and the program then refuses even though nothing is running. Clear the leftover socket and shared memory with xb-ripc -d first, then run the command again.
Running it
Stop the product with btquit:
btquit -y
Write the emergency licence:
# Non-networked
xb-emerglic -L
# Networked
xb-emerglic -N
The command prints the period it has written:
Your copy is licensed from 12/08/2026 to 20/08/2026
With no option, the program guesses whether a network licence is needed and asks you to confirm. It answers "yes" only if /etc/xi/batch-hosts exists and all four of the Xi-Batch service entries - xibatch, btq, xbnetsrv and xbapi - are present in the system services database. Any one missing and it defaults to "no".
xb-emerglic
Network licence required? [N]
If the existing licence is still valid, the program asks before replacing it, and the default answer is no:
Licence seems to be valid - continue? [N]
Answering N (or pressing return) leaves the licence untouched and exits 100.
Restart the product the way your system normally starts it. The shipped service unit runs:
btstart -j 2000 -v 500 -l 10000
Options, exactly as the program accepts them
| Option | Meaning |
|---|---|
| -L | Local licence - no network use |
| -N | Network licence |
| none | Guess, and prompt for confirmation |
The command accepts no other options. xb-emerglic prints a usage line reading xb-emerglic [-L/N] [days], and reads no day count. A second argument is accepted and then ignored; the period is always seven days. Three or more arguments produce the usage line and exit 1.
So xb-emerglic -N 30 is accepted and gives seven days. An argument that begins with anything other than a hyphen is ignored without comment, and you are prompted instead.
The period is exactly seven days, and cannot be varied
The end date is set seven days ahead of midday UTC on the day you run the command; the start date is set to midday UTC on the previous day, so a clock that is slightly out still leaves the licence valid from the moment it is written. The seven days are compiled in. No option, environment variable or configuration setting changes them.
Verifying it
Check what was written with xb-checklic:
xb-checklic
A successful check prints, with the fields separated by tabs:
Licensed to: Emergency Licence of Xi-Batch
Serial is: 4173
Start time: 11/08/2026
End time: 20/08/2026
Validated for networks
***Emergency licence***
The ***Emergency licence*** line is what identifies it. The site name is fixed text, and the serial number is generated locally and has no meaning outside the machine. Validated for networks appears only if -N was used or the prompt was answered yes.
From four days before the end date, the check adds:
*** NOTE: Licence about to expire ***
What warns you, and what does not
The only warning the product displays is in the interactive queue manager, btq, and its X11 equivalent. It appears once when the program starts, and needs a keystroke to clear:
*** WARNING - You have an emergency licence which ***
*** which will expire in 5 days ***
***************Please type any character to continue**************
It is shown only between 10:00 and 18:00 UTC, Monday to Friday, so an unattended overnight or weekend session is left to run. Nothing else warns: no message is written to the report file, no mail is sent, and jobs and command-line programs run without comment. If nobody at your site uses btq during working hours, the expiry will arrive with no notice at all. Put the end date in a diary.
What happens if it expires
The licence check returns "expired", and the scheduler exits instead of starting. A scheduler already running carries on until it is next restarted; from that restart onwards the machine has no batch scheduling.
Plan to have the permanent licence installed and verified with several days in hand.
Replacing it with a permanent licence
A permanent licence is issued against your serial number through the Xi Software customer portal, and installed with xb-vwrite. Installing it overwrites the emergency licence in the same file; there is nothing to remove first.
btquit -y
xb-vwrite
btstart -j 2000 -v 500 -l 10000
xb-checklic
Check that the output of the verification step names your organisation rather than Emergency Licence of…, and that the ***Emergency licence*** line has gone.
Licence codes issued by the portal expire twelve hours after they are generated, so obtain the code at the time you intend to install it. xb-vwrite refuses to run while the product is up, and exits 10 if it finds the scheduler running.
If the permanent licence has not arrived in time
Where the seven days are running out and the permanent licence is still to come, contact Xi Software and say so. The recovery is finished when the machine holds the licence it is entitled to.
Exit codes
| Code | Meaning |
|---|---|
| 0 | Emergency licence written |
| 1 | Too many arguments |
| 4 | Existing licence file too short to read |
| 10 | Not root, scheduler running, or the licence file could not be opened or created |
| 100 | Existing licence is valid and you declined to replace it |
Where this goes wrong
Running it with the product still up. The command refuses and exits 10. Stop the product first.
# Refused
xb-emerglic -N
It looks like the scheduler is running, please stop first
# Correct
btquit -y
xb-emerglic -N
btstart -j 2000 -v 500 -l 10000
Using the other product's command. On a machine running both products, xb-emerglic licences Xi-Batch and xt-emerglic licences Xi-Text. Running the wrong one leaves the product you meant to fix exactly as it was.
Forgetting to restart. The command writes a file; the licence is read when the scheduler starts. Until you restart, nothing has changed for the running system.
Passing a day count. It is accepted and ignored. You get seven days.
Related articles
Migrating Xi-Batch to Another System
Exporting the schedule, variables, interpreters and users, the restore order, and the holidays gap
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
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