Running Xi-Text on Solaris, AIX and HP-UX

Xi-TextXi-Textnetworkingplatformsprintersspaddspstart

You are running Xi-Text on a platform other than the one you are used to, or moving a spooler onto one. This article gives the settings that differ between Linux, Solaris, AIX and HP-UX, and what a move between them requires.

What differs, and what does not

The commands, options and file layout are the same on every platform. What differs is how the operating system names its devices, how it starts services at boot, and how it accounts for users.

One rule underlies all of it: the product is installed as a binary built for one platform, and a configuration moves between platforms as text produced by the conversion tools, never as a copy of the spool directory's state files.

The platforms a build is issued for

These are the platforms a system may be registered against on the customer portal, and therefore the platforms for which a build can be issued:

Linux
Debian 12 and 13, Rocky Linux 8 and 9 (and other Red Hat rebuilds), SUSE Linux Enterprise 15 / openSUSE Leap, Ubuntu 22.04 and 24.04, on x86_64; Debian 13 and Rocky Linux 9 also on aarch64

Solaris
Solaris 10 and 11 on SPARC, Solaris 11 on x86_64

AIX
AIX 7.1, 7.2 and 7.3 on POWER

HP-UX
HP-UX 11.23 and 11.31 on Itanium, HP-UX 11.23 on PA-RISC

Older releases of these operating systems, and platforms retired years ago, are served from the archive of historical builds rather than from current packages. If a platform is not offered when you register a system on the portal, there is no current build for it - ask Xi Software before planning a migration onto it.

Obtaining the right build

Builds are downloaded from the customer portal. Register the machine as a system, choosing its architecture, operating system and version; the portal then lists the builds that match it. Once a system is registered its platform fields are fixed, so a machine that changes platform is registered afresh rather than edited.

On Linux the product is supplied as an RPM or a Debian package, according to the distribution family. On Solaris, AIX and HP-UX it is supplied as a tar.gz containing an interactive installer.

Directories

The compiled-in defaults

The compiled-in defaults are the same on every platform:

• Spool directory: /var/spool/xi/spd
• Printer setup directories: /var/spool/xi/printers
• Internal programs: /usr/libexec/xi
• User commands: /usr/local/bin

Installations that use /usr/spool are older ones that were placed there when /usr/spool was the convention, on Linux as much as on the traditional Unix platforms. The location is a property of the installation, not of the platform. Read the installation's own master configuration file, /etc/xi/textconfig, rather than assuming either layout.

Changing the locations

The packaged installations use the defaults above. The tar.gz installer asks whether you want to change the location of the main directories, and then whether to base them all on a common directory; answering yes gives you base/spd, base/printers, base/progs and base/spuds. There is no command-line option for this - the installer takes no arguments and asks its questions interactively.

The user commands and the PATH

The user commands are installed in /usr/local/bin. Ensure that directory is on the PATH of everyone who uses the product, and of any startup script that calls spstart or sstop - several platforms omit it from root's default PATH.

Accounts

The system account is created for you

You do not normally create the system user by hand. The packaged installations create it in their pre-install step, and the tar.gz installer prints "I need to install user ..." and asks to continue, then creates it with the first free user id from 50. The Xi-Text user is spooler.

Because the id is chosen from whatever is free on each host, the same account usually carries different numeric ids on different machines, and the product works from the name.

If you must create the account yourself before installing - on a host where accounts come from a directory service, for example - create it with the name the product expects and a home directory under the spool area, then run the installation.

Xi-Text reads /etc/passwd and /etc/group directly

Xi-Text builds its own table of user names and ids by reading /etc/passwd and /etc/group directly, line by line, rather than through the system's name-service library. This has one consequence on a platform with centralised accounts:

NIS, LDAP and other directory services are not consulted. A user who exists only in a directory service is not found in that table, and is displayed and exported by number instead of by name, as U1234. Nothing fails; the name is simply wrong everywhere it appears, including in the scripts the conversion tools generate.

If you need names to appear, the accounts that use the product must be present in the local /etc/passwd on the machine running it. This is a good reason to keep the Xi accounts local even where the rest of the estate is centralised.

The table is read once when the scheduler starts, so an account added afterwards is not recognised until the scheduler is restarted.

Printer device names

