d/freebsd-nq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

1. Add some missing mailing lists. [jkh]

Browse Source 
2. Make the sup documentation more readable. [jkh]
3. Add new handbook section on terminals.

Submitted-By: Sean Kelly <kelly@fsl.noaa.gov>
This commit is contained in:
Jordan K. Hubbard 1996-07-29 07:15:57 +00:00
parent b7fb357273
commit 7da8f534ca
5 changed files with 551 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
share/doc/handbook/Makefile
View File

@ -1,4 +1,4 @@
# $Id: Makefile,v 1.14 1996/06/30 18:01:23 phk Exp $
# $Id: Makefile,v 1.15 1996/07/02 23:16:14 wosch Exp $
SRCS= authors.sgml basics.sgml bibliography.sgml boothelp.sgml
SRCS+= booting.sgml contrib.sgml crypt.sgml ctm.sgml current.sgml
@ -9,8 +9,8 @@ SRCS+= handbook.sgml history.sgml hw.sgml install.sgml isdn.sgml kerberos.sgml
SRCS+= kernelconfig.sgml kerneldebug.sgml memoryuse.sgml
SRCS+= mirrors.sgml nfs.sgml nutshell.sgml pgpkeys.sgml policies.sgml
SRCS+= porting.sgml ports.sgml ppp.sgml printing.sgml quotas.sgml relnotes.sgml
SRCS+= routing.sgml scsi.sgml sections.sgml sio.sgml
SRCS+= skey.sgml slipc.sgml slips.sgml stable.sgml submitters.sgml sup.sgml
SRCS+= synching.sgml troubleshooting.sgml userppp.sgml uart.sgml linuxemu.sgml
SRCS+= routing.sgml scsi.sgml sections.sgml sio.sgml skey.sgml slipc.sgml
SRCS+= slips.sgml stable.sgml submitters.sgml sup.sgml synching.sgml
SRCS+= term.sgml troubleshooting.sgml userppp.sgml uart.sgml linuxemu.sgml
.include <bsd.sgml.mk>

5
share/doc/handbook/eresources.sgml
View File

@ -1,4 +1,4 @@
<!-- $Id: eresources.sgml,v 1.24 1996/05/22 19:48:59 jkh Exp $ -->
<!-- $Id: eresources.sgml,v 1.25 1996/07/12 16:18:49 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project -->
<chapt>
@ -67,11 +67,13 @@ freebsd-emulation Emulation of other systems such as Linux/DOS/Windows
freebsd-fs Filesystems
freebsd-hackers General technical discussion
freebsd-hardware General discussion of hardware for running FreeBSD
freebsd-mobile Discussions about mobile computing
freebsd-multimedia Multimedia discussion
freebsd-platforms Concerning ports to non-Intel architecture platforms
freebsd-ports Discussion of the ports collection
freebsd-security Security issues
freebsd-scsi The SCSI subsystem
freebsd-smp Design discussions for [A]Symmetric MultiProcessing
</verb>
<bf>Limited lists:</bf> The following lists require approval to join,
@ -84,6 +86,7 @@ List Purpose
freebsd-admin Administrative issues
freebsd-arch Architecture and design discussions
freebsd-core FreeBSD core team
freebsd-hubs People running mirror sites (infrastructural support)
freebsd-install Installation development
freebsd-user-groups User group coordination
</verb>

4
share/doc/handbook/handbook.sgml
View File

