os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Include a new section explaining how to set up serial consoles. Rewrote

Browse source 
it slightly from the submission just to clean up some of the English,
but Kazutaka YOKOTA should get all the kudos for this.

Submitted by:   Kazutaka YOKOTA <yokota@zodiac.mech.utsunomiya-u.ac.jp>
This commit is contained in:
Nik Clayton 1999-07-27 18:18:11 +00:00
parent ace5579d11
commit 77c293076b
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=5254
3 changed files with 2187 additions and 3 deletions
en/handbook/serialcomms
chapter.sgml
en_US.ISO8859-1/books/handbook/serialcomms
chapter.sgml
en_US.ISO_8859-1/books/handbook/serialcomms
chapter.sgml

730
en/handbook/serialcomms/chapter.sgml
View file

@ -1,7 +1,7 @@
<!--
The FreeBSD Documentation Project
$Id: chapter.sgml,v 1.10 1999-03-08 22:04:49 nik Exp $
$Id: chapter.sgml,v 1.11 1999-07-27 18:18:11 nik Exp $
-->
<chapter id="serialcomms">
@ -1988,6 +1988,734 @@ raisechar=^^</programlisting>
to send them to the remote system.</para>
</sect2>
</sect1>
<sect1>
<title>Setting Up the Serial Console</title>
<para><emphasis>&a.yokota; and &a.wpaul:</emphasis></para>
<para><emphasis>The text is heavily based on
<filename>/sys/i386/boot/biosboot/README.serial</filename> written by
&a.wpaul;.</emphasis></para>
<sect2 id="serialconsole-intro">
<title>Introduction</title>
<para>The FreeBSD/i386 operating system can boot on a system with only
a dumb terminal on a serial port as a console. Such a configuration
should be useful for two classes of people; system administrators who
wish to install FreeBSD on a dedicated file/compute/terminal server
machines that have no keyboard or monitor attached, and developers who
want to debug the kernel or device drivers.</para>
<para>Starting from version 3.1, FreeBSD/i386 employs a three stage
bootstrap. The first two stages are in the boot block code which is
stored at the beginning of the FreeBSD slice on the boot disk. The
boot block will then load and run the boot loader
(<filename>/boot/loader</filename>) as the third stage code. (See
&man.boot.8; and &man.loader.8; for more details on the boot
process.)</para>
<para>In order to set up the serial console you must configure the boot
block code, the boot loader code and the kernel.</para>
<para>In FreeBSD version 3.0, the boot loader does not exist and there
are only two stages in the bootstrap; the boot blocks directly load
the kernel into memory. If you are using FreeBSD 3.0, then you should
disregard any reference to the boot loader in this section. You can
still use the serial port as a console.</para>
<para>FreeBSD versions 2.X are quite different from 3.X, in that the
serial port driver, &man.sio.4;, must be configured in a different
way. This chapter will not describe the settings for version 2.X
systems. If you are using these older versions of FreeBSD, please
consult <filename>/sys/i386/boot/biosboot/README.serial</filename>
instead.</para>
</sect2>
<sect2 id="serialconsole-howto">
<title>6 Steps to Set up the Serial Console</title>
<procedure>
<step>
<para>Prepare a serial cable.</para>
<para>You will need either a null-modem cable or a standard serial
cable and a null-modem adapter. See <xref linkend="term"> for
a discussion on serial cables.</para>
</step>
<step>
<para>Unplug your keyboard.</para>
<para>Most PC systems probe for the keyboard during the Power-On
Self-Test (POST) and will generate an error if the keyboard is not
detected. Some machines complain loudly about the lack of a
keyboard and will not continue to boot until it is plugged
in.</para>
<para>If your computer complains about the error, but boots anyway,
then you do not have to do anything special. (One machine with a
Phoneix BIOS that I have here merely says <errorname>Keyboard
failed</errorname> then continues to boot normally.)</para>
<para>If your computer refuses to boot without a keyboard attached
then you will have to configure the BIOS so that it ignores this
error (if it can). Consult your motherboard's manual for details
on how to do this.</para>
<tip>
<para>Setting the keyboard to &ldquo;Not installed&rdquo; in the
BIOS setup does <emphasis>not</emphasis> mean that you will not
be able to use your keyboard. All this does is tell the BIOS
not to probe for a keyboard at power-on so that it will not
complain if the keyboard is not plugged in. You can leave the
keyboard plugged in even with this flag set to &ldquo;Not
installed&rdquo; and the keyboard will still work.</para>
</tip>
<note>
<para>If your system has a PS/2 mouse, chances are very good that
you may have to unplug your mouse as well as your keyboard.
This is because PS/2 mice share some hardware with the keyboard,
and leaving the mouse plugged in can fool the keyboard probe
into thinking the keyboard is still there. It is said that a
Gateway 2000 Pentium 90Mhz system with an AMI BIOS that behaves
this way. In general this is not a problem since the mouse is
not much good without the keyboard anyway.</para>
</note>
</step>
<step>
<para>Plug a dumb terminal into <devicename>COM1:</devicename>
(<devicename>sio0</devicename>).</para>
<para>If you do not have a dumb terminal, you can use an old PC/XT
with a modem program, or the serial port on another UNIX box. If
you do not have a <devicename>COM1:</devicename>
(<devicename>sio0</devicename>), get one. At this time, there is
no way to select a port other than <devicename>COM1:</devicename>
for the boot blocks without recompiling the boot blocks. If you
are already using <devicename>COM1:</devicename> for another
device, you will have to temporarily remove that device and
install a new boot block and kernel once you get FreeBSD up and
running. (It is assumed that <devicename>COM1:</devicename> will
be available on a file/compute/terminal server anyway; if you
really need <devicename>COM1:</devicename> for something else
(and you can not switch that something else to
<devicename>COM2:</devicename> (<devicename>sio1</devicename>)),
then you probably should not even be bothering with all this in
the first place.)</para>
</step>
<step>
<para>Make sure the configuration file of your kernel has
appropriate flags set for <devicename>COM1:</devicename>
(<devicename>sio0</devicename>).</para>
<para>Relevant flags are:</para>
<variablelist>
<varlistentry>
<term><literal>0x10</literal></term>
<listitem>
<para>Enables console support for this unit. The other
console flags are ignored unless this is set. Currently, at
most one unit can have console support; the first one (in
config file order) with this flag set is preferred. This
option alone will not make the serial port the console. Set
the following flag or use the <option>-h</option> option
described below, together with this flag.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>0x20</literal></term>
<listitem>
<para>Forces this unit to be the console (unless there is
another higher priority console), regardless of the
<option>-h</option> option discussed below. This flag
replaces the <literal>COMCONSOLE</literal> option in FreeBSD
versions 2.X. The flag <literal>0x20</literal> must be used
together with the <option>0x10</option> flag.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>0x40</literal></term>
<listitem>
<para>Reserves this unit (in conjunction with
<literal>0x10</literal>) and makes the unit unavailable for
normal access. You should not set this flag to the serial
port unit which you want to use as the serial console. The
only use of this flag is to designate the unit for kernel
remote debugging. See <xref linkend="kerneldebug"> for more
information on remote debugging.</para>
<note>
<para>In FreeBSD 4.0-CURRENT or later the semantics of the
flag <literal>0x40</literal> are slightly different and
there is another flag to specify a serial port for remote
debugging.</para>
</note>
</listitem>
</varlistentry>
</variablelist>
<para>Example:</para>
<programlisting>
device sio0 at isa? port "IO_COM1" tty flags 0x10 irq 4</programlisting>
<para>See &man.sio.4; for more details.</para>
<para>If the flags were not set, you need to run UserConfig (on a
different console) or recompile the kernel.</para>
</step>
<step>
<para>Create <filename>boot.config</filename> in the root directory
of the <literal>a</literal> partition on the boot drive.</para>
<para>This file will instruct the boot block code how you would like
to boot the system. In order to activate the serial console, you
need one or more of the following options&mdash;if you want
multiple options, include them all on the same line:</para>
<variablelist>
<varlistentry>
<term><option>-h</option></term>
<listitem>
<para>Toggles internal and serial consoles. You can use this
to switch console devices. For instance, if you boot from
the internal (video) console, you can use
<option>-h</option> to direct the boot loader and the kernel
to use the serial port as its console device. Alternatively,
if you boot from the serial port, you can use the
<option>-h</option> to tell the boot loader and the kernel
to use the video display as the console instead.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-D</option></term>
<listitem>
<para>Toggles single and dual console configurations. In the
single configuration the console will be either the internal
console (video display) or the serial port, depending on the
state of the <option>-h</option> option above. In the dual
console configuration, both the video display and the
serial port will become the console at the same time,
regardless of the state of the <option>-h</option> option.
However, that the dual console configuration takes effect
only during the boot block is running. Once the boot loader
gets control, the console specified by the
<option>-h</option> option becomes the only console.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-P</option></term>
<listitem>
<para>Makes the boot block probe the keyboard. If no keyboard
is found, the <option>-D</option> and <option>-h</option>
options are automatically set.</para>
<note>
<para>Due to space constraints in the current version of the
boot blocks, the <option>-P</option> option is capable of
detecing extended keyboards only. Keyboards with less
than 101 keys (and without F11 and F12 keys) may not be
detected. Keyboards on some laptop computers may not be
properly found because of this limitation. If this is to
be the case with your system, you have to abondan using
the <option>-P</option> option. Unfortunately there is no
workaround for this problem.</para>
</note>
</listitem>
</varlistentry>
</variablelist>
<para>Use either the <option>-P</option> option to select the
console automatically, or the <option>-h</option> option to
activate the serial console.</para>
<para>You may include other options described in &man.boot.8; as
well.</para>
<para>The options, except for <option>-P</option>, will be passed to
the boot loader (<filename>/boot/loader</filename>). The boot
loader will determine which of the internal video or the serial
port should become the console by examining the state of the
<option>-h</option> option alone. This means that if you specify
the <option>-D</option> option but not the <option>-h</option>
option in <filename>/boot.config</filename>, you can use the
serial port as the console only during the boot block; the boot
loader will use the internal video display as the console.</para>
</step>
<step>
<para>Boot the machine.</para>
<para>When you start your FreeBSD box, the boot blocks will echo the
contents of <filename>/boot.config</filename> to the console. For
example;</para>
<screen>/boot.config: -P
Keyboard: no</screen>
<para>The second line appears only if you put <option>-P</option> in
<filename>/boot.config</filename> and indicates presense/absence
of the keyboard. These messages go to either serial or internal
console, or both, depending on the option in
<filename>/boot.config</filename>.</para>
<informaltable frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Options</entry>
<entry>Message goes to</entry>
</row>
</thead>
<tbody>
<row>
<entry>none</entry>
<entry>internal console</entry>
</row>
<row>
<entry><option>-h</option></entry>
<entry>serial console</entry>
</row>
<row>
<entry><option>-D</option></entry>
<entry>serial and internal consoles</entry>
</row>
<row>
<entry><option>-Dh</option></entry>
<entry>serial and internal consoles</entry>
</row>
<row>
<entry><option>-P</option>, keyboard present</entry>
<entry>internal console</entry>
</row>
<row>
<entry><option>-P</option>, keyboard absent</entry>
<entry>serial console</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>After the above messages, there will be a small pause before
the boot blocks continue loading the boot loader and before any
further messages printed to the console. Under normal
circumstances, you do not need to interrupt the boot blocks, but
you may want to do so in order to make sure things are set up
correctly.</para>
<para>Hit any key, other than Enter/Return, at the console to
interrupt the boot process. The boot blocks will then prompt you
for further action. You should now see something like:</para>
<screen>>> FreeBSD/i386 BOOT
Default: 0:wd(0,a)/boot/loader
boot:</screen>
<para>Verify the above message appears on either the serial or
internal console or both, according to the options you put in
<filename>/boot.config</filename>. If the message appears in the
correct console, hit Enter/Return to continue the boot
process.</para>
<para>If you want the serial console but you do not see the prompt
on the serial terminal, something is wrong with your settings. In
the meantime, you enter <option>-h</option> and hit Enter/Return
(if possible) to tell the boot block (and then the boot loader and
the kernel) to choose the serial port for the console. Once the
system is up, go back and check what went wrong.</para>
</step>
</procedure>
<para>After the boot loader is loaded and you are in the third stage of
the boot process you can still switch between the internal console and
the serial console by setting appropriate environment variables in the
boot loader. See <xref linkend="serialconsole-loader">.</para>
</sect2>
<sect2 id="serialconsole-summary">
<title>Summary</title>
<para>Here is the summary of various settings discussed in this section
and the console eventually selected.</para>
<sect3>
<title>Case 1: You set the flags to 0x10 for sio0</title>
<programlisting>device sio0 at isa? port "IO_COM1" tty flags 0x10 irq 4</programlisting>
<informaltable frame="none">
<tgroup cols="4">
<thead>
<row>
<entry>Options in /boot.config</entry>
<entry>Console during boot blocks</entry>
<entry>Console during boot loader</entry>
<entry>Console in kernel</entry>
</row>
</thead>
<tbody>
<row>
<entry>nothing</entry>
<entry>internal</entry>
<entry>internal</entry>
<entry>internal</entry>
</row>
<row>
<entry><option>-h</option></entry>
<entry>serial</entry>
<entry>serial</entry>
<entry>serial</entry>
</row>
<row>
<entry><option>-D</option></entry>
<entry>serial and internal</entry>
<entry>internal</entry>
<entry>internal</entry>
</row>
<row>
<entry><option>-Dh</option></entry>
<entry>serial and internal</entry>
<entry>serial</entry>
<entry>serial</entry>
</row>
<row>
<entry><option>-P</option>, keyboard present</entry>
<entry>internal</entry>
<entry>internal</entry>
<entry>internal</entry>
</row>
<row>
<entry><option>-P</option>, keyboard absent</entry>
<entry>serial and internal</entry>
<entry>serial</entry>
<entry>serial</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect3>
<sect3>
<title>Case 2: You set the flags to 0x30 for sio0</title>
<programlisting>device sio0 at isa? port "IO_COM1" tty flags 0x30 irq 4</programlisting>
<informaltable frame="none">
<tgroup cols="4">
<thead>
<row>
<entry>Options in /boot.config</entry>
<entry>Console during boot blocks</entry>
<entry>Console during boot loader</entry>
<entry>Console in kernel</entry>
</row>
</thead>
<tbody>
<row>
<entry>nothing</entry>
<entry>internal</entry>
<entry>internal</entry>
<entry>serial</entry>
</row>
<row>
<entry><option>-h</option></entry>
<entry>serial</entry>
<entry>serial</entry>
<entry>serial</entry>
</row>
<row>
<entry><option>-D</option></entry>
<entry>serial and internal</entry>
<entry>internal</entry>
<entry>serial</entry>
</row>
<row>
<entry><option>-Dh</option></entry>
<entry>serial and internal</entry>
<entry>serial</entry>
<entry>serial</entry>
</row>
<row>
<entry><option>-P</option>, keyboard present</entry>
<entry>internal</entry>
<entry>internal</entry>
<entry>serial</entry>
</row>
<row>
<entry><option>-P</option>, keyboard absent</entry>
<entry>serial and internal</entry>
<entry>serial</entry>
<entry>serial</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect3>
</sect2>
<sect2 id="serialconsole-tips">
<title>Tips for the Serial Console</title>
<sect3>
<title>Setting A Faster Serial Port Speed</title>
<para>By default the serial port settings are set to 9600 baud, 8
bits, no parity, 1 stop bit. If you wish to change the speed, you
need to recompile at least the boot blocks. Add the following line
to <filename>/etc/make.conf</filename> and compile new boot
blocks:</para>
<programlisting>BOOT_COMCONSOLE_SPEED=19200</programlisting>
<para>If the serial console is configured in some other way than by
booting with <option>-h</option>, or if the serial console used by
the kernel is different from the one used by the boot blocks, then
you must also add the following option to the kernel configuration
file and compile a new kernel:</para>
<programlisting>options CONSPEED=19200</programlisting>
</sect3>
<sect3 id="serialconsole-com2">
<title>Using Serial Port Other Than <devicename>sio0</devicename> For
The Console</title>
<para>Using a port other than <devicename>sio0</devicename> as the
console requires some recompiling. If you want to use another
serial port for whatever reasons, recompile the boot blocks, the
boot loader and the kernel as follows.</para>
<procedure>
<step>
<para>Get the kernel source.</para>
</step>
<step>
<para>Edit <filename>/etc/make.conf</filename> and set
<literal>BOOT_COMCONSOLE_PORT</literal> to the address of the
port you want to use (0x3F8, 0x2F8, 0x3E8 or 0x2E8). Only
<devicename>sio0</devicename> through
<devicename>sio3</devicename> (<devicename>COM1:</devicename>
through <devicename>COM4:</devicename>) can be used; multiport
serial cards will not work. No interrupt setting is
needed.</para>
</step>
<step>
<para>Create a custom kernel configuration file and add
appropriate flags for the serial port you want to use. For
example, if you want to make <devicename>sio1</devicename>
(<devicename>COM2:</devicename>) the console:</para>
<programlisting>device sio1 at isa? port "IO_COM2" tty flags 0x10 irq 3</programlisting>
<para>or</para>
<programlisting>device sio1 at isa? port "IO_COM2" tty flags 0x30 irq 3</programlisting>
<para>The console flags for the other serial ports should not be
set.</para>
</step>
<step>
<para>Recompile and install the boot blocks:</para>
<screen>&prompt.root; <userinput>cd /sys/boot/i386/boot2</userinput>
&prompt.root; <userinput>make</userinput>
&prompt.root; <userinput>make install</userinput></screen>
</step>
<step>
<para>Recompile and install the boot loader:</para>
<screen>&prompt.root; <userinput>cd /sys/boot/i386/loader</userinput>
&prompt.root; <userinput>make</userinput>
&prompt.root; <userinput>make install</userinput></screen>
</step>
<step>
<para>Rebuild and install the kernel.</para>
</step>
<step>
<para>Write the boot blocks to the boot disk with
&man.disklabel.8; and boot from the new kernel.</para>
</step>
</procedure>
</sect3>
<sect3>
<title>Entering the DDB Debugger from the Serial Line</title>
<para>If you wish to drop into the kernel debugger from the serial
console (useful for remote diagnostics, but also dangerous if you
generate a spurious BREAK on the serial port!) then you should
compile your kernel with the following options:</para>
<programlisting>options BREAK_TO_DEBUGGER
options DDB</programlisting>
</sect3>
<sect3>
<title>Getting a Login Prompt on the Serial Console</title>
<para>While this is not required, you may wish to get a
<emphasis>login</emphasis> prompt over the serial line, now that you
can see boot messages and can enter the kernel debugging session
through the serial console. Here is how to do it.</para>
<para>Open the file <filename>/etc/ttys</filename> with an editor
and locate the lines:</para>
<programlisting>ttyd0 "/usr/libexec/getty std.9600" unknown off secure
ttyd1 "/usr/libexec/getty std.9600" unknown off secure
ttyd2 "/usr/libexec/getty std.9600" unknown off secure
ttyd3 "/usr/libexec/getty std.9600" unknown off secure</programlisting>
<para><literal>ttyd0</literal> through <literal>ttyd3</literal>
corresponds to <devicename>COM1</devicename> through
<devicename>COM4</devicename>. Change <literal>off</literal> to
<literal>on</literal> for the desired port. If you have changed the
speed of the serial port, you need to change
<literal>std.9600</literal> to match the current setting, e.g.
<literal>std.19200</literal>.</para>
<para>You may also want to change the terminal type from
<literal>unknown</literal> to the actual type of your serial
terminal.</para>
<para>After editing the file, you must <command>kill -HUP 1</command>
to make this change take effect.</para>
</sect3>
</sect2>
<sect2 id="serialconsole-loader">
<title>Changing Console from the Boot Loader</title>
<para>Previous sections described how to set up the serial console by
tweaking the boot block. This section shows that you can specify the
console by entering some commands and environment variables in the
boot loader. As the boot loader is invoked as the third stage of the
boot process, after the boot block, the settings in the boot loader
will override the settings in the boot block.</para>
<sect3>
<title>Setting Up the Serial Console</title>
<para>You can easily specify the boot loader and the kernel to use the
serial console by writing just one line in
<filename>/boot/loader.rc</filename>:</para>
<programlisting>set console=comconsole</programlisting>
<para>This will take effect regardless of the settings in the boot
block discussed in the previous section.</para>
<para>You had better put the above line as the first line of
<filename>/boot/loader.rc</filename> so as to see boot messages on
the serial console as early as possible.</para>
<para>Likewise, you can specify the internal console as:</para>
<programlisting>set console=vidconsole</programlisting>
<para>If you do not set the boot loader environment variable
<envar>console</envar>, the boot loader, and subsequently the
kernel, will use whichever console indicated by the
<option>-h</option> option in the boot block.</para>
<para>In versions 3.2 or later, you may specify the console in
<filename>/boot/loader.conf.local</filename> or
<filename>/boot/loader.conf</filename>, rather than in
<filename>/boot/loader.rc</filename>. In this method your
<filename>/boot/loader.rc</filename> should look like:</para>
<programlisting>include /boot/loader.4th
start</programlisting>
<para>Then, create <filename>/boot/loader.conf.local</filename> and
put the following line there.</para>
<programlisting>console=comconsole</programlisting>
<para>or</para>
<programlisting>console=vidconsole</programlisting>
<para>See &man.loader.conf.5; for more information.</para>
<note>
<para>At the moment, the boot loader has no option equivalent to the
<option>-P</option> option in the boot block, and there is no
provision to automatically select the internal console and the
serial console based on the presense of the keyboard.</para>
</note>
</sect3>
<sect3>
<title>Using Serial Port Other than <devicename>sio0</devicename> for
the Console</title>
<para>You need to recompile the boot loader to use a serial port other
than <devicename>sio0</devicename> for the serial console. Follow the
procedure described in <xref linkend="serialconsole-com2">.</para>
</sect3>
</sect2>
<sect2 id="serialconsole-caveats">
<title>Caveats</title>
<para>The idea here is to allow people to set up dedicated servers that
require no graphics hardware or attached keyboards. Unfortunately,
while (most?) every system will let you boot without a keyboard, there
are quite a few that will not let you boot without a graphics adapter.
Machines with AMI BIOSes can be configured to boot with no graphics
adapter installed simply by changing the `graphics adapter' setting in
the CMOS configuration to `Not installed.'</para>
<para>However, many machines do not support this option and will refuse
to boot if you have no display hardware in the system. With these
machines, you'll have to leave some kind of graphics card plugged in,
(even if it's just a junky mono board) although you will not have to
attach a monitor into it. You might also try installing an AMI
BIOS.</para>
</sect2>
</sect1>
</chapter>
<!--

730
en_US.ISO8859-1/books/handbook/serialcomms/chapter.sgml
View file

@ -1,7 +1,7 @@
<!--
The FreeBSD Documentation Project
$Id: chapter.sgml,v 1.10 1999-03-08 22:04:49 nik Exp $
$Id: chapter.sgml,v 1.11 1999-07-27 18:18:11 nik Exp $
-->
<chapter id="serialcomms">
@ -1988,6 +1988,734 @@ raisechar=^^</programlisting>
to send them to the remote system.</para>
</sect2>
</sect1>
<sect1>
<title>Setting Up the Serial Console</title>
<para><emphasis>&a.yokota; and &a.wpaul:</emphasis></para>
<para><emphasis>The text is heavily based on
<filename>/sys/i386/boot/biosboot/README.serial</filename> written by
&a.wpaul;.</emphasis></para>
<sect2 id="serialconsole-intro">
<title>Introduction</title>
<para>The FreeBSD/i386 operating system can boot on a system with only
a dumb terminal on a serial port as a console. Such a configuration
should be useful for two classes of people; system administrators who
wish to install FreeBSD on a dedicated file/compute/terminal server
machines that have no keyboard or monitor attached, and developers who
want to debug the kernel or device drivers.</para>
<para>Starting from version 3.1, FreeBSD/i386 employs a three stage
bootstrap. The first two stages are in the boot block code which is
stored at the beginning of the FreeBSD slice on the boot disk. The
boot block will then load and run the boot loader
(<filename>/boot/loader</filename>) as the third stage code. (See
&man.boot.8; and &man.loader.8; for more details on the boot
process.)</para>
<para>In order to set up the serial console you must configure the boot
block code, the boot loader code and the kernel.</para>
<para>In FreeBSD version 3.0, the boot loader does not exist and there
are only two stages in the bootstrap; the boot blocks directly load
the kernel into memory. If you are using FreeBSD 3.0, then you should
disregard any reference to the boot loader in this section. You can
still use the serial port as a console.</para>
<para>FreeBSD versions 2.X are quite different from 3.X, in that the
serial port driver, &man.sio.4;, must be configured in a different
way. This chapter will not describe the settings for version 2.X
systems. If you are using these older versions of FreeBSD, please
consult <filename>/sys/i386/boot/biosboot/README.serial</filename>
instead.</para>
</sect2>
<sect2 id="serialconsole-howto">
<title>6 Steps to Set up the Serial Console</title>
<procedure>
<step>
<para>Prepare a serial cable.</para>
<para>You will need either a null-modem cable or a standard serial
cable and a null-modem adapter. See <xref linkend="term"> for
a discussion on serial cables.</para>
</step>
<step>
<para>Unplug your keyboard.</para>
<para>Most PC systems probe for the keyboard during the Power-On
Self-Test (POST) and will generate an error if the keyboard is not
detected. Some machines complain loudly about the lack of a
keyboard and will not continue to boot until it is plugged
in.</para>
<para>If your computer complains about the error, but boots anyway,
then you do not have to do anything special. (One machine with a
Phoneix BIOS that I have here merely says <errorname>Keyboard
failed</errorname> then continues to boot normally.)</para>
<para>If your computer refuses to boot without a keyboard attached
then you will have to configure the BIOS so that it ignores this
error (if it can). Consult your motherboard's manual for details
on how to do this.</para>
<tip>
<para>Setting the keyboard to &ldquo;Not installed&rdquo; in the
BIOS setup does <emphasis>not</emphasis> mean that you will not
be able to use your keyboard. All this does is tell the BIOS
not to probe for a keyboard at power-on so that it will not
complain if the keyboard is not plugged in. You can leave the
keyboard plugged in even with this flag set to &ldquo;Not
installed&rdquo; and the keyboard will still work.</para>
</tip>
<note>
<para>If your system has a PS/2 mouse, chances are very good that
you may have to unplug your mouse as well as your keyboard.
This is because PS/2 mice share some hardware with the keyboard,
and leaving the mouse plugged in can fool the keyboard probe
into thinking the keyboard is still there. It is said that a
Gateway 2000 Pentium 90Mhz system with an AMI BIOS that behaves
this way. In general this is not a problem since the mouse is
not much good without the keyboard anyway.</para>
</note>
</step>
<step>
<para>Plug a dumb terminal into <devicename>COM1:</devicename>
(<devicename>sio0</devicename>).</para>
<para>If you do not have a dumb terminal, you can use an old PC/XT
with a modem program, or the serial port on another UNIX box. If
you do not have a <devicename>COM1:</devicename>
(<devicename>sio0</devicename>), get one. At this time, there is
no way to select a port other than <devicename>COM1:</devicename>
for the boot blocks without recompiling the boot blocks. If you
are already using <devicename>COM1:</devicename> for another
device, you will have to temporarily remove that device and
install a new boot block and kernel once you get FreeBSD up and
running. (It is assumed that <devicename>COM1:</devicename> will
be available on a file/compute/terminal server anyway; if you
really need <devicename>COM1:</devicename> for something else
(and you can not switch that something else to
<devicename>COM2:</devicename> (<devicename>sio1</devicename>)),
then you probably should not even be bothering with all this in
the first place.)</para>
</step>
<step>
<para>Make sure the configuration file of your kernel has
appropriate flags set for <devicename>COM1:</devicename>
(<devicename>sio0</devicename>).</para>
<para>Relevant flags are:</para>
<variablelist>
<varlistentry>
<term><literal>0x10</literal></term>
<listitem>
<para>Enables console support for this unit. The other
console flags are ignored unless this is set. Currently, at
most one unit can have console support; the first one (in
config file order) with this flag set is preferred. This
option alone will not make the serial port the console. Set
the following flag or use the <option>-h</option> option
described below, together with this flag.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>0x20</literal></term>
<listitem>
<para>Forces this unit to be the console (unless there is
another higher priority console), regardless of the
<option>-h</option> option discussed below. This flag
replaces the <literal>COMCONSOLE</literal> option in FreeBSD
versions 2.X. The flag <literal>0x20</literal> must be used
together with the <option>0x10</option> flag.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>0x40</literal></term>
<listitem>
<para>Reserves this unit (in conjunction with
<literal>0x10</literal>) and makes the unit unavailable for
normal access. You should not set this flag to the serial
port unit which you want to use as the serial console. The
only use of this flag is to designate the unit for kernel
remote debugging. See <xref linkend="kerneldebug"> for more
information on remote debugging.</para>
<note>
<para>In FreeBSD 4.0-CURRENT or later the semantics of the
flag <literal>0x40</literal> are slightly different and
there is another flag to specify a serial port for remote
debugging.</para>
</note>
</listitem>
</varlistentry>
</variablelist>
<para>Example:</para>
<programlisting>
device sio0 at isa? port "IO_COM1" tty flags 0x10 irq 4</programlisting>
<para>See &man.sio.4; for more details.</para>
<para>If the flags were not set, you need to run UserConfig (on a
different console) or recompile the kernel.</para>
</step>
<step>
<para>Create <filename>boot.config</filename> in the root directory
of the <literal>a</literal> partition on the boot drive.</para>
<para>This file will instruct the boot block code how you would like
to boot the system. In order to activate the serial console, you
need one or more of the following options&mdash;if you want
multiple options, include them all on the same line:</para>
<variablelist>
<varlistentry>
<term><option>-h</option></term>
<listitem>
<para>Toggles internal and serial consoles. You can use this
to switch console devices. For instance, if you boot from
the internal (video) console, you can use
<option>-h</option> to direct the boot loader and the kernel
to use the serial port as its console device. Alternatively,
if you boot from the serial port, you can use the
<option>-h</option> to tell the boot loader and the kernel
to use the video display as the console instead.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-D</option></term>
<listitem>
<para>Toggles single and dual console configurations. In the
single configuration the console will be either the internal
console (video display) or the serial port, depending on the
state of the <option>-h</option> option above. In the dual
console configuration, both the video display and the
serial port will become the console at the same time,
regardless of the state of the <option>-h</option> option.
However, that the dual console configuration takes effect
only during the boot block is running. Once the boot loader
gets control, the console specified by the
<option>-h</option> option becomes the only console.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-P</option></term>
<listitem>
<para>Makes the boot block probe the keyboard. If no keyboard
is found, the <option>-D</option> and <option>-h</option>
options are automatically set.</para>
<note>
<para>Due to space constraints in the current version of the
boot blocks, the <option>-P</option> option is capable of
detecing extended keyboards only. Keyboards with less
than 101 keys (and without F11 and F12 keys) may not be
detected. Keyboards on some laptop computers may not be
properly found because of this limitation. If this is to
be the case with your system, you have to abondan using
the <option>-P</option> option. Unfortunately there is no
workaround for this problem.</para>
</note>
</listitem>
</varlistentry>
</variablelist>
<para>Use either the <option>-P</option> option to select the
console automatically, or the <option>-h</option> option to
activate the serial console.</para>
<para>You may include other options described in &man.boot.8; as
well.</para>
<para>The options, except for <option>-P</option>, will be passed to
the boot loader (<filename>/boot/loader</filename>). The boot
loader will determine which of the internal video or the serial
port should become the console by examining the state of the
<option>-h</option> option alone. This means that if you specify
the <option>-D</option> option but not the <option>-h</option>
option in <filename>/boot.config</filename>, you can use the
serial port as the console only during the boot block; the boot
loader will use the internal video display as the console.</para>
</step>
<step>
<para>Boot the machine.</para>
<para>When you start your FreeBSD box, the boot blocks will echo the
contents of <filename>/boot.config</filename> to the console. For
example;</para>
<screen>/boot.config: -P
Keyboard: no</screen>
<para>The second line appears only if you put <option>-P</option> in
<filename>/boot.config</filename> and indicates presense/absence
of the keyboard. These messages go to either serial or internal
console, or both, depending on the option in
<filename>/boot.config</filename>.</para>
<informaltable frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Options</entry>
<entry>Message goes to</entry>
</row>
</thead>
<tbody>
<row>
<entry>none</entry>
<entry>internal console</entry>
</row>
<row>
<entry><option>-h</option></entry>
<entry>serial console</entry>
</row>
<row>
<entry><option>-D</option></entry>
<entry>serial and internal consoles</entry>
</row>
<row>
<entry><option>-Dh</option></entry>
<entry>serial and internal consoles</entry>
</row>
<row>
<entry><option>-P</option>, keyboard present</entry>
<entry>internal console</entry>
</row>
<row>
<entry><option>-P</option>, keyboard absent</entry>
<entry>serial console</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>After the above messages, there will be a small pause before
the boot blocks continue loading the boot loader and before any
further messages printed to the console. Under normal
circumstances, you do not need to interrupt the boot blocks, but
you may want to do so in order to make sure things are set up
correctly.</para>
<para>Hit any key, other than Enter/Return, at the console to
interrupt the boot process. The boot blocks will then prompt you
for further action. You should now see something like:</para>
<screen>>> FreeBSD/i386 BOOT
Default: 0:wd(0,a)/boot/loader
boot:</screen>
<para>Verify the above message appears on either the serial or
internal console or both, according to the options you put in
<filename>/boot.config</filename>. If the message appears in the
correct console, hit Enter/Return to continue the boot
process.</para>
<para>If you want the serial console but you do not see the prompt
on the serial terminal, something is wrong with your settings. In
the meantime, you enter <option>-h</option> and hit Enter/Return
(if possible) to tell the boot block (and then the boot loader and
the kernel) to choose the serial port for the console. Once the
system is up, go back and check what went wrong.</para>
</step>
</procedure>
<para>After the boot loader is loaded and you are in the third stage of
the boot process you can still switch between the internal console and
the serial console by setting appropriate environment variables in the
boot loader. See <xref linkend="serialconsole-loader">.</para>
</sect2>
<sect2 id="serialconsole-summary">
<title>Summary</title>
<para>Here is the summary of various settings discussed in this section
and the console eventually selected.</para>
<sect3>
<title>Case 1: You set the flags to 0x10 for sio0</title>
<programlisting>device sio0 at isa? port "IO_COM1" tty flags 0x10 irq 4</programlisting>
<informaltable frame="none">
<tgroup cols="4">
<thead>
<row>
<entry>Options in /boot.config</entry>
<entry>Console during boot blocks</entry>
<entry>Console during boot loader</entry>
<entry>Console in kernel</entry>
</row>
</thead>
<tbody>
<row>
<entry>nothing</entry>
<entry>internal</entry>
<entry>internal</entry>
<entry>internal</entry>
</row>
<row>
<entry><option>-h</option></entry>
<entry>serial</entry>
<entry>serial</entry>
<entry>serial</entry>
</row>
<row>
<entry><option>-D</option></entry>
<entry>serial and internal</entry>
<entry>internal</entry>
<entry>internal</entry>
</row>
<row>
<entry><option>-Dh</option></entry>
<entry>serial and internal</entry>
<entry>serial</entry>
<entry>serial</entry>
</row>
<row>
<entry><option>-P</option>, keyboard present</entry>
<entry>internal</entry>
<entry>internal</entry>
<entry>internal</entry>
</row>
<row>
<entry><option>-P</option>, keyboard absent</entry>
<entry>serial and internal</entry>
<entry>serial</entry>
<entry>serial</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect3>
<sect3>
<title>Case 2: You set the flags to 0x30 for sio0</title>
<programlisting>device sio0 at isa? port "IO_COM1" tty flags 0x30 irq 4</programlisting>
<informaltable frame="none">
<tgroup cols="4">
<thead>
<row>
<entry>Options in /boot.config</entry>
<entry>Console during boot blocks</entry>
<entry>Console during boot loader</entry>
<entry>Console in kernel</entry>
</row>
</thead>
<tbody>
<row>
<entry>nothing</entry>
<entry>internal</entry>
<entry>internal</entry>
<entry>serial</entry>
</row>
<row>
<entry><option>-h</option></entry>
<entry>serial</entry>
<entry>serial</entry>
<entry>serial</entry>
</row>
<row>
<entry><option>-D</option></entry>
<entry>serial and internal</entry>
<entry>internal</entry>
<entry>serial</entry>
</row>
<row>
<entry><option>-Dh</option></entry>
<entry>serial and internal</entry>
<entry>serial</entry>
<entry>serial</entry>
</row>
<row>
<entry><option>-P</option>, keyboard present</entry>
<entry>internal</entry>
<entry>internal</entry>
<entry>serial</entry>
</row>
<row>
<entry><option>-P</option>, keyboard absent</entry>
<entry>serial and internal</entry>
<entry>serial</entry>
<entry>serial</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect3>
</sect2>
<sect2 id="serialconsole-tips">
<title>Tips for the Serial Console</title>
<sect3>
<title>Setting A Faster Serial Port Speed</title>
<para>By default the serial port settings are set to 9600 baud, 8
bits, no parity, 1 stop bit. If you wish to change the speed, you
need to recompile at least the boot blocks. Add the following line
to <filename>/etc/make.conf</filename> and compile new boot
blocks:</para>
<programlisting>BOOT_COMCONSOLE_SPEED=19200</programlisting>
<para>If the serial console is configured in some other way than by
booting with <option>-h</option>, or if the serial console used by
the kernel is different from the one used by the boot blocks, then
you must also add the following option to the kernel configuration
file and compile a new kernel:</para>
<programlisting>options CONSPEED=19200</programlisting>
</sect3>
<sect3 id="serialconsole-com2">
<title>Using Serial Port Other Than <devicename>sio0</devicename> For
The Console</title>
<para>Using a port other than <devicename>sio0</devicename> as the
console requires some recompiling. If you want to use another
serial port for whatever reasons, recompile the boot blocks, the
boot loader and the kernel as follows.</para>
<procedure>
<step>
<para>Get the kernel source.</para>
</step>
<step>
<para>Edit <filename>/etc/make.conf</filename> and set
<literal>BOOT_COMCONSOLE_PORT</literal> to the address of the
port you want to use (0x3F8, 0x2F8, 0x3E8 or 0x2E8). Only
<devicename>sio0</devicename> through
<devicename>sio3</devicename> (<devicename>COM1:</devicename>
through <devicename>COM4:</devicename>) can be used; multiport
serial cards will not work. No interrupt setting is
needed.</para>
</step>
<step>
<para>Create a custom kernel configuration file and add
appropriate flags for the serial port you want to use. For
example, if you want to make <devicename>sio1</devicename>
(<devicename>COM2:</devicename>) the console:</para>
<programlisting>device sio1 at isa? port "IO_COM2" tty flags 0x10 irq 3</programlisting>
<para>or</para>
<programlisting>device sio1 at isa? port "IO_COM2" tty flags 0x30 irq 3</programlisting>
<para>The console flags for the other serial ports should not be
set.</para>
</step>
<step>
<para>Recompile and install the boot blocks:</para>
<screen>&prompt.root; <userinput>cd /sys/boot/i386/boot2</userinput>
&prompt.root; <userinput>make</userinput>
&prompt.root; <userinput>make install</userinput></screen>
</step>
<step>
<para>Recompile and install the boot loader:</para>
<screen>&prompt.root; <userinput>cd /sys/boot/i386/loader</userinput>
&prompt.root; <userinput>make</userinput>
&prompt.root; <userinput>make install</userinput></screen>
</step>
<step>
<para>Rebuild and install the kernel.</para>
</step>
<step>
<para>Write the boot blocks to the boot disk with
&man.disklabel.8; and boot from the new kernel.</para>
</step>
</procedure>
</sect3>
<sect3>
<title>Entering the DDB Debugger from the Serial Line</title>
<para>If you wish to drop into the kernel debugger from the serial
console (useful for remote diagnostics, but also dangerous if you
generate a spurious BREAK on the serial port!) then you should
compile your kernel with the following options:</para>
<programlisting>options BREAK_TO_DEBUGGER
options DDB</programlisting>
</sect3>
<sect3>
<title>Getting a Login Prompt on the Serial Console</title>
<para>While this is not required, you may wish to get a
<emphasis>login</emphasis> prompt over the serial line, now that you
can see boot messages and can enter the kernel debugging session
through the serial console. Here is how to do it.</para>
<para>Open the file <filename>/etc/ttys</filename> with an editor
and locate the lines:</para>
<programlisting>ttyd0 "/usr/libexec/getty std.9600" unknown off secure
ttyd1 "/usr/libexec/getty std.9600" unknown off secure
ttyd2 "/usr/libexec/getty std.9600" unknown off secure
ttyd3 "/usr/libexec/getty std.9600" unknown off secure</programlisting>
<para><literal>ttyd0</literal> through <literal>ttyd3</literal>
corresponds to <devicename>COM1</devicename> through
<devicename>COM4</devicename>. Change <literal>off</literal> to
<literal>on</literal> for the desired port. If you have changed the
speed of the serial port, you need to change
<literal>std.9600</literal> to match the current setting, e.g.
<literal>std.19200</literal>.</para>
<para>You may also want to change the terminal type from
<literal>unknown</literal> to the actual type of your serial
terminal.</para>
<para>After editing the file, you must <command>kill -HUP 1</command>
to make this change take effect.</para>
</sect3>
</sect2>
<sect2 id="serialconsole-loader">
<title>Changing Console from the Boot Loader</title>
<para>Previous sections described how to set up the serial console by
tweaking the boot block. This section shows that you can specify the
console by entering some commands and environment variables in the
boot loader. As the boot loader is invoked as the third stage of the
boot process, after the boot block, the settings in the boot loader
will override the settings in the boot block.</para>
<sect3>
<title>Setting Up the Serial Console</title>
<para>You can easily specify the boot loader and the kernel to use the
serial console by writing just one line in
<filename>/boot/loader.rc</filename>:</para>
<programlisting>set console=comconsole</programlisting>
<para>This will take effect regardless of the settings in the boot
block discussed in the previous section.</para>
<para>You had better put the above line as the first line of
<filename>/boot/loader.rc</filename> so as to see boot messages on
the serial console as early as possible.</para>
<para>Likewise, you can specify the internal console as:</para>
<programlisting>set console=vidconsole</programlisting>
<para>If you do not set the boot loader environment variable
<envar>console</envar>, the boot loader, and subsequently the
kernel, will use whichever console indicated by the
<option>-h</option> option in the boot block.</para>
<para>In versions 3.2 or later, you may specify the console in
<filename>/boot/loader.conf.local</filename> or
<filename>/boot/loader.conf</filename>, rather than in
<filename>/boot/loader.rc</filename>. In this method your
<filename>/boot/loader.rc</filename> should look like:</para>
<programlisting>include /boot/loader.4th
start</programlisting>
<para>Then, create <filename>/boot/loader.conf.local</filename> and
put the following line there.</para>
<programlisting>console=comconsole</programlisting>
<para>or</para>
<programlisting>console=vidconsole</programlisting>
<para>See &man.loader.conf.5; for more information.</para>
<note>
<para>At the moment, the boot loader has no option equivalent to the
<option>-P</option> option in the boot block, and there is no
provision to automatically select the internal console and the
serial console based on the presense of the keyboard.</para>
</note>
</sect3>
<sect3>
<title>Using Serial Port Other than <devicename>sio0</devicename> for
the Console</title>
<para>You need to recompile the boot loader to use a serial port other
than <devicename>sio0</devicename> for the serial console. Follow the
procedure described in <xref linkend="serialconsole-com2">.</para>
</sect3>
</sect2>
<sect2 id="serialconsole-caveats">
<title>Caveats</title>
<para>The idea here is to allow people to set up dedicated servers that
require no graphics hardware or attached keyboards. Unfortunately,
while (most?) every system will let you boot without a keyboard, there
are quite a few that will not let you boot without a graphics adapter.
Machines with AMI BIOSes can be configured to boot with no graphics
adapter installed simply by changing the `graphics adapter' setting in
the CMOS configuration to `Not installed.'</para>
<para>However, many machines do not support this option and will refuse
to boot if you have no display hardware in the system. With these
machines, you'll have to leave some kind of graphics card plugged in,
(even if it's just a junky mono board) although you will not have to
attach a monitor into it. You might also try installing an AMI
BIOS.</para>
</sect2>
</sect1>
</chapter>
<!--

730
en_US.ISO_8859-1/books/handbook/serialcomms/chapter.sgml
View file

@ -1,7 +1,7 @@
<!--
The FreeBSD Documentation Project
$Id: chapter.sgml,v 1.10 1999-03-08 22:04:49 nik Exp $
$Id: chapter.sgml,v 1.11 1999-07-27 18:18:11 nik Exp $
-->
<chapter id="serialcomms">
@ -1988,6 +1988,734 @@ raisechar=^^</programlisting>
to send them to the remote system.</para>
</sect2>
</sect1>
<sect1>
<title>Setting Up the Serial Console</title>
<para><emphasis>&a.yokota; and &a.wpaul:</emphasis></para>
<para><emphasis>The text is heavily based on
<filename>/sys/i386/boot/biosboot/README.serial</filename> written by
&a.wpaul;.</emphasis></para>
<sect2 id="serialconsole-intro">
<title>Introduction</title>
<para>The FreeBSD/i386 operating system can boot on a system with only
a dumb terminal on a serial port as a console. Such a configuration
should be useful for two classes of people; system administrators who
wish to install FreeBSD on a dedicated file/compute/terminal server
machines that have no keyboard or monitor attached, and developers who
want to debug the kernel or device drivers.</para>
<para>Starting from version 3.1, FreeBSD/i386 employs a three stage
bootstrap. The first two stages are in the boot block code which is
stored at the beginning of the FreeBSD slice on the boot disk. The
boot block will then load and run the boot loader
(<filename>/boot/loader</filename>) as the third stage code. (See
&man.boot.8; and &man.loader.8; for more details on the boot
process.)</para>
<para>In order to set up the serial console you must configure the boot
block code, the boot loader code and the kernel.</para>
<para>In FreeBSD version 3.0, the boot loader does not exist and there
are only two stages in the bootstrap; the boot blocks directly load
the kernel into memory. If you are using FreeBSD 3.0, then you should
disregard any reference to the boot loader in this section. You can
still use the serial port as a console.</para>
<para>FreeBSD versions 2.X are quite different from 3.X, in that the
serial port driver, &man.sio.4;, must be configured in a different
way. This chapter will not describe the settings for version 2.X
systems. If you are using these older versions of FreeBSD, please
consult <filename>/sys/i386/boot/biosboot/README.serial</filename>
instead.</para>
</sect2>
<sect2 id="serialconsole-howto">
<title>6 Steps to Set up the Serial Console</title>
<procedure>
<step>
<para>Prepare a serial cable.</para>
<para>You will need either a null-modem cable or a standard serial
cable and a null-modem adapter. See <xref linkend="term"> for
a discussion on serial cables.</para>
</step>
<step>
<para>Unplug your keyboard.</para>
<para>Most PC systems probe for the keyboard during the Power-On
Self-Test (POST) and will generate an error if the keyboard is not
detected. Some machines complain loudly about the lack of a
keyboard and will not continue to boot until it is plugged
in.</para>
<para>If your computer complains about the error, but boots anyway,
then you do not have to do anything special. (One machine with a
Phoneix BIOS that I have here merely says <errorname>Keyboard
failed</errorname> then continues to boot normally.)</para>
<para>If your computer refuses to boot without a keyboard attached
then you will have to configure the BIOS so that it ignores this
error (if it can). Consult your motherboard's manual for details
on how to do this.</para>
<tip>
<para>Setting the keyboard to &ldquo;Not installed&rdquo; in the
BIOS setup does <emphasis>not</emphasis> mean that you will not
be able to use your keyboard. All this does is tell the BIOS
not to probe for a keyboard at power-on so that it will not
complain if the keyboard is not plugged in. You can leave the
keyboard plugged in even with this flag set to &ldquo;Not
installed&rdquo; and the keyboard will still work.</para>
</tip>
<note>
<para>If your system has a PS/2 mouse, chances are very good that
you may have to unplug your mouse as well as your keyboard.
This is because PS/2 mice share some hardware with the keyboard,
and leaving the mouse plugged in can fool the keyboard probe
into thinking the keyboard is still there. It is said that a
Gateway 2000 Pentium 90Mhz system with an AMI BIOS that behaves
this way. In general this is not a problem since the mouse is
not much good without the keyboard anyway.</para>
</note>
</step>
<step>
<para>Plug a dumb terminal into <devicename>COM1:</devicename>
(<devicename>sio0</devicename>).</para>
<para>If you do not have a dumb terminal, you can use an old PC/XT
with a modem program, or the serial port on another UNIX box. If
you do not have a <devicename>COM1:</devicename>
(<devicename>sio0</devicename>), get one. At this time, there is
no way to select a port other than <devicename>COM1:</devicename>
for the boot blocks without recompiling the boot blocks. If you
are already using <devicename>COM1:</devicename> for another
device, you will have to temporarily remove that device and
install a new boot block and kernel once you get FreeBSD up and
running. (It is assumed that <devicename>COM1:</devicename> will
be available on a file/compute/terminal server anyway; if you
really need <devicename>COM1:</devicename> for something else
(and you can not switch that something else to
<devicename>COM2:</devicename> (<devicename>sio1</devicename>)),
then you probably should not even be bothering with all this in
the first place.)</para>
</step>
<step>
<para>Make sure the configuration file of your kernel has
appropriate flags set for <devicename>COM1:</devicename>
(<devicename>sio0</devicename>).</para>
<para>Relevant flags are:</para>
<variablelist>
<varlistentry>
<term><literal>0x10</literal></term>
<listitem>
<para>Enables console support for this unit. The other
console flags are ignored unless this is set. Currently, at
most one unit can have console support; the first one (in
config file order) with this flag set is preferred. This
option alone will not make the serial port the console. Set
the following flag or use the <option>-h</option> option
described below, together with this flag.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>0x20</literal></term>
<listitem>
<para>Forces this unit to be the console (unless there is
another higher priority console), regardless of the
<option>-h</option> option discussed below. This flag
replaces the <literal>COMCONSOLE</literal> option in FreeBSD
versions 2.X. The flag <literal>0x20</literal> must be used
together with the <option>0x10</option> flag.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>0x40</literal></term>
<listitem>
<para>Reserves this unit (in conjunction with
<literal>0x10</literal>) and makes the unit unavailable for
normal access. You should not set this flag to the serial
port unit which you want to use as the serial console. The
only use of this flag is to designate the unit for kernel
remote debugging. See <xref linkend="kerneldebug"> for more
information on remote debugging.</para>
<note>
<para>In FreeBSD 4.0-CURRENT or later the semantics of the
flag <literal>0x40</literal> are slightly different and
there is another flag to specify a serial port for remote
debugging.</para>
</note>
</listitem>
</varlistentry>
</variablelist>
<para>Example:</para>
<programlisting>
device sio0 at isa? port "IO_COM1" tty flags 0x10 irq 4</programlisting>
<para>See &man.sio.4; for more details.</para>
<para>If the flags were not set, you need to run UserConfig (on a
different console) or recompile the kernel.</para>
</step>
<step>
<para>Create <filename>boot.config</filename> in the root directory
of the <literal>a</literal> partition on the boot drive.</para>
<para>This file will instruct the boot block code how you would like
to boot the system. In order to activate the serial console, you
need one or more of the following options&mdash;if you want
multiple options, include them all on the same line:</para>
<variablelist>
<varlistentry>
<term><option>-h</option></term>
<listitem>
<para>Toggles internal and serial consoles. You can use this
to switch console devices. For instance, if you boot from
the internal (video) console, you can use
<option>-h</option> to direct the boot loader and the kernel
to use the serial port as its console device. Alternatively,
if you boot from the serial port, you can use the
<option>-h</option> to tell the boot loader and the kernel
to use the video display as the console instead.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-D</option></term>
<listitem>
<para>Toggles single and dual console configurations. In the
single configuration the console will be either the internal
console (video display) or the serial port, depending on the
state of the <option>-h</option> option above. In the dual
console configuration, both the video display and the
serial port will become the console at the same time,
regardless of the state of the <option>-h</option> option.
However, that the dual console configuration takes effect
only during the boot block is running. Once the boot loader
gets control, the console specified by the
<option>-h</option> option becomes the only console.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-P</option></term>
<listitem>
<para>Makes the boot block probe the keyboard. If no keyboard
is found, the <option>-D</option> and <option>-h</option>
options are automatically set.</para>
<note>
<para>Due to space constraints in the current version of the
boot blocks, the <option>-P</option> option is capable of
detecing extended keyboards only. Keyboards with less
than 101 keys (and without F11 and F12 keys) may not be
detected. Keyboards on some laptop computers may not be
properly found because of this limitation. If this is to
be the case with your system, you have to abondan using
the <option>-P</option> option. Unfortunately there is no
workaround for this problem.</para>
</note>
</listitem>
</varlistentry>
</variablelist>
<para>Use either the <option>-P</option> option to select the
console automatically, or the <option>-h</option> option to
activate the serial console.</para>
<para>You may include other options described in &man.boot.8; as
well.</para>
<para>The options, except for <option>-P</option>, will be passed to
the boot loader (<filename>/boot/loader</filename>). The boot
loader will determine which of the internal video or the serial
port should become the console by examining the state of the
<option>-h</option> option alone. This means that if you specify
the <option>-D</option> option but not the <option>-h</option>
option in <filename>/boot.config</filename>, you can use the
serial port as the console only during the boot block; the boot
loader will use the internal video display as the console.</para>
</step>
<step>
<para>Boot the machine.</para>
<para>When you start your FreeBSD box, the boot blocks will echo the
contents of <filename>/boot.config</filename> to the console. For
example;</para>
<screen>/boot.config: -P
Keyboard: no</screen>
<para>The second line appears only if you put <option>-P</option> in
<filename>/boot.config</filename> and indicates presense/absence
of the keyboard. These messages go to either serial or internal
console, or both, depending on the option in
<filename>/boot.config</filename>.</para>
<informaltable frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Options</entry>
<entry>Message goes to</entry>
</row>
</thead>
<tbody>
<row>
<entry>none</entry>
<entry>internal console</entry>
</row>
<row>
<entry><option>-h</option></entry>
<entry>serial console</entry>
</row>
<row>
<entry><option>-D</option></entry>
<entry>serial and internal consoles</entry>
</row>
<row>
<entry><option>-Dh</option></entry>
<entry>serial and internal consoles</entry>
</row>
<row>
<entry><option>-P</option>, keyboard present</entry>
<entry>internal console</entry>
</row>
<row>
<entry><option>-P</option>, keyboard absent</entry>
<entry>serial console</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>After the above messages, there will be a small pause before
the boot blocks continue loading the boot loader and before any
further messages printed to the console. Under normal
circumstances, you do not need to interrupt the boot blocks, but
you may want to do so in order to make sure things are set up
correctly.</para>
<para>Hit any key, other than Enter/Return, at the console to
interrupt the boot process. The boot blocks will then prompt you
for further action. You should now see something like:</para>
<screen>>> FreeBSD/i386 BOOT
Default: 0:wd(0,a)/boot/loader
boot:</screen>
<para>Verify the above message appears on either the serial or
internal console or both, according to the options you put in
<filename>/boot.config</filename>. If the message appears in the
correct console, hit Enter/Return to continue the boot
process.</para>
<para>If you want the serial console but you do not see the prompt
on the serial terminal, something is wrong with your settings. In
the meantime, you enter <option>-h</option> and hit Enter/Return
(if possible) to tell the boot block (and then the boot loader and
the kernel) to choose the serial port for the console. Once the
system is up, go back and check what went wrong.</para>
</step>
</procedure>
<para>After the boot loader is loaded and you are in the third stage of
the boot process you can still switch between the internal console and
the serial console by setting appropriate environment variables in the
boot loader. See <xref linkend="serialconsole-loader">.</para>
</sect2>
<sect2 id="serialconsole-summary">
<title>Summary</title>
<para>Here is the summary of various settings discussed in this section
and the console eventually selected.</para>
<sect3>
<title>Case 1: You set the flags to 0x10 for sio0</title>
<programlisting>device sio0 at isa? port "IO_COM1" tty flags 0x10 irq 4</programlisting>
<informaltable frame="none">
<tgroup cols="4">
<thead>
<row>
<entry>Options in /boot.config</entry>
<entry>Console during boot blocks</entry>
<entry>Console during boot loader</entry>
<entry>Console in kernel</entry>
</row>
</thead>
<tbody>
<row>
<entry>nothing</entry>
<entry>internal</entry>
<entry>internal</entry>
<entry>internal</entry>
</row>
<row>
<entry><option>-h</option></entry>
<entry>serial</entry>
<entry>serial</entry>
<entry>serial</entry>
</row>
<row>
<entry><option>-D</option></entry>
<entry>serial and internal</entry>
<entry>internal</entry>
<entry>internal</entry>
</row>
<row>
<entry><option>-Dh</option></entry>
<entry>serial and internal</entry>
<entry>serial</entry>
<entry>serial</entry>
</row>
<row>
<entry><option>-P</option>, keyboard present</entry>
<entry>internal</entry>
<entry>internal</entry>
<entry>internal</entry>
</row>
<row>
<entry><option>-P</option>, keyboard absent</entry>
<entry>serial and internal</entry>
<entry>serial</entry>
<entry>serial</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect3>
<sect3>
<title>Case 2: You set the flags to 0x30 for sio0</title>
<programlisting>device sio0 at isa? port "IO_COM1" tty flags 0x30 irq 4</programlisting>
<informaltable frame="none">
<tgroup cols="4">
<thead>
<row>
<entry>Options in /boot.config</entry>
<entry>Console during boot blocks</entry>
<entry>Console during boot loader</entry>
<entry>Console in kernel</entry>
</row>
</thead>
<tbody>
<row>
<entry>nothing</entry>
<entry>internal</entry>
<entry>internal</entry>
<entry>serial</entry>
</row>
<row>
<entry><option>-h</option></entry>
<entry>serial</entry>
<entry>serial</entry>
<entry>serial</entry>
</row>
<row>
<entry><option>-D</option></entry>
<entry>serial and internal</entry>
<entry>internal</entry>
<entry>serial</entry>
</row>
<row>
<entry><option>-Dh</option></entry>
<entry>serial and internal</entry>
<entry>serial</entry>
<entry>serial</entry>
</row>
<row>
<entry><option>-P</option>, keyboard present</entry>
<entry>internal</entry>
<entry>internal</entry>
<entry>serial</entry>
</row>
<row>
<entry><option>-P</option>, keyboard absent</entry>
<entry>serial and internal</entry>
<entry>serial</entry>
<entry>serial</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect3>
</sect2>
<sect2 id="serialconsole-tips">
<title>Tips for the Serial Console</title>
<sect3>
<title>Setting A Faster Serial Port Speed</title>
<para>By default the serial port settings are set to 9600 baud, 8
bits, no parity, 1 stop bit. If you wish to change the speed, you
need to recompile at least the boot blocks. Add the following line
to <filename>/etc/make.conf</filename> and compile new boot
blocks:</para>
<programlisting>BOOT_COMCONSOLE_SPEED=19200</programlisting>
<para>If the serial console is configured in some other way than by
booting with <option>-h</option>, or if the serial console used by
the kernel is different from the one used by the boot blocks, then
you must also add the following option to the kernel configuration
file and compile a new kernel:</para>
<programlisting>options CONSPEED=19200</programlisting>
</sect3>
<sect3 id="serialconsole-com2">
<title>Using Serial Port Other Than <devicename>sio0</devicename> For
The Console</title>
<para>Using a port other than <devicename>sio0</devicename> as the
console requires some recompiling. If you want to use another
serial port for whatever reasons, recompile the boot blocks, the
boot loader and the kernel as follows.</para>
<procedure>
<step>
<para>Get the kernel source.</para>
</step>
<step>
<para>Edit <filename>/etc/make.conf</filename> and set
<literal>BOOT_COMCONSOLE_PORT</literal> to the address of the
port you want to use (0x3F8, 0x2F8, 0x3E8 or 0x2E8). Only
<devicename>sio0</devicename> through
<devicename>sio3</devicename> (<devicename>COM1:</devicename>
through <devicename>COM4:</devicename>) can be used; multiport
serial cards will not work. No interrupt setting is
needed.</para>
</step>
<step>
<para>Create a custom kernel configuration file and add
appropriate flags for the serial port you want to use. For
example, if you want to make <devicename>sio1</devicename>
(<devicename>COM2:</devicename>) the console:</para>
<programlisting>device sio1 at isa? port "IO_COM2" tty flags 0x10 irq 3</programlisting>
<para>or</para>
<programlisting>device sio1 at isa? port "IO_COM2" tty flags 0x30 irq 3</programlisting>
<para>The console flags for the other serial ports should not be
set.</para>
</step>
<step>
<para>Recompile and install the boot blocks:</para>
<screen>&prompt.root; <userinput>cd /sys/boot/i386/boot2</userinput>
&prompt.root; <userinput>make</userinput>
&prompt.root; <userinput>make install</userinput></screen>
</step>
<step>
<para>Recompile and install the boot loader:</para>
<screen>&prompt.root; <userinput>cd /sys/boot/i386/loader</userinput>
&prompt.root; <userinput>make</userinput>
&prompt.root; <userinput>make install</userinput></screen>
</step>
<step>
<para>Rebuild and install the kernel.</para>
</step>
<step>
<para>Write the boot blocks to the boot disk with
&man.disklabel.8; and boot from the new kernel.</para>
</step>
</procedure>
</sect3>
<sect3>
<title>Entering the DDB Debugger from the Serial Line</title>
<para>If you wish to drop into the kernel debugger from the serial
console (useful for remote diagnostics, but also dangerous if you
generate a spurious BREAK on the serial port!) then you should
compile your kernel with the following options:</para>
<programlisting>options BREAK_TO_DEBUGGER
options DDB</programlisting>
</sect3>
<sect3>
<title>Getting a Login Prompt on the Serial Console</title>
<para>While this is not required, you may wish to get a
<emphasis>login</emphasis> prompt over the serial line, now that you
can see boot messages and can enter the kernel debugging session
through the serial console. Here is how to do it.</para>
<para>Open the file <filename>/etc/ttys</filename> with an editor
and locate the lines:</para>
<programlisting>ttyd0 "/usr/libexec/getty std.9600" unknown off secure
ttyd1 "/usr/libexec/getty std.9600" unknown off secure
ttyd2 "/usr/libexec/getty std.9600" unknown off secure
ttyd3 "/usr/libexec/getty std.9600" unknown off secure</programlisting>
<para><literal>ttyd0</literal> through <literal>ttyd3</literal>
corresponds to <devicename>COM1</devicename> through
<devicename>COM4</devicename>. Change <literal>off</literal> to
<literal>on</literal> for the desired port. If you have changed the
speed of the serial port, you need to change
<literal>std.9600</literal> to match the current setting, e.g.
<literal>std.19200</literal>.</para>
<para>You may also want to change the terminal type from
<literal>unknown</literal> to the actual type of your serial
terminal.</para>
<para>After editing the file, you must <command>kill -HUP 1</command>
to make this change take effect.</para>
</sect3>
</sect2>
<sect2 id="serialconsole-loader">
<title>Changing Console from the Boot Loader</title>
<para>Previous sections described how to set up the serial console by
tweaking the boot block. This section shows that you can specify the
console by entering some commands and environment variables in the
boot loader. As the boot loader is invoked as the third stage of the
boot process, after the boot block, the settings in the boot loader
will override the settings in the boot block.</para>
<sect3>
<title>Setting Up the Serial Console</title>
<para>You can easily specify the boot loader and the kernel to use the
serial console by writing just one line in
<filename>/boot/loader.rc</filename>:</para>
<programlisting>set console=comconsole</programlisting>
<para>This will take effect regardless of the settings in the boot
block discussed in the previous section.</para>
<para>You had better put the above line as the first line of
<filename>/boot/loader.rc</filename> so as to see boot messages on
the serial console as early as possible.</para>
<para>Likewise, you can specify the internal console as:</para>
<programlisting>set console=vidconsole</programlisting>
<para>If you do not set the boot loader environment variable
<envar>console</envar>, the boot loader, and subsequently the
kernel, will use whichever console indicated by the
<option>-h</option> option in the boot block.</para>
<para>In versions 3.2 or later, you may specify the console in
<filename>/boot/loader.conf.local</filename> or
<filename>/boot/loader.conf</filename>, rather than in
<filename>/boot/loader.rc</filename>. In this method your
<filename>/boot/loader.rc</filename> should look like:</para>
<programlisting>include /boot/loader.4th
start</programlisting>
<para>Then, create <filename>/boot/loader.conf.local</filename> and
put the following line there.</para>
<programlisting>console=comconsole</programlisting>
<para>or</para>
<programlisting>console=vidconsole</programlisting>
<para>See &man.loader.conf.5; for more information.</para>
<note>
<para>At the moment, the boot loader has no option equivalent to the
<option>-P</option> option in the boot block, and there is no
provision to automatically select the internal console and the
serial console based on the presense of the keyboard.</para>
</note>
</sect3>
<sect3>
<title>Using Serial Port Other than <devicename>sio0</devicename> for
the Console</title>
<para>You need to recompile the boot loader to use a serial port other
than <devicename>sio0</devicename> for the serial console. Follow the
procedure described in <xref linkend="serialconsole-com2">.</para>
</sect3>
</sect2>
<sect2 id="serialconsole-caveats">
<title>Caveats</title>
<para>The idea here is to allow people to set up dedicated servers that
require no graphics hardware or attached keyboards. Unfortunately,
while (most?) every system will let you boot without a keyboard, there
are quite a few that will not let you boot without a graphics adapter.
Machines with AMI BIOSes can be configured to boot with no graphics
adapter installed simply by changing the `graphics adapter' setting in
the CMOS configuration to `Not installed.'</para>
<para>However, many machines do not support this option and will refuse
to boot if you have no display hardware in the system. With these
machines, you'll have to leave some kind of graphics card plugged in,
(even if it's just a junky mono board) although you will not have to
attach a monitor into it. You might also try installing an AMI
BIOS.</para>
</sect2>
</sect1>
</chapter>
<!--