Printer device names are a property of the operating system, so they are the single most common thing to change when a printer moves between platforms. Typical names:

Serial devices

Linux
/dev/ttyS0, /dev/ttyS1, etc.

Solaris
/dev/term/a, /dev/term/b, etc.

HP-UX
/dev/tty0p0, /dev/tty1p0, etc.

AIX
/dev/tty0, /dev/tty1, etc.

Parallel devices

Linux
/dev/lp0, /dev/lp1

Solaris
/dev/lp

HP-UX
/dev/lp

AIX
/dev/lp0

Confirm the name on the target system before adding the printer; consult the platform's own documentation, since the names above are conventions rather than guarantees.

How Xi-Text reads a device name

A device name that begins with / is used exactly as given. A device name that does not begin with / has /dev/ put in front of it, so a printer added with

spadd -l ttyS0 laser plain

opens /dev/ttyS0 for the printer named laser, whose form type is plain. Both forms of device name are accepted; the short form is the one that has to be re-checked when the platform changes.

Network printers

A printer reached over the network is added with the -N option, and its "device" is then a network address or description rather than a device file:

spadd -N -l printserver:9100 laser plain

The form of that address is interpreted by the printer's network filter command, which a network printer must have - without one the daemon reports "Network printer ... does not have network command specified" and the printer will not start. splist and spq display a network device inside angle brackets, so a device shown as \ is a network printer and not a file called that.

A network printer is the least platform-dependent way to attach a printer, and is the form to consider for any printer that has to come through a platform migration.

The IPC facilities in use

What a running spooler uses

A running Xi-Text uses:

• System V shared memory - for the job queue and the printer list. A further segment appears briefly while a segment is being grown.
• File locks - advisory record locks taken with fcntl() on lock files in the spool directory. No System V semaphores are used, except one set when a networked licence is in force.
• A Unix-domain socket for requests to the scheduler. No System V message queue is used.

All four platforms provide these facilities, so nothing here differs by platform in kind. What differs is the limit each kernel places on shared memory.

Sizing the shared memory

The size of the segments is decided by the job and printer counts given when the product is started, as in spstart 2000 50. Asking for a large queue on a system with a low shared-memory limit is what causes a failure to start, and it is reported as a message naming the segment and the system error, such as "Trouble attaching job data shared memory".

If you see that, either reduce the requested counts or raise the kernel's shared-memory limit using the platform's own tuning mechanism. The default limits on current Linux kernels are large enough for any realistic queue; the older Unix platforms are the ones where tuning is more often needed. Consult the platform's documentation for the current mechanism, as these have changed between releases of every one of these operating systems.

Networking

The service entries

All platforms use /etc/services for service-to-port mapping. The installation adds its own entries if they are not already present. Xi-Text adds:

xitext          2000/tcp        # Connection port
xitext          2000/udp        # Probe port
spq             2100/tcp        # Feeder port
xtnetsrv        2200/tcp        # External job submission
xtnetsrv        2200/udp        # Client access
xtapi           2210/tcp        # Xi-Text API
xtapi           2210/udp        # Xi-Text API

A site may change these, and the product reads the port from /etc/services rather than assuming it, so every machine in a networked installation must agree. Copy the entries rather than retyping them, and open the firewall for the ones you use.

Host resolution

The network configuration lives in /etc/xi/text-hosts. It names the other machines in the installation, and each name is resolved through the system resolver, so /etc/hosts, DNS or a mixture all work provided the answer is consistent on every machine.

Two constraints catch people out when this file is moved between platforms:

• Host addresses are resolved as IPv4. A name that resolves only to an IPv6 address will not be usable.
• The file may begin with a localaddress line giving the machine's own address, and if present it must be the first non-comment line in the file. A localaddress line further down is ignored and the file is flagged as having errors.

Because of the localaddress rule, this file is not simply copied identically to every machine. Keep one master list of the other hosts and prepend each machine's own localaddress line.

Terminal handling

Terminfo and termcap

The character-mode screens - spq and spuser - are curses programs and use whichever terminal database the platform's curses library was built against, terminfo on current systems and termcap on older ones. Ensure a definition exists for the terminal types in use.

Terminal types

Set the TERM environment variable appropriately:

Physical terminals
TERM=vt100, TERM=wyse60, etc.

