NEW Rev 1.3/Celeste's Tutorial on Solaris 2.x Modems & Terminals

From: Celeste Stokely (celeste@xs.com)
Date: Thu Apr 20 1995 - 09:03:56 CDT


             Celeste's Tutorial on Solaris 2.x Modems & Terminals
             ====================================================
                               Revision 1.3, 4/20/95

  Section Description Page
  ------------------------------------------------------------------------
  Lawyers....Copyright Notice .......................................... 2
  A..........Which Modem Should You Use? ------------------------------- 3
               Types of Modem Usage .................................... 3
               Modem Programming ....................................... 4
               Modem Speed ............................................. 4
               Flow Control and Parity ................................. 5
  B..........Celeste's Strategy for Configuring Modems and Terminals --- 6
               Ok, So What Do I Do? .................................... 6
                 To use a port for dial-out only ....................... 6
                 To use a port for dial-in only ........................ 6
                 To use a port for bidirectional use ................... 7
                 To configure a dumb terminal .......................... 7
  C..........Tip and /etc/remote -------------------------------------- 8
               /etc/remote example .................................... 10
  D..........Basic Modem Programming ---------------------------------- 11
  E..........Enabling Solaris For a Bidirectional Modem --------------- 12
               add_modem shell script ................................. 14
  F..........Enabling Solaris For A Dial-out-only Modem --------------- 15
  G..........Setting Up A Terminal on Solaris 2.x --------------------- 16
               add_terminal shell script .............................. 18
  H..........Setting Serial Port Modes -------------------------------- 19
               /etc/ttydefs examples .................................. 20
  I..........Configuring Serial Ports for UUCP ------------------------ 21
               Parity in UUCP ......................................... 21
               Flow control with UUCP ................................. 22
  J..........File format: /etc/saf/{pmtag}/_pmtab and /etc/saf/_sactab 23
  K..........Customizing the login message ---------------------------- 24
  L..........Vendor List ---------------------------------------------- 25

This document is a tutorial that will teach you everything you should need
to know about connecting asynchronous modems and terminals to a Sun SPARC
workstation under Sun's Solaris 2.x. It does not cover the specifics of
setting up PPP, nor Sun's 4.x releases. An abridged version of this
information has been/will be published in the 3/95 and future issues of
_Unix Review_. It will also be coming out on a WWW server soon--I promise!

You must execute the commands as root and you will probably have to reboot
the machine. So, plan the system's downtime accordingly.

You may distribute this information to anyone who wants it, as long as you
never attempt to copyright it in any way. If you find errors in it, or have
suggestions for changes in future revisions, please let me know via email.
Go for it--you can do it!

..Celeste Stokely, Unix System Administration Consultant, Stokely Consulting
EMAIL: celeste@xs.com / Voice: 415-967-6898 / FAX: 415-967-0160
USMAIL Address: Stokely Consulting/211 Thompson Square/Mountain View CA 94043


4/20/95-Rev 1.3 Celeste's Tutorial on Solaris 2.x Modems & Terminals Page 2

---------------------------------------------------------------------------
Lawyer Section:

  Copyright (c) 1995 Stokely Consulting

Permission to use, copy, and distribute this documentation for any purpose
and without fee is hereby granted, provided that the above copyright notice
appear in all copies, that both that copyright notice and this permission
notice appear in supporting documentation, that this document is not
modified, and that the name of Stokely Consulting not be used in advertising
or publicity pertaining to distribution of the software without specific,
written prior permission. Stokely Consulting makes no representations about
the suitability of this documentation for any purpose. It is provided "as
is" without express or implied warranty.

All other product names are copyrighted by their various owners.
---------------------------------------------------------------------------

Setting up modems and terminals under Unix is often painful. If you had
modem and terminal connection down to a science in SunOS 4.x, you're
probably having trouble understanding it in Solaris 2.x. Solaris 2.x uses
the SYSV-ish approach instead of the SunOS 4.x BSD approach. BSD uses getty
and friends to spawn login, while SYSV uses port monitors and new friends.

If this is your first attempt at hooking up a modem or terminal to a Unix
machine, I'll give you a sound strategy to use and walk you through it. It's
not really hard once you learn a few basics.

The Sun manuals and Answerbook have a few incorrect back quotes in vital
places. Following their instructions probably won't give you error messages,
but they won't work, either. However, Answerbook will explain all the ins
and outs of port monitors, if you want to understand them in detail.

Sun's admintool Serial Port Manager works for many simple modem and terminal
setups, but when it doesn't work, you need to know how to run the various
setup commands by hand.

WARNING: I have very strong feelings about modems and serial ports, their
uses, their manufacturers, and their support. My clients ask me to make
their modems work and stay working, so I tend to use only modems that are
robust, highly configurable, fast, and well-supported. They're not cheap,
but neither is a System Administrator's time. I use cheap modems for
doorstops and bookends.


4/20/95-Rev 1.3 Celeste's Tutorial on Solaris 2.x Modems & Terminals Page 3

A. Which Modem Should You Use?
==============================

There are hundreds of Hayes-compatible, asynchronous modems on the market
today. Most of them can be made to work on a Sun for dial-out. Many can work
for dial-in. Several will work gracefully for bidirectional (dial-in and
dial-out) use. Fewer still will bring a smile to a sysadm's heart.

If you're trying to connect a non Hayes-compatible modem to your Sun, this
article won't work for you.

This article covers the basic setup for many common serial port usages, such
as:
 - dial-in only access for human login accounts
 - dial-out only access for humans and programs using "tip".
 - dial-in and dial-out setups for UUCP (email, Usenet NetNews, file
   transfer)
 - Bidirectional modem use: dialing in and out on the same port
 - Basic dumb terminal connection, ("dumb terminal" == vt100, Wyse-50, and
   other plain, character-based terminals.)

This article specifically does not cover:
 - Setting up PPP or SLIP
 - Using your modem to send FAXes
 - X Terminal setup

In general, you get what you pay for. A $49 modem will cost you a fortune in
the time it takes to get it running. A $499 modem can often be configured
and running in under 20 minutes and give you little grief in day-to-day use.

