Why a change of machine is a change of substance
Moving a working installation onto a different machine looks like a copying job and is not one. Two of the things the installation depends on are properties of the machine it runs on rather than of the configuration you built: the form in which the product saves its live state, and the licence that lets the product start at all. Neither is carried by copying files, and both have to be planned for deliberately.
This article states that model. The commands, file names and procedures that act on it are in the Xi-Text and Xi-Batch articles.
The saved state is written for one machine
While the product runs it holds its live queue in memory. It writes that state out periodically, and flushes it as the last act of a clean shutdown. What it writes is a raw memory image, in the machine's own byte order and word size.
There is no version marker in it, no byte-order marker and no checksum, and the daemon does not validate the image when it loads it. So a saved state carried to a machine of a different byte order or a different word size does not produce an error: it produces a queue full of nonsense. Nothing warns the reader, and the damage is discovered later, in use.
The same is true across a major release change on the same machine, because the layout of the structures changes with the format version.
One further consequence of the state being written periodically rather than continuously: an export taken from a running system can be behind the live queue by however long it is since the last write. Stopping the product first is what makes an export current, and it is the reason every export procedure begins with a stop.
The exported text does travel
This is what the conversion tools exist to solve. Each of them reads a saved state file and writes a plain text script of ordinary commands, with every value written out as text. Text has no byte order and no word size, so the script replays on any supported platform.
The rule that follows is short and it is the whole method: run the conversion on the machine the state came from, carry the text, and replay it on the target. The conversion tools are the bridge, and they only work in that direction - they read the format their own machine wrote.
They also apply plausibility checks to what they are given and will usually refuse a state file from a foreign machine rather than convert it into nonsense. That refusal is a protection and is worth respecting rather than working around.
The licence is bound to the machine
A licence is a small binary record held on the machine it was issued for. On Linux the record is checksummed against the machine's hardware address - specifically the address of the network interface carrying the most traffic. It carries no record of the operating system and no record of the host name.
Three things follow, and they are the three questions readers arrive with:
- Renaming a machine leaves a working licence
- the host name forms no part of the binding.
- Moving to different hardware does not
- whether or not the platform changes, the machine has changed, and the licence was issued for the old one.
- Copying the licence across achieves nothing
- it is the contents of the record that are keyed to the old machine, so it fails on arrival. The record fails its checksum, is discarded, and the product reports the licence as invalid. The daemon makes the same check when it starts and simply exits, without a warning and without a grace period. A reader who has copied the licence sees a product that will not start and no obvious reason why.
The binding works differently on the other supported platforms, and a licence there may survive a move that would break it on Linux. Register the new machine in any case: the entitlement is recorded per system, and support and downloads for that machine depend on it being registered.
The licence is also bound to the word size of the build. The record is read back as a fixed-size structure whose length depends on whether the build is 32-bit or 64-bit, so replacing a 32-bit installation with a 64-bit one needs a new licence as well, even on the same machine with the same hardware address.
On a machine where more than one interface is active, which one carries the most traffic can change. A licence that validated yesterday can therefore stop validating after a reboot, a failover, or the arrival of a bonded or virtual interface. The symptom is identical to the migration case and so is the remedy.
Licensing is an event, not a file update
Because the licence belongs to the machine, obtaining one is a transaction with Xi Software rather than an edit to a system. Four properties of that transaction shape every licensing procedure:
- Registration is confirmed rather than granted
- a new machine is registered against a serial and the registration is confirmed by Xi Software, not issued on the spot. Allow for that in any plan with a cut-over date in it.
- One serial has one live machine
- issuing a licence registers the requesting machine against the serial and retires whichever machine was live on it before. A test system licensed against a production serial takes the production machine's registration with it.
- The two products are separate entitlements
- Xi-Text and Xi-Batch hold separate serials, and each product's licence covers only itself. A site running both licenses both.
- Licence codes are short-lived
- they carry the moment they were generated and are checked against the clock of the machine they are applied to. Obtain them at the time you intend to use them, and check the target machine's date and time before you do.
A fresh installation with no licence at all is given a trial, and the trial is what covers the interval while a registration is confirmed. It is set only where no licence is present, so it is not a way to extend an existing one.
An emergency licence is an ordinary licence record
Both products can write a short-term emergency licence for a machine whose licence has been lost or damaged. It is not a separate mode or a degraded state: it is a normal licence record in the normal format, bound to the machine's hardware address in exactly the same way, and it is superseded simply by installing a permanent licence over it. There is nothing to remove first.
Two consequences matter. An emergency licence cannot be copied to another machine any more than a permanent one can. And when it runs out the product does not degrade - the licence check reports it as expired and the daemon exits instead of starting, so the machine has no spooling or no scheduling at all from its next restart onwards. An emergency licence is a bridge to a permanent one and not a licensing route in its own right.
What an export does not carry
The conversion tools cover the configuration and the queue. Several things a reader expects to survive do not, and nothing warns them at the time:
- The licence
- covered above. Nothing in an export touches it.
- Job numbers
- the generated commands do not set them. The destination allocates its own, so any external record that refers to a job by number is broken by the migration.
- Output already produced
- only the redirection settings travel. Work that has already run and produced output leaves that output on the old machine.
- The system-wide settings
- the values that govern scheduling limits and logging are not exported. They come back at their defaults on the new machine, which silently turns off anything that was switched on by setting them. Set them again after the migration and check that they took.
- Logs and report files
- the daemons' report files and any activity log stay with the old system. Keep the old machine's copies if you need the history.
- Anything with no converter
- the tools cover the objects they were written for and no others. Where a category of configuration has no conversion tool, it is carried by hand or not at all, and the product-specific article says which those are.
- Queue entries whose data has already gone
- an entry whose spooled file has been removed is dropped from the export without a message and without affecting the exit status. This is why the counts are compared before and after rather than assumed.
What follows from all this
- Plan the licence step first. Everything else can be done perfectly and the product will still refuse to start without it.
- Stop the product before exporting, so that what you export is what was in the queue.
- Convert on the source machine and carry the text, never the raw state.
- Compare the counts on the new machine against the old one and account for every difference. A silently dropped entry shows up there and nowhere else.
- Treat a platform change as a re-licensing event, and a word-size change as one too.