Skip site navigation (1)Skip section navigation (2)
Date:      Wed, 7 May 2014 18:12:22 +0000 (UTC)
From:      Dru Lavigne <dru@FreeBSD.org>
To:        doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org
Subject:   svn commit: r44786 - head/en_US.ISO8859-1/books/handbook/serialcomms
Message-ID:  <201405071812.s47ICMpD010440@svn.freebsd.org>

next in thread | raw e-mail | index | archive | help
Author: dru
Date: Wed May  7 18:12:21 2014
New Revision: 44786
URL: http://svnweb.freebsd.org/changeset/doc/44786

Log:
  Finish editorial review of Terminals.
  
  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 16:22:52 2014	(r44785)
+++ head/en_US.ISO8859-1/books/handbook/serialcomms/chapter.xml	Wed May  7 18:12:21 2014	(r44786)
@@ -758,171 +758,112 @@
     </variablelist>
 
     <sect2 xml:id="term-config">
-      <title>Configuration</title>
+      <title>Terminal Configuration</title>
 
       <para>This section describes how to configure a &os; system to
-	enable a login session on a terminal.  It assumes that the
-	kernel is configured to support the serial port to which the
+	enable a login session on a serial terminal.  It assumes that the
+	system recognizes the serial port to which the
 	terminal is connected and that the terminal is
-	connected.</para>
+	connected with the correct cable.</para>
 
-      <para>The <command>init</command> process is responsible for all
-	process control and initialization at system startup.  One of
-	the tasks performed by <command>init</command> is to read
-	<filename>/etc/ttys</filename> and start a
+      <para>In &os;, <command>init</command> reads
+	<filename>/etc/ttys</filename> and starts a
 	<command>getty</command> process on the available terminals.
 	The <command>getty</command> process is responsible for
 	reading a login name and starting the <command>login</command>
-	program.</para>
-
-      <para>To configure terminals for a &os; system, the following
-	steps should be taken as <systemitem
-	  class="username">root</systemitem>:</para>
-
-      <procedure>
-	<step>
-	  <para>Add a line to <filename>/etc/ttys</filename> for the
-	    entry in <filename>/dev</filename> for the serial port if
-	    it is not already there.</para>
-	</step>
-
-	<step>
-	  <para>Specify that <command>/usr/libexec/getty</command>
-	    be run on the port, and specify the appropriate
-	    <replaceable>getty</replaceable> type from
-	    <filename>/etc/gettytab</filename>.</para>
-	</step>
-
-	<step>
-	  <para>Specify the default terminal type.</para>
-	</step>
-
-	<step>
-	  <para>Set the port to <quote>on.</quote></para>
-	</step>
-
-	<step>
-	  <para>Specify whether the port should be
-	    <quote>secure.</quote></para>
-	</step>
-
-	<step>
-	  <para>Force <command>init</command> to reread
-	    <filename>/etc/ttys</filename>.</para>
-	</step>
-      </procedure>
-
-      <para>As an optional step, create a custom
-	<replaceable>getty</replaceable> type for use in step 2 by
-	making an entry in <filename>/etc/gettytab</filename>.  For
-	more information, refer to &man.gettytab.5; and
-	&man.getty.8;.</para>
-
-      <sect3 xml:id="term-etcttys">
-	<title>Adding an Entry to
-	  <filename>/etc/ttys</filename></title>
-
-	<para><filename>/etc/ttys</filename> lists all of the ports
-	  on the &os; system which allow logins.  For example, the
-	  first virtual console, <filename>ttyv0</filename>, has an
-	  entry in this file, allowing logins on the console.  This
-	  file also contains entries for the other virtual consoles,
-	  serial ports, and pseudo-ttys.  For a hardwired terminal,
-	  list the serial port's <filename>/dev</filename> entry
-	  without the <literal>/dev</literal> part.  For example,
-	  <filename>/dev/ttyv0</filename> would be listed as
-	  <literal>ttyv0</literal>.</para>
-
-	<para>A default &os; install includes an
-	  <filename>/etc/ttys</filename> with support for the first
-	  four serial ports: <filename>ttyu0</filename> through
-	  <filename>ttyu3</filename>.  When attaching a terminal to
-	  one of those ports, this file does not need to be
-	  edited.</para>
-
-	<example xml:id="ex-etc-ttys">
-	  <title>Adding Terminal Entries to
-	    <filename>/etc/ttys</filename></title>
-
-	  <para>This example configures two terminals: a Wyse-50 and
-	    an old 286 IBM PC running
+	program.  The ports on the &os; system which allow logins are
+	listed in <filename>/etc/ttys</filename>.  For example, the
+	first virtual console, <filename>ttyv0</filename>, has an
+	entry in this file, allowing logins on the console.  This
+	file also contains entries for the other virtual consoles,
+	serial ports, and pseudo-ttys.  For a hardwired terminal,
+	the serial port's <filename>/dev</filename> entry is listed
+	without the <literal>/dev</literal> part.  For example,
+	<filename>/dev/ttyv0</filename> is listed as
+	<literal>ttyv0</literal>.</para>
+
+	<para>The default
+	  <filename>/etc/ttys</filename> configures support for the first
+	  four serial ports, <filename>ttyu0</filename> through
+	  <filename>ttyu3</filename>:</para>  
+
+	<programlisting>ttyu0   "/usr/libexec/getty std.9600"   dialup  off secure
+ttyu1   "/usr/libexec/getty std.9600"   dialup  off secure
+ttyu2   "/usr/libexec/getty std.9600"   dialup  off secure
+ttyu3   "/usr/libexec/getty std.9600"   dialup  off secure</programlisting>
+
+	<para>When attaching a terminal to
+	  one of those ports, modify the default entry to set the
+	  required speed and terminal type, to turn the device
+	  <literal>on</literal> and, if needed, to change the port's
+	  <literal>secure</literal> setting.  If the terminal is
+	  connected to another port, add an entry for the port.</para>
+
+	  <para><xref linkend="ex-etc-ttys"/> configures two
+	    terminals in <filename>/etc/ttys</filename>.  The first
+	    entry configures a Wyse-50
+	    connected to <filename>COM2</filename>.  The second entry
+	    configures an old computer running
 	    <application>Procomm</application> terminal software
