svn commit: r44789 - head/en_US.ISO8859-1/books/handbook/serialcomms

Dru Lavigne dru at FreeBSD.org
Wed May 7 19:51:05 UTC 2014


Author: dru
Date: Wed May  7 19:51:05 2014
New Revision: 44789
URL: http://svnweb.freebsd.org/changeset/doc/44789

Log:
  Editorial review of first 1/2 of Dial-in Service.
  
  Sponsored by:	iXsystems

Modified:
  head/en_US.ISO8859-1/books/handbook/serialcomms/chapter.xml

Modified: head/en_US.ISO8859-1/books/handbook/serialcomms/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/handbook/serialcomms/chapter.xml	Wed May  7 18:57:40 2014	(r44788)
+++ head/en_US.ISO8859-1/books/handbook/serialcomms/chapter.xml	Wed May  7 19:51:05 2014	(r44789)
@@ -971,48 +971,51 @@ ttyu5   "/usr/libexec/getty std.19200"  
   </sect1>
 
   <sect1 xml:id="dialup">
-    <!--
-    <sect1info>
+    <info>
+    <title>Dial-in Service</title>
+
       <authorgroup>
 	<author>
-	  <firstname>Guy</firstname>
+	<personname>
+	<firstname>Guy</firstname>
 	  <surname>Helmer</surname>
+	  </personname>
 	  <contrib>Contributed by </contrib>
 	</author>
       </authorgroup>
       <authorgroup>
 	<author>
+	<personname>
 	  <firstname>Sean</firstname>
 	  <surname>Kelly</surname>
+	  </personname>
 	  <contrib>Additions by </contrib>
 	</author>
       </authorgroup>
-    </sect1info>
-    -->
-    <title>Dial-in Service</title>
+    </info>
 
     <indexterm><primary>dial-in service</primary></indexterm>
 
     <para>Configuring a &os; system for dial-in service is similar
-      to connecting terminals except that modems are used instead of
+      to configuring terminals, except that modems are used instead of
       terminal devices.  &os; supports both external and internal
       modems.</para>
 
-    <para>External modems are more convenient for dial-up because
-      they often can be semi-permanently configured via parameters
-      stored in non-volatile RAM and they usually provide lighted
-      indicators that display the state of important RS-232 signals,
+    <para>External modems are more convenient because
+      they often can be configured via parameters
+      stored in non-volatile <acronym>RAM</acronym> and they usually provide lighted
+      indicators that display the state of important <acronym>RS-232</acronym> signals,
       indicating whether the modem is operating properly.</para>
 
-    <para>Internal modems usually lack non-volatile RAM, so their
-      configuration may be limited to setting DIP switches.  If the
+    <para>Internal modems usually lack non-volatile <acronym>RAM</acronym>, so their
+      configuration may be limited to setting <acronym>DIP</acronym> switches.  If the
       internal modem has any signal indicator lights, they are
       difficult to view when the system's cover is in place.</para>
 
     <indexterm><primary>modem</primary></indexterm>
 
     <para>When using an external modem, a proper cable is needed.  A
-      standard RS-232C serial cable should suffice.</para>
+      standard <acronym>RS-232C</acronym> serial cable should suffice.</para>
 
     <para>&os; needs the <acronym>RTS</acronym> and
       <acronym>CTS</acronym> signals for flow control at speeds
@@ -1022,7 +1025,8 @@ ttyu5   "/usr/libexec/getty std.19200"  
       after a session is complete.  Some cables are wired without all
       of the needed signals, so if a login session does not go away
       when the line hangs up, there may be a problem with the
-      cable.</para>
+      cable.  Refer to <xref linkend="term-cables-null"/> for more
+      information about these signals.</para>
 
     <para>Like other &unix;-like operating systems, &os; uses the
       hardware signals to find out when a call has been answered or a
@@ -1030,78 +1034,57 @@ ttyu5   "/usr/libexec/getty std.19200"  
       call.  &os; avoids sending commands to the modem or watching for
       status reports from the modem.</para>
 
-    <sect2>
-      <title>Serial Interface Considerations</title>
-
-      <para>&os; supports the NS8250-, NS16450-, NS16550-, and
-	NS16550A-based EIA RS-232C (CCITT V.24) communications
+      <para>&os; supports the <acronym>NS8250</acronym>,
+	<acronym>NS16450</acronym>, <acronym>NS16550</acronym>, and
+	<acronym>NS16550A</acronym>-based <acronym>RS-232C</acronym>
+	(<acronym>CCITT</acronym> V.24) communications
 	interfaces.  The 8250 and 16450 devices have single-character
 	buffers.  The 16550 device provides a 16-character buffer,
 	which allows for better system performance.  Bugs in plain
