FreeBSD has the ability to 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 machines that have no keyboard or monitor attached, and developers who want to debug the kernel or device drivers.
As described in Rozdział 12, The FreeBSD Booting Process, FreeBSD 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
(/boot/loader
) as the third stage code.
In order to set up the serial console you must configure the boot block code, the boot loader code and the kernel.
This section assumes that you are using the default setup and just want a fast overview of setting up the serial console.
Connect the serial cable to COM1 and the controlling terminal.
To see all boot messages on the serial console, issue the following command while logged in as the superuser:
#
echo 'console="comconsole"' >> /boot/loader.conf
Edit /etc/ttys
and change
off
to on
and
dialup
to vt100
for the
ttyd0
entry. Otherwise a password will not be
required to connect via the serial console, resulting in a
potential security hole.
Reboot the system to see if the changes took effect.
If a different configuration is required, a more in depth configuration explanation exists in Sekcja 22.6.3, „Serial Console Configuration”.
Prepare a serial cable.
You will need either a null-modem cable or a standard serial cable and a null-modem adapter. See Sekcja 22.2.2, „Cables and Ports” for a discussion on serial cables.
Unplug your keyboard.
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.
If your computer complains about the error, but boots anyway, then you do not have to do anything special. (Some machines with Phoenix BIOS installed merely say Keyboard failed and continue to boot normally.)
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.
Set the keyboard to „Not installed” in the BIOS setup. You will still be able to use your keyboard. All this does is tell the BIOS not to probe for a keyboard at power-on. Your BIOS should not complain if the keyboard is absent. You can leave the keyboard plugged in even with this flag set to „Not installed” and the keyboard will still work.
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 90 MHz 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.
Plug a dumb terminal into COM1
(sio0
).
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 COM1
(sio0
), get one. At this time, there is
no way to select a port other than COM1
for the boot blocks without recompiling the boot blocks. If you
are already using COM1
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 COM1
will
be available on a file/compute/terminal server anyway; if you
really need COM1
for something else
(and you cannot switch that something else to
COM2
(sio1
)),
then you probably should not even be bothering with all this in
the first place.)
Make sure the configuration file of your kernel has
appropriate flags set for COM1
(sio0
).
Relevant flags are:
0x10
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 -h
option
described below, together with this flag.
0x20
Forces this unit to be the console (unless there is
another higher priority console), regardless of the
-h
option discussed below.
The flag 0x20
must be used
together with the 0x10
flag.
0x40
Reserves this unit (in conjunction with
0x10
) 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 The
Developer's Handbook for more information on
remote debugging.
Example:
device sio0 at isa? port IO_COM1 flags 0x10 irq 4
See the sio(4) manual page for more details.
If the flags were not set, you need to run UserConfig (on a different console) or recompile the kernel.
Create boot.config
in the root directory
of the a
partition on the boot drive.
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:
-h
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
-h
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
-h
to tell the boot loader and the kernel
to use the video display as the console instead.
-D
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 -h
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 -h
option.
However, note 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
-h
option becomes the only console.
-P
Makes the boot block probe the keyboard. If no keyboard
is found, the -D
and -h
options are automatically set.
Due to space constraints in the current version of the
boot blocks, the -P
option is capable of
detecting 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
the case with your system, you have to abandon using
the -P
option. Unfortunately there is no
workaround for this problem.
Use either the -P
option to select the
console automatically, or the -h
option to
activate the serial console.
You may include other options described in boot(8) as well.
The options, except for -P
, will be passed to
the boot loader (/boot/loader
). The boot
loader will determine which of the internal video or the serial
port should become the console by examining the state of the
-h
option alone. This means that if you specify
the -D
option but not the -h
option in /boot.config
, 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.
Boot the machine.
When you start your FreeBSD box, the boot blocks will echo the
contents of /boot.config
to the console. For
example:
/boot.config: -P Keyboard: no
The second line appears only if you put -P
in
/boot.config
and indicates presence/absence
of the keyboard. These messages go to either serial or internal
console, or both, depending on the option in
/boot.config
.
Options | Message goes to |
---|---|
none | internal console |
-h | serial console |
-D | serial and internal consoles |
-Dh | serial and internal consoles |
-P , keyboard present | internal console |
-P , keyboard absent | serial console |
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.
Hit any key, other than Enter, at the console to interrupt the boot process. The boot blocks will then prompt you for further action. You should now see something like:
>> FreeBSD/i386 BOOT Default: 0:ad(0,a)/boot/loader boot:
Verify the above message appears on either the serial or
internal console or both, according to the options you put in
/boot.config
. If the message appears in the
correct console, hit Enter to continue the boot
process.
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 -h
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.
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 Sekcja 22.6.6, „Changing Console from the Boot Loader”.
Here is the summary of various settings discussed in this section and the console eventually selected.
device sio0 at isa? port IO_COM1 flags 0x10 irq 4
Options in /boot.config | Console during boot blocks | Console during boot loader | Console in kernel |
---|---|---|---|
nothing | internal | internal | internal |
-h | serial | serial | serial |
-D | serial and internal | internal | internal |
-Dh | serial and internal | serial | serial |
-P , keyboard present | internal | internal | internal |
-P , keyboard absent | serial and internal | serial | serial |
device sio0 at isa? port IO_COM1 flags 0x30 irq 4
Options in /boot.config | Console during boot blocks | Console during boot loader | Console in kernel |
---|---|---|---|
nothing | internal | internal | serial |
-h | serial | serial | serial |
-D | serial and internal | internal | serial |
-Dh | serial and internal | serial | serial |
-P , keyboard present | internal | internal | serial |
-P , keyboard absent | serial and internal | serial | serial |
By default, the serial port settings are: 9600 baud, 8
bits, no parity, and 1 stop bit. If you wish to change the speed, you
need to recompile at least the boot blocks. Add the following line
to /etc/make.conf
and compile new boot
blocks:
BOOT_COMCONSOLE_SPEED=19200
See Sekcja 22.6.5.2, „Using Serial Port Other Than sio0
for
the Console” for detailed
instructions about building and installing new boot blocks.
If the serial console is configured in some other way than by
booting with -h
, 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:
options CONSPEED=19200
Using a port other than sio0
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.
Get the kernel source. (See Rozdział 21, The Cutting Edge)
Edit /etc/make.conf
and set
BOOT_COMCONSOLE_PORT
to the address of the
port you want to use (0x3F8, 0x2F8, 0x3E8 or 0x2E8). Only
sio0
through
sio3
(COM1
through COM4
) can be used; multiport
serial cards will not work. No interrupt setting is
needed.
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 sio1
(COM2
) the console:
device sio1 at isa? port IO_COM2 flags 0x10 irq 3
or
device sio1 at isa? port IO_COM2 flags 0x30 irq 3
The console flags for the other serial ports should not be set.
Recompile and install the boot blocks and the boot loader:
#
cd /sys/boot
#
make clean
#
make
#
make install
Rebuild and install the kernel.
Write the boot blocks to the boot disk with bsdlabel(8) and boot from the new kernel.
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:
options BREAK_TO_DEBUGGER options DDB
While this is not required, you may wish to get a login 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.
Open the file /etc/ttys
with an editor
and locate the lines:
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
ttyd0
through ttyd3
corresponds to COM1
through
COM4
. Change off
to
on
for the desired port. If you have changed the
speed of the serial port, you need to change
std.9600
to match the current setting, e.g.
std.19200
.
You may also want to change the terminal type from
unknown
to the actual type of your serial
terminal.
After editing the file, you must kill -HUP 1
to make this change take effect.
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 at 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.
You can easily specify the boot loader and the kernel to use the
serial console by writing just one line in
/boot/loader.rc
:
set console="comconsole"
This will take effect regardless of the settings in the boot block discussed in the previous section.
You had better put the above line as the first line of
/boot/loader.rc
so as to see boot messages on
the serial console as early as possible.
Likewise, you can specify the internal console as:
set console="vidconsole"
If you do not set the boot loader environment variable
console
, the boot loader, and subsequently the
kernel, will use whichever console indicated by the
-h
option in the boot block.
In versions 3.2 or later, you may specify the console in
/boot/loader.conf.local
or
/boot/loader.conf
, rather than in
/boot/loader.rc
. In this method your
/boot/loader.rc
should look like:
include /boot/loader.4th start
Then, create /boot/loader.conf.local
and
put the following line there.
console=comconsole
or
console=vidconsole
See loader.conf(5) for more information.
At the moment, the boot loader has no option equivalent to the
-P
option in the boot block, and there is no
provision to automatically select the internal console and the
serial console based on the presence of the keyboard.
You need to recompile the boot loader to use a serial port other
than sio0
for the serial console. Follow the
procedure described in Sekcja 22.6.5.2, „Using Serial Port Other Than sio0
for
the Console”.
The idea here is to allow people to set up dedicated servers that require no graphics hardware or attached keyboards. Unfortunately, while most systems 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.”
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 will have to leave some kind of graphics card plugged in, (even if it is just a junky mono board) although you will not have to attach a monitor. You might also try installing an AMI BIOS.
All FreeBSD documents are available for download at http://ftp.FreeBSD.org/pub/FreeBSD/doc/
Questions that are not answered by the
documentation may be
sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.