Types of Modem Usage
-----------------------
Match your modem to your intended use for it. Don't buy a cheap 2400bps
modem to transfer all your company's mail and netnews. If your Internet
service provider offers your UUCP connection only over Telebit WorldBlazers,
you should strongly consider buying a Telebit WorldBlazer and dedicate it to
that use. If they're not a Telebit site and plan on staying that way, there
are faster, more widely-compatible modems available for a LOT less money.

My current favorite is the USRobotics Courier V.34--a sweet modem that gets
better with every release of the flash-upgrade for the ROM. Next month, who
knows what will be the darling? I have so many "former favorite" modems in
my office that it's starting to look like a modem museum.

If you have to support a lot of dial-in users with a wide collection of
random modems, then you need something which can happily work with all the
possible user modems. That means you need one that will run at least
14400bps. The new real V.34 28800bps modems will be even better, in the long
run. Plan on spending $250-$600 for this modem.


4/20/95-Rev 1.3 Celeste's Tutorial on Solaris 2.x Modems & Terminals Page 4

Modem Programming
--------------------
In deciding which modem to buy, a key consideration is how you can program
the modem. Some modems use DIP switches, some are programmed by connecting
to the modem and setting software registers, some use both methods. You get
more programming flexibility with software registers, and this is important
when you'll be connecting to a lot of different modem types.

If a modem has only DIP switches available, it probably will be hard to make
it do everything you need for lots of different connections. It's probably
also an old, slow modem. I call these "cheap PC modems" and avoid them like
spamming Internet lawyers.

Modem Speed
--------------
One of the most important features to look for is the modem's ability to run
at split speeds. You really want to run the Sun-to-modem connection at a
fixed speed (the "DTE rate" or "serial rate") all the time, and let the
modem negotiate the modem-to-modem speed ("DCE rate" or "line speed")
independently.

Beware, because many inexpensive modems can't do this. If your modem doesn't
do this, you and your users will have to hit <break> until the speeds sync
up. This drives users (and you) crazy!

You should try to run the Sun-to-modem (DTE) connection at 9600bps,
19200bps, or 38400bps. A Sun can NOT run the CPU serial port at 14400bps.
But, that's ok because all the 14400 modems I've ever seen can run at
19200bps DTE speed. You can also run at slower speeds, but why bother? Buy a
faster modem than you think you need and you'll get more use out of it in
the long run.

There are a few kernel hacks available to run the Sun CPU serial ports at
higher speed. Use them at your own risk. I do NOT recommend them--they're
too unstable for most purposes. The Sun CPU serial ports and their drivers
are bad enough without hacking on them yourself.