-	16550's prevent the use of the 16-character buffer, so use
-	16550A's if possible.  Because single-character-buffer
+	16550 devices prevent the use of the 16-character buffer, so use
+	16550A devices if possible.  Because single-character-buffer
 	devices require more work by the operating system than the
 	16-character-buffer devices, 16550A-based serial interface
 	cards are preferred.  If the system has many active serial
 	ports or will have a heavy load, 16550A-based cards are better
 	for low-error-rate communications.</para>
-    </sect2>
 
-    <sect2>
-      <title>Quick Overview</title>
+      <para>The rest of this section demonstrates how to configure a
+	modem to receive incoming connections, how to communicate
+	with the modem, and offers some troubleshooting tips.</para>
+
+    <sect2 xml:id="dialup-ttys">
+      <title>Modem Configuration</title>
 
       <indexterm><primary>getty</primary></indexterm>
       <para>As with terminals, <command>init</command> spawns a
 	<command>getty</command> process for each configured serial
-	port for dial-in connections.  For example, if a modem is
-	attached to <filename>/dev/ttyu0</filename>,
-	<command>ps ax</command> might show this:</para>
-
-      <screen> 4850 ??  I      0:00.09 /usr/libexec/getty V19200 ttyu0</screen>
-
-      <para>When a user dials the modem's line and the modems connect,
-	the Carrier Detect (<acronym>CD</acronym>) line is reported by
+	port used for dial-in connections.  When a user dials the
+	modem's line and the modems connect,
+	the <quote>Carrier Detect</quote> signal is reported by
 	the modem.  The kernel notices that the carrier has been
 	detected and instructs <command>getty</command> to open the
-	port.  <command>getty</command> sends a
+	port and display a
 	<prompt>login:</prompt> prompt at the specified initial line
