  NCD X terminal mini HOWTO
  Ian Hodge, ian at permedia.ca
  v1.09, March 27, 2000

  This document describes how to connect an NCD X terminal to a UNIX
  host
  ______________________________________________________________________

  Table of Contents


  1. Copyright

  2. Introduction

     2.1 Summary of steps

  3. Requirements

     3.1 The X terminal
     3.2 Physical Connection
     3.3 NCD X server software

  4. Configuring the UNIX Host

     4.1 TFTP and BootP

  5. Configuring the NCD X terminal Boot Process

     5.1 Boot Monitor command syntax
     5.2 Boot Monitor Setup Menu
     5.3 X Terminal Configuration Files
     5.4 Logging on to the host

  6. Fonts and the X terminal

     6.1 The font server

  7. Miscellaneous

     7.1 Supported Terminals
     7.2 Reference
     7.3 Equipment used in the preparation of this document
     7.4 Acknowledgments
     7.5 Outstanding Issues
     7.6 Feedback


  ______________________________________________________________________

  1.  Copyright

  The NCD X terminal mini HOWTO is copyright(c) 1998 by Ian Hodge. Linux
  HOWTO documents may be reproduced and distributed in whole or in part,
  in any medium physical or electronic, as long as this copyright notice
  is retained on all copies.


  2.  Introduction

  This document describes how an X terminal manufactured by NCD (Network
  Computing Devices) can be connected to and booted from a UNIX host
  using BootP (boot protocol). Many terminals are also capable of
  booting with RARP, NFS or locally from a PCMCIA card or over a serial
  link (either directly or with a modem).

  Although the material in this document was prepared based on
  experience with a single model of X terminal, much of the information
  applies to other models and other X terminals generally. There is also
  an Linux X terminal mini HOWTO document (declared obsolete by HOWTO
  maintainers at the time of writing and therefore possibly not
  available in all Linux distributions) which overlaps material from
  this document. That document covers X terminal information more
  generally.


  2.1.  Summary of steps

  The process of connecting an X terminal to a UNIX network can be
  summarized in the following steps:


  o  Physically connect the X terminal to the network.

  o  Configure the UNIX host you are going to boot from.

  o  Configure the X terminal boot procedure.

  o  Boot the X terminal.

  o  Log in to the network.



  3.  Requirements

  3.1.  The X terminal

  An X terminal is a device which communicates and displays over a
  network using a distributed network window system known as X.
  Typically, the terminal's X software, known as the X server, is
  retrieved from the network at boot time. Programs other then the X
  server software (X client programs) are not run locally on the X
  terminal (with some exceptions); instead, the X terminal displays
  programs running on other hosts on the network. The X terminal,
  therefore, is a type of network computer which uses the X protocol to
  access network resources.


  3.2.  Physical Connection

  The NCD X terminal (model Xncd19r was used in preparation of this
  document) has an RJ-45 (twisted pair) connector for use with 10baseT
  Ethernet. A hub is required to link more than two Ethernet devices
  using twisted pair. If the X terminal and its host are the only
  devices in the network, they may be connected with a 'null' cable
  which is described in the Linux Ethernet HOWTO document.


  3.3.  NCD X server software

  The terminal's X server software file is available from the
  manufacturer and presumably is provided with the terminal upon initial
  purchase. This file will reside on the boot host where it can be
  accessed by the X terminal when it boots. This file is specific to the
  terminal type but independent of boot host. The terminal can boot from
  any host which supports the boot communication protocol (explained
  later). In addition to X server, the X software may also include
  applications, like a window manager, which can run locally on the X
  terminal itself.


  4.  Configuring the UNIX Host

  At boot time, the X terminal retrieves files (including its X server
  software) from a remote host on the network. After the terminal boots,
  the X server software will control input, display, local clients and X
  protocol communication. The X server software is executed on the X
  terminal and therefore does not have to be software compatible with
  the host on which it resides.


  4.1.  TFTP and BootP

  Together, tftp (trivial file transfer protocol) and BootP (boot
  protocol server) are used on the remote host to allow the X terminal
  to retrieve its X server software and configuration files over the
  network. Both services are typically started by inetd (Internet
  Daemon).


  After the X terminal is powered up, if it is configured to boot from
  the network, it will send out a broadcast message using BootP (TCP/IP
  bootstrap protocol). This boot message will contain the X terminal's
  hardware (Ethernet) address which is used by the boot host to respond
  to the boot request.


  When a boot request is received by the remote host, inetd (listening
  on a port designated in /etc/services) starts the BootP daemon
  specified in /etc/inetd.conf.


  In file inetd.conf, create or uncomment lines that refer to TFTP and
  BootP. The final argument of the tftpd entry in the example below is
  the path of the directory containing the files required by the X
  terminal. Although directory names are not mandatory, for security
  reasons they should always be present as tftp access will then be
  restricted to files in specified directories.


  From a sample file /etc/inetd.conf:

  # tftp service is provided primarily for booting.  Most sites
  # run this only on machines acting as "boot servers".
  tftp   dgram udp wait root /usr/sbin/tcpd /usr/sbin/in.tftpd /usr/X11/lib/X11/ncd/
  bootps dgram udp wait root /usr/sbin/tcpd /usr/sbin/in.bootpd



  Upon activation, the BootP server daemon on the host will then read
  its database file /etc/bootptab. An entry for the X terminal must be
  placed in this file. Each entry contains a set of tags separated with
  ':' characters. The host name must be the very first tag in an entry.

  Useful bootptab tags:

     hd Bootfile home directory (eg /usr/X11/lib/X11/ncd/).

     ip Address of the X terminal (eg 10.0.0.1).


     sm Subnet mask (eg 255.0.0.0). To understand the use of the subnet
        mask and other IP networking principles, consult the Linux NET-3
        (networking) HOWTO document.


     gw IP Address of gateway (eg 10.0.0.1).

     ht Hardware type - Ethernet in this example.

     ha Hardware address of X terminal (6 byte Ethernet address)

        According to the bootptab UNIX man page, the 'ha' tag must be
        preceded by the 'ht' tag. The X terminal's Ethernet address is
        displayed when the terminal is first powered on. The address
        appears as a series of 6 double digit hex numbers separated by
        colons (e.g. 00:00:A7:12:26:19).


     tc Table continuation or label of another entry in the BootP
        database. See the example below.


     ds IP address of domain name server (eg 10.0.0.3). Not required if
        DNS is not used for hostname resolution.


     bf Name of X terminal boot file (Usually the terminal model is used
        as the X server file name eg Xncd19r).


  The following is an example of the Boot protocol server database file,
  /etc/bootptab. The character '\' is used to escape the end-of-line
  character.


  # This is an entry (here given the name default)
  # with information common to all BootP clients
  default:hd=/usr/X11/lib/X11/ncd/:\
          ds=10.0.0.3:\
          sm=255.0.0.0:\
          gw=10.0.0.1:

  # X terminal entry with hostname myxterm
  # Notice the tc tag reference to the entry default
  myxterm:ht=ethernet:\
          ha=0x0000a7122619:\
          ip=10.0.0.2:\
          tc=default:\
          bf=Xncd19r:



  When a matching entry for the hardware address in the boot request is
  found in the bootptab file, a response is sent by bootpd with the
  corresponding IP address from the matching entry. File transfer can
  then take place over IP using TFTP.

  A hostname can be assigned to the X terminal by creating an entry on
  the boot host in the file /etc/hosts. This file is used to map
  hostnames to IP addresses. In the this example, the X terminal
  (address 10.0.0.2) has been assigned the hostname 'myxterm'.


  10.0.0.1        linuxhost       # The boot host
  10.0.0.2        myxterm         # X terminal



  5.  Configuring the NCD X terminal Boot Process

  After being powered up, the X terminal attempts to boot. This is the
  process where the X software is loaded into memory and executed. If
  the X terminal cannot boot, the Boot Monitor prompt '>' will appear.
  The Boot Monitor is firmware found in terminal PROMs (programmable
  read-only memory). With the basic Boot Monitor interface, it is
  possible to configure the terminal to boot and retrieve its X server
  software from the host. Use


  Configuration parameters set with the boot monitor are stored in NVRAM
  (Non-volatile Random-Access Memory) and are retained when the terminal
  is powered down.


  From the boot monitor, the 'bt' command or a menu system can be used
  to boot the terminal. Functionality of the two methods largely
  overlaps but the menu provides control over more boot parameters.


  5.1.  Boot Monitor command syntax

  >bt file terminal_IP host_IP gateway_IP subnet_mask



     file
        The name of the file retrieved from the remote host containing
        the X server software used by the X terminal to boot (eg
        "Xncd19r"). Check that this file name is the same as the file
        name is found in the X terminal entry in the bootptab file on
        the host (explained in the previous section).


     terminal_IP
        The IP address assigned to the X terminal (eg 10.0.0.2). Again,
        this IP address should be the same as the address assigned in
        the X terminal entry of the bootptab file on the host.


     host_IP
        The IP address of the boot host (eg 10.0.0.1).


     gateway
        The IP address of the subnet gateway (eg 10.0.0.1)


     subnet_mask
        The subnet mask, specified as a decimal IP address or as a
        hexadecimal number (eg 255.0.0.0 or ff000000).


  5.2.  Boot Monitor Setup Menu

  The setup menus are accessed by pressing the 'Setup' key or typing
  'se' from the boot monitor '>' prompt.


     Get IP Addresses From
        The IP address of the X terminal should be obtained from boot
        monitor configuration stored in NVRAM. Only select IP address
        from the remote host.


     Terminal IP Address
        The IP address assigned to the X terminal (eg 10.0.0.2). This is
        the same as 'terminal_IP' parameter above.


     First Boot Host IP Address
        The IP address of the boot host (eg 10.0.0.1). This is the same
        as 'host_IP' parameter above.


     Gateway IP Address
        The IP address of the subnet gateway. This is the same as
        'gateway' parameter above.


     Subnet Mask
        The subnet mask, specified as a decimal IP address. This is the
        same as the 'subnet_mask' parameter above.


     Broadcast IP Address
        The IP address used to broadcast to the subnet. (eg
        10.255.255.255)


     Boot File
        The name of the file retrieved from the remote host containing
        the X server software used by the X terminal to boot (eg
        "Xncd19r"). This is the same as 'file' parameter described
        above.


     TFTP Boot Directory
        The name of the directory on the host which contains the boot
        file (eg "/usr/X11/lib/X11/ncd/" or "/tftpboot/").


     Config file
        The name of the X terminal configuration file on the remote host
        (See below).


     UNIX Config Directory
        Name of the directory containing X terminal configuration files
        (eg "/usr/X11/lib/X11/ncd/").


     TFTP Order, NFS Order, Local Order
        Assign '1' to the preferred method for booting. Assign '1' to
        TFTP when booting from a host using BootP.


  5.3.  X Terminal Configuration Files

  During the boot process, the X terminal will attempt to transfer and
  load files from the boot host. These files are not required for the X
  terminal to boot successfully. If a file is not found, the terminal
  will use default settings.

  Configuration Files transferred to the X terminal at boot time:

  o  X terminal configuration file (eg ncd.conf) used to retain terminal
     settings.

  o  Color file (eg rgb.txt).

  o  X key symbol database (eg XKeysymDB).

  o  Font directory files (eg font.dir, font.alias).


  After a successful boot, the X terminal console window with a menu bar
  should appear. The terminal setup key toggles display of this console
  window. From the console window 'setup' pull-down menu, terminal
  characteristics can be viewed, altered and saved on the boot host in
  the configuration file which can be used in future sessions.

  If TFTP is being used to transfer files from the boot host, then file
  permission must be world readable. Similarly, to save a configuration
  file to the boot host, the file must already exist and with world
  write permission enabled. If secure TFTP is used (this is recommended
  for security reasons), then file access is possible only through
  specified directories.

  Note: The terminal may fail to boot if it was previously configured to
  work with other hosts or with different configuration parameters.
  Resetting the NVRAM to remove stored settings may solve the problem.


  To reset NVRAM, from the boot monitor, type the 'nv' command. From
  this sub-menu, select 'l' to load defaults, 's' to save and finally
  'q' to quit. Resume the boot procedure described above.


  5.4.  Logging on to the host

  From the X terminal console window menu bar, select the 'terminals'
  pull-down menu and choose 'New Telnet...'. When the telnet window
  appears, insert the address of a network host in the service entry and
  click including a window manager, can be started from the telnet
  window.


  6.  Fonts and the X terminal

  The X terminal comes with a small set of fonts. In the X terminal
  setup menus and configuration files, these fonts are referred to as
  fonts are desirable. Fonts can be added by specifying font paths in X
  terminal console setup menus, configuration files or by using the xset
  command.


  Once the X server software is running on the X terminal, the font path
  can modified or queried with the command xset.

  To query the X server:

  xset -q


  To add a font entry:

  xset +fp <path>


  To remove a font entry:

  xset -fp <path>



  6.1.  The font server

  The font server (xfs) runs on a network host and retrieves fonts for
  the X terminal and other network clients. Use of the font server
  allows the use of a wide variety of fonts as the X server software is
  otherwise restricted to bitmap fonts. During retrieval, the font
  server can uncompress, scale and convert fonts for the X server and
  can help simplify the management of fonts for groups of terminals and
  network clients. Font server software is part of many Linux
  distributions and has been incorporated into X consortium software
  available from ftp.x.org <ftp://ftp.x.org>.

  To indicate the use of a font server, a tcp service entry is used
  instead of a font path in the X terminal's host resident configuration
  file or console setup menu.

  Format of tcp service entry:

  tcp/<IP address of font server>:<port used by font server>



  Example:

  tcp/10.0.0.1:7100



  An example of an entry in the X terminal configuration file found on
  the boot host:


  xserver-default-font-path = {
          { "tcp/10.0.0.1:7100" }
          { "built-ins" }
  }



  The xset command with the tcp service entry can used to add the font
  server to the path:


  xset +fp tcp/10.0.0.1:7100



  WARNING: Certain versions of NCDware require the font server entry to
  be listed first before X terminal 'built-in' fonts. This is contrary
  to the NCD documentation "System Administrator's Guide for UNIX
  Systems".  Experiment with the order of the font path and verify it
  with the


  On the font server host, the server is started at boot time from the
  rc.local startup script. The font server (xfs) is started with the
  following command:


  xfs -config <config file path> -port <font server port number>



  The standard font server port is 7100.

  Example:


  xfs -config /usr/X11/lib/X11/fs/config -port 7100



  Example font server configuration file:


     # font server configuration file

     # allow a max of 10 clients to connect to this font server
     client-limit = 10

     # when a font server reaches its client limit, start up a new one
     clone-self = on

     # use the UNIX syslog utility to log errors.
     use-syslog = on

     # list of font directories
     catalogue = /usr/X11R6/lib/X11/fonts/misc/,
        /usr/X11R6/lib/X11/fonts/Speedo/,
        /usr/X11R6/lib/X11/fonts/Type1/,
        /usr/X11R6/lib/X11/fonts/75dpi/,
        /usr/X11R6/lib/X11/fonts/100dpi/

     # file used to log errors if syslog is not used.
     error-file = /usr/X11R6/lib/X11/fs/fs-errors

     # 12 point in decipoints
     default-point-size = 120

     # 100 x 100 and 75 x 75
     default-resolutions = 75,75,100,100



  7.  Miscellaneous

  7.1.  Supported Terminals

  I have been told that this procedures in this document work (more or
  less) with the following terminals: NCD 19r, NCD 19c, NCD19m?, NCD
  15b, NCD MCX


  7.2.  Reference

  Unix man pages: bootpd(8), tftpd(8), bootptab(5), xdm(1x), xfs(1),
  fsinfo(1), xset(1), inetd(8)

  Linux Ethernet HOWTO document, Linux Net-3 (Networking) HOWTO document


  NCDware System Administrator's Guide for UNIX Systems (print version)

  NCD Techtips Archive <ftp://ftp.ncd.com/pub/ncd/Archive/NCD-
  Articles/index.html>


  Now available for download in the NCD Techtips Archive is the NCDware
  Reference Manual
  <ftp://ftp.ncd.com/pub/ncd/Archive/Documentation/NCDware/index.html>
  which covers almost every X terminal configuration issue in detail.

  The searchable NCD knowledge base
  <http://www.ncd.com/support/kbsearch/kbase.html> addresses some
  frequently asked questions as well as bug reports.


  Note that the above links are subject to change. Since the first
  version of this mini-HOWTO was published, the NCD web site has been
  extensively reorganized.


  7.3.  Equipment used in the preparation of this document

  X terminal: NCD model NCD19r with 19 monochrome monitor 1280x1024 8M
  RAM

  X server software: NCDware V3.2.CV 19r_s

  Remote Host: IBM Cyrix 686 P150+ running Slackware (Linux kernel
  version 2.0.31)

  Remote Host: IBM Cyrix M2 200 MMX running Red Hat 5.0 (Linux kernel
  version 2.0.32)

  Network Card: 10 base T Ethernet card (ne 2000 clone) and 8 port hub

  Font server version 2 release number 6300


  7.4.  Acknowledgments

  I would like to thank Michael de Lind van Wijngaarden, Jamal Hadi-
  Salim and Dwight Hodge for assistance in the preparation of this
  document.

  7.5.  Outstanding Issues


  o  Is it possible or wise to start the font server using inetd?

  o  If the remote host running the font server is powered down but
     later comes up again, with the font server active, the X terminal
     may fail to retrieve its fonts. The font path entry has to be re-
     entered with the console menu or xset. Why?

  o  Are the procedures for other models of X terminals roughly similar?

  o  What is the procedure to boot the X terminal using NFS (Network
     File System) or RARP (Reverse Address Resolution Protocol)?

  o  The following messages appear in the X terminal Console. I am
     suspicious that they come from xfree86 extensions to X which are
     not part of the X terminal server. Can someone confirm or deny
     this?

     %XSERVER-I-NEWCLIENT, host "localhost" connected with blank authorization
     %XSERVER-W-NOEXTENSION, client attempted to use non-existent extension "BIG-REQUESTS"
     %XSERVER-W-NOEXTENSION, client attempted to use non-existent extension "XKEYBOARD"
     %XSERVER-W-NOEXTENSION, client attempted to use non-existent extension "XFree86-Misc"



  o  Could Linux be ported to an X terminal? This is almost a joke
     question but Linux is already on some unlikely platforms.


  7.6.  Feedback

  Please write to ian at permedia.ca with any comments, questions,
  corrections, suggestions or contributions.  Many thanks to all who
  have written with feedback and additional information.



