HELIOS EtherShare 2.6 User manual

A 7: Technical notes
The following section contains miscellaneous technical information about EtherShare which is primarily of interest to experienced system administrators only.
A 7.1 EtherShare log files
The following describes the structure of the EtherShare printer log file and server log file. Please refer to your UNIX manuals for a description of the "system messages" file. All three files can be inspected in the EtherShare Admin by choosing the appropriate item in the Lists menu.
Printer log file structure
Each entry in the printer log file "$ESDIR/printer.acct" (with the appendices ".0", yesterday to ".6", seven days ago) has the following format:
status, ptrName, "username", "JobTitle",
startTime, duration, pages, ListOfFonts

status (decimal):
3 general UNIX warning
2 PostScript output
1 UNIX info (e.g. Extended print information)
0 OK
-1 communications error
-2 PostScript error
-3 terminated job (e.g. killed signal)
-4 UNIX error (e.g. file not found)
ptrName (string): logical (UNIX) printer name
"username" (string): from PostScript header of job
"JobTitle" (string): i.e. document name, from PostScript header of job
startTime (decimal): seconds since 1.1.1970 (UNIX time_t values)
duration (seconds): = endTime-startTime
pages (decimal): = endPage-startPage (determined by printer interrogation with the "pagecount.ps" query.
ListOfFonts (string array): fonts used, space delimited
If status0, the line is followed by the error output of the printer, bracketed by the lines "Error output:" and "End error output". Also, if no printable data are sent to the printer (pages=0), then duration will be "0".
Please refer to mail in chapter 11.6 "Configuring printers manually" for information on which types of message are written to the printer log file. Messages are only written to the printer log file if you checked the Accounting File switch when creating the printer queue with the EtherShare Admin.
User and
document names
in print jobs
The user name logged with each print job in the printer log file "$ESDIR/printer.acct" (and the user to which error messages are sent as mail) is determined by interrogating the PostScript header of the job for the name in the "%%For" comment.
Under Macintosh System 7.x or later, the name in the "%%For" comment is automatically set to the user name specified in the Macintosh's "Sharing Setup" control field.
If the "%%For" comment or the name field is missing, all jobs will be allocated to "nobody" by default.
If a name is specified but it cannot be found in the list of long or short names in "/etc/passwd", the specified (unknown) user name will still appear in the printer log file, but any error messages are sent as mail to "nobody" instead.

Note: If you check Save My Name Only or Save My Name and Password in the Macintosh Chooser, the name saved in the system may not be the same as the name in the File Sharing control field, since it is possible to overwrite the prompted name before saving it. The name stored in File Sharing is the one used by the log file.

The document title is determined by interrogating the PostScript header of the job for the name in the "%%Title" comment.
It may be possible for you to set these comments for UNIX and MS-DOS print jobs, too, in order to ensure that they also have complete records in the printer log file.
Server log file structure
Each entry in the server log file "$ESDIR/server.acct" (with the appendices ".0", yesterday to ".6", seven days ago) has the following format:
status, svrName, ws_address, pe_status, usrname,
startTime, duration, usrTime, sysTime, rusage

status = 1 (normal login)
svrName (string): server name
ws_address (string): workstation network address (TCP/IP or AppleTalk)
pe_status (decimal): UNIX process exit status (0 = OK; 1...127 = error exit, i.e. the program has been terminated; 128... = abnormal termination, ask your system administrator)
usrname (string): user login name
startTime (decimal): login time, seconds since 1.1.1970 (UNIX time_t values)
duration, seconds: = endTime-startTime
usrTime (decimal): processor time consumed by user process
sysTime (decimal): processor time consumed by the process while in system mode
rusage (decimal array): = resource usage information. The structure is operating system dependent - see the description of "getrusage" in your UNIX documentation. Some of the resource usage fields are decoded and used by the EtherShare Admin in the "Server log file" window.
Each entry in the server log file "$ESDIR/server.acct" has the following format for an unsuccessful login:
status, svrName, ws_address, pid, name, time
status = 2 (bad login)
svrName (string): server name
ws_address (string): workstation network address (TCP/IP or AppleTalk)
pid: process ID
name (string): attempted login name
time (decimal): attempted login time, seconds since 1.1.1970 (UNIX time_t values)
A 7.2 PostScript RIP INITs in the EtherShare Admin
Printer INITs in the EtherShare Admin must not contain the "exitserver" operator, because the following print job will not execute properly. This is because the INIT is sent to the printer in the same PAP (RIP) session as the following job.
Discussion: The INIT does not normally need to permanently change the server dictionary, because it automatically pre-fixes each and every print job. Furthermore, it is not recommended to try and change the server dictionary in an Admin INIT, because serverdict information is written each time you print to RIP EEPROM, and the latter has a programming life of 10,000 cycles only.
Solution: Simplify the INIT by removing the "exitserver" operator.
If possible, the INIT should also be designed to test the parameter it wants to change first, in order to see if the parameter already has the required value. This saves RIP processing time. For example:
INIT recommended in the RIP manual:
serverdict begin 0 exitserver
statusdict begin 2400 setresolution end

INIT recommended for use in EtherShare Admin:
statusdict begin
resolution 2400 eq not {2400 setresolution} if

The EtherShare Admin can be extended with custom PostScript calibration tools, which appear automatically in the Edit Initialization menu. HELIOS will provide on request programming guides for developing such tools to typesetter manufacturers.

Note: INITs cannot contain PostScript code to interrogate the RIP because at present, there is no way of returning the response to the EtherShare Admin.

Important: Please contact your RIP supplier and not HELIOS if you have any problems and/or questions regarding RIP INITs or RIP configuration.

A 7.3 Using the ISO-8859-1 character set under IBM AIX 4
Starting with AIX version 3.2, IBM supports two character sets for all text displayed by application programs and system utilities. The two supported character sets are IBM-850 (IBM-PC style) and ISO 8859-1 (DEC VT200 style). AIX 3.1 supported the IBM-850 character set only.
Helios Terminal is a DEC VT320 emulator and thus uses the ISO-8859-1 character set. By default, AIX uses IBM-850 encoding and thus all national accented characters such as German umlauts will not display properly. The "LANG" environment variable determines the encoding used. If the first letter of the "LANG" variable is in upper case, IBM-850 encoding is used, if the first letter is lower case, ISO-8859-1 is used. For Germany this would be:
LANG=de_DE for ISO-8859-1
LANG=De_DE for IBM-850
The "LANG" environment variable can be set locally in your ".profile" or ".login" files or globally as the default for the whole system with SMIT using the following SMIT menu path:
System Environments
-> Manage Language Environment
-> Change Language Environment

Unfortunately, not all message catalogs are available in all character sets. Luckily, SMIT has a menu option to convert message catalogs from one character set to another. Use the following SMIT menu path to do this:
System Environments
-> Manage Language Environment
-> Convert Files
-> Convert System Messages

You then specify inputs similar to the following (the example converts the German catalogs):
* CURRENT DIRECTORY name [/usr/lib/nls/msg/De_DE] +
NEW DIRECTORY name [/usr/lib/nls/msg/de_DE]
CURRENT CODE set [IBM-850] +
NEW CODE set [ISO8859-1] +

This converts all messages catalogs in the "/usr/lib/nls/msg/De_DE" directory from IBM-850 to ISO-8859-1 format. The original IBM-850 files are retained, so you will then have all message output available in both formats.
A 7.4 Accessing spool queues from an IBM logical printer
To use a printer setup for EtherShare from the IBM spooling system, you can define a new IBM queue to automatically forward all jobs it receives to the EtherShare spooling system. Assuming you have used the EtherShare Admin to define a UNIX printer that is named "lw", you should add the following lines to "/usr/lpd/qconfig":
device = lwdev
discipline = fcfs
backend = /usr/local/es/lpr -Plw

This creates an AIX queue named "lw" that uses the EtherShare queue "lw".
As all jobs are forwarded, you will no longer be able to see jobs in the IBM queue, and the jobs will appear in EtherShare's queue display instead.
Alternatively, you get the same functionality if you always remember to specify the full path of the EtherShare "lpr" program ("/usr/local/es/lpr") each time you use "lpr".
You can also create a queue that automatically converts text to PostScript, e.g.:
device = textdev
discipline = fcfs
backend = /usr/local/es/pstext -Plw

A 7.5 Accessing the System V "lpr" from the Print Server
The EtherShare Print Server is based on the BSD printing system. If your host uses the System V printing system (e.g. Sun Solaris 2.x), the Print Server normally uses its own BSD-style "lpr" program, which is provided in the "$ESDIR" directory in such cases. Manual pages for the BSD-style "lpr" are provided on the CD-ROM in the "manuals" directory.
In order to access the System V "lpr" from the EtherShare Print Server, you need a configuration which is very similar to that of "Printing to disk":
papsrv: name="xxxx", printer=xPrinter,
lpr=/bin/lpr, resolve

xxxx is the required AppleTalk printer name,
xPrinter is the logical (printcap) printer name, and
lpr specifies the System V "lpr" program rather
than the EtherShare "lpr" program in
In order to set up the required spool directory and symbolic link, and create a "/etc/printcap" entry and "FONTS" file automatically, we recommend that you first set up a dummy printer with a "Remote LPR" connection, then edit the corresponding "atalk.conf" entry and "FONTS" file manually.
A BSD-style "lpq" command is also provided with the RS/6000 version of EtherShare, because it is not included with AIX. You can use it to check the job status from a UNIX shell as follows: lpq
/usr/local/es/lpq -P<printername>.
Or instead, you can use "diskif" and a notify script (see notifyprog in 11.6 "Configuring printers manually").
A 7.6 Accessing the Print Server through "Remote LPR"
If your host uses the System V printing system (e.g. Sun Solaris 2.x), in the special case where you want to receive print jobs through "Remote LPR" into EtherShare's BSD-based printing system, you must disable the local System V network printing functionality before you can do this. By default the install procedure comments out the "printer" line in "/etc/inetd.conf".
A 7.7 AppleTalk kernel configuration
In order to be able to communicate using the AppleTalk protocols, EtherShare needs support from the operating system. Commonly, UNIX suppliers deliver the TCP/IP networking protocols together with their standard operating system release, but no AppleTalk networking protocols. EtherShare thus contains drivers that implement the AppleTalk protocol with Ethernet. On some machines, EtherShare also supports other network connections like Token Ring. All files that relate to the kernel side of the EtherShare system reside in the directory "$ESDIR/kernel". The following is a detailed description of what is changed in the operating system by the EtherShare installation. This is probably of interest to advanced UNIX users only, since the EtherShare configuration shell scripts hide most of the details necessary to get the AppleTalk drivers running.
The kernel modules come in two flavors, depending upon host operating system architecture. System V.4 based systems use a streams-based architecture where each AppleTalk communication endpoint is represented as a file descriptor opened through the streams multiplexor "/dev/ddp". Berkeley-based systems use file descriptors opened through the socket mechanism.
A 7.7.1 Loadable Drivers
Solaris 2.x, SGI IRIX, HP-UX 11, and IBM RS/6000 systems support a concept of loading drivers, which can be loaded into the operating system during runtime. In such cases, it is not necessary to re-link the UNIX kernel with new modules. The "start-atalk" shell script takes care of loading the driver when starting AppleTalk, if the driver is not already loaded.
Solaris 2.x
EtherShare uses two kernel modules on Solaris 2 systems, "aarp" contains the "AppleTalk Address Resolution Protocol" streams module and "ddp" the "Datagram Delivery Protocol" streams multiplexor. "aarp" is located in "/kernel/strmod" and "ddp" in "/kernel/drv". The installation procedure copies the files from "$ESDIR/kernel" to the "/kernel" directory. In addition, the installation script adds a line to the "/etc/minor_perm" and "/etc/devlink.tab" and files to get the proper link from "/devices/ pseudo/
clone:ddp" entry to "/dev/ddp" using the proper permissions. The drivers are loaded and unloaded by Solaris 2.x automatically, no loading or unloading should be necessary.
A long list of all loaded modules can be produced by using the "modinfo" command. The "modunload" command can be used to unload the drivers, but only if they are unused.
IBM RS/6000 systems
On IBM RS/6000 systems, only one driver is loaded by the "start-atalk" script ("$ESDIR/kernel/atalk"). This driver is dependent upon the AIX version. The installation procedure makes a link from the corresponding and appropriate file to "/usr/lib/drivers".
In addition, entries are added to the ODM database to allow the loading of the driver through the "mkdev" command. The logical name for the kernel module is "atalk0". Use the following command to load the module:
mkdev -t atalk
The "lsdev" command can be used to see if the kernel module is loaded:
lsdev -C -l atalk0

Note: Under AIX, the unloading of network protocols is not supported.

On SGI IRIX systems, the loadable drivers reside in "/usr/local/es/kernel" and are automatically loaded by "start-atalk" with the ml command. A list of all loaded drivers can be displayed using ml list. With ml unld and the corresponding ID number (which can be obtained from the drivers list) the module can be unloaded again.
HP-UX 11
The drivers "aarp" and "ddp" are copied into the system di-rectory of a HP-UX 11 operating system by the kminstall command. To automatically load the modules in the kernel use kmupdate.
To delete the drivers again, use the following commands:
kminstall -d aarp
kminstall -d ddp
A 7.7.2 Re-linking the kernel
For Data General AViiON systems, the AppleTalk driver is supplied in linkable form. The "install" shell script takes care of installing the necessary files in the system directory and rebuilding the kernel. All files modified or replaced by the script are saved with the ".noatalk" suffix.
On AViiON systems the installation procedure uses the "sysadm" menus to do most of the complicated rebuilding procedure. The installation procedure copies template and library files from the "$ESDIR/kernel" directory to "/etc/master.d" and "/usr/src/uts/aviion". The kernel is rebuilt using the following command:
asysadm -m system:kernel -o auto
The automatic option causes "sysadm" to collect all templates into a new system description and build a new kernel accordingly. The new kernel is installed into "/" when successful. Upon each boot, the "ddp" multiplexor driver creates a "/dev/ddp" entry for the user programs.
A 7.8 UNIX kernel tuning
This section describes optional tuning procedures which require substantial UNIX experience. With the exception of Other tuning tips (below), they should not be attempted by beginners.
If the EtherShare host has plenty of memory, it may be worthwhile adjusting some data structures inside the operating system to be larger than normal. This keeps more information in memory that otherwise may need to be continuously re-read from the disk. Modern operating systems adjust the data structure values depending on the available memory size. See your UNIX documentation for more information.
Solaris 2.x
The Solaris 2.x operating system has no facilities to rebuild the kernel. Thus parameters are not set by modifying a
C-language source and rebuilding the kernel, but simply by editing a text file. The file "/etc/system" may contain simple statements of the form "set variable=value" to tune system parameters. The two parameters especially interesting for EtherShare are "ufs_ninode" and "ncsize". "ncsize" is not prefixed by "ufs_" because it relates to all file systems, not just the normal UNIX file system. To set these two values to 20000, one would include the following statements in "/etc/system":
set ufs_ninode=20000
set ncsize=20000
Increasing the number of inodes that can be held in memory improves the performance considerably when doing Macintosh Finder operations or repeated opening and closing of files. Each file that needs to be accessed (directories are files as well) will occupy an inode entry. The inode will be kept around after closing a file or directory in case it will be referenced again, unless the operating system is out of free entries. In the latter case, the entry may not be re-used but is used for a different entry that will be loaded from disk. Thus, if you have several megabytes of memory to spend, you may increase the number of inode entries to, e.g. 20000, which will require approximately 4 MB of RAM.
If the kernel fails to boot because of wrong parameters in "/etc/system" you can boot the system using the "-a" option. You will then be asked which files and partitions to use, when asked for "/etc/system" just answer "/dev/null" instead.
Other tuning tips
EtherShare contains highly-efficient AppleTalk router modules which do not present an excessive load on the host's CPU, even with heavy routing traffic. You can often improve network response by installing two or more network cards in your host, and arranging your network to share traffic between two separate network segments. This approach is particularly beneficial if you have installed the EtherShare OPI option - in such cases we recommend installing a second network card to deal with printer/RIP traffic only, and thus separate it from workstation traffic. There is no theoretical limit to the number of network cards supported by the EtherShare router, but generally there are no gains to be made by installing more than 3 cards except in the fastest hosts.
Other UNIX architectures
For tuning on other UNIX architectures, please refer to the appropriate UNIX documentation. Generally, the sections describing "Performance tuning" in the respective manuals may be read carefully.

© 2002 HELIOS Software GmbH