Initial header tightening pass through this chapter, in prep for further work.

Made sure not to create any orphaned links. Some headings were better suited as tables which were created.

This is to be followed by a much needed white space fix.
This commit is contained in:
Dru Lavigne 2013-10-17 15:42:25 +00:00
parent de8b410af2
commit be4482403f
Notes: svn2git 2020-12-08 03:00:23 +00:00
svn path=/head/; revision=42984

View file

@ -57,13 +57,9 @@
</sect1> </sect1>
<sect1 id="serial"> <sect1 id="serial">
<title>Introduction</title> <title>Serial Terminology and Hardware</title>
<!-- XXX Write me! -->
<sect2 id="serial-terminology">
<title>Terminology</title>
<para>The following terms are often used in serial commnications:</para>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term><acronym>bps</acronym></term> <term><acronym>bps</acronym></term>
@ -76,16 +72,18 @@
<varlistentry> <varlistentry>
<term><acronym>DTE</acronym></term> <term><acronym>DTE</acronym></term>
<listitem> <listitem>
<para>An example of a Data Terminal Equipment<indexterm><primary>DTE</primary></indexterm> <para>Data Terminal Equipment<indexterm><primary>DTE</primary></indexterm>
(<acronym>DTE</acronym>) is a computer.</para> (<acronym>DTE</acronym>) is one of two endpoints in a
serial communication. An example would be a computer.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><acronym>DCE</acronym></term> <term><acronym>DCE</acronym></term>
<listitem> <listitem>
<para>An example of a Data Communications Equipment<indexterm><primary>DCE</primary></indexterm> <para>Data Communications Equipment<indexterm><primary>DCE</primary></indexterm>
(<acronym>DTE</acronym>) is a modem.</para> (<acronym>DTE</acronym>) is the other endpoint in a
serial communication. Typically, it is a modem.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -93,8 +91,8 @@
<term>RS-232</term> <term>RS-232</term>
<listitem> <listitem>
<para>The original standard for hardware serial <para>The original standard which defined hardware serial
communications. It is now usually referred to as communications. It has since been renamed to
<acronym>TIA</acronym>-232<indexterm><primary>RS-232C cables</primary></indexterm>.</para> <acronym>TIA</acronym>-232<indexterm><primary>RS-232C cables</primary></indexterm>.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -105,10 +103,7 @@
number of electrical state transitions that may be made in a number of electrical state transitions that may be made in a
period of time, while <acronym>bps</acronym> is the period of time, while <acronym>bps</acronym> is the
<emphasis>correct</emphasis> term to use.</para> <emphasis>correct</emphasis> term to use.</para>
</sect2>
<sect2 id="serial-cables-ports">
<title>Cables and Ports</title>
<para>To connect a modem or serial terminal to a &os; system, a <para>To connect a modem or serial terminal to a &os; system, a
serial port on the computer and the proper cable to connect to serial port on the computer and the proper cable to connect to
@ -116,17 +111,14 @@
with serial hardware and cabling can safely skip this with serial hardware and cabling can safely skip this
section.</para> section.</para>
<sect3 id="term-cables"> <sect2 id="term-cables-null">
<title>Cables</title> <title>Serial Cables and Ports</title>
<para>There are several different kinds of serial cables. The <para>There are several different kinds of serial cables. The
two most common types are null-modem cables and standard two most common types are null-modem cables and standard
RS-232 cables. The documentation for the hardware should RS-232 cables. The documentation for the hardware should
describe the type of cable required.</para> describe the type of cable required.</para>
<sect4 id="term-cables-null">
<title>Null-modem Cables</title>
<indexterm> <indexterm>
<primary>null-modem cable</primary> <primary>null-modem cable</primary>
</indexterm> </indexterm>
@ -431,10 +423,6 @@
another variation, SG connects to SG, TD connects to RD, another variation, SG connects to SG, TD connects to RD,
RTS and CTS connect to DCD, DTR connects to DSR, and RTS and CTS connect to DCD, DTR connects to DSR, and
vice-versa.</para> vice-versa.</para>
</sect4>
<sect4 id="term-cables-std">
<title>Standard RS-232C Cables</title>
<indexterm><primary>RS-232C cables</primary></indexterm> <indexterm><primary>RS-232C cables</primary></indexterm>
@ -445,20 +433,12 @@
This is the type of cable used to connect a modem to This is the type of cable used to connect a modem to
the &os; system, and is also appropriate for some the &os; system, and is also appropriate for some
terminals.</para> terminals.</para>
</sect4>
</sect3>
<sect3 id="term-ports">
<title>Ports</title>
<para>Serial ports are the devices through which data is <para>Serial ports are the devices through which data is
transferred between the &os; host computer and the transferred between the &os; host computer and the
terminal. This section describes the kinds of ports that terminal. This section describes the kinds of ports that
exist and how they are addressed in &os;.</para> exist and how they are addressed in &os;.</para>
<sect4 id="term-portkinds">
<title>Kinds of Ports</title>
<para>Several kinds of serial ports exist. Before <para>Several kinds of serial ports exist. Before
purchasing or constructing a cable, make sure it will purchasing or constructing a cable, make sure it will
fit the ports on the terminal and on the &os; fit the ports on the terminal and on the &os;
@ -471,10 +451,6 @@
<para>See the documentation that accompanied the hardware <para>See the documentation that accompanied the hardware
for specifications on the kind of port or visually verify for specifications on the kind of port or visually verify
the type of port.</para> the type of port.</para>
</sect4>
<sect4 id="term-portnames">
<title>Port Names</title>
<para>In &os;, each serial port is accessed through an <para>In &os;, each serial port is accessed through an
entry in <filename class="directory">/dev</filename>. entry in <filename class="directory">/dev</filename>.
@ -508,9 +484,6 @@
terminal. If the terminal is on the second serial port terminal. If the terminal is on the second serial port
(<devicename>COM2</devicename>), use (<devicename>COM2</devicename>), use
<filename>/dev/ttyu1</filename>, and so forth.</para> <filename>/dev/ttyu1</filename>, and so forth.</para>
</sect4>
</sect3>
</sect2> </sect2>
<sect2> <sect2>
@ -642,16 +615,17 @@
</sect1> </sect1>
<sect1 id="term"> <sect1 id="term">
<!--
<sect1info> <sect1info>
<authorgroup> <authorgroup>
<author> <author>
<firstname>Sean</firstname> <firstname>Sean</firstname>
<surname>Kelly</surname> <surname>Kelly</surname>
<contrib>Contributed by </contrib> <contrib>Contributed by in July 1996</contrib>
</author> </author>
<!-- 28 July 1996 -->
</authorgroup> </authorgroup>
</sect1info> </sect1info>
-->
<title>Terminals</title> <title>Terminals</title>
<indexterm><primary>terminals</primary></indexterm> <indexterm><primary>terminals</primary></indexterm>
@ -661,9 +635,6 @@
connected network. This section describes how to use terminals connected network. This section describes how to use terminals
with &os;.</para> with &os;.</para>
<sect2 id="term-uses">
<title>Uses and Types of Terminals</title>
<para>The original &unix; systems did not have consoles. <para>The original &unix; systems did not have consoles.
Instead, users logged in and ran programs through terminals Instead, users logged in and ran programs through terminals
that were connected to the computer's serial ports.</para> that were connected to the computer's serial ports.</para>
@ -681,13 +652,12 @@
otherwise be a single-user computer into a powerful multiple otherwise be a single-user computer into a powerful multiple
user system.</para> user system.</para>
<para>This section describes three kinds of terminals supported <para>&os; supports three types of terminals:</para>
by &os;: dumb terminals, computers acting as terminals, and X
terminals.</para>
<sect3 id="term-dumb">
<title>Dumb Terminals</title>
<variablelist>
<varlistentry>
<term><acronym>Dumb terminals</acronym></term>
<listitem>
<para>Dumb terminals are specialized hardware that connect to <para>Dumb terminals are specialized hardware that connect to
computers over serial lines. They are called computers over serial lines. They are called
<quote>dumb</quote> because they have only enough <quote>dumb</quote> because they have only enough
@ -704,12 +674,13 @@
<para>Dumb terminals are popular in work environments where <para>Dumb terminals are popular in work environments where
workers do not need access to graphical applications.</para> workers do not need access to graphical applications.</para>
</sect3> </listitem>
</varlistentry>
<sect3 id="term-pcs"> <varlistentry>
<title>Computers Acting as Terminals</title> <term>Computers Acting as Terminals</term>
<listitem>
<para>If a <link linkend="term-dumb">dumb terminal</link> has <para>If a dumb terminal has
just enough ability to display, send, and receive text, just enough ability to display, send, and receive text,
any spare computer can be a dumb terminal. All that is any spare computer can be a dumb terminal. All that is
needed is the proper cable and some <emphasis>terminal needed is the proper cable and some <emphasis>terminal
@ -750,11 +721,12 @@
through the Ports Collection, such as <filename through the Ports Collection, such as <filename
role="package">comms/minicom</filename>.</para> role="package">comms/minicom</filename>.</para>
</note> </note>
</sect3> </listitem>
</varlistentry>
<sect3 id="term-x">
<title>X Terminals</title>
<varlistentry>
<term>X Terminals</term>
<listitem>
<para>X terminals are the most sophisticated kind of terminal <para>X terminals are the most sophisticated kind of terminal
available. Instead of connecting to a serial port, they available. Instead of connecting to a serial port, they
usually connect to a network like Ethernet. Instead of usually connect to a network like Ethernet. Instead of
@ -763,8 +735,9 @@
<para>This chapter does <emphasis>not</emphasis> cover the <para>This chapter does <emphasis>not</emphasis> cover the
setup, configuration, or use of X terminals.</para> setup, configuration, or use of X terminals.</para>
</sect3> </listitem>
</sect2> </varlistentry>
</variablelist>
<sect2 id="term-config"> <sect2 id="term-config">
<title>Configuration</title> <title>Configuration</title>
@ -995,10 +968,7 @@ ttyu5 "/usr/libexec/getty std.19200" vt100 on insecure</programlisting>
Here is a list of common symptoms and some suggested Here is a list of common symptoms and some suggested
fixes.</para> fixes.</para>
<sect3> <para>If no login prompt appears, make sure the terminal is plugged in and powered up. If
<title>No Login Prompt Appears</title>
<para>Make sure the terminal is plugged in and powered up. If
it is a personal computer acting as a terminal, make sure it it is a personal computer acting as a terminal, make sure it
is running terminal emulation software on the correct serial is running terminal emulation software on the correct serial
port.</para> port.</para>
@ -1050,33 +1020,22 @@ ttyu5 "/usr/libexec/getty std.19200" vt100 on insecure</programlisting>
software flow control enabled when using software flow control enabled when using
<literal>3wire</literal> to prevent buffer overflows.</para> <literal>3wire</literal> to prevent buffer overflows.</para>
</sect3> <para>If garbage appears instead of a login prompt, make sure the terminal and &os; agree on the
<sect3>
<title>If Garbage Appears Instead of a Login Prompt</title>
<para>Make sure the terminal and &os; agree on the
<acronym>bps</acronym> rate and parity settings. Check the <acronym>bps</acronym> rate and parity settings. Check the
<command>getty</command> processes to make sure the correct <command>getty</command> processes to make sure the correct
<replaceable>getty</replaceable> type is in use. If not, <replaceable>getty</replaceable> type is in use. If not,
edit <filename>/etc/ttys</filename> and run <command>kill edit <filename>/etc/ttys</filename> and run <command>kill
-HUP 1</command>.</para> -HUP 1</command>.</para>
</sect3> <para>If characters appear doubled and the password appears when
typed, switch the terminal, or the terminal emulation software,
<sect3>
<title>Characters Appear Doubled and the Password Appears When
Typed</title>
<para>Switch the terminal, or the terminal emulation software,
from <quote>half duplex</quote> or <quote>local echo</quote> from <quote>half duplex</quote> or <quote>local echo</quote>
to <quote>full duplex.</quote></para> to <quote>full duplex.</quote></para>
</sect3>
</sect2> </sect2>
</sect1> </sect1>
<sect1 id="dialup"> <sect1 id="dialup">
<!--
<sect1info> <sect1info>
<authorgroup> <authorgroup>
<author> <author>
@ -1093,16 +1052,14 @@ ttyu5 "/usr/libexec/getty std.19200" vt100 on insecure</programlisting>
</author> </author>
</authorgroup> </authorgroup>
</sect1info> </sect1info>
-->
<title>Dial-in Service</title> <title>Dial-in Service</title>
<indexterm><primary>dial-in service</primary></indexterm> <indexterm><primary>dial-in service</primary></indexterm>
<para>Configuring a &os; system for dial-in service is similar <para>Configuring a &os; system for dial-in service is similar
to connecting terminals except that modems are used instead of to connecting terminals except that modems are used instead of
terminal devices.</para> terminal devices. &os; supports both external and internal modems.</para>
<sect2>
<title>External Versus Internal Modems</title>
<para>External modems are more convenient for dial-up because <para>External modems are more convenient for dial-up because
they often can be semi-permanently configured via parameters they often can be semi-permanently configured via parameters
@ -1115,9 +1072,6 @@ ttyu5 "/usr/libexec/getty std.19200" vt100 on insecure</programlisting>
internal modem has any signal indicator lights, they are internal modem has any signal indicator lights, they are
difficult to view when the system's cover is in place.</para> difficult to view when the system's cover is in place.</para>
<sect3>
<title>Modems and Cables</title>
<indexterm><primary>modem</primary></indexterm> <indexterm><primary>modem</primary></indexterm>
<para>When using an external modem, a proper cable is needed. <para>When using an external modem, a proper cable is needed.
@ -1196,8 +1150,6 @@ ttyu5 "/usr/libexec/getty std.19200" vt100 on insecure</programlisting>
the modem after a call. &os; avoids sending commands to the modem after a call. &os; avoids sending commands to
the modem or watching for status reports from the the modem or watching for status reports from the
modem.</para> modem.</para>
</sect3>
</sect2>
<sect2> <sect2>
<title>Serial Interface Considerations</title> <title>Serial Interface Considerations</title>
@ -1316,19 +1268,12 @@ ttyu5 "/usr/libexec/getty std.19200" vt100 on insecure</programlisting>
information on the format of the file and the list of information on the format of the file and the list of
capabilities.</para> capabilities.</para>
<sect4>
<title>Locked-speed Config</title>
<para>When locking a modem's data communications rate at a <para>When locking a modem's data communications rate at a
particular speed, no changes to particular speed, no changes to
<filename>/etc/gettytab</filename> should be <filename>/etc/gettytab</filename> should be
needed.</para> needed.</para>
</sect4>
<sect4> <para>However, a change is needed to create a matching-speed configuration. Create an entry in
<title>Matching-speed Config</title>
<para>Set up an entry in
<filename>/etc/gettytab</filename> to give <filename>/etc/gettytab</filename> to give
<command>getty</command> information about the speeds to <command>getty</command> information about the speeds to
use for the modem. For a 2400&nbsp;bps modem, use the use for the modem. For a 2400&nbsp;bps modem, use the
@ -1402,7 +1347,6 @@ vq|VH57600|Very High Speed Modem at 57600,8-bit:\
16550A-based serial ports, there may be 16550A-based serial ports, there may be
<errorname>sio</errorname> <errorname>sio</errorname>
<quote>silo</quote> errors at 57.6&nbsp;Kbps.</para> <quote>silo</quote> errors at 57.6&nbsp;Kbps.</para>
</sect4>
</sect3> </sect3>
<sect3 id="dialup-ttys"> <sect3 id="dialup-ttys">
@ -1456,9 +1400,6 @@ vq|VH57600|Very High Speed Modem at 57600,8-bit:\
<para>Wait until the modem is properly configured and <para>Wait until the modem is properly configured and
connected before signaling <command>init</command>.</para> connected before signaling <command>init</command>.</para>
<sect4>
<title>Locked-speed Config</title>
<para>For a locked-speed configuration, the <para>For a locked-speed configuration, the
<filename>ttys</filename> entry needs to have a <filename>ttys</filename> entry needs to have a
fixed-speed entry provided to <command>getty</command>. fixed-speed entry provided to <command>getty</command>.
@ -1474,10 +1415,6 @@ vq|VH57600|Very High Speed Modem at 57600,8-bit:\
instead of <literal>std.19200</literal>. Make sure to use instead of <literal>std.19200</literal>. Make sure to use
a valid type listed in a valid type listed in
<filename>/etc/gettytab</filename>.</para> <filename>/etc/gettytab</filename>.</para>
</sect4>
<sect4>
<title>Matching-speed Config</title>
<para>In a matching-speed configuration, the <para>In a matching-speed configuration, the
<filename>ttys</filename> entry needs to reference the <filename>ttys</filename> entry needs to reference the
@ -1489,7 +1426,6 @@ vq|VH57600|Very High Speed Modem at 57600,8-bit:\
this:</para> this:</para>
<programlisting>ttyu0 "/usr/libexec/getty V19200" dialup on</programlisting> <programlisting>ttyu0 "/usr/libexec/getty V19200" dialup on</programlisting>
</sect4>
</sect3> </sect3>
<sect3> <sect3>
@ -1627,9 +1563,6 @@ AT&amp;C1&amp;D2&amp;H1&amp;I0&amp;R2&amp;W</programlisting>
conversation between <command>getty</command> and the conversation between <command>getty</command> and the
modem.</para> modem.</para>
<sect3>
<title>Locked-speed Config</title>
<para>For a locked-speed configuration, configure the modem to <para>For a locked-speed configuration, configure the modem to
maintain a constant modem-to-computer data rate independent maintain a constant modem-to-computer data rate independent
of the communications rate. On a &usrobotics; &sportster; of the communications rate. On a &usrobotics; &sportster;
@ -1639,10 +1572,6 @@ AT&amp;C1&amp;D2&amp;H1&amp;I0&amp;R2&amp;W</programlisting>
<programlisting>ATZ <programlisting>ATZ
AT&amp;B1&amp;W</programlisting> AT&amp;B1&amp;W</programlisting>
</sect3>
<sect3>
<title>Matching-speed Config</title>
<para>For a variable-speed configuration, configure the modem <para>For a variable-speed configuration, configure the modem
to adjust its serial port data rate to match the incoming to adjust its serial port data rate to match the incoming
@ -1654,7 +1583,6 @@ AT&amp;B1&amp;W</programlisting>
<programlisting>ATZ <programlisting>ATZ
AT&amp;B2&amp;W</programlisting> AT&amp;B2&amp;W</programlisting>
</sect3>
<sect3> <sect3>
<title>Checking the Modem's Configuration</title> <title>Checking the Modem's Configuration</title>
@ -1680,9 +1608,6 @@ AT&amp;B2&amp;W</programlisting>
<para>Here are a few steps for troubleshooting a dial-up modem <para>Here are a few steps for troubleshooting a dial-up modem
on a &os; system.</para> on a &os; system.</para>
<sect3>
<title>Checking Out the &os; System</title>
<para>Hook up the modem to the &os; system, boot the <para>Hook up the modem to the &os; system, boot the
system, and, if the modem has status indication lights, system, and, if the modem has status indication lights,
watch to see whether the modem's <acronym>DTR</acronym> watch to see whether the modem's <acronym>DTR</acronym>
@ -1728,12 +1653,8 @@ AT&amp;B2&amp;W</programlisting>
appropriate device special files, appropriate device special files,
<filename>/dev/ttyuN</filename>, for any mistakes, missing <filename>/dev/ttyuN</filename>, for any mistakes, missing
entries, or missing device special files.</para> entries, or missing device special files.</para>
</sect3>
<sect3> <para>Next, try dialing into the system. Be sure to use 8 bits, no
<title>Try Dialing In</title>
<para>Try dialing into the system. Be sure to use 8 bits, no
parity, and 1 stop bit on the remote system. If a prompt parity, and 1 stop bit on the remote system. If a prompt
does not appear right away, or the prompt shows garbage, try does not appear right away, or the prompt shows garbage, try
pressing <keycap>Enter</keycap> about once per second. If pressing <keycap>Enter</keycap> about once per second. If
@ -1776,9 +1697,7 @@ AT&amp;B2&amp;W</programlisting>
it later. If it still does not work, try sending an it later. If it still does not work, try sending an
email message to the &a.questions; describing the modem email message to the &a.questions; describing the modem
and the problem.</para> and the problem.</para>
</sect3>
</sect2> </sect2>
</sect1> </sect1>
<sect1 id="dialout"> <sect1 id="dialout">
@ -2066,6 +1985,7 @@ raisechar=^^</programlisting>
</sect1> </sect1>
<sect1 id="serialconsole-setup"> <sect1 id="serialconsole-setup">
<!--
<sect1info> <sect1info>
<authorgroup> <authorgroup>
<author> <author>
@ -2082,13 +2002,11 @@ raisechar=^^</programlisting>
</author> </author>
</authorgroup> </authorgroup>
</sect1info> </sect1info>
-->
<title>Setting Up the Serial Console</title> <title>Setting Up the Serial Console</title>
<indexterm><primary>serial console</primary></indexterm> <indexterm><primary>serial console</primary></indexterm>
<sect2 id="serialconsole-intro">
<title>Introduction</title>
<para>&os; has the ability to boot a system with a dumb <para>&os; has the ability to boot a system with a dumb
terminal on a serial port as a console. This configuration is terminal on a serial port as a console. This configuration is
useful for system administrators who wish to install &os; on useful for system administrators who wish to install &os; on
@ -2106,8 +2024,6 @@ raisechar=^^</programlisting>
boot block code, the boot loader code, and the kernel need to boot block code, the boot loader code, and the kernel need to
be configured.</para> be configured.</para>
</sect2>
<sect2 id="serialconsole-howto-fast"> <sect2 id="serialconsole-howto-fast">
<title>Quick Serial Console Configuration</title> <title>Quick Serial Console Configuration</title>
@ -2160,7 +2076,7 @@ raisechar=^^</programlisting>
<para>Use either a null-modem cable or a standard serial <para>Use either a null-modem cable or a standard serial
cable and a null-modem adapter. See <xref cable and a null-modem adapter. See <xref
linkend="serial-cables-ports"/> for a discussion linkend="term-cables-null"/> for a discussion
on serial cables.</para> on serial cables.</para>
</step> </step>
@ -2482,16 +2398,12 @@ boot:</screen>
<sect2 id="serialconsole-summary"> <sect2 id="serialconsole-summary">
<title>Summary</title> <title>Summary</title>
<para>Here is the summary of the various settings discussed in <para>The following tables provide a summary of the various settings discussed in
this section:</para> this section.</para>
<sect3> <table frame="none" pgwide="1">
<title>Case 1: Set the Flags to 0x10 for <title>Case 1: Set the Flags to 0x10 for
<devicename>sio0</devicename></title> <devicename>sio0</devicename></title>
<programlisting>device sio0 flags 0x10</programlisting>
<informaltable frame="none" pgwide="1">
<tgroup cols="4"> <tgroup cols="4">
<thead> <thead>
<row> <row>
@ -2546,16 +2458,11 @@ boot:</screen>
</row> </row>
</tbody> </tbody>
</tgroup> </tgroup>
</informaltable> </table>
</sect3>
<sect3> <table frame="none" pgwide="1">
<title>Case 2: Set the Flags to 0x30 for <title>Case 2: Set the Flags to 0x30 for
<devicename>sio0</devicename></title> <devicename>sio0</devicename></title>
<programlisting>device sio0 flags 0x30</programlisting>
<informaltable frame="none" pgwide="1">
<tgroup cols="4"> <tgroup cols="4">
<thead> <thead>
<row> <row>
@ -2610,8 +2517,7 @@ boot:</screen>
</row> </row>
</tbody> </tbody>
</tgroup> </tgroup>
</informaltable> </table>
</sect3>
</sect2> </sect2>
<sect2 id="serialconsole-tips"> <sect2 id="serialconsole-tips">