-	    emulating a VT-100 terminal.  The Wyse is connected to the
-	    second serial port and the 286 to the sixth serial port on
-	    a multiport serial card.  The corresponding entries in
-	    <filename>/etc/ttys</filename> would look like
-	    this:</para>
+	    emulating a VT-100 terminal.  The computer is connected
+	    to the sixth serial port on
+	    a multi-port serial card.</para>
+    
+	<example xml:id="ex-etc-ttys">
+	  <title>Configuring Terminal Entries</title>
 
 	  <programlisting>ttyu1<co xml:id="co-ttys-line1col1"/>  "/usr/libexec/getty std.38400"<co xml:id="co-ttys-line1col2"/>  wy50<co xml:id="co-ttys-line1col3"/>  on<co xml:id="co-ttys-line1col4"/>  insecure<co xml:id="co-ttys-line1col5"/>
 ttyu5   "/usr/libexec/getty std.19200"  vt100  on insecure</programlisting>
 
 	  <calloutlist>
 	    <callout arearefs="co-ttys-line1col1">
-	      <para>The first field normally specifies the name of
-		the terminal special file as it is found in
-		<filename>/dev</filename>.</para>
+	      <para>The first field specifies the device name of
+		the serial terminal.</para>
 	    </callout>
 
 	    <callout arearefs="co-ttys-line1col2">
-	      <para>The second field is the command to execute for
-		this line, which is usually &man.getty.8;.
-		<command>getty</command> initializes and opens the
-		line, sets the speed, prompts for a user name, and
-		then executes &man.login.1;.</para>
-
-	      <para>The <command>getty</command> program accepts one
-		(optional) parameter on its command line, the
-		<replaceable>getty</replaceable> type.  A
-		<replaceable>getty</replaceable> type configures
+	      <para>The second field tells
+		<command>getty</command> to initialize and open the
+		line, set the line speed, prompt for a user name, and
+		then execute the <command>login</command> program.  The optional
+		<firstterm>getty type</firstterm> configures
 		characteristics on the terminal line, like
-		<acronym>bps</acronym> rate and parity.
-		<command>getty</command> reads these characteristics
-		from <filename>/etc/gettytab</filename>.</para>
-
-	      <para><filename>/etc/gettytab</filename> contains many
-		entries for terminal lines, both old and new.  In
-		almost all cases, the entries that start with the
-		text <literal>std</literal> will work for hardwired
+		<acronym>bps</acronym> rate and parity.  The available
+		getty types are listed in
+		<filename>/etc/gettytab</filename>.  In
+		almost all cases, the getty types that start with
+		<literal>std</literal> will work for hardwired
 		terminals as these entries ignore parity.  There is
 		a <literal>std</literal> entry for each
-		<acronym>bps</acronym> rate from 110 to 115200.
-		&man.gettytab.5; provides more information.</para>
-
-	      <para>When setting the <replaceable>getty</replaceable>
-		type in <filename>/etc/ttys</filename>, make sure
-		that the communications settings on the terminal
-		match.</para>
+		<acronym>bps</acronym> rate from 110 to 115200.  Refer to
+		&man.gettytab.5; for more information.</para>
 
-	      <para>For this example, the Wyse-50 uses no parity and
-		connects at 38400&nbsp;bps.  The 286&nbsp;PC uses no
+	      <para>When setting the getty
+		type, make sure to match
+		the communications settings used by the terminal.  For
+		this example, the Wyse-50 uses no parity and
+		connects at 38400&nbsp;bps.  The computer uses no
 		parity and connects at 19200&nbsp;bps.</para>
 	    </callout>
 
 	    <callout arearefs="co-ttys-line1col3">