@ -1,4 +1,4 @@
<!-- $Id: handbook.sgml,v 1.50 1996/07/02 23:16:15 wosch Exp $ -->
<!-- $Id: handbook.sgml,v 1.51 1996/07/07 02:00:46 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project -->
<!DOCTYPE linuxdoc PUBLIC "-//FreeBSD//DTD linuxdoc//EN" [
@ -105,7 +105,7 @@ name="FreeBSD FTP server"> or one of the numerous
<chapt><heading>Basic Networking</heading>
<sect><heading>* Ethernet basics</heading>
<sect><heading>* Serial basics</heading>
<sect><heading>* Hardwired Terminals</heading>
&term;
&dialup;
<chapt><heading>PPP and SLIP</heading>

3
share/doc/handbook/sections.sgml
View File

@ -1,4 +1,4 @@
<!-- $Id: sections.sgml,v 1.14 1996/06/30 18:01:25 phk Exp $ -->
<!-- $Id: sections.sgml,v 1.15 1996/07/02 23:16:17 wosch Exp $ -->
<!-- The FreeBSD Documentation Project -->
<!-- Entities containing all the pieces of the handbook are -->
@ -23,6 +23,7 @@
<!ENTITY history SYSTEM "history.sgml">
<!ENTITY hw SYSTEM "hw.sgml">
<!ENTITY install SYSTEM "install.sgml">
<!ENTITY term SYSTEM "term.sgml">
<!ENTITY isdn SYSTEM "isdn.sgml">
<!ENTITY kerberos SYSTEM "kerberos.sgml">
<!ENTITY kernelconfig SYSTEM "kernelconfig.sgml">

539
share/doc/handbook/term.sgml Normal file
View File

@ -0,0 +1,539 @@
<!-- This is an SGML document in the linuxdoc DTD describing
hardwired terminals with FreeBSD. By Sean Kelly, (c) 1996.
$Id$
The FreeBSD Documentation Project
<!DOCTYPE linuxdoc PUBLIC "-//FreeBSD//DTD linuxdoc//EN">
<linuxdoc>
<article>
<title> Hardwired Terminals
<author> Sean Kelly <tt/kelly@fsl.noaa.gov/
<date> 24 June 1996, (c) 1996
<abstract> This document describes using hardwired terminals
attached to computers running FreeBSD. It describes how to
set up the terminal hardware (including cabling), how to
configure FreeBSD to provide login sessions to those
terminals, and how to troubleshoot problems with terminals.
</abstract>
<toc>
-->
<sect><heading>Terminals<label id="term"></heading>
<p><em>Contributed by &a.kelly;<newline>28 July 1996</em>
Terminals provide a convenient and low-cost way to access the
power of your FreeBSD system when you are not at the computer's
console or on a connected network. This section describes how
to use terminals with FreeBSD.
<sect1><heading>Uses and Types of Terminals<label
id="term:uses"></heading>
<p>The original Unix systems did not have consoles. Instead,
people logged in and ran programs through terminals that were
connected to the computer's serial ports. It is quite similar
to using a modem and some terminal software to dial into a
remote system to do text-only work.
Today's PCs have consoles capable of high quality graphics,
but the ability to establish a login session on a serial port
still exists in nearly every Unix-style operating system
today; FreeBSD is no exception. By using a terminal attached
to a unused serial port, you can log in and run any text
program that you would normally run on the console or in an
<tt/xterm/ window in the X window system.
For the business user, you can attach many terminals to a
FreeBSD system and place them on your employees' desktops.
For a home user, a spare computer such as an older IBM PC or a
Macintosh can be a terminal wired into a more powerful
computer running FreeBSD. You can turn what might otherwise
be a single-user computer into a powerful multiple user
system.
For FreeBSD, there are three kinds of terminals:
<itemize>
<item><ref name="Dumb terminals" id="term:dumb">
<item><ref name="PCs acting as terminals" id="term:pcs">
<item><ref name="X terminals" id="term:x">
</itemize>
The remaining subsections describe each kind.
<sect2><heading>Dumb Terminals<label id="term:dumb"></heading>
<p>Dumb terminals are specialized pieces of hardware that let
you connect to computers over serial lines. They are called
``dumb'' because they have only enough computational power
to display, send, and receive text. You cannot run any
programs on them. It is the computer to which you connect
them that has all the power to run text editors, compilers,
email, games, and so forth.
There are hundreds of kinds of dumb terminals made by
many manufacturers, including Digital Equipment
Corporation's VT-100 and Wyse's WY-75. Just about any kind
will work with FreeBSD. Some high-end terminals can even
display graphics, but only certain software packages can
take advantage of these advanced features.
Dumb terminals are popular in work environments where
workers do not need access to graphic applications such as
those provided by the X window system.
<sect2><heading>PCs Acting As Terminals<label
id="term:pcs"></heading>
<p>If a <ref name="dumb terminal" id="term:dumb"> has just
enough ability to display, send, and receive text, then
certainly any spare personal computer can be a dumb
terminal. All you need is the proper cable and some
<em/terminal emulation/ software to run on the computer.
Such a configuration is popular in homes. For example, if
your spouse is busy working on your FreeBSD system's
console, you can do some text-only work at the same time
from a less powerful personal computer hooked up as a
terminal to the FreeBSD system.
<sect2><heading>X Terminals<label id="term:x"></heading>
<p>X terminals are the most sophisticated kind of terminal
available. Instead of connecting to a serial port, they
usually connect to a network like Ethernet. Instead of
being relegated to text-only applications, they can display
any X application.
We introduce X terminals just for the sake of completeness.
However, this chapter does <em/not/ cover setup,
configuration, or use of X terminals.
<sect1><heading>Cables and Ports<label
id="term:cables-ports"></heading>
<p>To connect a terminal to your FreeBSD system, you need the
right kind of cable and a serial port to which to connect it.
This section tells you what to do. If you are already
familiar with your terminal and the cable it requires, skip to
<ref name="Configuration" id="term:config">.
<sect2><heading>Cables<label id="term:cables"></heading>
<p>Because terminals use serial ports, you need to use
serial---also known as RS-232C---cables to connect the
terminal to the FreeBSD system.
There are a couple of kinds of serial cables. Which one
you'll use depends on the terminal you want to connect:
<itemize>
<item>If you are connecting a personal computer to act as
a terminal, use a <ref name="null-modem" id="term:null">
cable. A null-modem cable connects two computers or
terminals together.
<item>If you have an actual terminal, your best source of
information on what cable to use is the documentation
that accompanied the terminal. If you do not have the
documentation, then try a <ref name="null-modem"
id="term:null"> cable. If that does not work, then try
a <ref name="standard" id="term:std"> cable.
</itemize>
Also, the serial port on <em/both/ the terminal and your
FreeBSD system must have connectors that will fit the cable
you are using.
<sect3><heading>Null-modem cables<label id="term:null"></heading>
<p>A null-modem cable passes some signals straight through,
like ``signal ground,'' but switches other signals. For
example, the ``send data'' pin on one end goes to the
``receive data'' pin on the other end.
If you like making your own cables, here is a table
showing a recommended way to construct a null-modem cable
for use with terminals. This table shows the RS-232C
signal names and the pin numbers on a DB-25 connector.
<tscreen><verb>
Signal Pin# Pin# Signal
TxD 2 ----------------------- 3 RxD
RxD 3 ----------------------- 2 TxD
DTR 20 ----------------------- 6 DSR
DSR 6 ----------------------- 20 DTR
SG 7 ----------------------- 7 SG
DCD 8 ----------------------+ 4 RTS*
*RTS 4 + + 5 CTS*
*CTS 5 +---------------------- 8 DCD
* Connect pins 4 to 5 internally in the connector hood, and then to
pin 8 in the remote hood.
</verb></tscreen>
<sect3><heading>Standard RS-232C Cables<label
id="term:std"></heading>
<p>A standard serial cable passes all the RS-232C signals
straight-through. That is, the ``send data'' pin on one
end of the cable goes to the ``send data'' pin on the
other end. This is the type of cable to connect a modem
to your FreeBSD system, and the type of cable needed for
some terminals.
<sect2><heading>Ports<label id="term:ports"></heading>
<p>Serial ports are the devices through which data is
transferred between the FreeBSD host computer and the
terminal. This section describes the kinds of ports that
exist and how they are addressed in FreeBSD.
<sect3><heading>Kinds of Ports<label
id="term:portkinds"></heading>
<p>Several kinds of serial ports exist. Before you purchase
or construct a cable, you need to make sure it will fit
the ports on your terminal and on the FreeBSD system.
Most terminals will have DB25 ports. Personal computers,
including PCs running FreeBSD, will have DB25 or DB9
ports. If you have a multiport serial card for your PC,
you may have RJ-12 or RJ-45 ports.
See the documentation that accompanied the hardware for
specifications on the kind of port in use. A visual
inspection of the port often works, too.
<sect3><heading>Port Names<label
id="term:portnames"></heading>
<p>In FreeBSD, you access each serial port through an entry
in the <tt>/dev</tt> directory. There are two different
kinds of entries:
<itemize>
<item>Callin ports are named <tt>/dev/ttyd<it/X/</tt>
where <it/X/ is the port number, starting from zero.
Generally, you use the callin port for terminals.
Callin ports require that the serial line assert the
data carrier detect (DCD) signal to work.
<item>Callout ports are named <tt>/dev/cuaa<it/X/</tt>.
You usually do not use the callout port for terminals,
just for modems. You may use the callout port if the
serial cable or the terminal does not support the
carrier detect signal.
</itemize>
See the sio(4) manual page for more information.
If you have connected a terminal to the first serial port
(COM1 in DOS parlance), then you want to use
<tt>/dev/ttyd0</tt> to refer to the terminal. If it is on
the second serial port (also known as COM2), it is
<tt>/dev/ttyd1</tt>, and so forth.
Note that you may have to configure your kernel to support
each serial port, especially if you have a mutliport
serial card. See <ref name="Configuring the FreeBSD
Kernel" id="kernelconfig"> for more information.
<sect1><heading>Configuration<label id="term:config"></heading>
<p>This section describes what you need to configure on your
FreeBSD system to enable a login session on a terminal. It
assumes you have already configured your kernel to support the
serial port to which the terminal is connected---and that you
have connected it.
In a nutshell, you need tell the <tt/init/ process, which is
responsible for process control and initialization, to start a
<tt/getty/ process, which is responsible for reading a login
name and starting the <tt/login/ program.
To do so, you have to edit the <tt>/etc/ttys</tt> file.
First, use the <tt/su/ command to become root. Then, make the
following changes to <tt>/etc/ttys</tt>:
<enum>
<item>Add an line to <tt>/etc/ttys</tt> for the entry in the
<tt>/dev</tt> directory for the serial port if it is not
already there.
<item>Specify that <tt>/usr/libexec/getty</tt> be run on the
port, and specify the appropriate <tt/getty/ type from the
<tt>/etc/gettytab</tt> file.
<item>Specify the default terminal type.
<item>Set the port to ``on.''
<item>Specify whether the port should be ``secure.''
<item>Force <tt/init/ to reread the <tt>/etc/ttys</tt> file.
</enum>
As an optional step, you may wish to create a custom
<tt/getty/ type for use in step 2 by making an entry in
<tt>/etc/gettytab</tt>. This document does not explain how to
do so; you are encouraged to see the gettytab(5) and the
getty(8) manual pages for more information.
The remaining sections detail how to do these steps. We will
use a running example throughout these sections to illustrate
what we need to do. In our example, we will connect two
terminals to the system: a Wyse-50 and a old 286 IBM PC
running Procomm terminal software emulating a VT-100 terminal.
We connect the Wyse to the second serial port and the 286 to
the sixth serial port (a port on a multiport serial card).
For more information on the <tt>/etc/ttys</tt> file, see the
ttys(5) manual page.
<sect2><heading>Adding an Entry to <tt>/etc/ttys</tt><label
id="term:etcttys"></heading>
<p>First, you need to add an entry to the <tt>/etc/ttys</tt>
file, unless one is already there.
The <tt>/etc/ttys</tt> file lists all of the ports on your
FreeBSD system where you want to allow logins. For example,
the first virtual console <tt>ttyv0</tt> has an entry in
this file. You can log in on the console using this entry.
This file contains entries for the other virtual consoles,
serial ports, and pseudo-ttys. For a hardwired terminal,
just list the serial port's <tt>/dev</tt> entry without the
<tt>/dev</tt> part.
When you installed your FreeBSD system, the
<tt>/etc/ttys</tt> file included entries for the first four
serial ports: <tt/ttyd0/ through <tt/ttyd3/. If you are
attaching a terminal on one of those ports, you do not need
to add an entry.
In our example, we attached a Wyse-50 to the second serial
port, <tt/ttyd1/, which is already in the file. We need to
add an entry for the 286 PC connected to the sixth serial
port. Here is an excerpt of the <tt>/etc/ttys</tt> file
after we add the new entry:
<tscreen><verb>
ttyd1 "/usr/libexec/getty std.9600" unknown off secure
ttyd5
</verb></tscreen>
<sect2><heading>Specifying the <tt/getty/ Type<label
id="term:getty"></heading>
<p>Next, we need to specify what program will be run to handle
the logins on a terminal. For FreeBSD, the standard program
to do that is <tt>/usr/libexec/getty</tt>. It is what
provides the <tt>login:</tt> prompt.
The program <tt/getty/ takes one (optional) parameter on its
command line, the <em/<tt/getty/ type/. A <tt/getty/ type
tells about characteristics on the terminal line, like bps
rate and parity. The <tt/getty/ program reads these
characteristics from the file <tt>/etc/gettytab</tt>.
The file <tt>/etc/gettytab</tt> contains lots of entries for
terminal lines both old and new. In almost all cases, the
entries that start with the text <tt/std/ will work for
hardwired terminals. These entries ignore parity. There is
a <tt/std/ entry for each bps rate from 110 to 115200. Of
course, you can add your own entries to this file. The
manual page gettytab(5) provides more information.
When setting the <tt/getty/ type in the <tt>/etc/ttys</tt>
file, make sure that the communications settings on the
terminal match.
For our example, the Wyse-50 uses no parity and connects at
38400 bps. The 286 PC uses no parity and connects at 19200
bps. Here is the <tt>/etc/ttys</tt> file so far (showing
just the two terminals in which we are interested):
<tscreen><verb>
ttyd1 "/usr/libexec/getty std.38400" unknown off secure
ttyd5 "/usr/libexec/getty std.19200"
</verb></tscreen>
Note that the second field---where we specify what program
to run---appears in quotes. This is important, otherwise
the type argument to <tt/getty/ might be interpreted as the
next field.
<sect2><heading>Specifying the Default Terminal Type<label
id="term:deftermtype"></heading>
<p>The third field in the <tt>/etc/ttys</tt> file lists the
default terminal type for the port. For dialup ports, you
typically put <tt/unknown/ or <tt/dialup/ in this field
because users may dial up with practically any kind of
terminal or software. For hardwired terminals, the terminal
type does not change, so you can put a real terminal type in
this field.
Users will usually use the <tt/tset/ program in their
<tt/.login/ or <tt/.profile/ files to check the terminal
type and prompt for one if necessary. By setting a terminal
type in the <tt>/etc/ttys</tt> file, users can forego such
prompting.
To find out what terminal types FreeBSD supports, see the
file <tt>/usr/share/misc/termcap</tt>. It lists about 600
terminal types. You can add more if you wish. See the
termcap(5) manual page for information.
In our example, the Wyse-50 is a Wyse-50 type of terminal
(although it can emulate others, we will leave it in Wyse-50
mode). The 286 PC is running Procomm which will be set to
emulate a VT-100. Here are the pertinent yet unfinished
entries from the <tt>/etc/ttys</tt> file:
<tscreen><verb>
ttyd1 "/usr/libexec/getty std.38400" wy50 off secure
ttyd5 "/usr/libexec/getty std.19200" vt100
</verb></tscreen>
<sect2><heading>Enabling the Port<label
id="term:enable"></heading>
<p>The next field in <tt>/etc/ttys</tt>, the fourth field,
tells whether to enable the port. Putting <tt/on/ here will
have the <tt/init/ process start the program in the second
field, <tt/getty/, which will prompt for a login. If you
put <tt/off/ in the fourth field, there will be no
<tt/getty/, and hence no logins on the port.
So, naturally, you want an <tt/on/ in this field. Here
again is the <tt>/etc/ttys</tt> file. We have turned each
port <tt/on/.
<tscreen><verb>
ttyd1 "/usr/libexec/getty std.38400" wy50 on secure
ttyd5 "/usr/libexec/getty std.19200" vt100 on
</verb></tscreen>
<sect2><heading>Specifying Secure Ports<label
id="term:secure"></heading>
<p>We have arrived at the last field (well, almost: there is
an optional <tt/window/ specifier, but we will ignore that).
The last field tells whether the port is secure.
What does ``secure'' mean?
It means that the root account (or any account with a user
ID of 0) may login on the port. Insecure ports do not
allow root to login.
How do you use secure and insecure ports?
By marking a port as insecure, the terminal to which it is
connected will not allow root to login. People who know
the root password to your FreeBSD system will first have to
login using a regular user account. To gain superuser
privileges, they will then have to use the <tt/su/ command.
Because of this, you will have two records to help track
down possible compromises of root privileges: both the login
and the <tt/su/ command make records in the system log (and
logins are also recorded in the <tt/wtmp/ file).
By marking a port as secure, the terminal will allow root
in. People who know the root password will just login as
root. You will not have the potentially useful login and
<tt/su/ command records.
Which should you use?
Just use ``insecure.'' Use ``insecure'' <em/even/ for
terminals <em/not/ in public user areas or behind locked
doors. It is quite easy to login and use <tt/su/ if you
need superuser privileges.
Here finally are the completed entries in the
<tt>/etc/ttys</tt> file, with comments added to describe
where the terminals are:
<tscreen><verb>
ttyd1 "/usr/libexec/getty std.38400" wy50 on insecure # Kitchen
ttyd5 "/usr/libexec/getty std.19200" vt100 on insecure # Guest bathroom
</verb></tscreen>
<sect2><heading>Force <tt/init/ to Reread
<tt>/etc/ttys</tt><label id="term:hup"></heading>
<p>When you boot FreeBSD, the first process, <tt/init/, will
read the <tt>/etc/ttys</tt> file and start the programs
listed for each enabled port to prompt for logins.
After you edit <tt>/etc/ttys</tt>, you do not want to have
to reboot your system to get <tt/init/ to see the changes.
So, <tt/init/ will reread <tt>/etc/ttys</tt> if it receives
a SIGHUP (hangup) signal.
So, after you have saved your changes to <tt>/etc/ttys</tt>,
send SIGHUP to <tt/init/ by typing:
<tscreen><verb>
kill -HUP 1
</verb></tscreen>
(The <tt/init/ process <em/always/ has process ID 1.)
If everything is set up correctly, all cables are in place,
and the terminals are powered up, you should see login
prompts. Your terminals are ready for their first logins!
<sect1><heading>Debugging your connection<label
id="term:debug"></heading>
<p>Even with the most meticulous attention to detail, something
could still go wrong while setting up a terminal. Here is a
list of symptoms and some suggested fixes.
<descrip>
<tag/No login prompt appears/
Make sure the terminal is plugged in and powered up. If
it is a personal computer acting as a terminal, make sure
it is running terminal emulation software on the correct
serial port.
Make sure the cable is connected firmly to both the
terminal and the FreeBSD computer. Make sure it is the
right kind of cable.
Make sure the terminal and FreeBSD agree on the bps rate
and parity settings. If you have a video display
terminal, make sure the contrast and brightness controls
are turned up. If it is a printing terminal, make sure
paper and ink are in good supply.
Make sure that a <tt/getty/ process is running and serving
the terminal. Type
<tscreen><verb>
ps -axww|grep getty
</verb></tscreen>
to get a list of running <tt/getty/ processes. You should
see an entry for the terminal. For example, the display
<tscreen><verb>
22189 d1 Is+ 0:00.03 /usr/libexec/getty std.38400 ttyd1
</verb></tscreen>
shows that a <tt/getty/ is running on the second serial
port <tt/ttyd1/ and is using the <tt/std.38400/ entry in
<tt>/etc/gettytab</tt>.
If no <tt/getty/ process is running, make sure you have
enabled the port in <tt>/etc/ttys</tt>. Make sure you
have run <tt/kill -HUP 1/.
<tag/Garbage appears instead of a login prompt/
Make sure the terminal and FreeBSD agree on the bps rate
and parity settings. Check the getty processes to make
sure the correct <tt/getty/ type is in use. If not, edit
<tt>/etc/ttys</tt> and run <tt/kill -HUP 1/.
<tag/Characters appear doubled; the password appears when typed/
Switch the terminal (or the terminal emulation software)
from ``half duplex'' or ``local echo'' to ``full duplex.''
</descrip>