If you crave more speed than 38400bps, you need to look into SBUS serial-
port expander cards with DMA (I like Magma's line of DMA serial cards), or
even network-connected terminal servers, and modems which are even MORE
expensive. If you need a lot of high-speed serial connections, network
terminal servers are probably the way you should go.


4/20/95-Rev 1.3 Celeste's Tutorial on Solaris 2.x Modems & Terminals Page 5

Flow Control and Parity
--------------------------
When you run at higher speeds (9600bps and above), you MUST worry about flow
control. Ideally, you want hardware flow control where the Sun and modem
play the right games with the RTS/CTS lines to say "shut up" and "give me
more".

Historically, the Sun CPU ports have not been able to use incoming hardware
flow control, only outgoing. Sun has released a patch to enable incoming
flow control. This is Patch # 100999 for Solaris 2.2, also lovingly known as
the "Kernel Jumbo Patch". Refer to Sunsolve or Sun Technical Support to see
if there is a patch for your version of Solaris. I've had moderate success
with Patch 100999. Sometimes, it just doesn't work. Sometimes it does. It's
worth a try at least. If it doesn't work and you must have hardware flow
control, look into the higher-end SBUS-based serial port expander cards.

If the patch doesn't work for you, you can consider using software
(XON/XOFF) flow control. But, NEVER use software flow control with UUCP or
UUCP will go nuts from the unexpected XON and XOFF characters. If you can't
use hardware flow control with UUCP, it's better to use no flow control at
all and let UUCP do its own packet throttling.

I run my own communications server without port-level flow control on my 13
UUCP connections at 38400bps and all the mail and NetNews gets delivered
just fine.

Try to always run your ports and modems at 8 bits, no parity. Parity on
serial port transmissions is an outdated concept when you're using modern,
error-correcting modem protocols. By default, the Sun CPU ports run at 7
bits, even parity (7E1). I'll explain how to run them at 8 bits, no parity
(8N1). If you've got a legitimate use for odd, mark, or space parity, I want
to hear from you!


4/20/95-Rev 1.3 Celeste's Tutorial on Solaris 2.x Modems & Terminals Page 6

B. Celeste's Strategy for Configuring Modems and Terminals
==========================================================

This strategy gives you flexibility and maintainability in your serial port
configurations. It will work for nearly all configurations.

Important Rule: Add and configure only 1 modem or terminal at a time. Get it
working, then move on to the next one. Any other approach will result in
madness. I been there, done that. Trust me.

There are actually very few steps.

  To configure the port for a terminal, set up the port monitor, then
  configure the terminal.

  To configure the port for a modem, get tip working, program the modem, make
  sure your logical port devices have the proper permissions, then enable a
  bidirectional port monitor.

     Then, if you only want to use the modem port for incoming connections,
     disable tip for everyone but root.

     Or, if you only want to use the modem port for outgoing connections,
     remove the port monitor and turn off auto-answer on the modem.

Purists may argue that this modem-port configuration has extra, unneeded
steps or leaves the port monitor in bidirectional mode for incoming-only
connections. I find that if a sysadm sets up a port for only dial-in or dial-
out, someday he or she will want the port to be bidirectional. Setting
things up for this in the beginning means you'll have easier success in the
future. And, it doesn't hurt anything.

Ok, So What Do I Do?
--------------------
To use a port for dial-out only:
  - Configure /etc/remote for tip (See the section "Tip and /etc/remote" on
    page 8.)
  - Set up the word length and parity for the port (See the section "Setting
    Serial Port Modes" on page 19.)
  - Program the modem (See the section "Basic Modem Programming" on page 11.)
  - Remove any port monitor which may be on the serial port (See the
    section, "Enabling Solaris For A Dial-out-only Modem" on page 15.)

To use a port for dial-in only:
  - Configure /etc/remote for tip (See the section "Tip and /etc/remote" on
    page 8.)
  - Set up the word length and parity for the port (See the section "Setting
    Serial Port Modes" on page 19.)
  - Program the modem (See the section "Basic Modem Programming" on page 11.)
  - Configure the port monitor to spawn a login correctly (See the section
    "Enabling Solaris For a Bidirectional Modem" on page 12.)
  - Make /bin/tip owner-executable only. Don't delete it, you'll need it
    someday. And, remember to leave it setuid-uucp!


4/20/95-Rev 1.3 Celeste's Tutorial on Solaris 2.x Modems & Terminals Page 7

To use a port for bidirectional (dial-in and dial-out) use:
  - Configure /etc/remote for tip (See the section "Tip and /etc/remote" on
    page 8.)
  - Set up the word length and parity for the port (See the section "Setting
    Serial Port Modes" on page 19.)
  - Program the modem (See the section "Basic Modem Programming" on page 11.)
  - Configure the port monitor to spawn a login correctly (See the section
    "Enabling Solaris For a Bidirectional Modem" on page 12.)

To configure a dumb terminal on a port instead of a modem:
  - Ignore tip (That should be easy!)
  - Set up the word length and parity for the port (See the section "Setting
    Serial Port Modes" on page 19.)
  - Configure the port monitor to spawn a login correctly. (See the section
    "Setting Up A Terminal on Solaris 2.x" on page 16.)
  - Configure the terminal itself, setting up the baud rate, word length
    and parity, and flow control.

If you want to use UUCP, you must configure it as well. This article will
tell you about setting up parity and flow control in UUCP, but doesn't cover
all the other UUCP file changes. For that, get the O'Reilly and Associates
book _Managing UUCP and Usenet_.

Simple, huh? Find the parts of this article that do the pieces you want,
modify the scripts as needed, and go for it!


4/20/95-Rev 1.3 Celeste's Tutorial on Solaris 2.x Modems & Terminals Page 8

C. Tip and /etc/remote
======================

You may hate tip and love kermit or pcomm. I understand. But, do this via
tip to keep it simple, ok?

Decide which serial port you want to use. (One with no cable already plugged
in is often a good bet.) The port will be labeled "A", "B", "A/B" or could
even be "C" or higher.

If you use one labeled "A/B" and have no Y-type splitter cable plugged into
it, you'll have access only to port A. With the splitter, you'll get ports A
and B on separate sockets of the splitter cable.

The Sun serial port device driver splits each physical port into two logical
devices, /dev/term/a or /dev/term/b for incoming transmission, and
/dev/cua/a or /dev/cua/b for outgoing transmission.

The "speed" referred to in this section is the DTE or Sun-to-modem speed. It
is NOT the modem-to-modem speed. A 14400bps modem may have a 19200bps DTE
speed.

Make sure you have your serial port permissions right. uucp should own the
outgoing side, and root should own the incoming side.

Execute these commands as root, substituting your port name (a, b, c, or d)
where needed:

 prompt# chown uucp /dev/cua/a; chgrp tty /dev/cua/a
 prompt# chown root /dev/term/a; chgrp tty /dev/term/a

 
1. Edit tip's configuration file, /etc/remote, and find the entry beginning
   with "hardwire:". This is the entry you use to program the modem, and is
   not usually used for dialing out directly, unless you enjoy AT commands.

   (If this is the second modem you're adding, clone the entire hardwire
    entry and label the new entry "hardwire2".)

   Change it from an entry like:

     hardwire:\
        :dv=/dev/????/?:br#????:el=^C^S^Q^U^D:ie=%$:oe=^D:

   to one set to your port (like /dev/cua/a) and baud rate (like 9600):

     hardwire:\
        :dv=/dev/cua/a:br#9600:el=^C^S^Q^U^D:ie=%$:oe=^D:

>> Go to step 2


4/20/95-Rev 1.3 Celeste's Tutorial on Solaris 2.x Modems & Terminals Page 9

2. NOTE: Never run tip from a cmdtool. Use a shelltool, xterm, or some other
   window without scrollbars. The scrollbars may confuse tip's
   <carriage return> processing.
 
   There are exceptions to this, but if you never run tip in a scrollbar-type
   window, you won't have to remember all the ways it does and does not work.

   Now use your edited "hardwire" entry from /etc/remote and type:

   prompt# tip hardwire (or "tip hardwire2")
           you should see "connected"
   type:
          ATE1V1<carriage return>
          (This will work for all Hayes-compatible modems, even cheapies.)
           You should see "OK".
           Congratulations! You're talking with the modem!

               Now, issue the appropriate AT commands to program the modem.
               (See the section called "Basic Modem Programming" on page 11.
               Don't forget to write the new settings out to the modem's
               NonVolatile RAM.

    If you don't see "OK", you are not communicating with the modem.
    See if the modem is plugged in, verify the baud rate of the modem
    and the hardwire entry in /etc/remote, verify the modem cable.

- Exit tip by typing:
  <carriage return>~. (This will also exit rlogin, so if you're running
     tip through an rlogin, make that <carriage return>~~. or you'll only
     exit rlogin.)

- The cuaa entry (below) allows you to type "tip cuaa" and talk directly to
  a modem on port A at 19200bps, using 7 bits, even parity.

- The cuab entry (below) allows you to type "tip cuab" and talk directly to
  a modem on port A at 9600bps, using 8 bits, no parity.

- "tip some_phone_number" will look for the tip0 entry and use that
  definition to dial "some_phone_number". (In the example below, it will
  use tip0, which points to UNIX-19200, which sets up a dialup 19200bps
  7 bits even parity Hayes compatible modem. UNIX-19200 points to diala,
  which references /dev/cua/a. Convoluted, eh?)

- "tip mysystem" (below) looks up the "mysystem" entry, and dials the
  number 14155551234 via a 19200bps 7 bits, no parity connection on
  /dev/cua/a.


4/20/95-Rev 1.3 Celeste's Tutorial on Solaris 2.x Modems & Terminals Page 10

/etc/remote example
-------------------
  The following sample /etc/remote file is set up for:

    port a, 19200bps Hayes-compatible modem, 7 bits even parity
       (It's 7E1 because there is no "p8" entry)

    port b, 9600bps Hayes-compatible modem, 8 bits no parity
       (It's 8N1 because there is a "p8" entry)

  See the remote(4) man page for all the possible options.

cuaa:dv=/dev/cua/a:br#19200:
cuab:dv=/dev/cua/b:p8:br#9600
mysystem:pn=14155551234:tc=UNIX-19200:
hardwire:\
        :dv=/dev/cua/b:p8:br#9600:el=^C^S^Q^U^D:ie=%$:oe=^D:
tip0|tip19200:tc=UNIX-19200:
tip9600:tc=UNIX-9600:
UNIX-9600:\
        :el=^D^U^C^S^Q^O@:du:at=hayes:ie=#$%:oe=^D:br#9600:tc=dialb:
UNIX-19200:\
        :el=^D^U^C^S^Q^O@:du:at=hayes:ie=#$%:oe=^D:br#19200:tc=diala:
diala:\
        :dv=/dev/cua/a:
dialb:\
        :p8:dv=/dev/cua/b:
--------------------------------------------------------------------
The attributes are:
dv device to use for the tty
du make a call flag (dial up)
pn phone numbers (@ =>'s search phones file; possibly taken from
                              PHONES environment variable)
at ACU type
ie input EOF marks (default is NULL)
oe output EOF string (default is NULL)
cu call unit (default is dv)
br baud rate (defaults to 300)
tc to continue a capability


4/20/95-Rev 1.3 Celeste's Tutorial on Solaris 2.x Modems & Terminals Page 11

D. Basic Modem Programming
==========================
Dust off your modem manual and have it handy. Use tip to connect to the
modem and program the modem registers. Be sure to write out the modem's
registers to NonVolatile RAM when you're done. Program the modem with:

    - Hardware DTR, Normal DTR, or Reset When DTR Toggles. When the Sun
      drops DTR the modem should hang up the phone line and reset the modem
      to NonVolatile RAM settings.

    - Hardware Carrier Detect or Normal Carrier Detect. The modem should
      only raise Carrier Detect (known as CD or DCD) when there is an active
      carrier signal on the phone connection. You'll setup the port monitor
      so that when CD goes active, the Sun will spawn a login.

      When carrier drops, either when the other end of the connection
      terminated or if the phone connection is broken, the Sun will be
      notified and act appropriately. The CD signal is also used for
      coordinating dial-in and dial-out use on a single serial port.

    - Respond with numeric result codes if this is for tip's use. (Usually
      this is ATV0) If you're setting the modem for UUCP dialout, then
      program the modem to use English result codes (like CONNECT). (Usually,
      this is ATV1.)

      If you're using the modem for both tip and UUCP, set it up with
      numeric result codes, and have UUCP's chat script set it to English
      result codes for the duration of the UUCP connection. See the O'Reilly
      and Associates' book _Managing UUCP and Usenet_ for the nitty-gritties.

    - Send BASIC result codes ONLY. Tip only wants to see result codes 0
      through 4. If it sees other result codes, it calls them an error.
      (Sometimes this is ATX0 or ATQ0)

    - Do not echo commands. (Usually this is ATE0)

    - Modem is locked at a single speed setting between Sun and modem.
      The speed may vary as needed between local and remote modem, but
      should remain constant between the Sun and modem.(If your modem can't
      do this, use it for a paperweight and buy one that allows split speeds
      If your boss won't let you do this, ok, but you should whine loudly.)

    - If this modem is used for dial-in, turn on Auto-Answer. (Sometimes
      this is ATS0=1.) If the modem is not used for dial-in, turn off
      Auto-Answer. (Sometimes this is ATS0=0.)

    - Set the modem to your parity and word length requirements.
      Use 8 bits, no parity if you can.

    - Set the modem to your flow control scheme. Use hardware flow control
      (CTS/RTS) if you can, software flow control (XON/XOFF) if you must,
      or no flow control if you just have to.


4/20/95-Rev 1.3 Celeste's Tutorial on Solaris 2.x Modems & Terminals Page 12

E. Enabling Solaris For a Bidirectional Modem
=============================================

                      IMPORTANT NOTES:
   - All single quotes in these directions are BACK QUOTES,
      not FORWARD QUOTES, except where specifically noted.
                                                            
   - Be sure and execute these commands as root, from a BOURNE shell (sh),
      not ksh, tcsh, or csh. (If you use a Bourne shell script, that's good.)

   - If, after following these instructions, you get modem failures, or if
      the add_modem script gives an error message about "ttyadm: -V: invalid
      parameter", then make sure that root's default shell is /sbin/sh and
      not csh.

   - You want to have a maximum of 1 port monitor running on a given port.
      If you accidentally have 2 or more running on the port, your machine
      will probably panic.

   - There is much disagreement over whether these eeprom settings are
     required. Just use them and it will work.

1. Login as root and type:
      prompt# eeprom ttya-ignore-cd=true [this means use HW carrier detect]
      prompt# eeprom ttya-rts-dtr-off=true
>> go to step 2

2. Reboot the system by typing:
        prompt# init 6
 (Is it critical to reboot now? No. But, you'll need to reboot at some time.)
>> Go to step 3

3. Make sure the modem is properly connected to your port and already
   programmed. Make sure the cable is ok. Your cable needs at least lines
   1,2,3,4,5,6,7,8, and 20, all straight through, with none crossed.
   A 25-pin cable, wired "straight through" is fine. A Null Modem cable will
   NOT work.
>> Go to step 4

4. Is the Solaris 2.x port monitor, ttymon, configured and running?
   Login as root and type:
        prompt# sacadm -l -t ttymon

   If you get a message like:
      "Invalid request, ttymon does not exist"
      then the ttymon port monitor is not configured.
>> Go to step 5

   If you get a result like:
       PMTAG PMTYPE FLGS RCNT STATUS COMMAND
       zsmon ttymon - 0 ENABLED /usr/lib/saf/ttymon
>> Go to step 6


4/20/95-Rev 1.3 Celeste's Tutorial on Solaris 2.x Modems & Terminals Page 13

5. Configure an instance of ttymon called zsmon:

  prompt# sacadm -a -p zsmon -t ttymon -c /usr/lib/saf/ttymon -v `ttyadm -V`
      (Note: The string "zsmon" is known as a PMTAG.)
>> Go to step 6

6. Is there a service running on the zsmon port monitor?
   Type:
      prompt# pmadm -l

   a) If you got a result like:

      PMTAG PMTYPE SVCTAG FLGS ID <PMSPECIFIC>
      zsmon ttymon ttya u root /dev/term/a I - .........

      Then you need to remove the existing service. Issue this command and
      insert the PMTAG and SVCTAG found in the previous command by typing:

            prompt# pmadm -r -p zsmon -s ttya
                                 ^ ^
                               (PMTAG) (SVCTAG)
>> Go to step 7.

   b) If you don't see your port (like /dev/term/a) listed, then you're ok.
>> Go to step 7.

7. Make a script which will remove any existing port monitor and create a new
   bidirectional port service.

   Putting this in a script is a Very Good Idea because if you make a
   mistake, you can easily fix the problem and rerun the script. Don't try
   to do this without a script--there are too many typing errors waiting to
   be made in these commands.

   Type in the following script as a file (for instance, /sbin/add_modem),
   make it executable, then run it.


4/20/95-Rev 1.3 Celeste's Tutorial on Solaris 2.x Modems & Terminals Page 14

#!/bin/sh
# add_modem shell script. Must be run as root from bourne shell
# Change these parameters as needed for your particular needs.
#
# PARAMETER MEANING
# --------- -------
# PORT Port you want to set up. "a" or "b"
# TTYSPEED Speed setting, from /etc/ttydefs
# LOGINMSG The login message which will be displayed.
# -p zsmon PMTAG, name of this port monitor
# -s ttya SVCTAG, modem is on ttya. you may want ttyb
# -d /dev/term/$PORT Actual port device.
# -l contty5H Ttylabel, defined in /etc/ttydefs file. (speed
# setting. contty5H=19200 baud)
# -b Flag for bidirectional port use
# -S n Turn software carrier off (modem supplies
# hardware carrier detect signal)
# "dial in/out on serial port" This is a comment you'll see on pmadm -l
########################################################################
LOGINMSG="Always be nice to your sysadm. You may now login. "
# set PORT = either a or b
PORT="a"
#----------------------------------------
# choose your speed setting. See /etc/ttydefs for more, or build your
# own from the examples in the rest of this article.
# contty5H = 19200bps, 7 bits even parity, as supplied by Sun
# conttyH = 9600bps, 7 bits even parity, as supplied by Sun
TTYSPEED="contty5H"
#----------------------------------------
# change ownership of outgoing side of port to user uucp, group tty.
# change ownership of incoming side of port to user root, group tty.
chown uucp /dev/cua/$PORT; chgrp tty /dev/cua/$PORT
chown root /dev/term/$PORT; chgrp tty /dev/term/$PORT
#----------------------------------------
# Remove any existing port monitor on this port.
# You can ignore any error messages from this next command.
# If you see the message "Invalid request, ttya does not exist under zsmon",
# You may be trying to remove a port monitor which does not exist.
/usr/sbin/pmadm -r -p zsmon -s tty$PORT
#----------------------------------------
# Create the new port monitor
/usr/sbin/pmadm -a -p zsmon -s tty$PORT -i root \
-v `/usr/sbin/ttyadm -V` -fu -m "`/usr/sbin/ttyadm \
-p "$LOGINMSG" -d /dev/term/$PORT -s /usr/bin/login -l $TTYSPEED -b \
-S n -m ldterm,ttcompat`" -y "dial in/out on serial port"
############ end of add_modem script ###################################

  Make the script executable by typing: prompt# chmod 700 /sbin/add_modem
  then run it with: prompt# /sbin/add_modem
  For more information, see the section, "Tip and /etc/remote" on page 8.


4/20/95-Rev 1.3 Celeste's Tutorial on Solaris 2.x Modems & Terminals Page 15

F. Enabling Solaris For A Dial-out-only Modem
=============================================

  If there is no port monitor running on the port, then the Sun will not
  try to spawn a login. So, you have to remove any port monitor on the port.
  There is much disagreement over whether these eeprom settings are
  required. Just use them and it will work.

1. Login as root and type:
        prompt# eeprom ttya-ignore-cd=true [this means use HW carrier detect]
        prompt# eeprom ttya-rts-dtr-off=true
>> go to step 2

2. Reboot the system by typing:
        prompt# init 6
   (Is it critical to reboot now? No. But, you'll need to reboot at some
   time.)
>> Go to step 3

3. Make sure the modem is properly connected and already programmed.
   Make sure the cable is ok. Your cable needs at least lines
   1,2,3,4,5,6,7,8, and 20, all straight through, with none crossed.
   A 25-pin cable, wired "straight through" is fine. A Null Modem cable
   will NOT work.
>> Go to step 4

4. Is there a service running on the zsmon port monitor?
   Type:
      prompt# pmadm -l

   If you got a result like:
      PMTAG PMTYPE SVCTAG FLGS ID <PMSPECIFIC>
      zsmon ttymon ttya u root /dev/term/a I - /.....

      Then you need to remove the existing service. Insert the PMTAG and
      SVCTAG tokens with the output of the command above.
            prompt# pmadm -r -p zsmon -s ttya
                                 ^ ^
                               (PMTAG) (SVCTAG)
>> If you haven't already programmed the modem, go to the
         section, "Tip and /etc/remote" on page 8.

   If you see nothing listed for the port you're dealing with, then the
   Sun will not spawn a login on that port.


4/20/95-Rev 1.3 Celeste's Tutorial on Solaris 2.x Modems & Terminals Page 16

G. Setting Up A Terminal on Solaris 2.x
=======================================
                      IMPORTANT NOTES:
   - All single quotes in these directions are BACK QUOTES,
      not FORWARD QUOTES, except where specifically noted.
                                                            
   - Be sure and execute these commands as root, from a BOURNE shell (sh),
      not ksh, tcsh, or csh. (If you use a Bourne shell script, that's good.)

   - If, after following these instructions, you get modem failures, or if
      the add_modem script gives an error message about
      "ttyadm: -V: invalid parameter", then make sure that root's default
      shell is /sbin/sh and not csh.

   - You want to have a maximum of 1 port monitor running on a given port.
      If you accidentally have 2 or more running on the port, your machine
      will probably panic.
***************************************************************************
1. Is the Solaris 2.x port monitor, ttymon, configured and running?
   Login as root and type:
        prompt# sacadm -l -t ttymon

   If you get a message like:
      "Invalid request, ttymon does not exist"
      then the ttymon port monitor is not configured.
>> Go to step 2

   If you get a result like:
       PMTAG PMTYPE FLGS RCNT STATUS COMMAND
       zsmon ttymon - 0 ENABLED /usr/lib/saf/ttymon
>> Go to step 3

2. Configure an instance of ttymon called zsmon:
  prompt# sacadm -a -p zsmon -t ttymon -c /usr/lib/saf/ttymon -v `ttyadm -V`
      (Note: The string "zsmon" is known as a PMTAG.)
>> Go to step 3

3. Is there a service running on the zsmon port monitor?
   Type:
      prompt# pmadm -l
   a) If you got a result like:
      PMTAG PMTYPE SVCTAG FLGS ID <PMSPECIFIC>
      zsmon ttymon ttya u root /dev/term/a I - .........
      Then you need to remove the existing service. Issue this command and
      insert the PMTAG and SVCTAG found in the previous command by typing:
            prompt# pmadm -r -p zsmon -s ttya
                                 ^ ^
                               (PMTAG) (SVCTAG)
>> Go to step 4.
 
   b) If you don't see your port (like /dev/term/a) listed, then you're ok.
>> Go to step 4.


4/20/95-Rev 1.3 Celeste's Tutorial on Solaris 2.x Modems & Terminals Page 17

4. Setup the terminal

  - Set the terminal for the speed you wish (The example below assumes you
    are using 9600 baud.)
  - The only lines you really need in the terminal-to-Sun cable are 2, 3,
    and 7. Be sure to cross lines 2 and 3 in your cable. A Null Modem cable
    will work well for this.
  - Set the terminal for XON/XOFF flow control
  - Set the terminal for 7 bits, Even Parity. (1 stop bit, if you have that
    setting.) If you want a different parity or word length, see the section
    "Setting Serial Port Modes" on page 19.

>> Go to step 5.

5. Enable Solaris for the terminal
  - Edit and save the following script as add_terminal
  - Make the script executable with "chmod 700 add_terminal"
  - Edit add_terminal to meet your particular needs
  - Execute add_terminal as root
  - If the terminal doesn't give you a login when you hit <return>, try
    rebooting the machine once.


4/20/95-Rev 1.3 Celeste's Tutorial on Solaris 2.x Modems & Terminals Page 18

#!/bin/sh
# add_terminal shell script. Must be run as root.
# This script invokes pmadm with the following parameters.
# Change these parameters as needed for your particular needs.
#
# PARAMETER MEANING
# --------- -------
# PORT Port you want to set up. "a" or "b"
# TTYSPEED Speed setting, from /etc/ttydefs
# LOGINMSG The login message which will be displayed.
# -s tty$PORT Terminal is on tty$PORT
# -d /dev/term/$PORT Actual port device. you may want
# -l $TTYSPEED Speed/stty setting from /etc/ttydefs. choose a
# $TTYSPEED entry that meets your needs
# -T vt100 Your default terminal type for this port. This
# is a terminfo terminal type
# -i 'terminal disabled' Message sent to the tty port if the port is
# ever disabled
# -S y Turn on software carrier
##########################################################################
LOGINMSG="Always be nice to your sysadm. You may now login. "
PORT="a"
#----------------------------------------
# choose your speed setting. See /etc/ttydefs for more settings,
# or build your own from the examples in the rest of this article.
# conttyH = 9600bps, 7 bits even parity, as supplied by Sun
TTYSPEED="conttyH"
#----------------------------------------
# change ownership of outgoing side of port to user uucp, group tty.
# change ownership of incoming side of port to user root, group tty.
# (Yes, I know you're not using the outgoing side of the port, but if you
# do this now, it will be ready when you someday put a modem on the port.)
chown uucp /dev/cua/$PORT; chgrp tty /dev/cua/$PORT
chown root /dev/term/$PORT; chgrp tty /dev/term/$PORT
#----------------------------------------
# Remove any existing port monitor on the port
# You can ignore any error messages from this next command.
# You may be trying to remove a port monitor which does not exist.
/usr/sbin/pmadm -r -p zsmon -s tty$PORT
#----------------------------------------
# Create the new port monitor.
# QUOTE-ALERT: The single quotes delimiting the port-disabled message
# [terminal disabled] are FORWARD QUOTES
/usr/sbin/pmadm -a -p zsmon -s tty$PORT -i root -fu \
-v `/usr/sbin/ttyadm -V` -m "`/usr/sbin/ttyadm -l $TTYSPEED \
-p "$LOGINMSG" -d /dev/term/$PORT -T vt100 -i 'terminal disabled' \
 -s /usr/bin/login -S y`"
############ end of add_terminal script ###################################
Make the script executable by typing: prompt# chmod 700 /sbin/add_terminal
then run it with: prompt# /sbin/add_terminal


4/20/95-Rev 1.3 Celeste's Tutorial on Solaris 2.x Modems & Terminals Page 19

H. Setting Serial Port Modes
============================
Sun doesn't supply all the serial ports modes you're likely to want as stock
entries in /etc/ttydefs. (Sun seems to think that the whole world wants to
run as 7 bits, even parity.) I'll show you how to set up the entries in
/etc/ttydefs to match your own needs.

Serial port modes (the terminal I/O options found in stty(1)) are set in the
file /etc/ttydefs. The name of the serial port mode (like contty5H) is used
as the argument to the "-l" option in the "ttyadm" portion of the "pmadm -a"
command. (This is the "speed" setting you use when you add a new port
monitor.) See the stty man page for all the available terminal I/O options.

The format of the entries in ttydefs is defined as:
   ttylabel:initial-flags:final-flags:autobaud:nextlabel

   ttylabel The string ttymon tries to match against the TTY port's
                ttylabel field in the port monitor administrative file.
                It often describes the speed at which the terminal is
                supposed to run, for example, 1200.

  initial-flags Contains the initial termio(7) settings to which the
                terminal is to be set. For example, the system administrator
                can specify what the default erase and kill characters will
                be. initial-flags must be specified in the syntax recognized
                by the stty command.

   final-flags Final-flags must be specified in the same format as
                initial-flags. ttymon sets these final settings after a
                connection request has been made and immediately prior to
                invoking a port's service.

   autobaud If the autobaud field contains the character "A", autobaud
                will be enabled. Otherwise, autobaud will be disabled.
                ttymon determines what line speed to set the TTY port to by
                analyzing the carriage returns entered. If autobaud has been
                disabled, the hunt sequence is used for baud rate
                determination.(This works intermittently for me, so use this
                at your own risk.)

   nextlabel If the user indicates that the current terminal setting is
                not appropriate by sending a <break>, ttymon searches for a
                ttydefs entry whose ttylabel field matches the nextlabel
                field.
                If a match is found, ttymon uses that field as its ttylabel
                field. A series of speeds is often linked together in this
                way into a closed set called a hunt sequence. For example,
                4800 may be linked to 1200, which in turn is linked to 2400,
                which is finally linked to 4800.

If you have been clever enough to buy a modem which can handle split baud
rates, then you and your users will never have to hit <break> again in order
to match up the baud rate between modems.


4/20/95-Rev 1.3 Celeste's Tutorial on Solaris 2.x Modems & Terminals Page 20

WARNING: These stty modes are processed from left to right within each set
of "initial-flags" or "final-flags". So, the order of the modes in each
entry is significant.

IMPORTANT NOTE: When setting the mode to 8bits, do NOT enter it as
".... -parity ... sane", but as "... sane... -parity" because "sane" resets
the port to 7 bits.

/etc/ttydefs examples
----------------------

These examples should make you comfortable with the basics. I've been
advocating the use of 8 bits, no parity. Example 4 (below) shows you how to
set that up. (Each entry should be on 1 line. Some are split here just so
this document will print correctly.)

1. contty5H, as supplied by Sun, is 19200bps, 7 bits even parity
        contty5H:19200 opost onlcr:19200 hupcl sane::conttyH

   This is equivalent to:
        contty5H:19200 evenp opost onlcr:19200 sane evenp hupcl::conttyH
             or
        contty5H:19200 parenb -parodd opost onlcr:19200 sane parenb
               -parodd hupcl::conttyH

2. To change contty5H to "7 bits, no parity" (-parenb):
        contty5H:19200 -parenb opost onlcr:19200 sane -parenb hupcl::conttyH

3. To change contty5H to "7bits, odd parity" (parenb parodd, or oddp):
        contty5H:19200 parenb parodd opost onlcr:19200 sane parenb parodd
               hupcl::conttyH
           or
        contty5H:19200 oddp opost onlcr:19200 sane oddp hupcl::conttyH

4. To make a "38400bps, 8 bits no parity, hardware flow control" entry with
   no chance of selecting another DTE rate--my own personal favorite:
contty6H:38400 -parity opost onlcr:38400 sane -parity crtscts hupcl::contty6H


4/20/95-Rev 1.3 Celeste's Tutorial on Solaris 2.x Modems & Terminals Page 21

I. Configuring Serial Ports for UUCP
====================================

Parity in UUCP
--------------
   People often get confused about running UUCP in 7 bits vs. 8 bits vs. even
   vs. odd parity. Here's what's really going on and how to deal with it.

   Both the caller and receiver must agree on parity (even, odd, none) during
   the login sequence. 7 or 8 bit word length often doesn't matter, if you
   "do the right thing" with parity.

   Once the uucico's are running, UUCP's own protocol handles all these
   issues for you, but you need to be concerned with it during login.

   There are 4 parity-related options you can set up during the login chat:
       P_ZERO - 8 bits, no parity
       P_EVEN - 7 bits, even parity
       P_ODD - 7 bits, odd parity
       P_ONE - 7 bits, "1" or Mark parity

   It is usually safest to set up parity on a per-system-to-call basis in
   the /etc/uucp/Systems file, but it can also be set for all uses of the
   port in /etc/uucp/Dialers file.

    Example 1. Setting up a port within UUCP to run with 8 bits, no parity,
      on a per-system-connect basis.

      In the file /etc/uucp/Systems, include P_ZERO in the chat script,
      as in:

        outhost Any ACU 9600 5551212 "" P_ZERO ogin: mylogin ssword: mypass

      This means that when you first start trying to contact the machine
      "outhost" uucp expects nothing ("") and sets P_ZERO
      (8 bits, no parity or 8N1).

    Example 2. Setting up a port within UUCP to run with no parity, for all
      uses of this port.

      (This example assumes you are using the "tbfast" entry in your
      /etc/uucp/Devices file)

      In /etc/uucp/Dialers:
         tbfast =W-, "" P_ZERO "" \dA\pA\pA\pTE1V1X1......


4/20/95-Rev 1.3 Celeste's Tutorial on Solaris 2.x Modems & Terminals Page 22

Flow control with UUCP
----------------------
   With UUCP, either use hardware flow control or no flow control. Please
   remember that there is no incoming hardware flow control on Sun CPU
   serial ports, only outgoing hardware flow control. (There is no such
   limitation on non-CPU ports which claim to have hardware flow control.)

   Sun has released a patch for some releases of Solaris 2.x to enable
   hardware flow control on some systems' CPU serial ports. It may work on
   your system, but it may not.

   The lack of incoming hardware flow control is not a problem with UUCP,
   usually, because the UUCP protocol is robust enough to request
   retransmission of packets when the data isn't correct.

   Using a good modem that has built-in UUCP protocol support (also known as
   spoofing) may also help your throughput. (This is a good use for a
   Telebit WorldBlazer.) If all else fails, slow down the connection
   between the Sun and the modem to what you can support in your environment.

   The string "STTY=crtscts" tells UUCP to use hardware flow control. It's
   usually better to set this up on a per-port basis, rather than on a
   per-system basis, but UUCP will let you configure it however you want.

    Example 1. Setting up a port with UUCP to use hardware flow control for
      all uses of this port. (Preferred way)

      (This example assumes you are using the "tbfast" entry in your
      /etc/uucp/Devices file)

      In /etc/uucp/Dialers, add "STTY=crtscts" after the CONNECT:

        tbfast =W-, "" \dA\pTE1.... \EATDT\T\r\c CONNECT STTY=crtscts

    Example 2. Setting up a port with UUCP to use hardware flow control, on
      a per-system-connect basis. (Do this if you feel you must, but there
      are very few good reasons for it.)

      In the file /etc/uucp/Systems, include "STTY=crtscts" in the chat
      script, as in:

     outhost Any ACU 9600 5551212 ogin: mylog ssword: mypass "" STTY=crtscts


4/20/95-Rev 1.3 Celeste's Tutorial on Solaris 2.x Modems & Terminals Page 23

J. File format: /etc/saf/{pmtag}/_pmtab and /etc/saf/_sactab
===========================================================

Sometimes, it's easier to just edit the _pmtab file directly and restart the
port monitor, rather than fussing with pmadm. (This is not for the faint of
heart or those not feeling confident about their ability to recover from
trashing their Solaris system.)

If you're comfortable with hacking the file yourself, you'll need to know
the format of the _pmtab file. Many thanks to Andrew Miller
(amiller@snm.com) for providing this dissection! I haven't exhaustively
tested this, but I trust Mr. Miller's work. Refer to the pmadm(1M) man page
for more discussion of these fields.

/etc/saf/*/_pmtab:
  {svc_tag}:{flags}:{id}:reserved:reserved:reserved:
  {device_path}:{tty_flags}:{return_count}:{service_path}:{timeout_seconds}:
  {tty_def}:{streamio_modules}:{login_prompt}:{disabled_msg}:{term_type}:
  {softcar_yn}:# {comment}

/etc/saf/_smtab:
  {pm_tag}:{pm_type}:{flags}:{restart_count}:{monitor_path args} # comment

This is one of my own /etc/saf/zsmon/_pmtab lines. (This is really 1 line,
but you'll get the idea.):

  ttya:u:root:reserved:reserved:reserved:/dev/term/a:b::/usr/bin/login
  ::contty5H:ldterm,ttcompat:Please login and be nice. :::n:#dial in/out
  on serial port a

And here's my own /etc/saf/_sactab

  tcp:listen::999:/usr/lib/saf/listen tcp #
  zsmon:ttymon::0:/usr/lib/saf/ttymon #


4/20/95-Rev 1.3 Celeste's Tutorial on Solaris 2.x Modems & Terminals Page 24

K. Customizing the login message
================================

You can change the message displayed when login executes by using the "-p"
flag of ttyadm. This can be used to display a fixed string ("Login please"),
to display the contents of a file ("`cat /etc/myloginmsg`"), or to run a
text-producing program ("`uname -n` login ").

In fact, Sun's default /etc/inittab produces the console login prompt with a
combination of a fixed string and a program's output:

   co:234:respawn:/usr/lib/saf/ttymon -g -h -p "`uname -n` console login: "
   -T sun -d /dev/console -l console -m ldterm,ttcompat

WARNING: I haven't tested this completely. There is probably a maximum
amount of text that can be displayed. Use caution. And, let me know if you
find other good tricks to use with the login message.

Example 1: Setting the login prompt to a fixed string (as seen in add_modem
on page 14 and add_terminal on page 18):

  #!/bin/sh
  LOGINMSG="Welcome to ACME Widget Corp. Please login. "
  /usr/sbin/pmadm -a -p zsmon -s ttya -i root -v \
  `/usr/sbin/ttyadm -V` -fu -m "`/usr/sbin/ttyadm \
  -p "$LOGINMSG" -d /dev/term/a \
  -s /usr/bin/login -l conttyH -b -S n -m ldterm,ttcompat`" -y "comment"

Example 2: Setting the login prompt to the contents of a file
(/etc/myloginmsg):

  #!/bin/sh
  LOGINMSG="`cat /etc/myloginmsg`"
  /usr/sbin/pmadm -a -p zsmon -s ttya -i root -v \
  `/usr/sbin/ttyadm -V` -fu -m "`/usr/sbin/ttyadm \
  -p "$LOGINMSG" -d /dev/term/a \
  -s /usr/bin/login -l conttyH -b -S n -m ldterm,ttcompat`" -y "comment"

Example 3: Setting the login prompt to the output of a program and a fixed
string:

  #!/bin/sh
  LOGINMSG="Please login to the `uname -n` machine: "
  /usr/sbin/pmadm -a -p zsmon -s ttya -i root -v \
  `/usr/sbin/ttyadm -V` -fu -m "`/usr/sbin/ttyadm \
  -p "$LOGINMSG" -d /dev/term/a \
  -s /usr/bin/login -l conttyH -b -S n -m ldterm,ttcompat`" -y "comment"


4/20/95-Rev 1.3 Celeste's Tutorial on Solaris 2.x Modems & Terminals Page 25

L. Vendor List
==============

This list of vendors is vastly incomplete. These are just some of the
companies whose products and/or services my readers, clients, and I have
been usually satisfied with. If you have had a happy experience with other
vendors of serial-port-based products for Suns, send me the info and I'll
include them in this list.

Companies, their products, and their support staffs change regularly, so
your "satisfaction mileage" may vary. (And I don't receive any money or
special favors from any of these folks, nor would I consider it. I'm just a
consumer, like you.)

Serial cards:
  MAGMA
  6725 Mesa Ridge Rd., #100
  San Diego, CA 92121
  Voice: 800-285-8990 or 619-457-0750/FAX: 619-457-0798

Modems:
  US Robotics Telebit Corporation
  6100 N. McCormick Blvd. One Executive Drive
  Skokie, IL 60076 Chelmsford, MA 01824
  Voice: 800-877-2677 Voice: 800-TELEBIT

PPP:
  PUBLIC DOMAIN VERSION COMMERCIAL VERSION
  dp-3.1.4 (latest as of this Morning Star technologies, Inc.
  writing) available by anonymous 3518 Riverside Drive, suite 101
  ftp at acn.purdue.edu:/dp) Columbus OH USA 43221
                                       Voice: 800-558-7827/FAX: 614-459-5054
                                       ftp.MorningStar.Com (anonymous FTP)

Kermit:
  Anonymous ftp from kermit.columbia.edu

Terminal Servers:
  Annex (Annex terminal servers are available at VARs everywhere)

Publishers:
  O'Reilly and Associates (_Managing UUCP and Usenet_ is a must-read.)

----------------------------------------------------------------------------
Celeste Stokely is an outspoken and pro-user Unix System Administration
consultant who has been trying to make the world safer for Unix System
Administrators since 1983. She lives in Silicon Valley, California and runs
Stokely Consulting with her husband, Peter, and 2 bouncy cats, L.B. and
Sparcy. Celeste can be reached via email at celeste@xs.com.



This archive was generated by hypermail 2.1.2 : Fri Sep 28 2001 - 23:10:22 CDT