-	      <para>The third field is the type of terminal usually
-		connected to that terminal line.  For dial-up ports,
+	      <para>The third field is the type of terminal.  For dial-up ports,
 		<literal>unknown</literal> or
 		<literal>dialup</literal> is typically used since
 		users may dial up with practically any type of
 		terminal or software.  Since the terminal type does
 		not change for hardwired terminals, a real terminal
-		type from &man.termcap.5; can be used in this
-		field.</para>
-
-	      <para>For this example, the Wyse-50 uses the real
-		terminal type while the 286 PC running
-		<application>Procomm</application> will be set to
-		emulate at VT-100. </para>
+		type from <filename>/etc/termcap</filename> can be specified.
+		For this example, the Wyse-50 uses the real
+		terminal type while the computer running
+		<application>Procomm</application> is set to
+		emulate a VT-100.</para>
 	    </callout>
 
 	    <callout arearefs="co-ttys-line1col4">
 	      <para>The fourth field specifies if the port should be
-		enabled.  If set to <literal>on</literal>, the
-		<command>init</command> process will start the program
-		in the second field, <command>getty</command>.  If
-		this field is set to <literal>off</literal>, there
-		will be no <command>getty</command>, and hence no
-		logins on the port.</para>
+		enabled.  To enable logins on this port, this
+		field must be set to <literal>on</literal>.</para>
 	    </callout>
 
 	    <callout arearefs="co-ttys-line1col5">
@@ -930,27 +871,18 @@ ttyu5   "/usr/libexec/getty std.19200"  
 		port is secure.  Marking a port as
 		<literal>secure</literal> means that it is trusted
 		enough to allow <systemitem
-		  class="username">root</systemitem>, or any account
-		with a <acronym>UID</acronym> of 0, to login from that
+		  class="username">root</systemitem> to login from that
 		port.  Insecure ports do not allow <systemitem
 		  class="username">root</systemitem> logins.  On an
 		insecure port, users must login from unprivileged
-		accounts and then use &man.su.1; or a similar
-		mechanism to gain superuser privileges.</para>
-
-	      <para>It is highly recommended to use
-		<literal>insecure</literal>, even for terminals that
-		are behind locked doors.  It is quite easy to login
-		and use <command>su</command> when superuser
-		privileges are needed.</para>
+		accounts and then use <command>su</command> or a similar
+		mechanism to gain superuser privileges, as described
+		in <xref linkend="users-superuser"/>.  For security reasons,
+		it is recommended to change this setting to
+		<literal>insecure</literal>.</para>
 	    </callout>
 	  </calloutlist>
 	</example>
-      </sect3>
-
-      <sect3 xml:id="term-hup">
-	<title>Force <command>init</command> to Reread
-	  <filename>/etc/ttys</filename></title>
 
 	<para>After making any changes to
 	  <filename>/etc/ttys</filename>, send a SIGHUP (hangup)
@@ -959,18 +891,15 @@ ttyu5   "/usr/libexec/getty std.19200"  
 
 	<screen>&prompt.root; <userinput>kill -HUP 1</userinput></screen>
 
-	<note>
-	  <para><command>init</command> is always the first process
-	    run on a system, therefore it will always have a process
-	    ID of 1.</para>
-	</note>
+	  <para>Since <command>init</command> is always the first process
+	    run on a system, it always has a process
+	    <acronym>ID</acronym> of <literal>1</literal>.</para>
 
 	<para>If everything is set up correctly, all cables are in
-	  place, and the terminals are powered up, then a
-	  <command>getty</command> process should be running on each
+	  place, and the terminals are powered up, a
+	  <command>getty</command> process should now be running on each
 	  terminal and login prompts should be available on each
 	  terminal.</para>
-      </sect3>
     </sect2>
 
     <sect2 xml:id="term-debug">
@@ -996,20 +925,16 @@ ttyu5   "/usr/libexec/getty std.19200"  
 	controls are turned up.  If it is a printing terminal, make
 	sure paper and ink are in good supply.</para>
 
-      <para>Make sure that a <command>getty</command> process is
-	running and serving the terminal.  For example, to get a list
-	of running <command>getty</command> processes with
-	<command>ps</command>, type:</para>
-
-      <screen>&prompt.root; <userinput>ps -axww|grep getty</userinput></screen>
-
-      <para>There should be an entry for the terminal.  For example,
-	the following display shows that a <command>getty</command> is
+      <para>Use <command>ps</command> to make sure that a
+	<command>getty</command> process is
+	running and serving the terminal.  For example,
+	the following listing shows that a <command>getty</command> is
 	running on the second serial port, <filename>ttyu1</filename>,
 	and is using the <literal>std.38400</literal> entry in
 	<filename>/etc/gettytab</filename>:</para>
 
-      <screen>22189  d1  Is+    0:00.03 /usr/libexec/getty std.38400 ttyu1</screen>
+      <screen>&prompt.root; <userinput>ps -axww|grep ttyu</userinput>
+22189  d1  Is+    0:00.03 /usr/libexec/getty std.38400 ttyu1</screen>
 
       <para>If no <command>getty</command> process is running, make
 	sure the port is enabled in <filename>/etc/ttys</filename>.



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201405071812.s47ICMpD010440>