diff options
Diffstat (limited to 'en/handbook/serialcomms/chapter.sgml')
| -rw-r--r-- | en/handbook/serialcomms/chapter.sgml | 730 |
1 files changed, 729 insertions, 1 deletions
diff --git a/en/handbook/serialcomms/chapter.sgml b/en/handbook/serialcomms/chapter.sgml index affa6dedb3..b6b6e26c22 100644 --- a/en/handbook/serialcomms/chapter.sgml +++ b/en/handbook/serialcomms/chapter.sgml @@ -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 “Not installed” 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 “Not + installed” 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—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> <!-- |