Migrating Xi-Text to Another System

Understanding Xi-Text Migration Scenarios

Migration carries the configuration and the queued work of an existing Xi-Text installation onto a different installation. The cases that call for it:

Replacement hardware

Moving to a new server while keeping the print queue and the printers

A different operating system or architecture

The saved state files are raw C structures written by the running daemon, so they are readable only by a build for the same release on the same architecture. The conversion tools exist to bridge that gap

Major release upgrades

Xi-Text release 22 to release 23

Disaster recovery

Rebuilding a system from a backup taken with the same tools

Whatever the reason, the machine changes, and that has one consequence the rest of this article depends on.

The Licence Does Not Move With the System

A migration puts Xi-Text on a different machine, and the licence is tied to the machine it was issued on. The existing licence will not work on the new host, and copying the licence file across does not help. Plan the licence step before you plan anything else: everything below can be done perfectly and the product will still refuse to start without it.

What the licence is bound to

The licence is a small binary block in a hidden file in the internal-programs directory, /usr/libexec/xi/.xitext.lic by default. On Linux the block is encoded against the machine's hardware address - the address of the network interface carrying the most traffic. 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 system with Xi in any case: the entitlement is recorded per system, and support and downloads for the new machine depend on it being registered.

The block is validated by decoding it with the local machine's key and comparing an embedded checksum. On a different machine the checksum does not match, the block is zeroed, and the product reports it as invalid:

xt-checklic
Licence is not valid

The spooler makes the same check at startup and simply exits if it fails. There is no warning, no grace period, and the exit status is deliberately obscure (107 for an invalid licence, 110 for an expired one). A reader who has copied the licence file sees a product that will not start and no obvious reason why.

Getting a licence for the new machine

Licence codes come from the Xi customer portal:

• Sign in with your account reference and the email address held on the account. A one-time code is sent to that address.
• Open the panel for the serial number the old machine used, and choose Register a new system. Give it a label and host name, and pick the architecture, operating system, version and blend of the new machine.
• The registration is confirmed by Xi, not granted on the spot. Allow for that in the migration plan.
• Once the system is active, choose Generate licence codes. The codes are shown on screen, and can be emailed to you.

The codes are short-lived. They carry the time they were generated, and the licensing program compares it against the target machine's clock: codes more than twelve hours old are refused, and so are codes from a machine whose clock is more than six hours behind the moment of generation. Either case gives "Sorry - invalid codes." Generate them when you are ready to apply them, and check the date and time on the target machine first.

Apply them on the new machine, as root, with the spooler stopped:

sstop -y
xt-vwrite

The program asks for the organisation name and serial number, then for the codes. It refuses to run if you are not the superuser, and it refuses to run while the spooler is up.

Where the machine can reach the licence server directly, the codes can be fetched rather than typed:

xt-vwrite -q -I -s 52210000 -o "Your Organisation"

With -q all three of -I (fetch over the network), -s (serial) and -o (organisation) are mandatory; the program exits 20, 21 or 22 if any is missing.

The trial licence buys you the confirmation window

A package installation on a machine with no licence file sets a temporary licence automatically - 45 days from an RPM install, 30 days from a Debian install. That is what covers the period between installing on the new machine and the portal registration being confirmed. It is set only when no licence file exists, so it is not a way to extend an existing licence, and it cannot be re-run over a valid one.

What an Xi-Text Migration Carries

Jobs

The print queue, including the job data files themselves, parameters, ownership and state

Printers

Printer definitions - names, devices, form types, class codes

Printer setup directories

One directory per printer under the printer setup area, holding the device file and the control scripts. These are separate from the printer definitions and are copied as files, not exported

User permissions

Access privileges and per-user defaults, held in the user file

System configuration

The master config and hosts files under /etc/xi

When the Conversion Tools Are Required

A different machine, always

The saved state files are raw structure dumps. Copying them between machines of different architecture, or between builds of different major releases, is not supported. The conversion tools turn them into plain shell scripts, which are portable.

Major release changes

Release 22 to 23 on the same machine. The converters read the older formats and detect which one they have been given: xt-cjlist accepts job files from release 18 to 23, xt-cplist and xt-spuconv from release 16 to 23. A -v option forces a particular release if detection picks the wrong one.