Terminal emulators
TERM=xterm, TERM=rxvt, TERM=screen

SSH sessions
Usually inherited from the client, commonly xterm or xterm-256color

A TERM value the target platform does not have a definition for causes display corruption in the character-mode screens. Terminal databases differ between platforms, so a TERM setting that works on Linux may have no entry on AIX or HP-UX.

File systems

Maximum path length

The product falls back to a limit of 1024 characters where the platform does not define one. Spool file names and printer setup directories are all built within that limit, so a deeply nested base directory reduces the room left for the rest.

Maximum job size

Job sizes and file positions are held as 32-bit quantities in the saved formats, so a single spooled job is limited to just under 2 GB. This is a property of the format and applies equally on a 64-bit build and a 64-bit platform. Split anything larger before submitting it.

File locking

Locking uses fcntl() advisory record locks, which every supported platform provides. BSD-style flock() is not used.

NFS considerations
Advisory record locking over NFS depends on a working lock manager on both sides and behaves inconsistently in practice. Keep spool directories on local file systems.

Which file systems suit a spool directory

Local file systems (ext4, xfs, zfs, jfs2, vxfs)
Suitable for spool directories

Network file systems (NFS, SMB/CIFS)
Unsuitable, because of the locking behaviour above

Temporary file systems (tmpfs, ramfs)
Unsuitable - the queue would be lost at every reboot

Shells

The platform default shells

Linux
/bin/bash typically default

Solaris
/bin/sh (POSIX shell) or /bin/bash

HP-UX
/bin/sh (POSIX), /bin/ksh available

AIX
/bin/ksh (Korn shell) typically default

Which shell the product uses

Xi-Text uses a standard shell of its own, which is fixed when the build is made - it is the sh found on the machine the build was produced on. You can override it for the installation by setting SHELL in the master configuration file, /etc/xi/textconfig. That is the setting to check first if a printer filter or a control script fails with a "not found" error immediately after a platform change.

The generated scripts

The scripts produced by the conversion tools begin "#! /bin/sh" and use POSIX constructs only, so they replay on every supported platform. Run them with sh; bash is not present by default on stock AIX or HP-UX.

Character encoding

The spooler and its command-line tools do not set a locale, so they run in the C locale whatever LANG or LC_ALL are set to. Setting those variables does not change how Xi-Text handles a job.

What decides the result is the printer setup - the character set the printer is configured for, and any filter the setup runs. Xi-Text passes the job's bytes to that setup, so a file prepared as UTF-8 and sent to a printer configured for a single-byte character set prints the wrong glyphs for anything outside ASCII. The mismatch appears only at printing.

Where accented characters, currency symbols or box-drawing characters come out wrong after a move, compare the encoding the file is now produced in against the character set in the printer's setup rather than adjusting environment variables.

Starting at boot

What the installation sets up

The RPM and Debian packages install a systemd unit and enable it. The unit runs the product's own start and stop commands:

ExecStart=/usr/local/bin/spstart 2000 50
ExecStop=/usr/local/bin/sstop -y

Adjust the numbers on the ExecStart line to size the queue for the site, then reload systemd.

The tar.gz installer detects the platform's startup mechanism and writes the appropriate file:

systemd (current Linux)
a unit file, which the installer also enables

Upstart (older Ubuntu)
/etc/init/xitext.conf

LSB and System V init (older Linux, Solaris)
/etc/init.d/xitext plus rc links, registered with update-rc.d or chkconfig where available

AIX
a line appended to /etc/inittab, in the form xitext:\:once:/usr/local/bin/spstart 2000 50

HP-UX
the installer prints a message that it does not know how to handle HP-UX startups and installs nothing. Add the startup by hand as below.

Whatever the platform, verify after installation that the spooler actually starts on boot - reboot a test machine rather than assuming.

Adding the startup by hand

On a System V style system:

# Create startup script
cat > /etc/init.d/xitext << 'EOF'
#!/bin/sh
case "$1" in
start)
    /usr/local/bin/spstart 2000 50
    ;;
stop)
    /usr/local/bin/sstop -y
    ;;
esac
EOF

chmod 755 /etc/init.d/xitext
ln -s /etc/init.d/xitext /etc/rc3.d/S80xitext
ln -s /etc/init.d/xitext /etc/rc0.d/K01xitext

