The Linux Serial HOWTO
by Greg Hankins, gregh@cc.gatech.edu
v1.7, 29 October 1994
This document describes how to set up serial communications devices
on a Linux box.
1. Introduction
This is the Linux Serial HOWTO. All about how to set up modems and
terminals under Linux, some serial tips, and troubleshooting.
1.1. Copyright
The Linux Serial HOWTO is copyright (C) 1994 by Greg Hankins. Linux
HOWTO documents may be reproduced and distributed in whole or in part,
in any medium physical or electronic, as long as this copyright notice
is retained on all copies. Commercial redistribution is allowed and
encouraged; however, the author would like to be notified of any such
distributions.
All translations, derivative works, or aggregate works incorporating
any Linux HOWTO documents must be covered under this copyright notice.
That is, you may not produce a derivative work from a HOWTO and impose
additional restrictions on its distribution. Exceptions to these rules
may be granted under certain conditions; please contact the Linux
HOWTO coordinator at the address given below.
In short, we wish to promote dissemination of this information through
as many channels as possible. However, we do wish to retain copyright
on the HOWTO documents, and would like to be notified of any plans to
redistribute the HOWTOs.
If you have questions, please contact Matt Welsh, the Linux HOWTO
coordinator, at
mdw@sunsite.unc.edu. You may finger this address for phone number and
additional contact information.
1.2. Other sources of information
o man pages for: getty(1m), gettydefs(4), init(1), login(1),
setserial(8)
o Your modem manual
o UUCP HOWTO: for information on setting up UUCP
o Printing HOWTO: deals with setting up a serial printer
o NET-2 HOWTO: all about networking, including SLIP and PPP
o Term HOWTO: everything you wanted to know about the term program
o USENET newsgroups:
comp.os.linux.admin Installing and administering Linux systems.
comp.os.linux.announce Announcements important to the Linux community.
(Moderated)
comp.os.linux.development Ongoing work on the Linux operating system.
comp.os.linux.help Questions and advice about Linux.
comp.os.linux.misc Linux topics not covered by other groups.
o the Linux SERIAL channel mailing list. To join, send email to
linux-activists-request@niksula.hut.fi with ``X-Mn-Admin: join
SERIAL'' in the message body or header. If you send ``X-Mn-Admin:
help'' you get a help message.
1.3. New versions of this document
New versions will be placed on
sunsite.unc.edu:/pub/Linux/docs/HOWTO/Serial-HOWTO,
and the mirror sites. The Serial HOWTO
(http://sunsite.unc.edu/mdw/HOWTO/Serial-HOWTO.html) is also available
for WWW clients such as mosaic.
If you don't have FTP access, you can get Linux help files via email.
Bill Riemers runs a mail handler on his account. Send mail to
bcr@physics.purdue.edu with a subject of ``help'' for more infomation,
and to get an index file.
1.4. Feedback
Please send me any questions, comments, suggestions, or additional
material. I'm always eager to hear about what you think about the
HOWTO. I'm also always on the lookout for improvements! Tell me
exactly what you don't understand, or what could be clearer. You can
reach me at gregh@cc.gatech.edu via email. I can also be reached at:
Greg Hankins
College of Computing
801 Atlantic Drive
Atlanta, GA 30332-0280
via snail mail, and at my home page
(http://www.cc.gatech.edu/staff/h/Greg.Hankins/) via the WWW.
Please include the version number of the Serial HOWTO when writing,
this is version 1.7.
1.5. Disclaimer
Your milage may vary. The answers given may not work for all systems
and all setup combinations.
2. Supported serial hardware
Linux supports the following serial hardware, (ie is known to work
with).
o standard PC serial boards (COM1 - COM4)
o standard PC internal modems (COM1 - COM4)
2.1. Multiport serial boards
o Usenet Serial Board II
o Boca 4-port (BB-1004)
o Boca 8-port (BB-1008)
o Boca 16-port (BB-2016)
o Boca 6-port (IO/AT66)
o AST FourPort boards and clones
o Accent Async boards
o Bell Technologies HUB6
o STB-4COM
In general, Linux will support any serial board which uses a 8250,
16450, 16550, 16550A (or compatible) UART, or an internal modem which
emulates one of the above UARTs.
Special note on the BB-1004 and BB-1008, they do not support DCD and
RI lines, and thus are not usable for dialin modems. They will work
fine for all other purposes.
2.2. Intelligent multiport serial boards
o Cyclades Cyclom 8-port (Cyclom 8Y)
o Cyclades Cyclom 16-port (Cyclom 16Y)
o DigiBoard PC/Xe (2, 4, or 8 port) (expected November 1994)
o Digiboard COM/Xi (4 or 8 port)
(pre-ALPHA driver contact Simon Park <si@wimpol.demon.co.uk> for
information)
o Specialix SI0 (modular, 4 - 32 ports)
(ALPHA driver: contact Simon Allen <simonallen@cix.compulink.co.uk>
for information)
2.3. Network serial boards
o SDL N2 (RS-232 and V.35) HDLC (driver under developement)
o Sangoma Technologies frame-relay board (driver under developement)
3. What are the names of the serial ports?
There are the 4 serial devices corresponding to COM1 - COM4:
/dev/cua0, /dev/ttyS0 (COM1) address 0x3f8 IRQ 4
/dev/cua1, /dev/ttyS1 (COM2) address 0x2f8 IRQ 3
/dev/cua2, /dev/ttyS2 (COM3) address 0x3e8 IRQ 4
/dev/cua3, /dev/ttyS3 (COM4) address 0x2e8 IRQ 3
The /dev/ttySN devices are for incoming connections and /dev/cuaN
devices for outgoing connections. N is the serial port number. In
this document, I refer to COM1 as ttyS0, COM2 as ttyS1, COM3 as ttyS2,
and COM4 as ttyS3. If I am refering to a specific device in /dev, I
will always prepend /dev to avoid confusing you.
On some installations, two extra devices will be created, /dev/modem
for your modem and /dev/mouse for your mouse. Both of these are
symbolic links to the appropriate /dev/cuaN device which you specified
during the installation (unless you have a bus mouse, then /dev/mouse
will point to the bus mouse device).
There has been some discussion on the merits of /dev/mouse and
/dev/modem. I strongly discourage the use of these links. In
particular, if you are planning on using your modem for dialin you
will run into problems because the lock files will not work correctly
if you use /dev/modem. Also, Taylor UUCP does not support symlinks
either. Use them if you like, but be sure they point to the right
device.
3.1. Major and minor device numbers of serial devices in /dev
/dev/ttyS0 major 4, minor 64 /dev/cua0 major 5, minor 64
/dev/ttyS1 major 4, minor 65 /dev/cua1 major 5, minor 65
/dev/ttyS2 major 4, minor 66 /dev/cua2 major 5, minor 66
/dev/ttyS3 major 4, minor 67 /dev/cua3 major 5, minor 67
Note that all distributions come with these devices already made
correctly.
3.1.1. Creating devices in /dev
If you don't have a device, you will have to create it with the mknod
command.
Example, suppose you needed to create devices for ttyS0:
linux# mknod -m 666 /dev/cua0 c 5 64
linux# mknod -m 666 /dev/ttyS0 c 4 64
You can also get the MAKEDEV script, available on the usual FTP sites.
This simplifies the making of devices. For example, if you needed to
make the devices for ttyS0 you would type:
linux# cd /dev
linux# MAKEDEV ttyS0
This handles the devices creation for the incoming and outgoing
devices.
3.1.2. Notes for multiport boards
The devices your multiport board uses depends on what kind of board
you have. These are listed in detail in the rc.serial which comes
with the setserial program. You will probably need to create these
devices. Either use the mknod command, or get the MAKEDEV script.
Devices for mulitport boards are made by adding 64 + the port number.
So, if you wanted to create devices for ttyS17, you would type:
linux# mknod -m 666 /dev/cua17 c 5 81
linux# mknod -m 666 /dev/ttyS17 c 4 81
Note that ``64 + 17 = 81''. Using the MAKEDEV script, you would type:
linux# cd /dev
linux# /dev/MAKEDEV ttyS17
4. What is getty_ps?
This is just another version of getty, which is a program that handles
some of the login process when you log in to a UNIX box. It was
written by Paul Sutcliffe, Jr. <paul@devon.lns.pa.us>. Kris Gleason
<gleasokr@boulder.colorado.edu> currently maintains it. 2.0.7e is the
latest version, and supercedes any older versions. Most Linux
distributions come with getty_ps installed as the default getty.
Thus, I will mainly focus on using the getty_ps package in this
document, but you are free to use any getty you like. You should
check to make sure you do indeed have getty_ps as the default getty.
At your Linux prompt, type:
linux# strings /sbin/getty | grep RINGBACK
If grep returns ``RINGBACK'' then you have the right getty. If you do
not have this version of getty, I highly recommend that you get it.
It can be found on the standard Linux FTP sites. (Kris has promised
me to implement a version feature in the next release, to avoid doing
this grep sillyness.)
4.1. Installing getty_ps
Get the latest version from a Linux FTP site.
By default, getty_ps will be configured to be Linux FSSTND (FileSystem
STaNDard) compliant, which means that it will put the binaries in
/sbin, and config files in /etc/conf.{uu}getty.ttySN. It will also
expect lock files to go in /var/lock. Make sure you have the
/var/lock directory.
If you don't want FSSTND compliance, binaries will go in /etc, config
files will go in /etc/default/{uu}getty.ttySN, and lock file will go
in /usr/spool/uucp. I recommend doing things this way if you are
using UUCP, because Taylor UUCP will have problems if you move the
lock files to where it isn't looking for them. You could always link
/usr/spool/uucp to /var/lock though, I guess.
getty_ps also uses syslogd to log messages. See the man pages for
syslogd(1) and syslog.conf(5) for setting up syslogd, if you don't
have it running already. Messages are logged with priority LOG_AUTH,
errors use LOG_ERR, and debugging uses LOG_DEBUG. If you don't want
to use syslogd you can edit tune.h in the getty_ps source files to use
a log file for messages instead, namely /var/adm/getty.log by default.
When you have decided if you want FSSTND, and syslog, edit tune.h and
the Makefile in the getty_ps source directory to reflect you
decisions. Now, install according to the instructions.
Once you have installed getty_ps, and are certain it is working, you
can remove any other versions of getty you have. Be sure to check in
/bin, /etc, /usr/bin, /usr/etc, /usr/man/man1, and /usr/man/cat1 for
any thing called getty - there are old versions lurking everywhere.
Also, you can safely remove the old config file /etc/gettytab - you
only need /etc/gettydefs. From this point on, all references to getty
will refer to getty_ps. References to uugetty will refer to the
uugetty that comes with the getty_ps package.
5. What is setserial?
setserial is a program which allows you to look at and change various
attributes of a serial device, including its port, its IRQ, and other
serial port options. It was initially written Rick Sladkey, and was
heavily modified by Ted T'so <tytso@athena,mit.edu>, who also
maintains it. The newest version is 2.10, and can be found on the
Linux FTP sites. You can find out what version you have by running
setserial with no arguments.
On boot, only the ttyS{0-3} ports are configured, using the default
IRQs of 4 and 3. So, if you have any other serial ports provided by
other boards (such as an AST Fourport), or if ttyS{0-3} have a non-
standard IRQ, you must use this program in order to configure those
serial ports. For the full listing of options, consult the man page.
6. How do I dial out with my modem?
6.1. Hardware requirements
First, make sure you have the right cable. Your modem requires a
straight through cable, with no pins crossed. Any computer store
should have these. Make sure you get the correct gender. Your DB25
serial port on your PC is always male. Do not confuse it with the
parallel port, which is the female DB25. Hook up your modem to one of
your serial ports. Consult your modem manual on how to do this if you
need help.
6.1.1. Notes on internal modems
For an internal modem, you will not need a cable. An internal modem
does not need a serial port, it has one built in. All you need to do
is configure it to use an interrupt that is not being used, and
configure the I/O address. Consult your modem manual if you get
stuck. Also, see section ``Can I use more than 2 serial devices?''
if you need help on choosing interrupts or addresses.
Due to a bit of stupidity on IBM's part, you may encounter problems if
you want your internal modem to be on ttyS3. If Linux does not detect
your internal modem on ttyS3, you can use setserial and the modem will
work fine. Internal modems on ttyS{0-2} should not have any problems
being detected.
6.2. Talking to your modem
Make sure that nothing is using the serial port you hooked your modem
to. Check your /etc/inittab for getty processes using the serial
port. Comment the line out (with a ``#'') and restart init:
linux# init q
Do not comment any lines that contain a ttyN device, only ones
containing ttySN devices. ttyN devices are your virtual consoles.
Use kermit to test the setup. For example, say your modem was on
ttyS3, and it could handle 2400 bps. You would do the following:
linux# kermit
C-Kermit 5A(188), 23 Nov 92, POSIX
Type ? or HELP for help
C-Kermit>set line /dev/cua3
C-Kermit>set speed 2400
/dev/cua3, 2400 bps
C-Kermit>c
Connecting to /dev/cua3, speed 2400.
The escape character is Ctrl-\ (ASCII 28, FS)
Type the escape character followed by C to get back,
or followed by ? to see other options.
AT
OK
<ctrl>-\-C
(Back at linux)
C-Kermit>quit
linux#
If your modem responds to AT commands, you can assume your modem is
working correctly on the Linux side. Try calling another modem. If
you don't like kermit, try one of the more advanced comm programs.
Check out section ``Noteworthy communications programs'' about comm
programs if you need some pointers.
6.3. Dial out modem configuration
For dial out use only, you can configure your modem however you want.
I like to see result codes, so I set Q0 - result codes are reported.
To set this on my modem, I would have to preceed the register name
with an AT command. Using kermit or some comm program, connect to
your modem and do the following:
ATQ0
If your modem says OK back to you, then the register is set. Do this
for each register you want to set.
I also like to see what I'm typing, so I set E1 - command echo on. If
your modem has data compression capabilities, you probably want to
enable them. If you can lock the serial port speed, and let the modem
handle modem-modem bps rate transitions, do this. Consult your modem
manual for more help, and a full listing of options. If your modem
supports a stored profile, be sure to write the configuration to the
modem (often done with AT&W) if not you will have to set the registers
everytime you turn on your, or reset your modem.
When you dial out with your modem, set the speed to the highest bps
rate that your modem supports. Since there is no speed named 57600 or
115200 bps, you must use the setserial program to set your serial port
to a higher speed. See section ``How do I set up my serial ports for
higher speeds?'' for doing this. Then, set the speed to 38400 bps in
your comm program.
6.4. Hardware flow control
If your modem supports hardware flow control (RTS/CTS), I highly
recommend you use it. This will allow you to lock your serial port -
modem speed (DTE - DCE) at a high bps rate, independant from the modem
- modem speed. This is particularly important for modems that support
data compression. First, you have to enable RTS/CTS flow control on
the serial port itself. This is best done on startup, like in
/etc/rc.local or /etc/rc.serial:
stty crtscts < /dev/cua3
Be sure to put in the correct serial port you wish to enable.
You must also enable RTS/CTS flow control on your modem. Consult your
modem manual on how to do this, as it varies between modem
manufacturers. Be sure to save your modem configuration if your modem
supports stored profiles.
7. How do I dial in and out with my modem?
Get your modem to dial out correctly. If you haven't read section
``How do I dial out with my modem'' go read it now.
7.1. Dial in and out modem configuration
For dialin and dialout use, you have to set up your modem a certain
way (again, using the AT command on your modem):
E1 command echo ON
Q0 result codes are reported
V1 verbose ON
S0=0 never answer (uugetty handles this with the WAITFOR option)
If you don't set these correctly, your INIT string in your config file
may fail, hosing the whole process. But, more on config files
below...
&C1 DCD is on after connect only
&S0 DSR is always on
DTR on/off resets modem (depends on manufacturer - RTFM)
These affect what your modem does when calls start and end.
If your modem does not support a stored profile, you can set these
through the INIT string in your config file. See below. Some modems
come with DIP switches that affect register settings. Be sure these
are set correctly, too.
I have started a collection of modem setups for different types of
modems. So far, I only have a few of them, if you would like to send
me your working configuration, please do so! If you would like me to
send you one of the configurations, just mail me and ask. I'm not
listing them here due to space concerns. I have setups for Telebit
T1600, USR Courier, and Zoom 14.4/28.8 modems.
7.2. Setting up uugetty
For dialing into, and out from your modem, we want to use uugetty.
uugetty does important lock file checking. Replace the stock getty
with getty_ps as described in section ``What is <tt>getty_ps</tt>''.
Update /etc/gettydefs to include entries for modems (note that the
entries point to each other, these are not for fixed speed):
# Modem entries
38400# B38400 CS8 # B38400 SANE -ISTRIP HUPCL #@S @L @B login: #19200
19200# B19200 CS8 # B19200 SANE -ISTRIP HUPCL #@S @L @B login: #9600
9600# B9600 CS8 # B9600 SANE -ISTRIP HUPCL #@S @L @B login: #2400
2400# B2400 CS8 # B2400 SANE -ISTRIP HUPCL #@S @L @B login: #1200
1200# B1200 CS8 # B1200 SANE -ISTRIP HUPCL #@S @L @B login: #300
300# B300 CS8 # B300 SANE -ISTRIP HUPCL #@S @L @B login: #38400
If you have a 9600 bps or faster modem, you can lock your serial port
speed and let the modem handle the transition to other bps rates.
Then, instead of the step down series of lines listed above,
/etc/gettydefs only needs to contain one line for the modem:
# 38400 fixed speed
F38400# B38400 CS8 # B38400 SANE -ISTRIP HUPCL #@S @L @B login: #F38400
# 19200 fixed speed
F19200# B19200 CS8 # B19200 SANE -ISTRIP HUPCL #@S @L @B login: #F19200
# 9600 fixed speed
F9600# B9600 CS8 # B9600 SANE -ISTRIP HUPCL #@S @L @B login: #F9600
If you have your modem set up to do RTS/CTS hardware flow control, you
can add CRTSCTS to the entries:
# 38400 fixed speed with hardware flow control
F38400# B38400 CS8 CRTSCTS # B38400 SANE -ISTRIP HUPCL CRTSCTS #@S @L @B login: #F38400
# 19200 fixed speed with hardware flow control
F19200# B19200 CS8 CRTSCTS # B19200 SANE -ISTRIP HUPCL CRTSCTS #@S @L @B login: #F19200
# 9600 fixed speed with hardware flow control
F9600# B9600 CS8 CRTSCTS # B9600 SANE -ISTRIP HUPCL CRTSCTS #@S @L @B login: #F9600
If you want, you can make uugetty print interesting things in the
login banner. In my examples, I have the system name, the serial
line, and the current bps rate. You can add other things:
@B The current (evaluated at the time the @B is seen) bps rate.
@D The current date, in MM/DD/YY.
@L The serial line to which getty is attached.
@S The system name.
@T The current time, in HH:MM:SS (24-hour).
@U The number of currently signed-on users. This is a
count of the number of entries in the /etc/utmp file
that have a non-null ut_name field.
@V The value of VERSION, as given in the defaults file.
To display a single '@' character, use either '\@' or '@@'.
Next, make sure that you have an outgoing and incoming device for the
serial port your modem is on. If you have your modem on ttyS3 you
will need the /dev/cua3, and /dev/ttyS3 devices. If you don't have
the correct devices, see section ``Creating devices in <tt>/dev</tt>''
on how to create devices, and create the devices.
7.3. Customizing uugetty
There are lots of parameters you can tweak for each port you have.
These are implemented in seperate config files for each port. The
file /etc/conf.uugetty will be used by all instances of uugetty, and
/etc/conf.uugetty.ttySN will only be used by that one port. Sample
default config files can be found with the getty_ps source files,
which come with most Linux distributions. Due to space concerns, they
are not listed here. Note that if you are using older versions of
getty (older than 2.0.7e), or aren't using FSSTND, then the default
files will be in /etc/default/uugetty.ttySN. My
/etc/conf.uugetty.ttyS3 looks like this:
# sample uugetty configuration file for a Hayes compatible modem to allow
# incoming modem connections
# alternate lock file to check... if this lock file exists, then uugetty is
# restarted so that the modem is re-initialized
ALTLOCK=cua3
ALTLINE=cua3
# line to initialize
INITLINE=cua3
# timeout to disconnect if idle...
TIMEOUT=60
# modem initialization string...
#
# format: <expect> <send> ... (chat sequence)
INIT="" \d+++\dAT\r OK\r\n ATH0\r OK\r\n AT\r OK\r\n
WAITFOR=RING
CONNECT="" ATA\r CONNECT\s\A
# this line sets the time to delay before sending the login banner
DELAY=1
#DEBUG=010
Add the following line to your /etc/inittab, so that uugetty is run on
your serial port (substituting in the correct information for your
environment - port, speed, and terminal type):
S3:456:respawn:/sbin/uugetty ttyS3 F38400 vt100
Restart init:
linux# init q
For the speed parameter in your inittab, you will want to use the
highest bps rate that your modem supports. Since there is no speed
named 57600 or 115200, you must use the setserial program to set your
serial port to a higher speed. See section ``How do I set up my
serial ports for higher speeds?'' for doing this. Then, use 38400 bps
in your inittab.
Now Linux will be watching your serial port for connections. Dial in
from another site and login to you Linux system. Rejoice.
getty and uugetty have a lot more options, see the man page for
getty(1m) for a full description. Among other things there is a
scheduling feature, and a ringback feature. RTFM :-).
8. How do I set up a terminal connected to my PC?
8.1. Hardware requirements
Make sure you have the right kind of cable. A null modem cable bought
at a computer store will do it. But it must be a null modem cable!
Make sure you are using your serial port, and not your parallel port.
At a minimum, you should have (for a DB25 connector):
RxD Receive Data 2 - 3 TxD Transmit Data
TxD Transmit Data 3 - 2 RxD Receive Data
GND Signal Ground 7 - 7 GND Signal Ground
If you want to have flow control and hardware handshaking, you must
have a full null modem cable:
Frame Ground 1 - 1 Frame Ground
RxD Receive Data 2 - 3 TxD Transmit Data
TxD Transmit Data 3 - 2 RxD Receive Data
RTS Request To Send 4 - 5 CTS Clear To Send
CTS Clear To Send 5 - 4 RTS Request To Send
DSR Data Set Ready 6 - 20 DTR Data Terminal Ready
GND Signal Ground 7 - 7 GND Signal Ground
DCD Carrier Detect 8 - 20 DTR Data Terminal Ready
DTR Data Terminal Ready 20 - 6 DSR Data Set Ready
DTR Data Terminal Ready 20 - 8 DCD Carrier Detect
If you have a DB9 connector on your port, try the following:
DB9 DB25
RxD Receive Data 2 - 2 TxD Transmit Data
TxD Transmit Data 3 - 3 RxD Receive Data
GND Signal Ground 5 - 7 GND Signal Ground
Alternatively, a DB9-DB25 null modem cable:
DB9 DB25
DCD Carrier Detect 1 - 20 DTR Data Terminal Ready
RxD Receive Data 2 - 2 TxD Transmit Data
TxD Transmit Data 3 - 3 RxD Receive Data
DTR Data Terminal Ready 4 - 6 DSR Data Set Ready
DTR Data Terminal Ready 4 - 8 DCD Carrier Detect
GND Signal Ground 5 - 7 GND Signal Ground
DSR Data Set Ready 6 - 20 DTR Data Terminal Ready
RTS Request To Send 7 - 5 CTS Clear To Send
CTS Clear To Send 8 - 4 RTS Request To Send
(RI Ring Indicator 9 not needed)
If you are not using a full null modem cable, you might have to do the
following trick: on your computer side of the connector, connect RTS
and CTS together, and also connect DSR, DCD and DTR together. This
way, when the computer wants a certain handshaking signal, it will get
it (from itself).
Now that you have the right kind of cable, connect your terminal to
your computer. If you can, tell you terminal to ignore modem control
signals. Try using 9600 bps, 8 data bits, 1 stop bit, no parity bits
for the terminal's setup.
8.2. Setting up getty
Replace the stock getty with getty_ps as described in section ``What
is <tt>getty_ps</tt>?''. Add an entry for getty to use for your
terminal in /etc/gettydefs:
# 38400 bps Dumb Terminal entry
DT38400# B38400 CS8 CLOCAL # B38400 SANE -ISTRIP CLOCAL #S @L login: #DT38400
# 19200 bps Dumb Terminal entry
DT19200# B19200 CS8 CLOCAL # B19200 SANE -ISTRIP CLOCAL #S @L login: #DT19200
# 9600 bps Dumb Terminal entry
DT9600# B9600 CS8 CLOCAL # B9600 SANE -ISTRIP CLOCAL #S @L login: #DT9600
You can add HUPCL so the login is killed whenever you switch of the
terminal (provided you use a proper null modem cable).
If you want, you can make getty print interesting things in the login
banner. In my examples, I have the system name and the serial line
printed. You can add other things:
@B The current (evaluated at the time the @B is seen) bps rate.
@D The current date, in MM/DD/YY.
@L The serial line to which getty is attached.
@S The system name.
@T The current time, in HH:MM:SS (24-hour).
@U The number of currently signed-on users. This is a
count of the number of entries in the /etc/utmp file
that have a non-null ut_name field.
@V The value of VERSION, as given in the defaults file.
To display a single '@' character, use either '\@' or '@@'.
Edit your /etc/inittab file to run getty on the serial port
(substituting in the correct information for your environment - port,
speed, and terminal type):
S1:456:respawn:/sbin/getty ttyS1 DT9600 vt100
Restart init:
linux# init q
At this point, you should see a login prompt on your terminal. You
may have to hit return a couple of times to get the terminal's
attention. Rejoice. Party. Log in on your terminal and PC. talk to
yourself from accross the room.
9. Can I use more than 2 serial devices?
You don't need to read this section, unless you want to use 3 or more
serial devices... (assuming you don't have a multiport board).
Providing you have another spare serial port, yes, you can.
The number of serial ports you can use is limited by the number of
interrupts (IRQ) and port I/O addresses we have to use. Each serial
devices must be assigned it's own interrupt and address. A serial
device can be a serial port, an internal modem, or a multiport serial
board.
Multiport serial boards are specially designed to have multiple serial
ports that share the same IRQ for all serial ports on the board.
Linux gets data from them by using a different I/O address for each
port on the card.
9.1. Choosing serial device interrupts
Your PC will normally come with ttyS0 and ttyS2 at IRQ 4, and ttyS1
and ttyS3 at IRQ 3. To use more than 2 serial devices, you will have
to give up an interrupt to use. A good choice is to reassign an
interrupt from your parallel port. Your PC normally comes with IRQ 5
and IRQ 7 set up as interrupts for your parallel ports, but few people
use 2 parallel ports. You can reassign one of the interrupts to a
serial device, and still happily use a parallel port. You will need
the setserial program to do this. In addition, you have to play with
the jumpers on your boards, check the docs for your board. Set the
jumpers to the IRQ you want for each port.
You will need to set things up so that there is one, and only one
interrupt for each serial device. Here is how I set mine up in
/etc/rc.local - you should do it upon startup somewhere:
/etc/setserial /dev/cua0 irq 3 # my mouse
/etc/setserial /dev/cua1 irq 4 # my dumb terminal
/etc/setserial /dev/cua2 irq 5 # my 2400 bps modem
/etc/setserial /dev/cua3 irq 9 # my telebit modem
Standard IRQ assignments:
IRQ 0 Timer channel 0
IRQ 1 Keyboard
IRQ 2 Cascade for controller 2
IRQ 3 Serial port 2
IRQ 4 Serial port 1
IRQ 5 Parallel port 2
IRQ 6 Floppy diskette
IRQ 7 Parallel port 1
IRQ 8 Real-time clock
IRQ 9 Redirected to IRQ2
IRQ 10 not assigned
IRQ 11 not assigned
IRQ 12 not assigned
IRQ 13 Math coprocessor
IRQ 14 Hard disk controller
IRQ 15 not assigned
There is really no Right Thing to do when choosing interrupts. Just
make sure it isn't being used. 2, 3, 4, 5, or 7 is a good choice.
``not assigned'' means that currently nothing standard uses these
IRQs. Also note that IRQ 2 is the same as IRQ 9. You can call it
either 2 or 9, the serial driver is very understanding.
If you have a serial card with a 16-bit bus connector, you can also
use IRQ 10, 11, 12 or 15.
Just make sure you don't use IRQ 0, 1, 6, 8, 13 or 14! These are used
by your mother board. You will make her very unhappy by taking her
IRQs.
9.2. Setting serial device addresses
Next, you must set the port address. Check the manual on your board
for the jumper settings. Like interrupts, there can only be one
serial device at each address. Yours port will usually come
configured as follows:
/dev/cua0, /dev/ttyS0 address 0x3f8 ttyS0
/dev/cua1, /dev/ttyS1 address 0x2f8 ttyS1
/dev/cua2, /dev/ttyS2 address 0x3e8 ttyS2
/dev/cua3, /dev/ttyS3 address 0x3e8 ttyS3
Choose which address you want each serial device to have and set the
jumpers accordingly. I have my modem on ttyS3, and my mouse on ttyS0.
When you reboot, Linux should see your serial ports at the address you
set them. The IRQ Linux sees may not correspond to the IRQ you set
with the jumpers. Don't worry about this. Linux does not do any IRQ
detection when it boots, because IRQ detection is dicy and can be
fooled. Use setserial to tell Linux what IRQ the port is using.
10. Can Linux configure the serial devices automagically?
Yes. To get Linux to detect and set up the serial devices
automatically on startup, add the line:
/etc/setserial /dev/cua0 auto_irq skip_test autoconfig
to your /etc/rc.local or /etc/rc.serial file. Do this for every
serial port you want to auto configure. Be sure to give the correct
location of where your setserial program lives, and give a device name
that really does exist on your machine.
10.1. Notes for multiport boards
For board addresses, and IRQs, look at the rc.serial that comes with
the setserial program. It has a lot of detail on multiport boards,
including I/O addresses and device names.
11. How do I set up my serial ports for higher speeds?
Use setserial, with the spd_hi flag to configure your serial port to
use 57600 bps. Use spd_vhi to use 115200 bps. Then, set your speed
to 38400 bps. This is now the new speed you have set. There is no
speed named 57600 or 115200. Make sure you have 16550A UARTs :-).
In my /etc/rc.local I set ttyS3 to 115200 bps by doing:
/bin/setserial /dev/cua3 irq 9 spd_vhi
12. Noteworthy communications programs and utilities
Once you get everything working, you may want to check out these more
advanced programs, all are available on the usual FTP sites, if they
didn't come with your distribution.
o seyon - X based comm program
o minicom - telix-like comm program
o procomm - procommish comm program with zmodem
These programs offer more features that just kermit alone, including
telephone directories, auto-dialing and so on.
o Another useful program is term. term multiplexes many connections
over one serial line. It is somewhat similar to SLIP, and offers
some SLIP functionality. These include rlogin, telnet, ftp, ncftp,
finger, rdate, xmosaic and tredir. tredir is a special program
which lets you redirect remote TCP/IP ports to your local machine.
This allows for remote NNTP, and SMTP access. The good thing about
term is that is runs entirely in user space, meaning it requires no
kernel support, or sysadmin support (like SLIP does).
o screen is another multi-session program. This one behaves like the
virtual consoles.
o callback is a program that will have your modem call you back
immediately from where you just called.
o mgetty+fax handles FAX stuff, and provides an alternate getty
o Other things can be found on
sunsite.unc.edu:/pub/Linux/system/Serial
and sunsite.unc.edu:/pub/Linux/apps/comm or one of the many
mirrors. These are the directories where all the serial type
things are kept.
13. Serial Tips
Here are some serial tips you might find helpful...
13.1. kermit and zmodem
To use zmodem with kermit, add the following to your .kermrc:
define rz !rz < /dev/cua3 > /dev/cua3
define sz !sz \%0 > /dev/cua3 < /dev/cua3
Be sure to put in the correct port your modem is on. Then, to use it,
just type rz or sz <filename> at the kermit prompt.
13.2. Setting terminal types automagically
To set your terminal type automagically when you log in, add the
terminal type to the entry in /etc/inittab. If I have a vt100
terminal on ttyS1, I would add ``vt100'' to the getty command:
S1:456:respawn:/sbin/getty ttyS1 DT9600 vt100
You can also get tset from sunsite.unc.edu:/pub/Linux/system/Terminal-
management or a mirror site. See the docs that come with tset to
learn how to use it. tset can establish terminal characteristics when
you log in, and doesn't depend on any defaults.
13.3. Color ls on serial connections
If ls is screwing up your terminal emulation with the color feature,
turn it off. ls --color, and ls --colour all use the color feature.
Some installations have ls set to use color by default. Check
/etc/profile and /etc/csh.cshrc for ls aliases. You can also alias ls
to ls -o or ls --no-color, if you don't want to change the system
defaults.
13.4. Printing to a printer connected to a terminal
There is a program called vtprint that will do this, written by
Garrett D'Amore <garrett@sciences.sdsu.edu>. It is available from
ftp.sdsu.edu:/pub/vtprint. The following is from the README file that
comes with the program:
vtprint is a program that allows users to print from a
remote UNIX host to a printer attached to their local termi-
nal or emulator, which makes it great for printing files at
home, etc. (It only does text files, though.)
14. Linux FTP sites
sunsite.unc.edu [152.2.22.81]:/pub/Linux (NC, USA)
tsx-11.mit.edu [18.172.1.2]:/pub/linux (MA, USA)
nic.funet.fi [128.214.6.100)]/pub/OS/Linux (Finland, Europe)
sunsite.unc.edu is the official Linux FTP site, and has many mirrors.
Please use a mirror site if at all possible to save sunsite some
traffic.
sunsite mirrors:
site path
------------------------------------------------------------------------------
mrcnext.cso.uiuc.edu /pub/linux/
ftp.linux.org /pub/mirrors/sunsite.unc.edu/
ftp.uni-paderborn.de /pub/Mirrors/sunsite.unc.edu/
ftp.cs.cuhk.hk /pub/Linux/
ftp.dungeon.com /pub/lunux/sunsite-mirror/
ftp.dfv.rwth-aachen.de /pub/linux/sunsite/
ftp.maths.warwick.ac.uk /mirrors/linux/sunsite.unc-mirror/
ftp.rus.uni-stuttgart.de /pub/unix/systems/linux/MIRROR.sunsite/
ftp.uni-erlangen.de /pub/Linux/MIRROR.sunsite/
ftp.uni-paderborn.de /pub/linux/sunsite/
ftp.gwdg.de /pub/linux/mirrors/sunsite/
ftp.tu-graz.ac.at /pub/Linux/
pub.vse.cz /pub/386-unix/linux/
dcs.muni.cz /pub/UNIX/linux/
ftp.univ-angers.fr /pub/linux/
hypergly.watson.ibm.com /pub/linux-sunsite (IBM internal network only)
brandy.jf.intel.com /something (Intel internal network only)
ftp.tu-dresden.de /pub/Linux/sunsite/
ftp.germany.eu.net /pub/os/Linux/Mirror.SunSITE/
ftp.nus.sg /pub/unix/Linux/
ftp.uni-tuebingen.de /pup/linux/Mirror.sunsite/
ftp.cnr.it /pub/Linux/
ftp.kfki.hu /pub/linux/
cnuce-arch.cnr.it /pub/Linux/
ftp.orst.edu /pub/mirrors/sunsite.unc.edu/linux/
ftp.nectec.or.th /pub/mirrors/linux/
ftp.switch.ch /mirrors/linux/
ftp.iquest.com /pub/linux/sunsite/
src.doc.ic.ac.uk /packages/linux/sunsite.unc-mirror/
smug.student.adelaide.edu.au /pub/sunsite.linux/
ftp.ba-mannheim.de /pub/linux/mirror.sunsite
ftp.loria.fr /pub/linux/sunsite
ftp.rz.uni-ulm.de /pub/mirrors/linux/sunsite
ftp.cc.gatech.edu /pub/linux
These FTP sites support annonymous FTP, which means login as ftp, and
password as your email address, ie logname@yourhost.yourdomain.
15. One step further...
15.1. What are lock files?
Lock file are simply a file saying that a particular device is in use.
They are kept in /usr/spool/uucp, or /var/lock. Lock files are named
LCK..<name>, where <name> is either a device name, or a UUCP site
name. Certain processes create these locks so that they can have
exclusive access to devices, for instance if you dial out on your
modem, a lock will appear telling other processes that someone is
using the modem already. Locks mainly contain the PID of the process
that has locked the device. Most programs look at the lock, and try
to determine if that lock is still valid by checking the process table
for the process that has locked the device. If the lock is found to
be valid, the program (should) exit. If not, some programs remove the
stale lock, and use the device, creating their own lock in the
process. Other programs just exit and tell you that the device is in
use.
15.2. ``baud'' vs. ``bps''
``baud'' and ``bps'' are prehaps one of the most misused terms in the
computing/telecom field. Many people use these terms interchangeably,
when in fact they are not!
baud
The baud rate is a measure of how many times per second the
signal sent by a modem (modulator-demodulator) changes. For
example, a baud rate of 1200 implies one signal change every 833
microseconds. Common baud rates are 300, 600, 1200, and 2400.
Most high speed modems run at 2400 baud. Because of the
bandwidth limitations on voice-grade phone lines, baud rates
greater than 2400 are harder to achieve, and only work under
very pristine phone line quality. ``baud'' is named after Emile
Baudot, the inventor of the asynchronous telegraph printer.
bps
The bps rate is a measure of how many bits per second are
transmitted. Common modem bps rates are 300, 1200, 2400, 4800,
... 28800. With V.42bis compression (4:1 compression),
theoretical bps rates are possible up to 115200. This is what
most people mean when they misuse the word ``baud''.
So, if high speed modems are running at 2400 baud, how can they send
14400 bps? The modems achive a bps > baud rate by encoding a number
of bits per baud. Thus, when 2 or more bits are encoded per baud, the
bps rate exceeds the baud rate. If your modem connects at 14400 bps,
it's going to be sending 6 bits per baud.
How did this confusion start? Well, back when low speed modems were
high speed modems, the bps rate actually did equal the baud rate. One
bit would be encoded per baud. People would use bps and baud
interchangeably, because they were the same number. For example, a
300 bps modem also had a baud rate of 300. This all changed when
faster bps modems came around, and the bit rate exceeded the baud
rate.
15.3. What are UARTs? How do they affect performance?
UARTs (Universal Asyncronous Receiver Transmitter) are chips on your
PC serial card. Their purpose is to convert data to bits, send the
bits down the serial line, and then rebuild the data again on the
other end. UARTs deal with data in byte sized pieces, which is
conveniently also the size of ASCII characters.
Say you have a terminal hooked up to your PC. When you type a
character, the terminal presents it to it's transmitter (also a UART,
although probably different that the PC UART). The transmitter sends
that byte out onto the serial line, one bit at a time, at a specific
rate. On the PC end, the receiving UART takes all the bits and
rebuilds the byte and puts it in a buffer.
There are two different types of UARTs. You have probably heard of
dumb UARTs - the 8250 and 16450, and smart or FIFO UARTs - the 16550A.
To understand their differences, first let's examine what happens when
a UART has sent or received a byte.
The UART itself can't do anything with the data, it just sends and
receives it. The CPU gets an interrupt every time a byte has been
sent or received. The CPU then moves the received byte out of the
UART's buffer and into memory somewhere, or gives the UART another
byte to send. The 8250 and 16450 UARTs only have a 1 byte buffer.
That means, that every time 1 byte is sent or received, it interrupts
the CPU. At low rates, this is OK. But, at high transfer rates, the
CPU get so busy dealing with the UART, that is doesn't have time to
tend to other tasks. In some cases, the CPU does not get around to
servicing the interrupt in time, and the byte is overwritten, because
they are coming in so fast.
That's where the 16550A UARTs come in. These chips come with 16 byte
FIFOs. This means that it can receive or transmit up to 16 bytes
before it has to interrupt the CPU. Not only can it wait, but the CPU
then can transfer all 16 bytes at a time. Although the interrupt
threshold is seldom set at 16, this is still a significant advantage
over the other UARTs, which only have the 1 byte buffer. The CPU
receives less interrupts, and is free to do other things. Data is
not lost, and everyone is happy.
In general, the 8250 and 16450 UARTs should be fine for speeds up to
19200 bps. At speeds greater than 19200 bps, you might start seeing
data loss, and a reduction in interactive response time. Other PC
operating systems (definition used loosely here), like DOS aren't
multitasking, so they might be able to cope better with 8250 or
16450s. That's why some people don't see data loss, until they switch
to Linux.
Keep in mind that these dumb UART types are not bad, they just aren't
good for high speeds. You should have no problem connecting a
terminal, or a mouse to these UARTs. But, for a high speed modem, the
16550A is definately a must.
You can buy serial cards with the 16550A UARTs for a little more
money, just ask your dealer what type of UART is on the card. Or if
you want to upgrade your existing card, you can simply purchase 16550A
chips and replace your existing 16450 UARTs. They are pin-to-pin
compatible. Some cards come with socketed UARTs for this purpose, if
not you can solder. Note, that you'll probably save yourself a lot of
trouble by just getting a new card, if you've got the money, they are
under US$ 50.
16. Troubleshooting
16.1. I keep getting ``line NNN of inittab invalid''.
Make sure you are using the correct syntax for your version of init.
The different init's that are out there use different syntax in the
/etc/inittab file. Make sure you are using the correct syntax for
your version of getty.
16.2. When I try to dial out, it says ``/dev/cuaN: Device or resource
busy''.
This problem can arise when DCD or DTR are not set correctly. DCD
should only be set when there is an actual connection (ie someone is
dialed in), not when getty is watching the port. Check to make sure
that your modem is configured to only set DCD when there is a
connection. DTR should be set whenever something is using, or
watching the line, like getty, kermit, or some other comm program.
Another common cause of ``device busy'' errors, is that you set up
your serial port with an interrupt already taken by something else.
As each device initializes, it asks Linux for permission to use its
hardware interrupt. Linux keeps track of which interrupt is assigned
to whom, and if your interrupt is already taken, your device won't be
able to initialize properly. The device really doesn't have much of
any way to tell you that this happened, except that when you try to
use it, it will return a ``device-busy'' error. Check the interrupts
on all of your cards (serial, ethernet, SCSI, etc.). Look for IRQ
conflicts.
16.3. I keep getting ``Id SN respawning too fast: disabled for 5 min-
utes''.
Make sure your modem is configured correctly. Look at registers ` E
and Q. This can occur when your modem is chatting with getty.
Make sure you are calling getty correctly from your /etc/inittab.
Using the wrong syntax or device names will cause serious problems.
16.4. Serial devices are slow or serial devices can only send in one
direction.
You probably have an IRQ conflict. Make sure there are no IRQs being
shared. Check all your cards (serial, ethernet, SCSI, etc...). Make
sure the jumper settings, and the setserial parameters are correct for
all your serial devices.
16.5. My modem is hosed after someone hangs up.
This can happen when your modem doesn't reset when DTR is dropped. I
saw my RD and SD LEDs go nuts when this happened to me. You need to
have your modem reset. Most Hayes compatible modems do this with &D3,
but on my USR Courier, I had to set &D2 and S13=1. Check your modem
manual.
16.6. I have a serial device connected, but root can't login on it.
This is done on purpose for security reasons. Generally, you should
only have root logins enabled on the console. It is considered
dangerous to allow root logins on anything other than the console.
But, you asked... Edit /etc/login.defs, and find the line that says
CONSOLE. Add the name of the serial device to it. Say I have my
terminal on ttyS1. I would change the line:
CONSOLE tty1:tty2:tty3:tty4:tty5:tty6:tty8
to
CONSOLE tty1:tty2:tty3:tty4:tty5:tty6:tty8:ttyS1
16.7. it just locks up. I have my terminal connected to my PC, but
after I type in a login name,
You probably don't have CLOCAL in your /etc/gettydefs entry for the
terminal, and you're probably not using a full null modem cable. You
need CLOCAL. CLOCAL tells Linux to ignore modem control signals.
Here is what it should look like:
# 38400 bps Dumb Terminal entry
DT38400# B38400 CS8 CLOCAL # B38400 SANE -ISTRIP CLOCAL #@S @L login: #D38400
# 19200 bps Dumb Terminal entry
DT19200# B19200 CS8 CLOCAL # B19200 SANE -ISTRIP CLOCAL #@S @L login: #DT19200
# 9600 bps Dumb Terminal entry
DT9600# B9600 CS8 CLOCAL # B9600 SANE -ISTRIP CLOCAL #@S @L login: #DT9600
Next, kill the getty process so a new one will be spawned with the new
entry.
16.8. At high speeds, my modem looses data.
If you are trying to run your modem at > 19200 bps, and you don't have
16550A UARTs, you should upgrade them. See section ``What are
UARTs?'' about UARTs.
16.9. them configured. On startup, Linux doesn't report the serial
devices the way I have
This is true. Linux does not do any IRQ detection on startup, it only
does serial device detection. Thus, disregard what it says about the
IRQ, because it's just assuming the standard IRQs. This is done,
because IRQ detection is unreliable, and can be fooled.
So, even though I have my ttyS2 set at IRQ 5, I still see
Jan 23 22:25:28 misfits vmunix: tty02 at 0x03e8 (irq = 4) is a 16550A
You have to use setserial to tell Linux the IRQ you are using.
16.10. rz and/or sz don't work when I call my Linux box on my modem.
If Linux looks for /dev/modem when you try to transfer files, look at
/etc/profile, and /etc/csh.cshrc. There are a bunch of aliases
defined there on some distributions, most notably Slackware. These
aliases mess up the zmodem programs. Take them out, or correct them.
16.11. My screen is printing funny looking characters.
This happens on virtual consoles when you send binary data to your
screen, or sometimes on serial connections. The way to fix this is to
type echo ^v^[c. For the control-character-impaired, thats echo
<ctrl>v<esc>c.
16.12. getty or uugetty still doesn't work.
There is a DEBUG option that comes with getty_ps. Edit your config
file /etc/conf.{uu}getty.ttySN and add DEBUG=NNN. Where NNN is one of
the following combination of numbers according to what you are trying
to debug:
D_OPT 001 option settings
D_DEF 002 defaults file processing
D_UTMP 004 utmp/wtmp processing
D_INIT 010 line initialization (INIT)
D_GTAB 020 gettytab file processing
D_RUN 040 other runtime diagnostics
D_RB 100 ringback debugging
D_LOCK 200 uugetty lockfile processing
D_SCH 400 schedule processing
D_ALL 777 everything
Setting DEBUG=010 is a good place to start.
If you are running syslogd, debugging info will appear in your log
files. If you aren't running syslogd info will appear in
/tmp/getty:ttySN for debugging getty and /tmp/uugetty:ttySN for
uugetty. Look at the debugging info and see what is going on. Most
likely, you will need to tune some of the parameters in your config
file, and you may have to configure your modem differently, too.
16.12.1. Alternate versions of getty
You might like these better:
mgetty, a different version of getty, can also handle faxes. It can
be found on the Linux FTP sites.
agetty, a simpler version of getty. This version comes with most
distributions. If not, it should be on the Linux FTP sites.
17. Contributions
There was no possible way to write this HOWTO alone. Although a lot
of the HOWTO is my writing, I have often rewritten contributions to
maintain continuity in the writing style and flow. Thanks to everyone
who has contributed or commented, the list of people has gotten too
long to list (somewhere over fifty). Special thanks to Matt Welch for
coordinating the LPD project (I suspect that's much like herding
cats), Ted T'so for answering questions about the serial drivers, and
to Kris Gleason who maintains getty_ps.
END OF Serial-HOWTO