Minor version upgrades

Within the same major release, on the same machine - 23.43 to 23.500, say - stop the product, install the new binaries and restart. No conversion is needed.

File names carry the major release

The user file is named for the major version - spufile23 on a release 23 system, spufile22 on a release 22 one. Look in the spool directory before typing a command that names it.

The Migration Procedure

Step 1: Stop the spooler first

The queue and printer files on disk are rewritten at most every 300 seconds while the spooler runs, so an export taken from a live system can be five minutes out of date. Stopping the spooler flushes both files as the last thing it does.

# On a packaged Linux system
systemctl stop xitext

# Or directly
sstop -y

# Verify
ps -ef | grep spshed

Stopping aborts whatever is printing. Printers that are initialising, running or shutting down are signalled, given a short grace period, and then killed. Jobs arriving over the network from other hosts are dropped from the saved queue file entirely - only local jobs are written. Let the printers drain before you stop if that matters.

Step 2: Create the backup directory

BACKUP_DIR=/var/tmp/textsave
mkdir -p "$BACKUP_DIR/Scripts"

The scripts directory must exist before the job converter is run - the converter checks for it and refuses to start if it is missing.

Step 3: Export jobs, printers and users

The product ships a driver that runs all three converters and the printer setup copy for you, and it is installed by the tarball, the RPM and the deb:

xt-backup

It must be run as root, and it asks where to put the backup. To do the same by hand, with the default spool directory:

xt-cjlist -D /var/spool/xi/spd spshed_jfile "$BACKUP_DIR/joblist.sh" "$BACKUP_DIR/Scripts"
xt-cplist -D /var/spool/xi/spd spshed_pfile "$BACKUP_DIR/ptrlist.sh"
xt-spuconv -D /var/spool/xi/spd spufile23 "$BACKUP_DIR/userlist.sh"

Substitute your own spool directory if it is not the default, or give the literal word SPOOLDIR to -D and let the tool read the configured value. Note that xt-spuconv has no default source directory, so it needs -D or a full path even when the others would manage without.

What each one produces:

• joblist.sh - a shell script of spr commands, one per job, and Scripts/ holding a copy of each job's data file
• ptrlist.sh - a shell script of spadd commands recreating the printer definitions
• userlist.sh - a shell script of spuchange commands recreating the user permissions and defaults

The scripts call the commands by their plain names, so the restoring system needs the user command directory on its PATH.

Step 4: Copy the printer setup directories

Printer setup files are not exported by xt-cplist. They live one directory per printer under the printer setup area, /var/spool/xi/printers by default, and each holds the device file and any control scripts for that printer.

cd /var/spool/xi/printers
tar cf "$BACKUP_DIR/ptrdefs.tar" .

Step 5: Copy the configuration files

cp /etc/xi/textconfig "$BACKUP_DIR/"
cp /etc/xi/text-hosts "$BACKUP_DIR/"

Also under /etc/xi and worth carrying if your installation uses them: Xitext-extern, usermap and pwfile.

Step 6: Install on the new system

Install Xi-Text on the target by the normal route for that platform. A package installation sets a temporary licence at this point, which is what gives you working software while the portal registration is confirmed.

Step 7: Licence the new system

Register the new machine in the portal against your serial, wait for Xi to confirm it, generate the codes and apply them with xt-vwrite as described above. Confirm before going further:

xt-checklic

Step 8: Restore the configuration and the printer setup directories

# Configuration - review rather than overwrite if the new install
# uses different directories
cp "$BACKUP_DIR/text-hosts" /etc/xi/

# Printer setup directories
cd /var/spool/xi/printers
tar xf /path/to/ptrdefs.tar

Take care with textconfig: it records the directories this installation was built and installed with, so overwriting the new machine's copy with the old machine's copy is only right when the two installations are laid out identically.

Step 9: Restore users, then printers, then jobs

Order matters, and so does whether the spooler is running:

# 1. Users. spuchange edits the user file directly and does not
#    need the spooler.
sh "$BACKUP_DIR/userlist.sh"

# 2. Printers. spadd is a link to spstart and will start the
#    spooler itself if it is not already running.
sh "$BACKUP_DIR/ptrlist.sh"

