Protogate Frequently Asked Questions

This is the Protogate FAQ (Frequently Answered Questions list).
The latest HTML version of this list is available from http://www.protogate.com/faq.html, on Protogate's website.


1. General

  • 1.1) Who is Protogate? What does Protogate do?
  • 1.2) What is Protogate's operating philosophy?
  • 1.3) What are Protogate's main products?
  • 1.4) What is an "ICP board"?
  • 1.5) What is a "serial communications protocol"?
  • 1.6) What is a "Freeway®"?
  • 1.7) What is the "Message Switch"?
  • 1.8) What is the "DLI" and "TSI"?
  • 2. Freeway®

  • 2.1) What is a Freeway good for?
  • 2.2) What are the Freeway models?
  • 2.3) I have my Freeway; how do I connect to it as a user, to see what it's doing (console access)?
  • 2.4) I don't have a serial terminal. Is there any other way to get console access to my Freeway, while it's booting?
  • 2.4a) Can I use a USB keyboard instead of a PS/2 keyboard to get console access to my Freeway?
  • 2.5) How about SNMP access to my Freeway?
  • 2.6) How are all the configuration files and parameters of a Freeway related to each other?
  • 2.7) How do I change the configuration of my Freeway?
  • 2.8) Help! I changed the configuration of my Freeway, and now after it boots, I can't log in -- what can I do?
  • 2.9) Help! I changed the configuration files in my Freeway, but now after it boots, it has exactly the same configuration as before (my changes are gone). How do I make my changes permanent, so they survive when I reboot the Freeway?
  • 2.10) I received a new CDROM from Protogate, with a new version of the Freeway software. Should I upgrade?
  • 2.11) How do I use the Freeway CDROM to upgrade my Protogate Freeway to a new software version?
  • 2.12) What kind of logging is available on the Freeway?
  • 2.13) Does the Freeway provide any other kind of diagnostic help, besides the Freeway logs?
  • 2.14) I'd like to do something in the Freeway menus, but there is no menu screen that will do what I want. What can I do?
  • 2.15) Where can I find more information about the BSD-shell commands I can enter on my Freeway?
  • 2.16) How can I configure my Freeway as an NTP (Network Time Protocol) client or server?
  • 2.17) How can I configure my Freeway to perform Unix-style "syslog"ing?
  • 2.18) Why did you tell that last guy (who wanted to configure syslog on his Freeway) to put his syslog configuration statements into his bootcfg file? Isn't that doing it the hard way? I put similar lines directly into a syslog.conf file in my Freeway's /ro/etc/ subdirectory and it worked fine.
  • 2.19) Can I configure PPP links on my Freeway?
  • 2.20) I would like my Freeway to automatically reboot itself once a week, every Sunday morning at 2:00 AM; how can I get it to do that? (or: How do I get my Freeway to perform some task automatically at a specified time?)
  • 2.21) I need my Freeway to be able to boot into different configurations, but I don't want to have to edit the configuration files each time. How can I do that?
  • 2.22) There are all these different ways to configure the Freeway, or alter what it does while it boots. What is the exact sequence of steps the Freeway performs when it boots?
  • 2.23) I want to secure my Freeway by eliminating all known and all unnecessary login accounts. Which accounts must I leave and which can I remove?
  • 2.24) How about restricting the access method? I want to force users to use SSH to login to the Freeway, and not allow user access via telnet, rlogin, or ftp.
  • 2.25) I need even tighter Freeway access security. Can I configure a firewall on the Freeway, and restrict access to certain IP addresses?
  • 2.26) My Freeway has two ethernet interfaces. Can I configure it to detect when one fails (or is disconnected) and automatically switch to the other interface (redundant failover)?
  • 2.27) What is a Freeway "SRA" (Server-Resident Application)? How can I create one?
  • 2.28) I need the Freeway to automatically close all socket connections when my client reboots, or is reset, or is disconnected from the LAN. How can I configure the Freeway to do this?
  • 2.29) How can I tell if my Freeway contains a CPU-47, CPU-48, or CPU-49 Single Board Computer (SBC)? What are the differences in behavior between a Freeway with a CPU-47, a Freeway with a CPU-48, and a Freeway with a CPU-49?
  • 2.30) Is there kernel-level auditing support on the Freeway? How can I configure that and enable it?
  • 2.31) How can I save the configuration of a Freeway, for restoration later?
  • 2.32) I just received a new Freeway (or upgraded one of my Freeways), and now my ssh client programs can't login to it. How can I fix this?
  • 3. Message Switch

  • 3.1) What is the Message Switch good for?
  • 3.2) Can I configure the Message Switch to receive data from a WAN link, and send it as UDP packets on my LAN?
  • 3.3) How about the other direction (to receive UDP packets, and send them to a WAN link)?
  • 3.4) Can the UDP packets use broadcast or multicast addresses?
  • 3.5) Can the source or destination be a TCP data stream, rather than a UDP packet stream?
  • 3.6) When using a TCP data stream, does the Freeway (with Message Switch) have to be the "listen"er (the passive, server side of the TCP connection), or can it also be the "connect"er (the active, client side)?
  • 3.7) Not that I want to do this, but I'm just curious: could I configure the Message Switch to take a stream of UDP packets and send them to a TCP connection (and vice-versa)?
  • 3.8) I think I've got it now. The Message Switch connects data stream sources and destinations to each other, and the sources and destinations can be any combination of UDP packet streams, TCP connections, and WAN ports. Is that right?
  • 3.9) What is a "programmable endpoint"?
  • 3.10) Can the Message Switch receive data from a single source (WAN port, UDP packet stream, TCP data stream, or programmable endpoint) and send it to several different destinations?
  • 3.11) Can it retrieve data from several different sources and send that data to a single destination?
  • 3.12) Can I configure the Message Switch to send more than just the data? I need it to send the protocol information, too (link up/down notification, data acknowledgements, etc.)
  • 3.13) How can I configure the Message Switch to use my WAN line as a PPP link?
  • 3.14) Can I configure more than one PPP link on a single Freeway with the Message Switch?
  • 3.15) Can I configure the Message Switch to compress my data before sending it to me or to a WAN port?
  • 3.16) Can I configure the Message Switch to take the data it retrieves from some source (or sources), pack it into files, and send those files to an FTP server?
  • 3.17) How do I write my own Programmable Endpoints?
  • 4. DLI/TSI and Client programs which connect to a Freeway

  • 4.1) What is the "DLI"?
  • 4.2) What is the "TSI"?
  • 4.3) What is "Normal Mode"?
  • 4.4) What are the dlicfg and tsicfg programs for?
  • 4.5) When I try to run the dlicfg program, I get an error which says "DLI was built with stub ***.c, and does not support ***". What does that mean?
  • 4.6) Can I use a multi-threaded program with the DLI/TSI library?
  • 4.7) Can I run a DLI/TSI client program on the Freeway itself?
  • 5. ICP Boards

  • 5.1) What does the ICP board do?
  • 5.2) What types of ICP board are available?
  • 5.3) Are there ICP boards which plug into VMEbus?
  • 5.4) I get a "Device time out" message after resetting my ICP board, so I cannot download the protocol. Is my ICP board broken?
  • 6. Protocols

  • 6.1) Why do I need a "protocol"?
  • 6.2) What protocols do you have available "off-the-shelf"?
  • 6.3) Protogate doesn't already have the protocol I need. Can I create it myself? What tools and skills do I need to do that?
  • 6.4) Protogate doesn't already have the protocol I need. Can you create it for me? How much would that cost?
  • 6.5) I'm using a synchronous protocol, and I'm not sure I have the clocksource set correctly. What symptoms would I see if my ICP port's clocksource is set to "internal", but the other side of the WAN link (or the modem that my ICP board is connected to) is sending the clock signal?
  • 6.6) I'm using a synchronous protocol, and I'm not sure I have the datarate set correctly. What symptoms would I see if I configured my ICP port's datarate to a lower or higher speed than the actual rate of the external clock?
  • 7. Troubleshooting Techniques

  • 7.1) My client program is having trouble connecting through my Freeway to a WAN port; what do I do?
  • 7.2) How do I get a "Freeway trace" file?
  • 7.3) I configured my Freeway to boot from the network, rather than from its own hard disk, and it sometimes fails to boot -- why?
  • 7.4) I remember my Freeway printed lots of hardware probing information on the console when it booted. How can I retrieve that information?
  • 7.5) Is there a quick command to see details about all the PCI devices (such as ICP boards) installed in my Freeway?
  • 7.6) I think one of my ICP boards is dying. How can I get information about the health of my Freeway's ICP boards?
  • 7.7) Can I examine the contents of an ICP board's physical RAM?

  • 1. General


    1.1) Who is Protogate? What does Protogate do?

    Protogate is a U.S. corporation which is dedicated to providing solutions for all Wide Area Network (WAN) data communications needs. We design, build, sell, and support hardware and software which enables data to flow over many different types of serial data communications lines, and allows IP-connected computers to send and receive data on those lines.


    1.2) What is Protogate's operating philosophy?

    "If our customers don't succeed, we don't succeed." We keep that thought in mind for everything we do -- during design, engineering, manufacturing, and customer support.


    1.3) What are Protogate's main products?

    Protogate's primary hardware products are ICP boards and Freeway®s. Our primary software products are serial communications protocol programs which run on our ICP boards, server daemons (such as the Message Switch) which run on the Freeways, and DLI/TSI subroutine libraries which run on various platforms (Sun Solaris, NT, VMS, HPUX, etc.) and which make it easier for our customers to make connections from their machines to a Freeway. We also provide ICP board drivers for a few operating systems, for customers who want to install ICP boards directly into their own machines.


    1.4) What is an "ICP board"?

    An ICP (Intelligent Communications Processor) board is a general-purpose serial-communications board. It is optimized for serial data communications, but has a CPU on it which enables it to handle many different types of serial communications protocols. All current ICP boards are PCIbus-based, and there are models with 2, 4 or 8 communications ports.

    More information is in the 5.) ICP board section of this FAQ.


    1.5) What is a "serial communications protocol"?

    A "serial communications protocol" is a set of rules for sending and receiving data over a serial communications line. (A serial communications line is one where all the bits of data are transmitted serially, one after the other -- often using only a single data channel in each direction: a leased telephone line, a radio-frequency channel, etc.). A set of rules is necessary to allow the receiving side to receive exactly what the sender intended. The rules specify everything about the data transfer: how the data is encoded, the data rate, where the message boundaries are, mechanism(s) (such as sequence numbers, and/or a checksum or CRC flag) to detect if data is lost or corrupted, how to recover from lost or corrupted data, etc.

    Protogate's ICP boards are capable of handling many different protocols. They are programmed for a specific protocol by downloading a "protocol image" file, which handles one particular protocol type. Variations within that protocol type are then specified by sending commands to the ICP board (to tell it which datarate to use, for instance).

    More information is in the 6.) Protocols section of this FAQ.


    1.6) What is a "Freeway®"?

    A Freeway is a rackmount or desktop box, containing a computer and several slots into which ICP boards can be installed. It has two or more WAN connections and two ethernet LAN connections. Once connected to a LAN (or LANs) and one or more WAN lines, a Freeway serves as a general-purpose data communications server; it allows ethernet IP connections from any IP-accessible machine on the IP network, and allows programs which are connected to it to send and receive data on the WAN lines.

    More information is in the 2.) Freeway section of this FAQ.


    1.7) What is the "Message Switch"?

    The Message Switch is a software component which runs on the Freeway. It serves as an automated "switch", connecting data streams from WAN lines, TCP data streams, and multicast or unicast UDP packet sequences to each other. It can connect one source to multiple destinations, many sources to a single destination, or many sources to many destinations, all without limitation on the type of source or destination. It is used mainly to provide easy "socket-level" access to simple data streams, but also to connect data streams to other software components (such as PPP links, automated FTP senders, data compressors, etc.).

    More information is in the 3.) Message Switch section of this FAQ.


    1.8) What is the "DLI" and "TSI"?

    The DLI and TSI are very portable subroutine libraries which are designed to make it easier to connect to a Freeway from various types of client machines (Solaris, NT, VMS, etc.). The names stand for "Data Link Interface" and "Transport Subsystem Interface".

    More information is in the 4.) DLI/TSI section of this FAQ.


    2. Freeway®


    2.1) What is a Freeway good for?

    A Freeway is a server system which contains ICP boards, and which is optimized to provide access to WAN communications links; it attaches to an IP network and serves clients who wish to connect to WAN ports. It manages all aspects of the WAN communications, such as downloading and initiating the ICP boards, maintaining a buffer pool, managing throughput, allowing diagnostic status-checking of the ICP board and protocol, etc.

    Use of a Freeway is much more straightforward and less error-prone than the other way of connecting to a WAN link, which is to use an embedded ICP board installed into one of your own machine's PCIbus slots. Because the Freeway offloads the ICP board access CPU load from your machine, and handles all the downloading and message processing tasks, we recommend using a Freeway instead of embedded ICP boards whereever possible. For details about the advantages of using Freeway, see the list describing the Advantages of Using Freeway Versus Embedded ICP Boards, on Protogate's website.


    2.2) What are the Freeway models? How compatible are they with each other?

    The basic current Freeway models are the 3114, 3214, 3414, and 214. The 3114, 3214, and 3414 can be mounted in standard 19-inch equipment racks, and the 214 is a desktop model. All of these models are logically identical; they only differ in their physical size and the number of ICP boards they can hold: the 3114 is 1U high (about 1.75 inches, or 4.5 centimeters), the 3214 is 2U high (about 3.5 inches), the 3414 is 4U high (about 7 inches) and about 19 inches deep, and the 214 is a desktop model, about 7" wide by 10" tall by 16" deep. Several of these models have other options available, such as dual- or quad-redundant power supplies, front-panel temperature/voltage sensors, etc. Detailed information about these and previous Freeway models is available in the Freeways section of Protogate's website.

    The external "DLI/TSI" API supported by all Freeways is the same; its design has not changed since 1995. So from the point of view of your client programs, all Freeways look identical to each other. In fact, several of our customers have replaced 10-year-old Freeways with our current Freeways, without even recompiling their existing client programs.

    Previous models made by Protogate were the Freeway 3112, 3212, 3412, and 3612, and prior to that the 3110 (and 3111), 3210, 3410, and 3610. The "3x12" models were built from 2010 until 2015; they differ from the current "3x14" models in the CPU board and backplanes: the 3x12 models used a CPU-48 in PCI-only backplanes, and the 3x14 models use a CPU-49 in backplanes with PCI, PCI-X, and PCIe slots. The "3x10" models were built from 2005 until 2010; they differ from the 3x12 models only in the CPU board: the 3x10 models used a CPU-47 and the 3x12 models used a CPU-48. 3x10 Freeways are thus almost identical to the 3x12 models except that the 3x12 models must run Freeway software versions 5.0-1 or later, whereas the previous Protogate 3x10 Freeway models can run any Freeway software version later than version 4.0-0. Our current 3x14 models must run Freeway software versions 6.0-0 or later. See FAQ entry 2.29) How can I tell if my Freeway contains a CPU-47, CPU-48, or CPU-49 Single Board Computer (SBC)? What are the differences in behavior between a Freeway with a CPU-47, a Freeway with a CPU-48, and a Freeway with a CPU-49? for more details about the differences between Freeways with different types of CPU boards.

    Even earlier models made by Protogate were the Freeway 500, 3100, 3200, 3400, and 3600. Those were built from 2000 until 2005; they differ from the current models in some internal ways, but are otherwise identical to the current models -- however, the current models must run Freeway software versions 6.0-0 or later, whereas the 3x00 Protogate Freeway models can run any Freeway software version later than version 3.0-0. Even earlier models, made by Simpact from 1995 until 1999, were the Freeway 1000, 1100, 1150, 2000, 4000, 8000, and 8800. Internally, those differ substantially from our current Freeways (some of those use different CPUs than our current Freeways do, and some use ISA bus or VMEbus rather than the PCIbus which our current Freeways use) -- but our current Freeways, running our current Freeway software, can still be used as drop-in replacements even for those, because the external interface (the interface between client programs and the Freeway) is still exactly the same.


    2.3) I have my Freeway; how do I connect to it as a user, to see what it's doing (console access)?

    You can connect a serial terminal (such as a VT100 or equivalent) to the "Freeway console" port at the back of the Freeway case. The terminal should be set to 9600 bps, 8 bits/character, No parity, and 1 stop bit (sometimes abbreviated as "9600 8N1"). The Freeway will display all the boot information (probing devices, setting up its IP addresses, etc.) on that serial terminal. Once booted, the serial terminal will display a login prompt, and you can login and traverse the Freeway system menus to view the system logs, check the status, or change the configuration.

    In addition, once the Freeway is up and running you can use telnet or rlogin to login to the Freeway and get access to the same Freeway system menus as are available on the serial terminal. In normal operation, most customers do not need serial terminal access to their Freeways, and so do not keep a serial terminal connected to their Freeways; they use telnet access instead. The only benefit of a serial terminal is that it provides access while the Freeway is booting (before it even has an IP address to telnet to).


    2.4) I don't have a serial terminal. Is there any other way to get console access to my Freeway, while it's booting?

    Yes; in addition to connecting a serial terminal to the "console" connector at the back of the Freeway, you can also connect an ordinary VGA monitor and PS/2 keyboard. When the Freeway boots, it first checks to see if a keyboard is connected; if there is a keyboard connected then the Freeway uses the VGA monitor and keyboard as the main system console, and all the boot information is displayed there. If no keyboard is connected, then the serial output console connector becomes the main system console.

    In either case, when the boot processing is complete both the serial console port and the VGA monitor/keyboard offer login prompts, allowing users to login and manage the Freeway system using a set of menus or typed-in commands (the same menus and typed-in commands which are available to telnet or rlogin sessions).


    2.4a) Can I use a USB keyboard instead of a PS/2 keyboard to get console access to my Freeway?

    Yes, you can use a USB keyboard rather than a PS/2 keyboard, but that may require some additional steps.

    Plug the USB keyboard into any USB connector on the Freeway (either at the back of the chassis or the front), then power-up the Freeway. Stop the boot process early by typing the DEL character to enter the BIOS setting screens (you can use the USB keyboard itself for this, since the USB keyboard always works this early in the boot sequence). Then set the appropriate options as described below for the type of CPU inside your Freeway.

    Under the "Integrated Peripherals" section of the BIOS, enter the "Onboard Devices" subsection and change the "USB Controller" to "Enabled" and the "USB Keyboard Support" to "Enabled".

    If your Freeway has a CPU-48, then in addition to the changes above, also go into "Power Management Setup" BIOS section and change the "ACPI Function" to "Disabled". CAUTION -- if you disable the ACPI function, you will no longer be able to power off your Freeway with the command shell ("shutdown -p now") or via any webpages. For that reason, we recommend that if you modify these BIOS settings to enable use of a USB keyboard, that you reset the settings back to their defaults when you no longer need the USB keyboard.

    To distinguish a CPU-47 from a CPU-48 or CPU-49 from the back of the Freeway: the tailplate for the CPU-47 has the USB connections above the secondary ethernet connector on the left tailplate, and the CPU-48 or CPU-49 has one tailplate with the USB keyboard connector above both ethernet connectors. To tell the difference between a CPU-48 and CPU-49 (which both look the same from the back of the chassis), look at the type of BIOS on the BIOS screen: the CPU-48 will have an "Award" BIOS, and the CPU-49 will have an "AMI" BIOS -- or see 2.29) How can I tell if my Freeway contains a CPU-47, CPU-48, or CPU-49 Single Board Computer (SBC)?


    2.5) How about SNMP access to my Freeway?

    SNMP access is available on the Freeway, and is enabled by default. There are also a full set of client SNMP tools, such as snmpwalk. The MIBs which are specific to the Freeway are described in the freeway/include/ directory on your Freeway software CDROM, in the files SIMPACTFREEWAY-MIB.txt and RS-232-MIB.txt . Those files are also installed in the Freeway itself, in the directory /usr/local/share/snmp/mibs/ .

    For more information about SNMP, login to your Freeway, select "6" to enter the BSD shell, and type these commands:

       man snmpd
       man snmp.conf
       man snmpd.conf
    
       snmpwalk -v 2c -c public localhost freeway
       snmpwalk -v 2c -c public localhost icpName
       snmpwalk -v 2c -c public localhost icpType
       snmpwalk -v 2c -c public localhost icpProtocol
       snmpwalk -v 2c -c public localhost icpProtocolRelease
       snmpwalk -v 2c -c public localhost icpOSRelease
       snmpwalk -v 2c -c public localhost icpPhysicalStatus
       snmpwalk -v 2c -c public localhost icpServiceStatus
       snmpwalk -v 2c -c public localhost icpNumberPorts
       snmpwalk -v 2c -c public localhost icpSlaveAddress
       snmpwalk -v 2c -c public localhost icpDownloadScript
       snmpwalk -v 2c -c public localhost rs232PortType
       snmpwalk -v 2c -c public localhost rs232PortInSigNumber
       snmpwalk -v 2c -c public localhost rs232PortOutSigNumber
       snmpwalk -v 2c -c public localhost rs232PortInSpeed
       snmpwalk -v 2c -c public localhost rs232PortOutSpeed
       snmpwalk -v 2c -c public localhost rs232PortInFlowType
       snmpwalk -v 2c -c public localhost rs232PortOutFlowType
       snmpwalk -v 2c -c public localhost rs232AsyncPortBits
       snmpwalk -v 2c -c public localhost rs232AsyncPortStopBits
       snmpwalk -v 2c -c public localhost rs232AsyncPortParity
       snmpwalk -v 2c -c public localhost rs232AsyncPortAutobaud
       snmpwalk -v 2c -c public localhost rs232AsyncPortParityErrs
       snmpwalk -v 2c -c public localhost rs232AsyncPortFramingErrs
       snmpwalk -v 2c -c public localhost rs232AsyncPortOverrunErrs
       snmpwalk -v 2c -c public localhost rs232SyncPortClockSource
       snmpwalk -v 2c -c public localhost rs232SyncPortFrameCheckErrs
       snmpwalk -v 2c -c public localhost rs232SyncPortTransmitUnderrunErrs
       snmpwalk -v 2c -c public localhost rs232SyncPortReceiveOverrunErrs
       snmpwalk -v 2c -c public localhost rs232SyncPortInterruptedFrames
       snmpwalk -v 2c -c public localhost rs232SyncPortAbortedFrames
       snmpwalk -v 2c -c public localhost rs232SyncPortRole
       snmpwalk -v 2c -c public localhost rs232SyncPortEncoding
       snmpwalk -v 2c -c public localhost rs232SyncPortRTSControl
       snmpwalk -v 2c -c public localhost rs232SyncPortRTSCTSDelay
       snmpwalk -v 2c -c public localhost rs232SyncPortMode
       snmpwalk -v 2c -c public localhost rs232SyncPortIdlePattern
       snmpwalk -v 2c -c public localhost rs232SyncPortMinFlags
       snmpwalk -v 2c -c public localhost rs232InSigState
       snmpwalk -v 2c -c public localhost rs232InSigChanges
       snmpwalk -v 2c -c public localhost rs232OutSigState
       snmpwalk -v 2c -c public localhost rs232OutSigChanges
    

    From another machine (not a Freeway), commands like these should work, if "fwy_ip_addr" is the IP address of a Freeway:

       snmpwalk -v 2c -c public fwy_ip_addr 1.3.6.1.4.1.854.1.1.1.1
       snmpwalk -v 2c -c public fwy_ip_addr 1.3.6.1.4.1.854.1.2.2.1.2
       snmpwalk -v 2c -c public fwy_ip_addr 1.3.6.1.4.1.854.1.2.2.1.3
       snmpwalk -v 2c -c public fwy_ip_addr 1.3.6.1.4.1.854.1.2.2.1.4
       snmpwalk -v 2c -c public fwy_ip_addr 1.3.6.1.4.1.854.1.2.2.1.5
       snmpwalk -v 2c -c public fwy_ip_addr 1.3.6.1.4.1.854.1.2.2.1.6
       snmpwalk -v 2c -c public fwy_ip_addr 1.3.6.1.4.1.854.1.2.2.1.7
       snmpwalk -v 2c -c public fwy_ip_addr 1.3.6.1.4.1.854.1.2.2.1.8
       snmpwalk -v 2c -c public fwy_ip_addr 1.3.6.1.4.1.854.1.2.2.1.9
       snmpwalk -v 2c -c public fwy_ip_addr 1.3.6.1.4.1.854.1.2.2.1.10
       snmpwalk -v 2c -c public fwy_ip_addr 1.3.6.1.4.1.854.1.2.2.1.11
       snmpwalk -v 2c -c public fwy_ip_addr 1.3.6.1.2.1.10.33.2.1.2
       snmpwalk -v 2c -c public fwy_ip_addr 1.3.6.1.2.1.10.33.2.1.3
       snmpwalk -v 2c -c public fwy_ip_addr 1.3.6.1.2.1.10.33.2.1.4
       snmpwalk -v 2c -c public fwy_ip_addr 1.3.6.1.2.1.10.33.2.1.5
       snmpwalk -v 2c -c public fwy_ip_addr 1.3.6.1.2.1.10.33.2.1.6
       snmpwalk -v 2c -c public fwy_ip_addr 1.3.6.1.2.1.10.33.2.1.7
       snmpwalk -v 2c -c public fwy_ip_addr 1.3.6.1.2.1.10.33.2.1.8
       snmpwalk -v 2c -c public fwy_ip_addr 1.3.6.1.2.1.10.33.3.1.2
       snmpwalk -v 2c -c public fwy_ip_addr 1.3.6.1.2.1.10.33.3.1.3
       snmpwalk -v 2c -c public fwy_ip_addr 1.3.6.1.2.1.10.33.3.1.4
       snmpwalk -v 2c -c public fwy_ip_addr 1.3.6.1.2.1.10.33.3.1.5
       snmpwalk -v 2c -c public fwy_ip_addr 1.3.6.1.2.1.10.33.3.1.6
       snmpwalk -v 2c -c public fwy_ip_addr 1.3.6.1.2.1.10.33.3.1.7
       snmpwalk -v 2c -c public fwy_ip_addr 1.3.6.1.2.1.10.33.3.1.8
       snmpwalk -v 2c -c public fwy_ip_addr 1.3.6.1.2.1.10.33.4.1.2
       snmpwalk -v 2c -c public fwy_ip_addr 1.3.6.1.2.1.10.33.4.1.3
       snmpwalk -v 2c -c public fwy_ip_addr 1.3.6.1.2.1.10.33.4.1.4
       snmpwalk -v 2c -c public fwy_ip_addr 1.3.6.1.2.1.10.33.4.1.5
       snmpwalk -v 2c -c public fwy_ip_addr 1.3.6.1.2.1.10.33.4.1.6
       snmpwalk -v 2c -c public fwy_ip_addr 1.3.6.1.2.1.10.33.4.1.7
       snmpwalk -v 2c -c public fwy_ip_addr 1.3.6.1.2.1.10.33.4.1.8
       snmpwalk -v 2c -c public fwy_ip_addr 1.3.6.1.2.1.10.33.4.1.9
       snmpwalk -v 2c -c public fwy_ip_addr 1.3.6.1.2.1.10.33.4.1.10
       snmpwalk -v 2c -c public fwy_ip_addr 1.3.6.1.2.1.10.33.4.1.11
       snmpwalk -v 2c -c public fwy_ip_addr 1.3.6.1.2.1.10.33.4.1.12
       snmpwalk -v 2c -c public fwy_ip_addr 1.3.6.1.2.1.10.33.4.1.13
       snmpwalk -v 2c -c public fwy_ip_addr 1.3.6.1.2.1.10.33.4.1.14
       snmpwalk -v 2c -c public fwy_ip_addr 1.3.6.1.2.1.10.33.5.1.3
       snmpwalk -v 2c -c public fwy_ip_addr 1.3.6.1.2.1.10.33.5.1.4
       snmpwalk -v 2c -c public fwy_ip_addr 1.3.6.1.2.1.10.33.5.1.5
       snmpwalk -v 2c -c public fwy_ip_addr 1.3.6.1.2.1.10.33.5.1.6
    

    2.6) How are all the configuration files and parameters of a Freeway related to each other?

    At the root of everything are the boot parameters, which can be displayed from the Freeway system menus by selecting (starting from the Main Menu):

        "2) Display Options"           then
        "3) Display Configuration"     then
        "4) Display Boot Parameters"
    

    Those parameters specify the Freeway's IP address, and where the Freeway should go to get its runtime files and its primary configuration file. The primary configuration file is specified as the "Configuration File Name" boot parameter. That file usually has a name like "bootcfg", and is generically called the "boot configuration" file; it serves as the root of all further configuration files.

    The boot configuration file specifies load files for each ICP board, usually with names like "awsloadb", and those load files specify the names of all the files to be downloaded into the ICP. The boot configuration file also specifies whether the Message Switch should be started; if the Message Switch is started, it uses a file named "switch.cfg" as its main configuration file (to tell it how to switch between sources and destinations), and files named "swdcfg" and "swtcfg" as its DLI and TSI configuration files. Finally, the main boot configuration file could start additional daemons, with their own configuration files; if so, it generally uses "exec =" lines to create those configuration files (see, for instance, the answer to question 2.16) How can I configure my Freeway as an NTP (Network Time Protocol) client or server?).


    2.7) How do I change the configuration of my Freeway?

    To change the boot parameters, select these menu items from the Freeway system menus (starting from the Main Menu):

        "3) Modify Configuration"      then
        "2) Modify Boot Parameters"
    

    The resulting display will take you through all the boot parameters, letting you change each one (just type in the new value of any parameter, or hit "enter" to keep the existing value, or "." (period) to clear a parameter).

    To change any other part of the configuration of your Freeway, you need to identify which configuration file you want to change. If the Freeway is configured to boot from its own internal hard disk (as most Freeways are -- the "Boot Device" boot parameter is set to "ide=0,0"), then the file(s) you want to change will be in its /tmp/boot/ directory. You can login to the Freeway, select "6" to enter the command shell, "cd /tmp/boot" to go to that directory, then "vi filename" to edit the file -- or you can use FTP to retrieve the file onto another system, edit it, then FTP the new file back into the Freeway.

    When you have made all your desired changes, you must command the Freeway to copy your newly-changed file(s) to a permanent location where it(they) will survive being rebooted (the /tmp/boot/ directory is only a volatile "memory disk" or "RAM disk", and its contents are lost every time the Freeway is rebooted). To command the Freeway to make your changes permanent, select these menu items (starting from the Main Menu):

        "5) Disk Drive Options"                 then
        "3) Hard Disk Maintenance Options"      then
        "3) Build Hard Disk From Boot Server"
    

    Then reboot your Freeway to have all your changes take effect.

    If your Freeway is configured to boot over the network (the "Boot Device" boot parameter is set to "fei0", "em0", "fxp0", or something similar), then the files will be in the boot server's directory (specified in the Freeway's boot parameters, where the Freeway is configured to get all its files from). In that case, you must change those files, and then reboot your Freeway.

    One thing to watch out for: the Freeway is sensitive to the additional ctrl-M character that some editors tack onto the end of each line. So if you FTP the files off the Freeway and edit them with your own editor, make sure it doesn't add those ctrl-M characters, or make sure to use "ASCII" mode (rather than "BINARY" mode) when FTPing the configuration files back to the Freeway (in ASCII mode, the Freeway will remove any trailing ctrl-M characters as it receives the file).


    2.8) Help! I changed the configuration of my Freeway, and now after it boots, I can't log in -- what can I do?

    This occurs if your changes have disrupted the normal boot sequence so badly that the Freeway daemon can't even start -- in that case ordinary menu access doesn't work, so user accounts like "root" and "freeway" are unable to log in. The solution is to login as user "shell" (default password "setup", and use the command prompt that it provides to fix things. The "dmesg" command may help you identify what went wrong, and why the Freeway daemon wasn't able to start.

    One likely cause is if you made your changes by FTPing the configuration files from the Freeway to another machine, and edited them there; the editor on that other machine may have put ctrl-M characters onto the end of some lines of the configuration files, which the Freeway boot process doesn't like. Always be sure to specify "ASCII" mode (rather than "BINARY" mode) when copying configuration files back to the Freeway.


    2.9) Help! I changed the configuration files in my Freeway, but now after it boots, it has exactly the same configuration as before (my changes are gone). How do I make my changes permanent, so they survive when I reboot the Freeway?

    This usually results from changing configuration files in /tmp/boot/ of your Freeway, but forgetting to copy those changed files into the permanent location, where they are copied from during the next boot sequence. To make your changes permanent, follow all the steps described in question 2.7) How do I change the configuration of my Freeway? carefully.


    2.10) I received a new CDROM from Protogate, with a new version of the Freeway software. Should I upgrade?

    We generally like customers to upgrade, but we understand that where a Freeway is performing a critical role in a production environment, the risks of downtime make upgrading unwelcome. In other environments (such as a development lab), however, keeping your Freeway upgraded to the latest Freeway software version will provide you with the latest features and bugfixes, and will help us to support you better.

    If you are still undecided, learning what features and bugfixes you will gain by upgrading to the new version may help you decide. If you insert your new Freeway CDROM into any machine with a web browser, you can find the release notes and the release notes history (or take the plain text versions of those files directly from the root of the CDROM; they are the files "relnotes.ser" and "relhist.ser"). Those files will describe the changes that were made since the Freeway version that you are currently running, and should help you decide whether you would benefit from upgrading. (To find the software version you are currently running, look at the version string which appears at the top of the Freeway Main Menu , immediately after you log in to your Freeway).


    2.11) How do I use the Freeway CDROM to upgrade my Protogate Freeway to a new software version?

    NOTE: the recommended procedure for upgrading a Freeway has changed, starting with the "X-B" Freeway release CDROM (based on Freeway 3.1-3), which was released on 12 May, 2004. The previous method should still be used for all Freeway releases prior to that.

    Beginning with the 3.1-3 Freeway release, the Freeway install CDROM will by default attempt to save existing configuration files and protocol image files before initializing the Freeway disk, then will restore those files after loading the new software onto the disk (previous versions had to be explicitly commanded to perform this service by setting "PRESERVE_PARTS=yes"). Another enhancement starting with that version is that now when the Freeway is booted from the CDROM, it determines the IP address which is used by the Freeway when booted normally (from its own disk), and sets an alias to that IP address. So if, for example, your Freeway ordinarily uses IP address 192.168.100.100, then when you boot it from the CDROM it will have two addresses: 192.168.135.1 (the standard address for a CDROM-booted Freeway) and 192.168.100.100 -- and you can telnet to it using either of those addresses. These two enhancements simplify upgrading your Freeway.

    Below are the procedures: first the new procedure, then the previous one -- use the section corresponding to your CDROM's Freeway version. And as always, if you have any questions or problems upgrading your Freeway to any Freeway software version, don't hesitate to contact Protogate directly, at (US) 858-451-0865 or support@protogate.com.

    For Freeway CDROMs "X-B" (3.1-3) or later:

    First backup anything on your Freeway that you want to preserve (most Freeways do not have anything which must be preserved, but if you are developing code on the Freeway you may have some files on its disk, or if you have altered or created additional configuration files you may wish to save those). Then insert the CDROM into the Freeway's CDROM drive and boot the Freeway. It will boot from the CDROM, and once it has completed booting you should telnet to it (using either its usual IP address or 192.168.135.1), login as root/setup, type "6" to enter the command shell, then type these commands, exactly as shown:

         cd /etc
         . /etc/rc.buildfwy
    

    The rc.buildfwy command will warn you that it's going to overwrite things on the disk, but you don't need to type anything more; just give it 10 minutes or so to finish, and then you can remove the CDROM and reboot your Freeway again, and it will be using the new software.

    The above command attempts to preserve your boot parameters, config files and some programs, but isn't guaranteed not to overwrite any of those (which is why you backed up your own programs earlier). If you want to simply clobber all the permanent storage on the entire Freeway and do a completely clean install, you can use the command

         PRESERVE_CFG=no ; . /etc/rc.buildfwy
    
    instead of the one above. If you do that, you will have to re-enter your boot parameters and re-install any protocols that were on that Freeway before the upgrade.

    If for some reason you can't telnet to your Freeway, you can connect a serial terminal to the "Console" connector at the back of the Freeway case and use that to login and enter the upgrade command, or you can connect an ordinary VGA monitor and keyboard to the back of the case, and use that.

    For Freeway CDROMs "W-A" (3.1-1) or earlier:

    As described above, you should first backup anything on your Freeway that you want to preserve. Then connect a serial console terminal to the "Freeway console" port on the back of the Freeway case, insert the CDROM into the Freeway's CDROM drive, and reboot the Freeway. It will boot from the CDROM, and once it has completed booting you should login as root/setup, type "6" to enter the command shell, then type these commands, exactly as shown:

         cd /etc
         PRESERVE_PARTS=yes ; . /etc/rc.buildfwy
    

    The rc.buildfwy command will warn you that it's going to overwrite things on the disk, but you don't need to type anything more; just give it 10 minutes or so to finish, and then you can remove the CDROM and reboot your Freeway again, and it will be using the new software.

    The above command attempts to preserve your boot parameters, config files and programs, but isn't guaranteed not to overwrite any of those (which is why you backed up your own programs earlier). If you wanted to simply clobber all the permanent storage on the entire Freeway and do a completely clean install, you could use the plain " . /etc/rc.buildfwy " command instead of the one above. If you do that, you will have to re-enter your boot parameters and re-install any protocols that were on that Freeway before (We don't suggest doing it this way; the "PRESERVE_PARTS=yes" command shown above seems to work best for most customers).

    If you don't have a serial terminal, you can instead connect an ordinary VGA monitor and keyboard to the back of the case, and use that to enter the commands. You may also be able to telnet to the Freeway; its IP address when booted from the CDROM will be 192.168.135.1 (but it will go back to what it was before, when the upgrade process is complete and you remove the CDROM and reboot).


    2.12) What kind of logging is available on the Freeway?

    The basic logging of messages from the Freeway daemon is available in the Freeway menus, which you can get by logging in to the Freeway and selecting these menu items:

       "2) Display Options",      then
       "2) Display Log Messages"
    

    Once viewed, those messages will not be displayed again, so re-entering those menu items will only show new messages (that occurred after the previous message log viewing). To see all messages in the circular buffer, use these menu items (starting from the Freeway Main Menu):

       "2) Display Options",                    then
       "5) Display System Information",         then
       "6) Display Circular Queue of Messages"
    

    In addition to the Freeway daemon logs, there is also a system-level log which you can view with the "dmesg" command, from the BSD shell.


    2.13) Does the Freeway provide any other kind of diagnostic help, besides the Freeway logs?

    Yes, probably the most helpful thing the Freeway does is provide the ability to extract a "trace file", containing all the IP message traffic to and from the Freeway. For information about getting a trace file, see the answer to question 7.2) How do I get a "Freeway trace" file?.

    There is also "tcpdump", a command available from the command shell which can be used to show the complete contents of all IP packets, or a selected subset of the IP packets. Use "man tcpdump" for more details.


    2.14) I'd like to do something in the Freeway menus, but there is no menu screen that will do what I want. What can I do?

    You can probably do what you want in the BSD shell, which is a command-line interface available by logging in to the Freeway and selecting menu item "6". That will give you a BSD prompt, where you can type any command which is available on the Freeway. When finished, you use the "exit" command to return to the Freeway menus.

    There are hundreds of commands you can run from that command-line prompt, and chances are you will be able to do anything you want to do.


    2.15) Where can I find more information about the BSD-shell commands I can enter on my Freeway?

    There are Unix-style "man pages" available for many of the commands, so use the command "man foo" to find out detailed information about the command "foo". If you don't know the name of a command, but only know what you want to accomplish, use the command "apropos foo" (where "foo" is a keyword describing what you want to accomplish). The "apropos" command provides a list of man pages containing subject matter relevant to the keyword you specify, and you can use the "man" command to read those man pages. For example, "apropos ntp" shows a list containing several NTP-related man pages, including "ntpd", "ntp.conf", "ntpq" etc. -- and you can use "man ntpd", "man ntp.conf", etc. to find which one includes the information you need.


    2.16) How can I configure my Freeway as an NTP (Network Time Protocol) client or server?

    Setting up basic NTP on a Freeway is very easy. You can configure it as either an NTP client, a server, or both. You just have to add a few lines to the bootcfg file that your Freeway uses, so you have lines something like these:

      ## to synchronize with an NTP (Network Time Protocol) timeserver at powerup
      exec = /usr/bin2/ntpdate 192.168.135.22
    
      ## to create an NTP configuration file
      exec = echo "server 192.168.135.22 prefer"       > /tmp/ntp.conf
      exec = echo "driftfile /var/run/ntpd.driftfile" >> /tmp/ntp.conf
    
      ## to start an ntpd daemon (see "man ntpd" for details)
      exec = /usr/bin2/ntpd -p /tmp/ntpd.pid -c /tmp/ntp.conf
    

    (These lines assume a time server at 192.168.135.22, so make sure to change that to your timeserver's IP address, in 2 places.)

    The lines with "#" as the first non-blank character are comments. The lines starting with "exec =" are commands to be executed at system startup. The ntpdate command synchronizes the time once, at power-up, then the ntpd program keeps the Freeway time synched with the timeserver as long as the Freeway is running. The two echo lines create a small ntp.conf file, which tells the ntpd daemon which IP address to synchronize to, and where to store information about the drift speed and direction of the Freeway clock. The ntpdate command is necessary because if the Freeway time is too far different from the timeserver's time when the Freeway is booted, the ntpd daemon will refuse to change the Freeway time (so don't remove or comment-out that ntpdate line).

    After you make these bootcfg changes and reboot your Freeway, you should be able to login and run the "ntptrace" command on it, and see that it is synching to your timeserver (you might have to wait a few minutes for your Freeway to sync completely, because the NTP protocol is very cautious about claiming to be synchronized).

    For more information, login to your Freeway, select "6" to enter the BSD shell, and type these commands:

       man ntpd            (the NTP daemon)
       man ntp.conf        (the NTP configuration file)
       man ntptrace        (trace a chain of NTP servers back to the primary source)
       man ntpq            (standard NTP query program)
       man ntpdc           (special NTP query program)
       apropos ntp         (for a list of NTP-related man pages)
    

    2.17) How can I configure my Freeway to perform Unix-style "syslog"ing?

    The syslogd daemon isn't started by default on a Freeway, but you can start it by putting a few lines into your boot configuration file. One thing to watch out for, though: if you keep your Freeway powered up for extended periods, you should check occasionally to make sure the disk partition doesn't fill up with log data (or also set up the newsyslog daemon). There should be several megabytes available in the partition which contains /var/log/, so you ought to be okay for several weeks of uptime, at least, if you put your log files there -- and you can run the "df /var/log" command occasionally to tell you how much free space is left.

    Here is a simple example of how to setup the syslogd daemon so that it starts automatically when the Freeway is booted, by adding these lines to the Freeway's boot configuration file:

      exec = touch /var/log/lastlog
      exec = chmod 644 /var/log/lastlog
      exec = echo "auth_list = passwd"      > /etc/auth.conf
    
      exec = touch /var/log/all.log
      exec = chmod 644 /var/log/all.log
      exec = echo "*.*  /var/log/all.log"   > /etc/syslog.conf
      exec = /usr/sbin/syslogd -s
    

    That will set up syslogd to log all syslog output to the /var/log/all.log file. /var/log/ is a "Memory Disk" partition, so the all.log file will be lost every time the Freeway is rebooted; if you need access to the log files across reboots, you should set up syslogd to log onto another machine in your network somewhere.

    Note also that if you add more than that single line to /etc/syslog.conf, you must use ">>" rather than a ">" in your added lines (all lines except the first), to append to the file rather than re-create it.

    For more information about the syslogd daemon and the various options available when setting it up, login to your Freeway, select "6" to enter the BSD shell, and type these commands:

       man syslogd         (the syslogd daemon)
       man syslog.conf     (the syslogd configuration file)
       man newsyslog       (maintain syslog files at specified sizes)
    

    2.18) Why did you tell that last guy (who wanted to configure syslog on his Freeway) to put his syslog configuration statements into his bootcfg file? Isn't that doing it the hard way? I put similar lines directly into a syslog.conf file in my Freeway's /ro/etc/ subdirectory and it worked fine.

    It is a bit roundabout, the way we suggest doing it. It seems simpler to do what you did (to create a permanent file in /ro/etc/, rather than using the "exec =" statements in the boot configuration file to create the file when the Freeway is booted). But the advantage of doing it in the boot config file, the way we suggest, is that then that single file can contain all the local customized configuration changes, making it much easier to administer the Freeway. Upgrading to a new Freeway software version will be easier, too, since the upgrade process does not change the boot configuration file, so all the changes you've made will remain intact. If you make changes in other places, then you'll have to keep track of those changes so you know how to re-establish the configuration you had, when you upgrade your Freeway to the latest software, or when you receive a new Freeway from Protogate.


    2.19) Can I configure PPP links on my Freeway?

    Yes, if you configure your Freeway to use the Message Switch, you can configure the Freeway to use any or all of your Normal Mode WAN ports as PPP links. See the answers to question 3.13) How can I configure the Message Switch to use my WAN line as a PPP link? and question 3.14) Can I configure more than one PPP link on a single Freeway with the Message Switch?.


    2.20) I would like my Freeway to automatically reboot itself once a week, every Sunday morning at 2:00 AM; how can I get it to do that? (or: How do I get my Freeway to perform some task automatically at a specified time?)

    Setting up scheduled events on a Freeway is simple, using the "cron" daemon. You just have to add a few lines to your Freeway's bootcfg file, similar to these:

      ## to create a crontab file
      exec = echo "SHELL=/bin/sh"                             > /etc/crontab
      exec = echo "PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin"  >> /etc/crontab
      exec = echo "HOME=/var/log"                            >> /etc/crontab
      exec = echo "#"                                        >> /etc/crontab
      exec = echo "#minute hour   mday   month   wday    who     command" >> /etc/crontab
      exec = echo "#"                                        >> /etc/crontab
      exec = echo "0         2      *      *       0     root    /sbin/reboot -n -q" >> /etc/crontab
    
      ## to start the cron daemon (see "man cron" for details)
      exec = /usr/sbin/cron
    

    These lines would cause the Freeway to reboot automatically at 2:00 AM every Sunday morning, but the crontab file can be used to execute any command at any time. Additional lines can be added, too, to configure the Freeway to execute several different command at different times (for example, to change the firewall settings at different times of day).

    For more information, login to your Freeway, select "6" to enter the BSD shell, and type these commands:

       man cron            (the cron "scheduled commands" daemon)
       man 5 crontab       (the cron "scheduled commands" configuration file)
    

    2.21) I need my Freeway to be able to boot into different configurations, but I don't want to have to edit the configuration files each time. How can I do that?

    The simplest way is to create an ordinary CDROM (non-bootable) containing a file called bootparm.txt in the root directory. That file should contain lines which specify any changes you want to make in the boot parameters. For instance, if you maintain two (or more) alternate boot configuration files, then you can use bootparm.txt to modify the boot parameters to change which boot configuration file is used, and completely alter the configuration of the Freeway (it could have different protocols loaded into the ICP boards, for instance).

    The bootparm.txt file must contain lines of this form:

                   Boot_Device                  : fei
                   Processor_Number             : 0
                   FTP_User_Name                : freeway
                   FTP_Password                 : password
                   Flags                        : 0
                   Freeway_Server_Name          : freeway1
                   Freeway_Inet_Address         : 192.168.1.193
                   Freeway_Subnet_Mask          : ffffff00
                   Boot_Server_Name             : bootmaster
                   Boot_Server_Inet_Address     : 192.168.1.2
                   System_Boot_Directory        : /usr/local/freeway/boot
                   System_Boot_File_Name        : fw486
                   Configuration_File_Name      : bootcfg.pci
                   Secondary_Net_Interface      :
                   Gateway_Inet_Address         :
    

    The field to the right of the colon is the new value for the specified boot parameter. Empty-valued fields will keep the previously-existing boot parameter value, and "." will erase the boot parameter value (make it blank). Lines with "#" as the first non-whitespace character are taken as comments, and have no effect on any boot parameters. Boot parameters without a corresponding line in the bootparm.txt file will remain unchanged.

    An even more powerful method of making automatic changes to your Freeway configuration is also available: by creating an ordinary CDROM (non-bootable) containing a file called command.sh in the root directory. That file can contain "sh" script commands, which the Freeway will execute when it powers up. You can use those commands to do anything you want, including make changes to the Freeway configuration files.

    The bootparm.txt and command.sh files can co-exist on the same CDROM, if you want to combine both capabilities.


    2.22) There are all these different ways to configure the Freeway, or alter what it does while it boots. What is the exact sequence of steps the Freeway performs when it boots?

    The order of all initialization commands performed by the Freeway during power-up is as follows:

    1. look for a 'bootparm.txt' file on the CDROM, and if found use it to set the boot parameters;
    2. if not found, look for a 'bootparm.txt' file on the floppy, and if found use it to set the boot parameters;
    3. if not found, look for a 'bootparm.txt' file on the first (DOS) partition of the internal disk, and if found use it to set the boot parameters (if that file is found it is also deleted after the boot parameters are set, so it will not continue to be used again with each subsequent system boot;
    4. if no bootparm.txt file is found in any of those 3 places, use the current boot parameters.
    5. boot using the (possibly-modified) boot parameters
    6. retrieve 'sra_module =' files (specified in the boot cfg file)
    7. execute 'exec =' commands (specified in boot cfg file)
    8. start the main Freeway daemon (initializes the ICP boards)
    9. start the Message Switch, if specified in the boot cfg file
    10. execute 'sra_entry =' commands (specified in boot cfg file)
    11. execute the shell commands in /ro/etc/rc.startsra
    12. if the file /tmp/boot/rc.startsra exists, execute it as a shell command script file.
    13. if the file /usr/local/freeway/boot.src/rc.startsra exists, copy it to /tmp/boot/rc.startsra and execute it as a shell command script file
    14. look for a 'command.sh' file on the CDROM, and if found execute it as a shell command script file


    2.23) I want to secure my Freeway by eliminating all known and all unnecessary login accounts. Which accounts must I leave and which can I remove?

    The original (as installed) Freeway accounts and passwords are:

        username    password
        --------    --------
        root        setup
        shell       setup
        user        PicoBSD
        freeway     password
        protogate   password
        simpact     password
    

    The "shell" and "user" accounts are meant as failsafe entry points which can be used to login even if the Freeway software itself fails to start; they take the user to a plain command shell rather than into the Freeway menus (see the answer to question 2.8) Help! I changed the configuration of my Freeway, and now after it boots, I can't log in -- what can I do? for an example of how those accounts can be useful). So you should keep at least the "root", "shell" and "freeway" accounts, if possible.

    A good start on securing your Freeway would be to remove the "user", "protogate", and "simpact" accounts, and change the passwords of the 3 accounts that are left ("root", "shell", and "freeway"). The easiest way to remove accounts is through the menus; when logged in as root, select (starting from the Main Menu):

       "3) Modify Configuration",         then
       "3) Modify User Names",            then
       "3) Delete User From Login Table", then
    

    then type in the username that you want to delete (you don't even need the passwords for those usernames).

    The easiest way to change a password is to login as root and select the

       "3) Add User to Login Table"
    

    selection from the "Modify User Names" menu. That will allow you to add new usernames or to change the password of existing usernames.


    2.24) How about restricting the access method? I want to force users to use SSH to login to the Freeway, and not allow user access via telnet, rlogin, or ftp.

    You can do that simply by changing the /etc/inetd.conf file on your Freeway. But remember that the permanent copy of that file is kept in /ro/etc/inetd.conf, so we suggest changing it in the user configuration file, by adding lines like this in your /usr/local/freeway/boot.src/rc.startsra file, to add a preceding "#" character to comment-out the access methods you don't want to allow:

      sed -e "s~^telnet~#telnet~" /etc/inetd.conf  > /etc/inetd.conf2
      sed -e "s~^login~#login~"   /etc/inetd.conf2 > /etc/inetd.conf3
      sed -e "s~^ftp~#ftp~"       /etc/inetd.conf3 > /etc/inetd.conf4
      rm /etc/inetd.conf
      cp /etc/inetd.conf4 /etc/inetd.conf
      rm /etc/inetd.conf2 /etc/inetd.conf3 /etc/inetd.conf4
      kill -HUP `cat /var/run/inetd.pid`
    

    You can implement this change by logging in as the root user, editing the /tmp/boot/rc.startsra file to add those lines, then using the user menus to make the changes permanent, as described in the answer to question 2.7. Doing it that way preserves all your changes in a single place, and makes it easier to upgrade to later versions of the Freeway software (for instance, even if the upgrade process installs a new version of inetd.conf, your changes will still work -- see the answer to question 2.18 for more discussion about this).


    2.25) I need even tighter Freeway access security. Can I configure a firewall on the Freeway, and restrict access to certain IP addresses?

    Yes, Freeway software versions 3.1-1 and later include full firewall capabilities. By default, the firewall is open (it allows connections from any source), but you can add your own rules to restrict access in any manner you desire, with lines like these in your boot configuration file:

       exec = /sbin/ipfw add 1000 deny ip from 192.168.3.0/24 to any
       exec = /sbin/ipfw add 1100 deny ip from 192.168.4.4 to any
    

    ( those lines would disallow all IP access from any machine on the 192.168.3.0 subnet, and from 192.168.4.4 ).

    The "ipfw list" command (typed in from the BSD shell) shows a list of all existing firewall rules, and "ipfw show" shows statistics about the number of packets which have been treated under each rule. See the output of "man ipfw" for additional commands, and for details about the rule syntax.


    2.26) My Freeway has two ethernet interfaces. Can I configure it to detect when one fails (or is disconnected) and automatically switch to the other interface (redundant failover)?

    Yes, you can configure the Freeway to run a script which monitors the ethernet interfaces and switches between them when necessary. The example script below keeps the second ethernet interface turned off, but sets that interface to the same ethernet (MAC) address as the first interface, so that switching between the two won't disturb ARP on the LAN segment, even if both interfaces are plugged into the same ethernet hub or switch. The script then sets the second interface to the same IP address as the first interface, then enters a loop where it continually tries to ping two other IP addresses. Whenever it fails to reach both of those IP addresses it switches the current ethernet interface off and the other one on, effectively "failing over" to the other interface.

    A simple way to configure your Freeways to use a script like this is to put it into the Freeway's /tmp/boot/ directory, then add a line like this to the rc.startsra file in that directory:

       sh /tmp/boot/ipfailover.sh &
    

    Then you will have to select "5", "3", and "3" from the Freeway menus to copy those files back to the permanent place on the Freeway's disk, so they will be copied to /tmp/boot/ whenever the Freeway is booted (see FAQ entry 2.7) How do I change the configuration of my Freeway? for details about this).

    Here is the script:

    
    #!/bin/sh
    #
    # This script alternates between em0 and em1 (or between fxp0 and fxp1
    # on older Freeways) whenever it detects a failure on the interface
    # which is currently in use.
    #
    
    export ETH_PINGTARGET1=192.168.1.193
    export ETH_PINGTARGET2=192.168.1.194
    
    export ETH_DEV="`ifconfig |sed -e '2,/*/d' |sed -e 's/0.*//'`"
    
    if [ -n ${ETH_DEV} -a -n "${ETH_PINGTARGET1}" -a -n "${ETH_PINGTARGET2}" ] ; then
    
      ifconfig ${ETH_DEV}0 down
      ifconfig ${ETH_DEV}1 down
      export ETH0_ETHERLINE="`ifconfig ${ETH_DEV}0 | sed \"/ether/!d\"`"
                         # Note: The 2 bracketed areas in the line below each
                         #      contain one tab character and one space character.
      export ETH0_INETLINE="`ifconfig ${ETH_DEV}0 | sed \"/[ 	]*inet[ 	]*/!d\" | sed \"2,\\$d\"`"
      ifconfig ${ETH_DEV}1 ${ETH0_ETHERLINE}
      ifconfig ${ETH_DEV}1 ${ETH0_INETLINE}
    
      # do forever
      while true ; do
    
        # Resetting to use the first Ethernet device (em0 or fxp0)
        ifconfig ${ETH_DEV}1 down
        ifconfig ${ETH_DEV}0 up
        route -n change default -ifp ${ETH_DEV}0
        sleep 30
      
                  # stay here as long as we can ping either target
        while ping -n -o -t 10 ${ETH_PINGTARGET1} > /dev/null ||
              ping -n -o -t 10 ${ETH_PINGTARGET2} > /dev/null ||
              ping -n -o -t 10 ${ETH_PINGTARGET1} > /dev/null ||
              ping -n -o -t 10 ${ETH_PINGTARGET2} > /dev/null    ; do
          sleep 10
        done
    
        # Resetting to use the second Ethernet device (em1 or fxp1)
        ifconfig ${ETH_DEV}0 down
        ifconfig ${ETH_DEV}1 up
        route -n change default -ifp ${ETH_DEV}1
        sleep 30
    
                  # stay here as long as we can ping either target
        while ping -n -o -t 10 ${ETH_PINGTARGET1} > /dev/null ||
              ping -n -o -t 10 ${ETH_PINGTARGET2} > /dev/null ||
              ping -n -o -t 10 ${ETH_PINGTARGET1} > /dev/null ||
              ping -n -o -t 10 ${ETH_PINGTARGET2} > /dev/null    ; do
          sleep 10
        done
    
      done
    
    else
      echo "Configuration error in ipfailover.sh.  Exiting..."
    fi
    
    

    If you use this script, don't forget to change the IP addresses to machines that are actually on your network which will be available to respond to pings whenever your Freeway is running. Both ETH_PINGTARGET variables can be set to the same IP address, if there is only one other address available. You may also want to change the count or timing of the ping commands; "man ping" from the Freeway shell will give you information about the arguments to that command.

    In our tests with Freeways using this script, we have found that we can have both ethernet cables plugged into a single hub and can then alternately remove those cables without affecting a loopback test running from another client machine; the Freeway would switch interfaces to whichever one is still connected, and the client machine never knew any difference (except for the delay before the script switched interfaces).


    2.27) What is a Freeway "SRA" (Server-Resident Application)? How can I create one?

    An "SRA", or "Server-Resident Application", is a client program which runs on the Freeway itself. SRA programs have all the abilities that any other DLI/TSI client program has: they can open/close, enable/disable, read/write, or perform any other operation on any link. They can also read or write to files, send or receive data via IP sockets, etc. A typical example of an SRA is a program running on the Freeway which opens a protocol link and reads all the data from it, passing selected data to another system via the LAN (or writing it to a file). Another example of an SRA is a program running on the Freeway which opens two serial links (possibly using two different protocols), then reads from one link and sends the data to the other link -- in fact, the Message Switch is actually an SRA which performs this function in a general-purpose way, under the control of a configuration file (to tell it which links to read, and which links to send the data to).

    SRAs are written just like any ordinary client program is written, using the DLI/TSI libraries which are installed on all Freeways (and to make certain you have everything you need, the DLI/TSI library code is available on all Freeways in both sourcecode and binary form). Every Freeway is also delivered with a full set of GNU C/C++ compiling/linking tools, as well as the gdb debugger, the BSD "make" utility, and several editors, including the "vi" editor -- so any Freeway can serve as an excellent self-contained workstation, to completely develop, code, and test any SRA.

    To create an SRA, you simply write your code into an appropriate subdirectory under your Freeway's /usr/local/freeway/client/test/ directory, then compile it and run it just as you would on any other machine. And because we run the loopback tests for all protocols as SRAs, there are probably already subdirectories containing SRA sourcecode under the /usr/local/freeway/client/test/ directory on your Freeway that you can use as examples (we installed those subdirectories when we tested the serial links on your Freeway, before we delivered it).


    2.28) I need the Freeway to automatically close all socket connections when my client reboots, or is reset, or is disconnected from the LAN. How can I configure the Freeway to do this?

    If a client program (which has an active connection to a Freeway) is killed, but the machine it was running on stays up, then the operating system on that machine will send TCP/IP FIN or RESET packets to the Freeway to close all of that client's TCP connections, and the Freeway will then close the associated sessions by sending DLI_ICP_CMD_TERM packets to their ICP boards immediately. But if the client's machine is killed by pushing a reset switch, or its ethernet connection is disconnected, then the FIN or RESET TCP fragments won't be sent to (or won't reach) the Freeway, and the Freeway won't know that the client is gone (of course, if the previous client machine is able to finish booting, the Freeway might discover that the connections are gone when it tries to send a TCP packet fragment to one of those connections, and the newly-rebooted client machine returns a RESET packet, because it knows nothing about the previous connections).

    The problem here is that if the Freeway never receives a FIN or RESET, it has no way of knowing that the connection is gone -- it simply thinks the client isn't sending anything any more on those connections. And that prevents a new client from connecting to those links, because the Freeway thinks there is already a client connected there. The solution is to configure the Freeway to perform keepalive processing on the TCP links. When configured for keepalive, the Freeway monitors all TCP links for activity; if no activity occurs for a specified amount of time on a TCP connection, the Freeway sends a "keepalive" packet to the other end of that connection. If healthy, the other end of the TCP connection sends a response back to the Freeway (neither the keepalive packet or the keepalive response affects the stream of data between the two ends of the TCP connection). If no response is received for a specified time, the Freeway sends another keepalive. If no response is received after 8 keepalives have been sent, the Freeway assumes that the other end of the connection has crashed, and closes the TCP connection.

    The keepalive discovery process can take quite a while (several hours, by default), but you can set the keepalive times on your Freeway by adding lines in its bootcfg file similar to these:

       exec = sysctl net.inet.tcp.keepidle=20000
       exec = sysctl net.inet.tcp.keepintvl=5000
       exec = sysctl net.inet.tcp.always_keepalive=1
    

    The Freeway system sends the first keepalive packet if there is no activity on a TCP connection for "keepidle" milliseconds; if that gets no response from the other side it then sends 7 additional keepalive packets, spaced "keepintvl" milliseconds apart. If none of those get a response, the connection is declared dead and the socket is closed. So the total detection time (in seconds) is given by this formula:

       ( keepidle + 8 * keepintvl ) / 1000
    

    (The multiplier is 8 rather than 7 because the system waits "keepintvl" milliseconds even after the last keepalive packet is sent).

    The defaults for those values are keepidle=7200000 and keepintvl=75000, which gives a detection time of

      ( 7200 + 8 * 75 ) = 2 hours and 10 minutes
    

    Setting them as shown above (to 20000 and 5000) would result in:

       ( 20 + 8 * 5 ) = 60 seconds
    

    You'll want to set yours to values that are small enough so the Freeway detects failed connections as quickly as you want it to, but not so small that it fills your network with unnecessary keepalive packets. See "man tcp" on your Freeway for more details (after entering that command, you can hit "/keep" and a carriage-return to go down to the keepalive-related text).


    2.29) How can I tell if my Freeway contains a CPU-47, CPU-48, or a CPU-49 Single Board Computer (SBC)? What are the differences in behavior between a Freeway with a CPU-47, a Freeway with a CPU-48, and a Freeway with a CPU-49?

    If you take a look at the back of the Freeway, the differences between a CPU-47 and CPU-48 or CPU-49 are visible. The tailplate for a CPU-47 has the USB connections above the secondary ethernet connector on the left tailplate, and the CPU-48 or CPU-49 has one tailplate with the USB keyboard connector above both ethernet connectors.

    In software, or when logged in, the easiest way to tell which type of CPU a Freeway has is by looking for the string "atapci1:" in the device probing information; a CPU-47 has two ATA devices called atapci0 and atapci1, but a CPU-48 has only one ATA device and therefore has no atapci1. A CPU-49 also has an atapci1, but it is implemented by a "Panther Point" controller rather than the CPU-47's ICH controller.

    For example, a shell script such as rc.startsra could use code like this to tell which type of CPU it is running on:

      if /usr/bin/grep "atapci1:" /var/run/dmesg.boot >/dev/null ; then
        if /usr/bin/grep "atapci0:.*Panther" /var/run/dmesg.boot >/dev/null ; then
          # This is a CPU-49, add CPU-49 code here...
        else
          # This is a CPU-47, add CPU-47 code here...
        fi
      else
        # This is a CPU-48, add CPU-48 code here...
      fi
    

    There are 2 differences that Freeway users may need to adjust for between a Freeway containing a CPU-48 and a Freeway containing a CPU-49. The first and most major difference is that Freeway software versions 5.1-0 and earlier will not run on a CPU-49 (actually they run, but the Ethernets are not supported, so the TCP/IP network is not available). Freeway versions 6.0-0 or later run fine on either CPU-48 or CPU-49 (and also run fine on a CPU-47).

    The second difference is that the PCI bus mapping of ICP boards differs between CPU-48 and CPU-49 Freeways. This generally requires altering the bootcfg file settings -- for example, on a Freeway 3412 with a CPU-48, where the bootcfg file has these lines in the icp0 section:

       bus_number    =   4
       slave_address = 0xa
    

    An equivalent Freeway 3414 with a CPU-49 would require these lines, even though the ICP board is installed into approximately the same location (the nearest useable slot to the power supply) on both Freeways:

       bus_number    =   2
       slave_address = 0xc
    

    This difference normally doesn't affect Freeway users, since each Freeway is configured differently anyway (for its own complement of ICP boards, etc.). And even in the case where identical disks are desired between CPU-48 and CPU-49 Freeways (for example, if you want to be able to move a disk from a CPU-48 Freeway to a CPU-49 Freeway, assuming they both have the same number of ICP boards in similarly-positioned slots), it is easy to adjust for the differences automatically with a boot-time script such as /usr/local/freeway/boot.src/rc.startsra . For example, you could use grep commands similar to those in the shell script above, and add code to copy either a bootcfg.cpu48 or bootcfg.cpu49 file to bootcfg . We've implemented scripts like that; please contact us at (US) 858-451-0865 or support@protogate.com if you need something similar.

    There are 4 differences that Freeway users may need to adjust for between a Freeway containing a CPU-47 and a Freeway containing a CPU-48. The first and most major difference is that Freeway software versions 5.0-0 and earlier will not run on a CPU-48 (actually they run, but the Ethernets are not supported, so the TCP/IP network is not available). Freeway versions 5.0-1 or later run fine on either CPU-47 or CPU-48. For users who need to run Freeway software 5.0-0 or earlier on CPU-48 Freeways, we can install separate dual-Ethernet boards which are compatible with the old software -- though of course we recommend that you upgrade to the latest software instead.

    The second difference is that the PCI bus mapping of ICP boards differs between CPU-47 and CPU-48 Freeways. This generally requires altering the bootcfg file settings, as described above for the CPU-48/CPU-49 differences. For example, on a Freeway 3410 with a CPU-47, where the bootcfg file has a "bus_number = 3" line in the icp0 section, an equivalent Freeway 3412 with CPU-48 would require that line to be "bus_number = 4", even though the ICP board is installed into the exact same physical slot.

    The third difference is that the CPU-47 generally does not exhibit an SNMP problem which was fixed in Freeway software version 5.0-2, which was causing the output of 3 SNMP requests to be incorrect on the CPU-48: icpType, icpNumberPorts, and icpSlaveAddress. Under Freeway software 5.0-2 or later, this difference disappears, and both CPU-47 and CPU-48 Freeways behave correctly (and so do CPU-49 Freeways with Freeway software 6.0-0 or later).

    The fourth difference is that the CPU-47 supports a USB keyboard a little more easily than the CPU-48 does. The CPU-48 requires that ACPI be turned off to support the USB keyboard fully, but neither the CPU-47 nor the CPU-49 require anything other than that USB be enabled in the BIOS. See 2.4a) Can I use a USB keyboard instead of a PS/2 keyboard to get console access to my Freeway? for more details.

    Of the 4 differences, the first and the third do not occur if the latest Freeway software is used, and the second and fourth do not affect most Freeway users, and have simple workarounds for users who need them.


    2.30) Is there kernel-level auditing support on the Freeway? How can I configure that and enable it?

    All versions of the Freeway software from 6.0-1 or later include full support for kernel-level auditing. It can be configured and enabled by adding lines like these to the Freeway's /usr/local/freeway/boot.src/rc.startsra file:

      if [ ! -d /var/audit ]; then
        mkdir -p -m 750 /var/audit
      fi
      chmod go-w /etc/security
      if /usr/bin/grep "^host:" /etc/security/audit_control >/dev/null; then
        echo "host line already in audit file -- will not tamper with it..."
      else
        echo "host:${B_FWY_SERVERNAME}"  >> /etc/security/audit_control
      fi
    
                       # If audit_user file has not been altered by any user, then
                       # add default settings for the 3 initial login accounts.
      if [ 5 = `cat /etc/security/audit_user |wc -l` ]; then
        echo "user:ex,ap,aa,lo,ad,na,fd,fc,fm,fw,-fr:no"       >> /etc/security/audit_user
        echo "freeway:ex,ap,aa,lo,ad,na,fd,fm,fc,fw,-fr:no"    >> /etc/security/audit_user
        echo "protogate:ex,ap,aa,lo,ad,na,fd,fm,fc,fw,-fr:no"  >> /etc/security/audit_user
        echo "simpact:ex,ap,aa,lo,ad,na,fd,fm,fc,fw,-fr:no"    >> /etc/security/audit_user
      fi
    
                # Start the kernel-level audit daemon.
      /usr/sbin/auditd
    
    

    That configuration assumes there is a writeable disk partition mounted at /var/, and the audit records will be stored into files in the /var/audit/ directory. The lines added to the /etc/security/audit_user file configure auditing of the 4 originally-configured Freeway users. For a description of the format of the /etc/security/audit_user file, run "man audit_user" on a 6.0-1 (or later) Freeway. For the available event types, see the /etc/security/audit_class and /etc/security/audit_event files.

    Once kernel-level event auditing is started, the root user can use "praudit -l /var/audit/current" to see the audit entries, or "praudit -l /dev/auditpipe" to continually see the latest entries as they appear.


    2.31) How can I save the configuration of a Freeway, for restoration later?

    All files which have been changed or added since the original installation of the Freeway should be saved, to allow restoration of the full Freeway configuration later. However, under most circumstances, and especially if the Freeway has been configured as described in question 2.18) Why do you recommend putting all configuration statements into the bootcfg file? , you should only need to save these files:

    They can all be saved into a single file with commands like this (executed as the root user):

      cd /
      tar -cvf /tmp/configfiles.tar ro/etc/*passwd*
      tar -rvf /tmp/configfiles.tar ro/etc/*pw*
      tar -rvf /tmp/configfiles.tar ro/etc/group
      tar -rvf /tmp/configfiles.tar usr/local/freeway/boot.src/bootcfg*
      tar -rvf /tmp/configfiles.tar usr/local/freeway/boot.src/muxcfg*
      tar -rvf /tmp/configfiles.tar usr/local/freeway/boot.src/nvram.txt
      tar -rvf /tmp/configfiles.tar usr/local/freeway/boot.src/*load*
      tar -rvf /tmp/configfiles.tar usr/local/freeway/boot.src/*mem
      tar -rvf /tmp/configfiles.tar usr/local/freeway/boot.src/rc.startsra*
    

    Then copy the resulting /tmp/configfiles.tar file to another machine and save it. (The configfiles.tar file should be considered sensitive, since it will contain encrypted copies of the passwords of all user accounts that were on the Freeway when it was created.) To restore the configuration later, copy that configfiles.tar file to the Freeway again (for example, into the /tmp/ directory) and execute commands like this (again as the root or shell user):

      cd /
      mount -u -o rw /
      mount -u -o rw /usr
      tar -xvf /tmp/configfiles.tar
      mount -u -o ro /
      mount -u -o ro /usr
    

    After that, when you reboot your Freeway it will again have the same configuration it had when you originally saved all those files.

    NOTE: If you have an SRA configured to run on your Freeway, you may have some additional files to save, such as the SRA program file itself, its DLI and TSI configuration files, and any other configuration files it needs. Those files will probably be in the /usr/local/freeway/boot.src/ directory, so just add "tar -rvf ..." commands to save them into your /tmp/configfiles.tar file, along with all the other files.


    2.32) I just received a new Freeway (or upgraded one of my Freeways), and now my ssh client programs can't login to it. How can I fix this?

    Starting with Freeway software version 7.1-4, the secure shell (ssh) daemon on the Freeway became more tightly restrictive by default, and stopped allowing some of the weaker ciphers, message authentication codes, and key exchange algorithms that were allowed by previous versions. This change was necessary to preserve security -- but because of this change, some older ssh client programs will not be able to connect with a Freeway, if it is running Freeway software version 7.1-4 or later in its default configuration.

    If this change affects you (you have older ssh client programs that cannot connect to a Freeway, and you need them to do so), you can configure the Freeway to allow those old, weaker connection methods, so your old ssh client programs will be able to connect to it. That change requires adding a line to the Freeway's /ro/etc/ssh/sshd_config file, and then rebooting the Freeway. From then on, your older ssh clients will always be able to connect to the Freeway. The line which needs to be added is this:

      KexAlgorithms "+diffie-hellman-group1-sha1,diffie-hellman-group-exchange-sha1"
    

    To add that line, you first will need to find a way to login to the Freeway. You can either find an ssh client that does work, or connect a VGA screen and keyboard to the Freeway, or connect a serial terminal console to the Freeway. Then you will need to login and become the root (shell) user. If the default user accounts have not been modified, you can login with username "freeway", password "password" -- then type "6" to select the "6) Run FreeBSD Shell" menu item (to enter the command shell), then "su - shell" to login as the root (shell) user with password "setup". Once logged on as the root (shell) user, enter the following 5 commands, exactly as shown:

      cd /ro/etc/ssh/
      mount -u -o rw /
      cp -pf sshd_config   sshd_config.defaultkex
      echo 'KexAlgorithms "+diffie-hellman-group1-sha1,diffie-hellman-group-exchange-sha1"' >> sshd_config
      mount -u -o ro /
    

    Then "reboot" and all of your ssh clients should work. The change is permanent, so your ssh clients should always work after that (until you re-install or upgrade the Freeway software; if you haven't upgraded your ssh clients by then, you will have to perform this procedure again after upgrading the Freeway software).

    A bit of explanation: The "mount" commands above are necessary because the disk filesystems are normally mounted read-only on all Freeways, so those commands mount it read-write temporarily so you can make the change, then read-only again after making the change. The "cp" command saves a copy of the original sshd_config file, so you can use that to return to the original configuration if you want to.

    If you have any problems, or need additional help or explanations, contact us directly at (US) 858-451-0865 or support@protogate.com .


    3. Message Switch


    3.1) What is the Message Switch good for?

    The Message Switch is a software daemon which runs on the Freeway and transfers data between a selected set of sources and destinations. The usefulness comes from its ability to transfer data between different types of source and destination. The simplest application is where you have a client program which can receive one type of data (for example, UDP/IP packets); the Message Switch can be configured to transfer WAN data directly to your client (or to many clients). But there are lots of other uses for the abilities of the Message Switch.

    For instance, two Message Switch-equipped Freeways can reside at two different sites, connected by an IP network (such as the Internet). If the first Message Switch is configured to convert an incoming WAN data stream to a TCP data stream and send it to the IP address of the second Freeway/Message Switch, and the second Freeway/Message Switch is configured to convert the incoming TCP data stream back into an outgoing WAN data stream, then the final recipient of the data can receive the WAN data exactly as if it was located at the first site -- the two Message Switches act as a WAN "bridge" across the IP network.

    The opposite application also works, for the case where there is a WAN connection (leased line) between two sites, with one Freeway/Message Switch converting IP traffic into outgoing WAN data, and the second Freeway/Message Switch converting it back to IP data stream -- in this case the two Message Switches act as an IP "bridge" across the WAN data link.

    Some of the Message Switch capabilities are explored in the How to Access WAN Protocol Data from an IP Network page of Protogate's website. That page has links to the C sourcecode of several programs that you can use with the Message Switch to do various things.

    Additional information is in the Message Switch User's Guide (or the PDF file ) available from Protogate's website.


    3.2) Can I configure the Message Switch to receive data from a WAN link, and send it as UDP packets on my LAN?

    Yes, by adding a line like this to the switch.cfg file:

    icp0port0 > udp://192.168.1.2:0x4000/
    

    The Message Switch would then send every packet received from icp0port0 as a UDP packet to 192.168.1.2, UDP port 0x4000 (decimal port 16384). You could also use a line like this, if icp8port0 is configured (in your Freeway's boot configuration file) as an icp_ip device setup to transmit and receive UDP packets:

    icp0port0 > icp8port0
    

    3.3) How about the other direction (to receive UDP packets, and send them to a WAN link)?

    Sure -- just switch the order of the line in switch.cfg:

    icp0port0 > udp://192.168.1.2:0x4000/
    

    You could also configure it to transfer data in both directions:

    icp0port0                  > udp://192.168.1.2:0x4000/
    udp://192.168.1.2:0x4000/  > icp0port0
    

    3.4) Can the UDP packets use broadcast or multicast addresses?

    Yes, just use a broadcast or multicast address in the switch.cfg lines:

       icp0port0 > udp://192.168.1.255:0x4000/
    or
       icp0port0 > udp://234.5.6.10:0x4000/
    

    3.5) Can the source or destination be a TCP data stream, rather than a UDP packet stream?

    Yes, but there is no corresponding "tcp:" specifier available, so you have to configure a "TCP" ICP_IP device in your Freeway's boot configuration file, and use that. So lines like these (in your boot config file):

    device_name          =  icp8
    device_type          =  icp_ip
    socket_type          =  sock_stream_listen
    local_address        =  0.0.0.0
    local_port_base      =  0x3600              # 13824
    foreign_port_base    =  0x0000
    send_q_size          =  0x14                # 20 packets
    internal_protocol    =  ipnull
    

    Would setup a listening socket at TCP port 0x3600 (decimal 13824). Then lines like these (in your switch.cfg file):

    icp0port0 > icp8port0
    icp8port0 > icp0port0
    

    Would tell the Message Switch to transfer all data from icp0port0 to the TCP connection, and vice-versa.


    3.6) When using a TCP data stream, does the Freeway (with Message Switch) have to be the "listen"er (the passive, server side of the TCP connection), or can it also be the "connect"er (the active, client side)?

    The ICP_IP device that the Message Switch uses can be a TCP listener or connector; the device should be configured in the boot configuration file either with

        socket_type = sock_stream_listen
    or
        socket_type = sock_stream_connect
    

    When configured as a connector, a "connect_period =" line can also be used to specify how often it attempts to connect.


    3.7) Not that I want to do this, but I'm just curious: could I configure the Message Switch to take a stream of UDP packets and send them to a TCP connection (and vice-versa)?

    Yes, or multiple streams of UDP packets to a single TCP connection (or vice-versa), or to multiple TCP connections (or vice-versa), or to a set of TCP connections and a set of WAN links (or vice-versa), or ...


    3.8) I think I've got it now. The Message Switch connects data stream sources and destinations to each other, and the sources and destinations can be any combination of UDP packet streams, TCP connections, and WAN ports. Is that right?

    Yes, that's exactly right, except you forgot the most flexible of all source/destination types: programmable endpoints.


    3.9) What is a "programmable endpoint"?

    The Message Switch software which runs on the Freeway can be configured to transfer data from a set of inputs to one or more sets of outputs. From the Message Switch's point of view, these inputs and outputs are simply "endpoints"; the Message Switch takes data from each endpoint and sends it to one or more other endpoints. These endpoints can be WAN links, UDP or TCP sockets, or other devices (hard disk files, etc.). Another type of endpoint supported by the Message Switch is called "Programmable Endpoints".

    Programmable Endpoints are separate programs, running on the Freeway, which have their Standard Input and Standard Output connected to the Message Switch. When the Message Switch is configured to use a Programmable Endpoint, it forks a separate process running the Programmable Endpoint program, with data pipes set up to connect that process to the Message Switch. Whenever the Message Switch sends data to that endpoint, the Programmable Endpoint process will receive it on stdin, and whenever the Programmable Endpoint process sends data to stdout, the Message Switch will be able to read it from that endpoint.

    Because the Programmable-Endpoint program is a simple stdin-stdout program, it can be easy to create, but because it has access to all of the features of the Freeway it can have great power. For example, a program to compress WAN-link data can be written in about 250 lines of C code, and another program to send WAN-link data to an FTP server can be written in even fewer lines.

    The last program described above is a good example of the power and flexibility of the Freeway when running the Message Switch with Programmable Endpoints. When configured this way, the Freeway will take all of the data on all desired WAN links and write it into a set of files on an FTP server; and it will begin doing so automatically, as soon as it is powered up, with no intervention necessary by any person or other machine.


    3.10) Can the Message Switch receive data from a single source (WAN port, UDP packet stream, TCP data stream, or programmable endpoint) and send it to several different destinations?

    Yes, by adding several lines to the switch.cfg file with the same source specifier. For example:

    icp1port2 > icp6port0
    icp1port2 > icp6port1
    icp1port2 > icp7port0
    

    would send each packet received from icp1port2 to all 3 of the destinations shown. And if desired, icp1, icp6, and icp7 could all be running different protocols.


    3.11) Can it retrieve data from several different sources and send that data to a single destination?

    Yes, by adding several lines to the switch.cfg file with the same destination specifier. For example:

    icp0port0 > icp6port3
    icp1port0 > icp6port3
    icp2port0 > icp6port3
    

    Would send each packet received from icp0port0, icp1port0, or icp2port0 to icp6port3, regardless of which protocols are running in icp0, icp1, icp2, or icp6.


    3.12) Can I configure the Message Switch to send more than just the data? I need it to send the protocol information, too (link up/down notification, data acknowledgements, etc.)

    Yes, by adding an "h" character either before or after the ">" or ">>" characters, you can configure the Message Switch to expect or produce a standard 32-byte ICP/Protocol header preceding the data of each packet. For example, "h>" or "h>>" would cause the Message Switch to convert the first 32 bytes of data received from that source into an ICP/Protocol header to be sent to the destination, and ">h" or ">>h" would cause the Message Switch to convert ICP/Protocol header coming from the source into a 32-byte header preceding the data, when sending to the destination. The result is that switch.cfg lines like these (this assumes icp8 is an icp_ip device, setup to transmit and receive UDP packets to/from a simple socket-level client program):

       icp8port0 h>   icp1port0
       icp1port0  >h  icp8port0
    

    would result in every UDP packet received or sent by the client program having a 32-byte header preceding the data. The client can use that header to send non-data packets (such as those to configure/enable/disable the link) and to receive non-data packets (such as those notifications of link up/down status, data acknowledgements, etc.).

    The header is assumed to be in network-standard order, so the client program should use the ntohs() and htons() routines wherever necessary.


    3.13) How can I configure the Message Switch to use my WAN line as a PPP link?

    For an asynchronous PPP link, all that is required is to start the PPP daemon and tell it to take its input/output from a UDP port, then configure the Message Switch to transfer data from/to an ICP board loaded with the AWS protocol to/from that same UDP port (using the localhost address, because these UDP packets are being sent between processes within the same Freeway). That results in lines like this in the switch.cfg file:

       udp:/127.0.0.1/0.0.0.0:3000/  >  icp0port0
       icp0port0                     >  udp:/127.0.0.1/0.0.0.0:3000/
    

    For a synchronous PPP line (which is compatible with a router's "WAN PPP" link), the ICP board must be loaded either with the Protocol Toolkit protocol or the X.25 protocol. When loaded with the Protocol Toolkit, the configuration is similar to the configuration used for asynchronous PPP described in the paragraph above. When loaded with X.25, a special programmable endpoint called the swbsdx25 must be used, to configure the X.25 link into "RAW HDLC" mode and handle the sending and receiving of data -- and the Message Switch is then configured to send/receive data between the UDP port (connected to the PPP daemon) and the swbsdx25 programmable endpoint (which is connected to the X.25 link).

    Because it is the most complex, the example shown here is for the case where the X.25 protocol is loaded into icp0. This example also uses the rc.startsra file, which you can put into your boot directory and the Freeway will execute when it boots. In this example, the rc.startsra file contains all the lines necessary to configure and start the Message Switch and start the PPP daemon which the Message Switch connects to.

    The rc.startsra file:

      #!/bin/sh
      #
      cd /tmp/boot
      dlicfg swx25dcfg
      tsicfg swx25tcfg
      /tmp/boot/x25_manager cs_config 0 mgr hdlcraw.setup
      dlicfg swdcfg
      tsicfg swtcfg
      swbsd >/dev/console &
      sleep 1
      sleep 1
      /sbin/ppp -ddial udpconn1
    

    The switch.cfg file (fragment):

    DLICfgFile = swdcfg
    
    # Create connections between an ICP loaded with X.25/HDLC and the PPP daemon:
    
    udp:/127.0.0.1/0.0.0.0:3001/      >>h  prog:swbsdx25~cs_config~link0~h
    prog:swbsdx25~cs_config~link0~h  h>>   udp:/127.0.0.1/0.0.0.0:3001/
    

    The swx25dcfg file (fragment):

    main
    {
        LogLev = 3;                    // Level of logging
        TraceLev = 3;                  // Level of tracing
        MaxSess = 32;                  // max # sessions allowed
        AsyncIO = "Yes";               // Non-blocking mode
        SessPerConn = 1;               // max # sessions per TSI connection
        tracesize=64000;
        LogName   = "/tmp/swx25dli.log";   // file name for log facility
        TraceName = "/tmp/swx25dli.trc";   // file name for trace facility
        TSICfgName = "swx25tcfg.bin";      // TSI configuration file name
    }
    
    RawSess0
    {
        Protocol = "Raw";               // Raw session type
        Transport = "ClientVX";         // Transport connection name
                                        // defined in TSICfgName file
        Mode = "User";                  // Mode of operation for ICP
        Family = "Protocol";            // Family --- Protocol only
        BoardNo = 0;                    // ICP board number -- based 0
        PortNo = 0;                     // Port number.
        Timeout = 32000;                // Timeout value in seconds
        Retries = 1;                    // Number of retries
        TraceLev = 3;
        LogLev = 7;
        MaxInQ = 50;                    // Max # entries in input Q
        MaxOutQ = 50;                   // Max # entries in output Q
        MaxErrors = 100;
        LocalAck = "Yes";
        AsyncIO = "Yes";
        AlwaysQIO = "Yes";
        OutOfBand = "Yes";
        ReUseTrans = "No";              // Multiple sessions per conn
    }
    
    RawSess1
    {
        initfrom = "RawSess0";
        PortNo = 1;
    }
    
    ... etc. ...
    
    BoardMgr
    {
        initfrom = "RawSess0";
        Mode = "Mgr";                   // Mode of operation for ICP
    }
    

    swx25tcfg (fragment):

    main
    {
        AsyncIO = "Yes";                 // Non-blocking mode
    //    tracelev = 3;
    //    loglev = 3;
        maxbufsize = 2200;
    //    maxbuffers = 256;
    //    maxconns = 32;
        tracesize = 64000;
        tracelev = 0;
        loglev = 0;
        tracename =  "/tmp/swx25tsi.trc";
        logname   =  "/tmp/swx25tsi.log";
    }
    
    ClientVX
    {
        transport = "tcp-socket";
        logLev = 7;
        traceLev = 3;
        retries = 1;
    //  maxbufsize =1324;
        timeout = 32000;
        maxinq = 60;
        maxoutq = 60;
        maxerrors = 10;
        remtsi = "yes";
        asyncio = "Yes";
        segmenting = "no";
        buffering = "no";
        outofband = "yes";
        server = "localhost";
        wellknownport = 0x'2010';
    //  tcpnodelay    = "yes";           // TCP_NODELAY socket option
    }
    

    hdlcraw.setup:

    COMMENT
      ( jag; ************************************************************
      The following command file text may be fed to the X25_MANAGER
      sample program to configure X.25/HDLC on the Freeway ICP to
      use "RAW HDLC".  The Message Switch can then use the swbsdx25
      program to connect input and output of a Raw HDLC port to the
      PPP daemon, to implement synchronous PPP.
    
      The configuration may be summarized as follows:
    
        HDLC        link 0 DTE
        HDLC        link 1 DCE
    
      ************************************************************)
    
    SAPX25
      {
      VERSION,              comment(report X.25 software version data)
      BUFFERS
        [                   COMMENT(CONFIGURE Freeway ICP BUFFERS),
        BIG(0),             comment(segmentation buffer size in bytes),
        SMALL(2140),        comment(communication buffer size in bytes),
                            comment(the SMALL size must be exactly
                                    60 bytes less than the size specified
                                    for maxbufsize in muxcfg and in
                                    swx25tcfg)
        ],
      }
    SAPSLP
      {                     COMMENT(BEGIN HDLC SERVICE CONFIGURATION)
      COMMENT
      (******************************************************
      *     CONFIGURE EVEN LINKS as DTE under HDLC          *
      ******************************************************)
      SLP [                 COMMENT(CONFIGURE HDLC LAPB DATA LINKS),
        LINKS(0),           comment(links for following configuration),
        DXE(DTE),           comment(DTE or DCE),
        CLOCK(EXTERNAL),    comment(INTERNAL, EXTERNAL or X21V11),
        RAW_HDLC(YES),      comment(raw HDLC -- no LAPB),
        MODULUS(8),         comment(frame modulus 8 or 128),
        WINDOW(7),          comment(frame window 1 to modulus-1),
        T1(2.0),            comment(0.1 to 255.9 seconds),
        T2(0.1),            comment(0.1 to 255.9 seconds),
        N2(5),              comment(1 to 255 retries),
        RATE(64000),        comment(300 to 128000 baud),
        EIA(V35),           comment(232, 449, 530, or V35)
        ],
      COMMENT
      (******************************************************
      *     CONFIGURE ODD LINKS as DCE under HDLC           *
      ******************************************************)
      SLP [                 COMMENT(CONFIGURE HDLC LAPB DATA LINKS),
        LINKS(1),           comment(links for following configuration),
        DXE(DCE),           comment(DTE or DCE),
        CLOCK(EXTERNAL),    comment(INTERNAL, EXTERNAL or X21V11),
        RAW_HDLC(YES),      comment(raw HDLC -- no LAPB),
        MODULUS(8),         comment(frame modulus 8 or 128),
        WINDOW(7),          comment(frame window 1 to modulus-1),
        T1(2.0),            comment(0.1 to 255.9 seconds),
        T2(0.1),            comment(0.1 to 255.9 seconds),
        N2(5),              comment(1 to 255 retries),
        RATE(64000),        comment(300 to 128000 baud),
        EIA(V35),           comment(232, 449, 530, or V35)
        ],
      }                     COMMENT(END HDLC SERVICE CONFIGURATION)
    EXIT
    

    /etc/ppp/ppp.conf (fragments):

    default:
     set log Phase Chat LCP IPCP CCP tun command
     ident user-ppp VERSION (built COMPILATIONDATE)
     set device /dev/ttyp5
     set speed 9600
     set timeout 600
     add default HISADDR
     enable dns
     set server 3000 ""
     disable dns
    
    udpconn1:
     set server 3001 ""
     set speed sync
     set device 127.0.0.1:3001/udp
     set dial
     set timeout 30
     set log Phase Chat Connect hdlc LCP IPCP IPV6CP CCP tun
     set ifaddr 10.1.4.2/0 10.1.4.1/0
     # the next 4 lines disable compression, just for debugging
     # (so I can see the data)
     disable deflate
     deny deflate
     disable pred1
     deny pred1
    

    3.14) Can I configure more than one PPP link on a single Freeway with the Message Switch?

    Yes. There is no limit to the number you can have, other than the hardware limitations on the Freeway itself (the amount of RAM, etc.).


    3.15) Can I configure the Message Switch to compress my data before sending it to me or to a WAN port?

    Yes, by using the swbsdz programmable endpoint. You simply include lines like these into your switch.cfg file:

       icp0port0              >> prog:swbsdz~0~2000~id1
       prog:swbsdz~0~2000~id1 >> icp1port0
    

    In that example, the first argument to the swbsdz program is 0, which specifies compression (non-zero would specify de-compression), the second argument is 2000, which specifies that the maximum size of the resulting data is 2000 bytes, and the final argument is "id1" which is a string not used by the swbsdz program, but which the Message Switch uses to differentiate between several compression streams, since the Message Switch assumes that each differing endpoint string defines a different endpoint.

    If icp1port0 in the above example is configured as a UDP socket which sends to another Freeway/Message Switch, then that other Freeway/MSW could have lines like this in its switch.cfg file:

       icp1port0              >> prog:swbsdz~1~2000~id1
       prog:swbsdz~1~2000~id1 >> icp0port0
    

    Which would cause it to de-compress the data coming from icp1port0 (which should be set up to receive data from the other Freeway) and send it to icp0port0.


    3.16) Can I configure the Message Switch to take the data it retrieves from some source (or sources), pack it into files, and send those files to an FTP server?

    Yes, the swbsdftp programmable endpoint does this. You simply include lines like this into your switch.cfg file:

       icp0port0 >> prog:swbsdftp~192.168.135.22~anonymous~emailaddr~incoming~ftp%d
    

    To have each packet coming from icp0port0 sent to a file on the FTP server at 192.168.135.22, using login "anonymous", password "emailaddr", in the directory "incoming", and with filenames "ftp1", "ftp2", "ftp3", etc.


    3.17) How do I write my own Programmable Endpoints?

    Programmable endpoints are fairly easy to write, since they are simple stdin/stdout programs. There are descriptions with links to example sourcecode on the How to Access WAN Protocol Data from an IP Network page of Protogate's website; those examples are intended to serve as useful starting points.

    The Freeway itself has a full set of C/C++ compilation/linking tools, as well as the gdb debugger and a few editors, including the "vi" editor, so it serves as an excellent self-contained workstation to completely develop, code, and test a programmable endpoint.


    4. DLI/TSI, and Client Programs which Connect to a Freeway


    4.1) What is the "DLI"?

    The DLI is a very portable subroutine library which is designed to make it easier to connect to a Freeway from various types of client machines (Solaris and other Unixes, NT, VMS, etc.). The name stands for "Data Link Interface".

    The DLI operates in one of two modes: Normal Mode or Raw Mode. In Raw Mode it makes a connection to a Freeway and requires the client program to do everything else. In Normal Mode the DLI makes a connection to a Freeway, then to an ICP board, then to the protocol code running on that ICP board, then configures and enables a specific WAN link -- and then allows the client program to send/receive data from the WAN link. All of the DLI operations in Normal Mode are controlled by lines in a DLI configuration file, which tell the DLI which protocol is running on a given ICP board, how to configure the WAN link, whether to enable the link, etc.).

    The DLI uses the TSI as its low-level data transport layer; the DLI and TSI are generally compiled into a single library file (they are supplied to you in sourcecode form, and you compile them on your own system).


    4.2) What is the "TSI"?

    The TSI is a very portable subroutine library which is designed to make it easier to connect to a Freeway from various types of client machines (Solaris and other Unixes, NT, VMS, etc.). The name stands for "Transport Subsystem Interface".

    The TSI uses TCP/IP connections to transport data, but provides message boundary preservation, logging, and several other services beyond what a simple TCP connection would provide. The TSI serves as the low-level data transport layer for the higher-level DLI; the DLI and TSI are generally compiled into a single library file (we supply them to you in sourcecode format, and you compile them on your own system).


    4.3) What is "Normal Mode"?

    Normal Mode is the term used to denote a DLI connection which incorporates processing that is customized for a specific protocol. The alternate form of DLI connection is a "Raw Mode" connection.

    In Raw Mode, the client application program must send all protocol-specific commands to the Freeway or ICP board itself (to tell it how to configure/enable the link, etc.), but in Normal Mode it can rely on the DLI sending those commands. The result is that a client program using Raw Mode looks like this:

       dlOpen()
       ... wait for open to complete ...
       dlWrite( command to configure ICP board )
       ... wait for response ...
       dlWrite( command to configure link )
       ... wait for response ...
       dlWrite( command to enable link )
       ... wait for response ...
       dlRead( data ) and dlWrite( data )
    

    Whereas a client program written to use Normal Mode looks like this:

       dlOpen()
       ... wait for open to complete ...
       dlRead( data ) and dlWrite( data )
    
    In Normal Mode, the link configuration parameters specified in the DLI configuration file are used by the internal DLI code to configure and enable the link, so to change something like the data rate, for instance, you simply make a change to your configuration file, then re-run your program.


    4.4) What are the dlicfg and tsicfg programs for?

    The dlicfg and tsicfg programs are used to change plaintext (ASCII) versions of the DLI and TSI configuration files into their binary equivalents which are used by the DLI/TSI library code. Another purpose of dlicfg and tsicfg is to validate the structure and syntax of the DLI/TSI configuration files, and report any errors -- which allows errors to be detected and corrected prior to running the actual DLI/TSI client application program.


    4.5) When I try to run the dlicfg program, I get an error which says "DLI was built with stub ***.c, and does not support ***". What does that mean?

    This is because you are using the standard DLI/TSI library to connect to one of Protogate's "access-controlled" protocols. For these protocols, there is an additional file included on your protocol CDROM, with the name given in the above command (shown above as ***.c); you should copy that file into the freeway/lib/dli/ subdirectory of your DLI/TSI library sourcecode, replacing the smaller "stub" file of the same name which already exists there. Then when you rebuild your DLI/TSI library and re-link your application with the new library, this error will no longer occur.


    4.6) Can I use a multi-threaded program with the DLI/TSI library?

    Yes, but you must use a DLI/TSI library which has been compiled to use pthreads. If you are compiling/linking your application directly on a Freeway, all you have to do is to change your Makefile to link against the /usr/local/freeway/client/bsd/lib/libbsdfw_r.a library instead of the plain libbsdfw.a library, define DLI_PTHREAD during your compiles, and set the -pthread switch on your compile and link commands.

    If your application will run on a separate system (other than a Freeway) you must re-compile your DLI/TSI to use pthreads, by changing the CFLAGS lines in your Makefiles from this:

       CFLAGS= -O
    

    to something like this:

      CFLAGS= -O -DDLI_PTHREAD -pthread
    

    You must make that change in all of your DLI/TSI Makefiles. For instance, if your client program machine is to run under Solaris, you should make that change in the 4 Makefile.SOL files under ..../freeway/lib/, in the subdirectories cfg/, dli/, tsi/, and util/ .

    Re-compiling the DLI/TSI this way is necessary because the TSI ordinarily uses signals to tell it when there is data available on a socket, and calls the callback routines (into your code) within the context of a signal handler. That isn't a reliable method under pthreads, so when the code is compiled with DLI_PTHREAD defined it uses pthreads instead; it creates a separate thread to watch for data on the sockets, and when data is available it calls the callback routines (which run within the context of that thread).

    The "-pthread" part of the CFLAGS line above may not be correct for your build tools, so you may have to substitute another definition for it to tell your build tools to compile for use with pthreads ("-pthread" is the keyword used by the GCC compiler). The "-DDLI_PTHREAD" part is the part that tells our DLI/TSI code to use the alternate method of checking for socket data.

    If you add "-DDLI_PTHREAD" and rebuild your DLI code, but still have problems (your calls to dlOpen() complete normally, but subsequent calls to dlPoll() never result in the DLI session reporting DLI_STATUS_READY; the status remains DLI_STATUS_NOT_READY) -- then your operating system may have a problem which we have seen occasionally with the use of select() under pthreads. In that case, add "|| defined( SOLARIS )" (or whatever keyword is defined by your Makefiles) to 1 #ifdef line to change the code to reduce the reliance on select(). The line to change is in lib/tsi/tsisupp.c, and is the line which contains: "defined( SGI )".


    4.7) Can I run a DLI/TSI client program on the Freeway itself?

    Yes, in fact it's quite easy to develop and run a client program directly on the Freeway; see the answer to question 2.27 for more information about how to do this. These types of client programs are called "SRA"s, which is an acronym for Server-Resident Applications.

    The only difference between an SRA and any other DLI/TSI client program is that the "server" field of the TSI configuration file used by the SRA should be set to "localhost", to make it connect to the Freeway it's running on, rather than to some other machine with a different IP address.


    5. ICP Boards


    5.1) What does the ICP board do?

    An ICP (Intelligent Communications Processor) board is a general-purpose serial-communications board. It is optimized for serial data communications, but has a CPU on it which enables it to handle many different types of serial communications protocols. The rear panel of every ICP board has a connector or connectors which can be connected to serial WAN data communications links.

    ICP boards handle the lowest-level sending and receiving of bits on a serial communications link, and implement the medium-level protocol rules. The resulting data is packaged into blocks for sending/receiving to and from the machine that the ICP is plugged into (which may be a Freeway).


    5.2) What types of ICP board are available?

    All current ICP boards are PCIbus-based, and there are models with 2, 4 or 8 communications ports; these 3 models are called the ICP2432B-2, ICP2432B-4 and the ICP2432B-8. The 2- and 4-port models allow each port's electrical interface (EIA-232, EIA-449, EIA-530, V.35, etc.) to be selected under software control; the 8-port model is EIA-232 only. Additional information about ICP2432B boards is available in the ICP2432 for PCIbus section of Protogate's website.

    Previous models of ICP boards connected to a VMEbus (the ICP6000) or to a PCIbus, but with a different CPU and serial controller (the ICP2432A). Due to the unavailability of some of the Integrated Circuits used on these ICP boards, these models are no longer in production, but Protogate can still repair them.


    5.3) Are there ICP boards which plug into VMEbus?

    A previous generation ICP board, the ICP6000, was available until January of 2002. That board is no longer in production, because some of the parts it used are no longer available, but Protogate can still repair these boards.


    5.4) I get a "Device time out" message after resetting my ICP board, so I cannot download the protocol. Is my ICP board broken?

    This is most likely because you are using an older driver, or a new driver with a previous (too short) timeout value.

    When reset, each ICP goes through a complete check of its systems before it responds on the PCIbus, to tell the host system that it is ready to be downloaded. The host driver must wait until the board is ready; and if the board does not respond after a timeout period, the driver declares the ICP inaccessible. But older ICPs completed their system checks more quickly than current ICPs (mostly because they had much smaller amounts of RAM onboard), so the timeout values previously used are inadequate for current ICP2432B boards. The timeout values for current ICP2432B boards should be 20 seconds or more; increasing your timeout value to 20 seconds or more should solve this problem.


    6. Protocols


    6.1) Why do I need a "protocol"?

    A protocol is simply a set of rules of behavior. When data is transmitted over a serial link from one site to another, it is necessary for both the sender and the receiver to follow the same set of rules, otherwise the receiver may not receive the data that the sender sent. These rules are called a "serial communications protocol" (for our purposes we will often shorten the name to simply "protocol").

    There are many different serial communications protocols, broadly classified according to how they send bit sequences on the serial line. Since Protogate's ICP board is a general-purpose serial line communications board, and is capable of following the rules of any serial communication protocol, it needs some way of telling it how to behave -- how to follow the rules of a specific protocol. We do that by writing the rules into a set of "C" and assembly language instructions, then compiling those instructions into a protocol image (a file). We provide that protocol image file to you along with your ICP board, and you configure your Freeway (or embedded system) to download that file into your ICP board, and then to command the ICP board to execute those instructions. When that is done, the serial links on the ICP will behave according to the specified protocol.

    For us the word "protocol" can mean two things: it can mean the set of rules themselves, or it can mean the protocol image file which an ICP board uses to tell it how to obey those rules. So when you ask "Why do I need a "protocol?" (the first meaning) the answer is "so you and the other side of your serial communications link will agree on how to send and receive data." The answer for the second meaning is "you need a protocol (image file) to make your ICP obey the rules of a specific protocol."


    6.2) What protocols do you have available "off-the-shelf"?

    A partial list of our WAN protocol products includes:
    CD2, X.25, HDLC LAPB, Link11B (TADIL-B), ATDL-1 (UDL), IDL, Link1, Lateral Tell, MBDL, STD-1200B, STD-1300, ADCCP ABM, ADCCP NRM, nine-bit radars, transparent bisync radars, Mode I (AUTODIN) and Mode II (AUTODIN), BSC 3270/3780, Asynchronous, DDCMP, Market Feed, SWIFT, and CHIPs.

    We also have partial implementations of some additional protocols, and some of the protocols listed here also occasionally go by other names, so please contact us if you don't find the protocol you need.

    Additional information about our off-the-shelf protocols is available in the WAN protocol products section of Protogate's website.


    6.3) Protogate doesn't already have the protocol I need. Can I create it myself? What tools and skills do I need to do that?

    Yes, it is possible for you to create your own protocol code, resulting in a protocol image which is downloaded into an ICP board to implement your protocol. All the software tools you'll need to develop and test any software for the ICP board's "Coldfire" CPU (editors, C compiler, assembler, and linker) are right on your Freeway and freely available for use at any time. (The compiler/assembler/linker are different from those required for developing SRA programs which run on the Freeway CPU itself. Both sets of tools are resident on every Freeway).

    To create a protocol image, you'll need to have a good understanding of how your protocol operates (the serial-link transactions between sender and receiver); you'll also need to know how to program in C, and some knowledge of the architecture of the ICP board and of the serial communications integrated circuits which it uses. Protogate offers classes which may help; see the description of the Protocol Toolkit Course on Protogate's website for details.


    6.4) Protogate doesn't already have the protocol I need. Can you create it for me? How much would that cost?

    Yes, we do this fairly often, for customers with one-of-a-kind protocols. We need a detailed description of the protocol; that description is usually found in a document called a "Protocol Specification", which describes exactly what the protocol should do.

    The cost is dependent on the complexity of the protocol, and on whether it is similar to any already-existing protocols we have (sometimes a custom protocol is actually derived from a standard protocol, with only a few changes; in that case it is quite simple for us to create a new protocol image). The way to proceed with this is to send us the protocol specification and ask us to provide you a quote for implementing it on our ICP boards.


    6.5) I'm using a synchronous protocol, and I'm not sure I have the clocksource set correctly. What symptoms would I see if my ICP port's clocksource is set to "internal", but the other side of the WAN link (or the modem that my ICP board is connected to) is sending the clock signal?

    That could work for a little while, but could fail or give data errors at seemingly random times. Anytime the two ends are using different clocks to send and receive a data stream, then there is a possibility of errors, even though both clocks are running at the same nominal rate (because the clocks won't be exactly synchronized, and will drift until one is different enough from the other to cause one side to receive an extra bit, or miss a bit). The symptom you'll see from that is occasional read errors on the other end of your WAN link; and the greater the discrepancy between the two clock rates, the greater the frequency of errors.

    This kind of mismatch won't cause read errors on the ICP end, though, because the ICP's receive clock is always supplied externally for synchronous protocols, even when "clocksource" is set to "internal". For synchronous protocols, the clocksource setting only affects which clock is used for the data being transmitted by the ICP.


    6.6) I'm using a synchronous protocol, and I'm not sure I have the datarate set correctly. What symptoms would I see if I configured my ICP port's datarate to a lower or higher speed than the actual rate of the external clock?

    If the clocksource of the port is configured for "external clock", then there may be no effect on the data transfers, because everything will really be driven by the external clock anyway. But the protocol code running on the ICP board may use the configured data rate (the datarate that you gave it) for some internal calculations, so if that datarate differs from the actual clock rate it might cause problems with data transfers -- in fact, it may make it impossible to send or receive data at all.

    For example, some protocols use the configured datarate to calculate how long the transfers should take, so if your configured datarate is higher than the actual external clock rate, you might receive "transmit timeout" messages (because the protocol expects it to take only some short amount of time to send a block of data, and the data is really trickling out slower than that). And some protocols use the configured datarate to estimate how many incoming characters can be put into the internal hardware registers before interrupting the ICP board's CPU to remove and store them; for those protocols, an incorrect datarate setting could cause an increase in data errors. It is always best to find out what the external clock's actual rate is, and set the protocol's datarate setting as close as possible to that rate.

    If the port is configured for "internal clock", then the data it sends will be at the specified rate, rather than at the rate of your external link, and that might cause problems at the other end (the site that's receiving data at a different rate than it expects). The data coming into the ICP port will always be at the "external link" rate, regardless of the port's configured data rate (because for synchronous protocols like you have, the incoming data is always clocked in by an external clock; the "clock source" selection only specifies the clock used for the outgoing data). See the answer to question 6.5 for more information about internal clocking.


    7. Troubleshooting Techniques


    7.1) My client program is having trouble connecting through my Freeway to a WAN port; what do I do?

    The connection that your client program is attempting to make occurs in several layers: first it makes a TCP connection to the Freeway, then sends commands through that TCP connection to attach to an ICP board, then to configure the ICP board, configure the protocol running on that ICP board, connect to one of the WAN links on that ICP board, enable that link, and send/receive data (when you are using the DLI operating in Normal Mode, the DLI will perform many of these steps for you). One of those steps is probably not working, and the easiest way to find out which step is at fault is to get a trace of all the transactions. The trace is a file showing all the packets passing in both directions, with the most relevant fields of each packet broken out into a form which is easy for humans to read (well, easier than the raw binary message contents, anyway).

    If your client program is using the DLI/TSI library, then you can command it to generate a trace file. However, it is usually easier to login to the Freeway and command it to generate a trace file; see the answer to the 7.2) How do I get a "Freeway trace" file? question for instructions describing how to do that.


    7.2) How do I get a "Freeway trace" file?

    To turn tracing on, login to the Freeway and select

       "4) Trace Functions (Trace Disabled)",   then
       "2) Turn MSGMUX Trace On"
    

    Then start your client program and run your test, and as soon as the item of interest has occurred (data sent, data received, an error message received, etc.), go back to your xterm (or whatever you used, where you logged in to the Freeway), and in the Trace Functions menu select:

       "3) Turn MSGMUX Trace Off"
    

    so the trace buffer doesn't fill with any additional traffic (it's a circular buffer, and new data coming in will eventually overwrite the oldest data).

    Then you can select:

       "4) Process Trace Data"
    

    and type in a filename like "trace1.txt", and "2" for DLI trace level, and the trace file will be generated. It'll be in the /tmp/ subdirectory of the Freeway and you should be able to use FTP to retrieve it (or if your Freeway is configured to boot from the network, it'll be in the directory where the Freeway booted from).


    7.3) I configured my Freeway to boot from the network, rather than from its own hard disk, and it sometimes fails to boot -- why?

    If the Freeway displays messages similar to this when it fails to boot:

    fetch:
    +ftp://freeway:password@192.168.1.123/d:/usr/local/freeway/boot/fwybsd:
    +Can't open data connection
    ERROR: Unable to find file fwybsd
    

    then the Freeway was unable to retrieve some of the files it needs to boot successfully. Look into the logs of your FTP server to see why it failed.

    This failure happens occasionally with the wftpd ftp server for Windows NT. If possible, try to use another FTP server, or change to boot the Freeway from its own hard disk.


    7.4) I remember my Freeway printed lots of hardware probing information on the console when it booted. How can I retrieve that information?

    You can always enter the "BSD shell" (login to the Freeway and select menu item "6") and type the command "dmesg" -- that will provide several dozen lines of output about the internal operation of the Freeway. If it has been several days or weeks since your Freeway was booted, however, the boot probe messages may have been superceded by later messages, and may no longer appear in the "dmesg" output; in that case you can view the /tmp/var/run/dmesg.boot file (or use FTP to retrieve it from the Freeway to another machine). Immediately after being booted, the Freeway saves the boot probe messages into /tmp/var/run/dmesg.boot , in order to solve this problem of users who need to see the boot messages after their Freeway has been up for a long time.


    7.5) Is there a quick command to see details about all the PCI devices (such as ICP boards) installed in my Freeway?

    The command "pciconf -l -v" gives information about all PCI devices in the system, including the ICP boards. ICP2432"A" boards will show vendor "Simpact Associates Inc", and ICP2432"B" boards will show vendor "Protogate Inc".


    7.6) I think one of my ICP boards is dying. How can I get information about the health of my Freeway's ICP boards?

    Login to your Freeway, select "6" to enter the BSD shell, then use the command "icpprint". That command displays the console output which was printed by the programs running on an ICP board, and will show if one of the programs is running into difficulty, and why.

    When run without arguments (as above), "icpprint" will prompt for the ICP number to display; you can also append the ICP number as the first argument to eliminate the prompt (e.g. "icpprint 0"). "icpprint ?" will show a list of optional arguments.

    The icpprint utility requires use of OS/Protogate version 1.2-0 or later.


    7.7) Can I examine the contents of an ICP board's physical RAM?

    Yes, we have a program called icpdump, which you can use to extract a copy of any portion (or all) of any ICP2432B board's RAM. icpdump requires only that the ICP board is installed in a Freeway, and the Freeway software version is 3.1-0 or later.


    End of the Protogate FAQ ( $Revision: 1.25 $ ).

    Freeway® is a registered trademark of Protogate, Inc.
    All other trademarks and trade names are the properties of their respective holders.

    Copyright (C) 2004-2015 Protogate, Inc.