Use the run level the system actually boots to - the initdefault entry in /etc/inittab - rather than assuming 3, and start the product late (S80 above) so that the network is already up.

Those paths are the Solaris and older-Linux ones. On HP-UX the startup directories are under /sbin, not /etc: write the script as /sbin/init.d/xitext and link it from /sbin/rc3.d and /sbin/rc0.d. HP-UX is the platform the installer leaves alone, so this is the case that most often has to be done by hand.

On a systemd system, if you are adding a unit rather than taking the packaged one:

# Create unit file
cat > /etc/systemd/system/xitext.service << 'EOF'
[Unit]
Description=Xi-Text Print Spooler
After=network.target

[Service]
Type=forking
ExecStart=/usr/local/bin/spstart 2000 50
ExecStop=/usr/local/bin/sstop -y
Restart=on-failure
TimeoutStopSec=330
KillMode=mixed

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable xitext
systemctl start xitext

Type=forking is required - spstart returns once the daemon is running. The generous TimeoutStopSec matters: a graceful stop halts every printer and syncs the spool before releasing the shared memory, which can take longer than systemd's default, and a scheduler killed part way through leaves its shared memory segments behind.

What a platform change requires

Two things are properties of the machine, and stay with it when the product moves to different hardware.

The licence. It is keyed to the machine's hardware signature and to the word size of the build. Renaming a machine leaves a working licence; moving to different hardware calls for new codes, and so does replacing a 32-bit installation with a 64-bit one on the same machine. Register the new system on the portal and obtain codes before the cut-over - Xi Software confirms the registration as a separate step, and a trial licence covers the interval until it does.

The saved state. The job, printer and user files in the spool directory are raw memory images in the machine's own byte order and word size. Copied to a machine of a different byte order or word size, they load without an error and produce an unusable queue. Use the conversion tools on the source machine and carry their text output; those tools apply plausibility checks and usually refuse a file from a foreign machine with "I am confused about the format of your job file".

The model behind both is set out in the concept article on what travels between machines; the export and restore procedure is in the Xi-Text migration article.

What decides throughput

Throughput is dominated by the storage holding the spool directory and by the printers themselves. Two things bear on it:

• Local storage outperforms network storage for spool directories, which brings the locking behaviour described above with it.
• Shared memory is sized once at startup, from the job and printer counts on the start command. Growing a segment while running is supported and involves a copy, so size it generously for the site's busiest day.

Where a specific platform needs tuning, that shows up as a failure to allocate shared memory at startup.

Running on several platforms at once

Consistent directory structure
Use the default locations on every platform unless there is a reason not to. Where you do relocate, record the base directory alongside the installation.

Consistent account names
The generated restore scripts name users and groups by name, so what matters is that every account exists on the target. The numeric ids need not match, and by default they will not.

Network configuration
Maintain one master list of the hosts in the installation and distribute it, prepending each machine's own localaddress line. The files are not byte-identical across machines.

Platform documentation
Record the platform-specific settings for each host - device names, base directories, the startup mechanism in use.

Testing migration scripts
Replay the generated scripts on a non-production machine of the target platform before the real cut-over.

Scheduled maintenance windows
Stop the product before exporting. The saved files are rewritten only every few minutes, so an export taken from a running system can be several minutes behind the queue.

Rollback procedures
Keep the old system available, and its licence intact, during the parallel operation phase.

Checklists for a change of platform

From Solaris to Linux:

• Adjust device names on printers (/dev/term/a becomes /dev/ttyS0, and so on)
• Replace the init.d script with the packaged systemd unit
• Verify terminfo entries exist for the terminal types in use
• Register the new machine on the portal and obtain new licence codes

From HP-UX to Solaris:

• Adjust device names on printers
• Check the shared-memory limit on the target against the queue size you intend to start with
• Confirm the spool directory is on a local file system
• Add the startup script by hand or let the installer write the System V one
• Register the new machine on the portal and obtain new licence codes

From AIX to Linux:

• Adjust device names on printers
• Replace the /etc/inittab entry with the packaged systemd unit
• Check the character set configured in each printer's setup against the encoding of the files now being submitted
• Register the new machine on the portal and obtain new licence codes

Related articles

All articles · Release notes · Contact support