# 3. Jobs. spr requires a running spooler and exits with
#    "Spooler not running" if there is none.
sh "$BACKUP_DIR/joblist.sh"

Step 10: Verify

# Printers
splist

# Jobs
sqlist

# Users
spulist

Use splist, sqlist and spulist rather than spq or spuser for this. spq and spuser are full-screen interactive programs and are no use in a script or over a connection without a working terminal type.

What the Export Does Not Carry

The conversion tools cover the configuration and the queue. Several things a reader would expect to survive do not, and nothing warns them:

The licence

Covered above. Nothing in the export touches it.

Job numbers

Nothing in the generated commands sets a job number. The destination allocates new ones, so any external record that refers to a job by number is broken by the migration.

Job output files

Only the redirection settings are carried. Output already produced on the old system stays there.

Logs and report files

spshed_reps is not exported. Keep it with the old system if you need the history.

Printer setup directories

Copied as files in step 4, not exported. Skip that step and the printers are recreated with nothing to drive them.

Jobs whose data file has gone

The job converter copies each job's spool file into the scripts directory. A queue entry whose file has already been removed is dropped from the export without a message and without affecting the exit status. Compare the job count before and after.

Editing the Generated Scripts

The generated scripts are plain text and can be edited before they are replayed. Common changes:

Selective restoration

Delete or comment out the lines for jobs or printers you do not want

Parameter changes

Edit a command in place to change an owner, a priority or a path

Filtering

Cut the file down with grep. The job owner is set with -u and the group with -g:

# Only restore jobs owned by jsmith
grep '^spr .*-u jsmith' joblist.sh > joblist-jsmith.sh

Each spr line ends with the path of the job's data file in the scripts directory, so moving or renaming that directory breaks every line in the file.

Common Migration Patterns

Test migration before production

Restore to a test system first and verify, then migrate production. A test system needs its own licence - register it in the portal as a separate system

Selective migration

Carry the printers and users and start with an empty queue

Incremental migration

Restore users and printers first and let new work be submitted to the new system, rather than restoring the old queue

Parallel operation

Run both systems during the transition and let the old one finish its existing work. Both need a valid licence for as long as they run

Platform-Specific Considerations

Run the converters on the source machine

The state files are raw structure dumps, and a file written by a big-endian build is not reliably readable by a little-endian one. The shell scripts the converters produce are plain text and cross the gap safely.

Directory differences

The current defaults are /var/spool/xi/spd for the spool directory and /var/spool/xi/printers for the printer setup files. Older installations used paths under /usr/spool. Edit the scripts if the two installations differ.

User and group IDs

The generated commands name users and groups by name, so the accounts must exist on the target. Where they do not, the affected lines fail.

Device names

Printer device paths differ between platforms. Update the printer setup directories and the spadd lines accordingly.

Character sets

A printer's character set is part of its setup, not of the job. After a move, compare the encoding your files are now produced in against the character set the printer is configured for.

Network addressing

Update /etc/xi/text-hosts if hostnames or addresses change.

Verifying a Successful Migration

Licence

xt-checklic reports the organisation, serial and expiry. Do this first - nothing else can be verified until the product runs

Counts

Compare job, printer and user counts against the old system, and account for any difference. A silently dropped job shows up here and nowhere else

User access

Check that ordinary users can submit work and view the queue

Printer operation

Print a test job to every migrated printer

Network operation

If networked, check remote submission and shared printers

Troubleshooting

"Licence is not valid" or the spooler exits at startup

The licence was issued for the old machine. Register the new system in the portal and generate fresh codes. Copying the licence file across cannot work

"Sorry - invalid codes." from xt-vwrite

The codes have gone stale or the machine clock is wrong. Check the date and time, then generate the codes again

"Spooler not running" during restore

spr needs the spooler running. Start it before running the job script

The printers start but produce nothing

The printer setup directories were not copied. Restore them from step 4's archive and start the printers again

Permission denied errors

The restore scripts assume the privileges of whoever runs them. Run them as root or as an account holding the relevant Xi privileges

Users appear by number rather than by name

Xi-Text reads /etc/passwd directly rather than through the system's name service, so an account that exists only in a directory service is exported and displayed by number. Add the accounts locally on the machine running the product