-	speed.  <command>getty</command> watches to see if legitimate
-	characters are received, and, in a typical configuration, if
-	it finds junk (probably due to the modem's connection speed
-	being different than <command>getty</command>'s speed),
+	speed.  In a typical configuration, if garbage characters are
+	received, usually due to the modem's connection speed
+	being different than the configured speed,
 	<command>getty</command> tries adjusting the line speeds until
-	it receives reasonable characters.</para>
-
-      <indexterm>
-	<primary><command>/usr/bin/login</command></primary>
-      </indexterm>
-      <para>After the user enters their login name,
+	it receives reasonable characters.  After the user enters their login name,
 	<command>getty</command> executes
-	<filename>/usr/bin/login</filename>, which completes the login
+	<command>login</command>, which completes the login process
 	by asking for the user's password and then starting the user's
 	shell.</para>
-    </sect2>
-
 
-    <sect2>
-      <title>Configuration Files</title>
-
-      <para>There are three system configuration files in
-	<filename>/etc</filename> that probably
-	need to be edited to allow dial-up access to the &os; system.
-	<filename>/etc/gettytab</filename> contains configuration
-	information for the <filename>/usr/libexec/getty</filename>
-	daemon.  <filename>/etc/ttys</filename> holds information that
-	tells <command>init</command> which
-	<filename>tty</filename>s should have
-	<command>getty</command> processes running on them.  Lastly,
-	port initialization commands can be placed in
-	<filename>/etc/rc.d/serial</filename>.</para>
+      <indexterm>
+	<primary><command>/usr/bin/login</command></primary>
+      </indexterm>
 
-      <para>There are two schools of thought regarding dial-up modems
-	on &unix;.  One group likes to configure their modems and
+      <para>There are two schools of thought regarding dial-up modems.
+	One confiuration method is to set the modems and
 	systems so that no matter at what speed a remote user dials
-	in, the local computer-to-modem RS-232 interface runs at a
+	in, the dial-in <acronym>RS-232</acronym>
+	interface runs at a
 	locked speed.  The benefit of this configuration is that the
 	remote user always sees a system login prompt immediately.
 	The downside is that the system does not know what a user's
@@ -1110,68 +1093,44 @@ ttyu5   "/usr/libexec/getty std.19200"  
 	screen-painting methods to make their response better for
 	slower connections.</para>
 
-      <para>The other group configures their modems' RS-232 interface
+      <para>The second method is to configure the <acronym>RS-232</acronym> interface
 	to vary its speed based on the remote user's connection speed.
-	For example, V.32bis (14.4 Kbps) connections to the modem
-	might make the modem run its RS-232 interface at
-	19.2 Kbps, while 2400 bps connections make the
-	modem's RS-232 interface run at 2400 bps.  Because
+	Because
 	<command>getty</command> does not understand any particular
-	modem's connection speed reporting, <command>getty</command>
+	modem's connection speed reporting, it
 	gives a <prompt>login:</prompt> message at an initial speed
 	and watches the characters that come back in response.  If the
-	user sees junk, it is assumed that they know they should press
+	user sees junk, they should press
 	<keycap>Enter</keycap> until they see a recognizable prompt.
 	If the data rates do not match, <command>getty</command> sees
-	anything the user types as <quote>junk</quote>, tries going to
-	the next speed and gives the <prompt>login:</prompt> prompt
+	anything the user types as junk, tries
+	the next speed, and gives the <prompt>login:</prompt> prompt
 	again.  This procedure normally only takes a keystroke or two
 	before the user sees a good prompt.  This login sequence does
-	not look as clean as the <quote>locked-speed</quote> method,
+	not look as clean as the locked-speed method,
 	but a user on a low-speed connection should receive better
 	interactive response from full-screen programs.</para>
 
-      <para>This section will try to give balanced configuration
-	information, but is biased towards having the modem's data
-	rate follow the connection rate.</para>
-
-      <sect3>
-	<title><filename>/etc/gettytab</filename></title>
-
-	<indexterm>
-	  <primary><filename>/etc/gettytab</filename></primary>
-	</indexterm>
-	<para><filename>/etc/gettytab</filename> is a
-	  &man.termcap.5;-style file of configuration information for
-	  &man.getty.8;.  Refer to &man.gettytab.5; for complete
-	  information on the format of the file and the list of
-	  capabilities.</para>
-
 	<para>When locking a modem's data communications rate at a
 	  particular speed, no changes to
-	  <filename>/etc/gettytab</filename> should be needed.</para>
-
-	<para>However, a change is needed to create a matching-speed
-	  configuration.  Create an entry in
-	  <filename>/etc/gettytab</filename> to give
-	  <command>getty</command> information about the speeds to use
-	  for the modem.  For a 2400 bps modem, use the existing
-	  <literal>D2400</literal> entry.</para>
-
-	<programlisting>#
-# Fast dialup terminals, 2400/1200/300 rotary (can start either way)
-#
-D2400|d2400|Fast-Dial-2400:\
-        :nx=D1200:tc=2400-baud:
-3|D1200|Fast-Dial-1200:\
-        :nx=D300:tc=1200-baud:
-5|D300|Fast-Dial-300:\
-        :nx=D2400:tc=300-baud:</programlisting>
-
-	<para>For a higher speed modem, add an entry in
-	  <filename>/etc/gettytab</filename>.  This entry is for a
+	  <filename>/etc/gettytab</filename> should be needed.
+	  However, for a matching-speed
+	  configuration, additional entries may be required in
+	  order to define the speeds to use
+	  for the modem.  This example configures a
 	  14.4 Kbps modem with a top interface speed of
-	  19.2 Kbps:</para>
+	  19.2 Kbps using 8-bit, no parity connections.  It
+	  configures <command>getty</command> to start the
+	  communications rate for a V.32bis connection at
+	  19.2 Kbps, then cycles
+	  through 9600 bps, 2400 bps,
+	  1200 bps, 300 bps, and back to 19.2 Kbps.
+	  Communications rate cycling is implemented with the
+	  <literal>nx=</literal> (next table)
+	  capability.  Each line uses a
+	  <literal>tc=</literal> (table continuation)
+	  entry to pick up the rest of the
+	  settings for a particular data rate.</para>
 
 	<programlisting>#
 # Additions for a V.32bis Modem
@@ -1187,24 +1146,9 @@ up|V9600|High Speed Modem at 9600,8-bit:
 uq|V19200|High Speed Modem at 19200,8-bit:\
         :nx=V9600:tc=std.19200:</programlisting>
 
-	<para>This will result in 8-bit, no parity connections.</para>
-
-	<para>The example above starts the communications rate at
-	  19.2 Kbps (for a V.32bis connection), then cycles
-	  through 9600 bps (for V.32), 2400 bps,
-	  1200 bps, 300 bps, and back to 19.2 Kbps.
-	  Communications rate cycling is implemented with the
-	  <literal>nx=</literal> (<quote>next table</quote>)
-	  capability.  Each of the lines uses a
-	  <literal>tc=</literal> (<quote>table continuation</quote>)
-	  entry to pick up the rest of the <quote>standard</quote>
-	  settings for a particular data rate.</para>
-
-	<para>For a 28.8 Kbps modem or to take advantage of
+	<para>For a 28.8 Kbps modem, or to take advantage of
 	  compression on a 14.4 Kbps modem, use a higher
-	  communications rate than 19.2 Kbps.  Here is an
-	  example of a <filename>gettytab</filename> entry starting
-	  a 57.6 Kbps:</para>
+	  communications rate, as seen in this example:</para>
 
 	<programlisting>#
 # Additions for a V.32bis or V.34 Modem
@@ -1221,116 +1165,71 @@ vp|VH9600|Very High Speed Modem at 9600,
 vq|VH57600|Very High Speed Modem at 57600,8-bit:\
         :nx=VH9600:tc=std.57600:</programlisting>
 
-	<para>For a slow CPU or a heavily loaded system without
-	  16550A-based serial ports, there may be
+        <para>For a slow <acronym>CPU</acronym> or a heavily loaded system without
+	  16550A-based serial ports, this configuration may produce
 	  <errorname>sio</errorname>
 	  <quote>silo</quote> errors at 57.6 Kbps.</para>
-      </sect3>
-
-      <sect3 xml:id="dialup-ttys">
-	<title><filename>/etc/ttys</filename></title>
 
 	<indexterm>
 	  <primary><filename>/etc/ttys</filename></primary>
 	</indexterm>
 
-	<para>Configuration of <filename>/etc/ttys</filename>
-	  is covered in <xref linkend="ex-etc-ttys"/>.
-	  Configuration for modems is similar, but a different
-	  argument is passed to <command>getty</command> and a
-	  different terminal type is specified.  The general format
-	  for both locked-speed and matching-speed configurations
-	  is:</para>
+	<para>The configuration of <filename>/etc/ttys</filename>
+	  is similar to <xref linkend="ex-etc-ttys"/>,
+	  but a different
+	  argument is passed to <command>getty</command> and
+	  <literal>dialup</literal> is used for the terminal type.
+	  Replace
+	  <replaceable>xxx</replaceable> with the process
+	  <command>init</command> will run on the device:</para>
 
 	<programlisting>ttyu0   "/usr/libexec/getty <replaceable>xxx</replaceable>"   dialup on</programlisting>
 
-	<para>The first item in the above line is the device special
-	  file for this entry.  <literal>ttyu0</literal> indicates
-	  that <command>getty</command> is watching
-	  <filename>/dev/ttyu0</filename>.  The
-	  <replaceable>xxx</replaceable> will replace the initial
-	  <filename>gettytab</filename> capability and is the process
-	  <command>init</command> will run on the device.  The third
-	  item, <literal>dialup</literal>, is the default terminal
-	  type.  The fourth parameter, <literal>on</literal>,
-	  indicates to <command>init</command> that the line is
-	  operational.  There can be a fifth parameter,
-	  <literal>secure</literal>, but it should only be used for
-	  terminals which are physically secure, such as the system
-	  console.</para>
-
-	<para>The default terminal type, <literal>dialup</literal> in
-	  this example, may depend on local preferences.
-	  <literal>dialup</literal> is the traditional default
-	  terminal type on dial-up lines so that users may customize
-	  their login scripts to notice when the terminal is
-	  <literal>dialup</literal> and automatically adjust their
-	  terminal type.  Setting <literal>vt102</literal> as the
-	  default terminal type allows users to use VT102 emulation on
+	<para>The <literal>dialup</literal> terminal type can be
+	  changed.  For example, setting <literal>vt102</literal> as the
+	  default terminal type allows users to use <acronym>VT102</acronym> emulation on
 	  their remote systems.</para>
 
-	<para>After editing <filename>/etc/ttys</filename>, send the
-	  <command>init</command> process a <acronym>HUP</acronym>
-	  signal to re-read the file:</para>
-
-	<screen>&prompt.root; <userinput>kill -HUP 1</userinput></screen>
-
-	<para>Wait until the modem is properly configured and
-	  connected before signaling <command>init</command>.</para>
-
-	<para>For a locked-speed configuration, the
-	  <filename>ttys</filename> entry needs to have a
-	  fixed-speed entry provided to <command>getty</command>.
-	  For a modem whose port speed is locked at 19.2 Kbps,
-	  the <filename>ttys</filename> entry might look like
-	  this:</para>
-
-	<programlisting>ttyu0   "/usr/libexec/getty std.19200"   dialup on</programlisting>
-
-	<para>If the modem is locked at a different data rate,
-	  substitute the appropriate value for
-	  <literal>std.<replaceable>speed</replaceable></literal>
-	  instead of <literal>std.19200</literal>.  Make sure to use
+	<para>For a locked-speed configuration, specify the speed with
 	  a valid type listed in
-	  <filename>/etc/gettytab</filename>.</para>
+	  <filename>/etc/gettytab</filename>.
+	  This example is for a modem whose port speed is locked at
+	  19.2 Kbps:</para>
+
+	<programlisting>ttyu0   "/usr/libexec/getty std.<replaceable>19200</replaceable>"   dialup on</programlisting>
 
 	<para>In a matching-speed configuration, the
-	  <filename>ttys</filename> entry needs to reference the
+	  entry needs to reference the
 	  appropriate beginning <quote>auto-baud</quote> entry in
-	  <filename>/etc/gettytab</filename>.  For example, for the
-	  above suggested entry for a matching-speed modem that
-	  starts at 19.2 Kbps, the
-	  <filename>/etc/ttys</filename> entry might look like
-	  this:</para>
+	  <filename>/etc/gettytab</filename>.  To continue the example
+	  for a matching-speed modem that
+	  starts at 19.2 Kbps, use this entry:</para>
 
 	<programlisting>ttyu0   "/usr/libexec/getty V19200"   dialup on</programlisting>
-      </sect3>
 
-      <sect3>
-	<title><filename>/etc/rc.d/serial</filename></title>
+	<para>After editing <filename>/etc/ttys</filename>, wait until
+	  the modem is properly configured and
+	  connected before signaling <command>init</command>:</para>
+
+	<screen>&prompt.root; <userinput>kill -HUP 1</userinput></screen>
 
 	<indexterm>
 	  <primary>rc files</primary>
 	  <secondary><filename>rc.serial</filename></secondary>
 	</indexterm>
 
-	<para>High-speed modems, like V.32, V.32bis, and V.34 modems,
-	  need to use hardware (<literal>RTS/CTS</literal>) flow
-	  control.  <command>stty</command> can be used to set the
-	  hardware flow control flag in the &os; kernel for the modem
-	  ports.</para>
-
-	<para>For example, to set the <literal>termios</literal> flag
-	  <varname>crtscts</varname> on
+	<para>High-speed modems, like <acronym>V.32</acronym>,
+	  <acronym>V.32bis</acronym>, and <acronym>V.34</acronym> modems,
+	  use hardware (<literal>RTS/CTS</literal>) flow
+	  control.  Use <command>stty</command> to set the
+	  hardware flow control flag for the modem
+	  port.  This example sets the
+	  <varname>crtscts</varname> flag on
 	  <filename>COM2</filename>'s dial-in and dial-out
-	  initialization devices, the following lines could be added
-	  to <filename>/etc/rc.d/serial</filename>:</para>
+	  initialization devices:</para>
 
-	<programlisting># Serial port initial configuration
-stty -f /dev/ttyu1.init crtscts
-stty -f /dev/cuau1.init crtscts</programlisting>
-
-      </sect3>
+	<screen>&prompt.root; <userinput>stty -f /dev/ttyu1.init crtscts</userinput>
+&prompt.root; <userinput>stty -f /dev/cuau1.init crtscts</userinput></screen>
     </sect2>
 
     <sect2>
@@ -1462,9 +1361,6 @@ AT&B1&W</programlisting>
       <programlisting>ATZ
 AT&B2&W</programlisting>
 
-      <sect3>
-	<title>Checking the Modem's Configuration</title>
-
 	<para>Most high-speed modems provide commands to view the
 	  modem's current operating parameters in a somewhat
 	  human-readable fashion.  On the &usrobotics; &sportster;
@@ -1477,7 +1373,6 @@ AT&B2&W</programlisting>
 	<para>For a different brand of modem, check the modem's manual
 	  to see how to double-check the modem's configuration
 	  parameters.</para>
-      </sect3>
     </sect2>
 
     <sect2>


More information about the svn-doc-all mailing list