FreeBSD has the ability to boot a system with a dumb terminal on a serial port as a console. This configuration is useful for 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 , 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 then loads and runs the boot loader as the third stage code.
In order to set up booting from a serial console, the boot block code, the boot loader code, and the kernel need to be configured.
This section assumes the default setup and provides a fast overview of setting up the serial console.
Connect the serial cable to COM1 and the controlling terminal.
To see all the boot messages on the serial console, issue the following command as the superuser:
# echo 'console="comconsole"' >> /boot/loader.conf
Edit /etc/ttys and change off to on and dialup to vt100 for the ttyu0 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, see the next section for a more in-depth configuration explanation.
Prepare a serial cable.
Use either a null-modem cable or a standard serial cable and a null-modem adapter. See for a discussion on serial cables.
Unplug the keyboard.
Many 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 will refuse to boot until the keyboard is plugged in.
If the computer complains about the error, but boots anyway, no further configuration is needed.
If the computer refuses to boot without a keyboard attached, the BIOS needs to be configured so that it ignores this error (if it can). Consult the motherboard's manual for details on how to do this.
Tip: Try setting the keyboard to “Not installed” in the BIOS. The keyboard can still be used as this setting just tells the BIOS not to probe for a keyboard at power-on. The 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 the above option is not present in the BIOS, look for an “Halt on Error” option instead. Setting this to “All but Keyboard” or even to “No Errors”, will have the same effect.
Note: If the system has a PS/2® mouse, chances are good that both the mouse and keyboard need to be unplugged. 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.
Plug a dumb terminal into COM1 (sio0).
If a dumb terminal is not available, use an old computer with a modem program, or the serial port on another UNIX® box. If there is no 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 COM1 is being used by another device, temporarily remove that device and install a new boot block and kernel once FreeBSD is up and running.
Make sure the configuration file of the custom kernel has appropriate flags set for COM1 (sio0).
Relevant flags are:
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 -h as described
below, together with this flag.
Forces this unit to be the console, unless there is another higher priority
console, regardless of -h as discussed below. The
flag 0x20 must be used together with the
0x10 flag.
Reserves this unit (in conjunction with 0x10) and makes the unit unavailable for normal access. This flag should not be set to the serial port 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.
Here is an example setting:
device sio0 flags 0x10
Refer to sio(4) for more details.
If the flags were not set, 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 instructs the boot block code how to boot the system. In order to activate the serial console, one or more of the following options are needed. When using multiple options, include them all on the same line:
-hToggles between the internal and serial consoles. Use this to switch
console devices. For instance, to boot from the internal (video) console,
use -h to direct the boot loader and
the kernel to use the serial port as its console device. Alternatively, to
boot from the serial port, use -h to tell the boot
loader and the kernel to use the video display as the console
instead.
-DToggles between the 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 -h. 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 -h. However, the
dual console configuration takes effect only while the boot block
is running. Once the boot loader gets control, the console specified by
-h becomes the only console.
-PMakes the boot block probe the keyboard. If no keyboard is found, the -D and -h options are
automatically set.
Note: Due to space constraints in the current version of the boot blocks,
-Pis 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 laptops may not be properly found because of this limitation. If this is the case, do not use-P. Unfortunately there is no workaround for this problem.
Use either -P to select the console automatically,
or -h to activate the serial console.
Other options are described in boot(8).
The options, except for -P, are passed to the boot
loader. The boot loader will determine whether the internal video or the serial
port should become the console by examining the state of -h. This means that if -D is
specified but -h is not specified in /boot.config, the serial port can be used as the console only
during the boot block as the boot loader will use the internal video display as the
console.
Boot the machine.
When FreeBSD starts, the boot blocks echo the contents of /boot.config to the console. For example:
/boot.config: -P Keyboard: no
The second line appears only if -P is in /boot.config and indicates the presence or absence of the
keyboard. These messages go to either the 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 message, there will be a small pause before the boot blocks continue loading the boot loader and before any further messages are printed to the console. Under normal circumstances, there is no need to interrupt the boot blocks, but one can do so in order to make sure things are set up correctly.
Press any key, other than Enter, at the console to interrupt the boot process. The boot blocks will then prompt for further action:
>> FreeBSD/i386 BOOT Default: 0:ad(0,a)/boot/loader boot:
Verify that the above message appears on either the serial or internal console, or both, according to the options in /boot.config. If the message appears in the correct console, press Enter to continue the boot process.
If there is no prompt on the serial terminal, something is wrong with the
settings. Enter -h then Enter or
Return 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.
During the third stage of the boot process, one can still switch between the internal console and the serial console by setting appropriate environment variables in the boot loader. See for more information.
Here is the summary of the various settings discussed in this section:
device sio0 flags 0x10
| 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 flags 0x30
| 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. To change the default console speed, the following options are available:
Recompile the boot blocks with BOOT_COMCONSOLE_SPEED set to the new console speed. See 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, add the following option to a custom
kernel configuration file and compile a new kernel:
options CONSPEED=19200
Add the -S boot option to /boot.config. See boot(8) for a
description of how to add options to /boot.config and a
list of the supported options.
Enable comconsole_speed in /boot/loader.conf. This option depends on console, boot_serial, and
boot_multicons being set in /boot/loader.conf too. An example of using comconsole_speed to change the serial console speed is:
boot_multicons="YES" boot_serial="YES" comconsole_speed="115200" console="comconsole,vidconsole"
Using a port other than sio0 as the console requires the boot blocks, the boot loader, and the kernel to be recompiled as follows.
Edit /etc/make.conf and set BOOT_COMCONSOLE_PORT to the address of the port to use: 0x3F8, 0x2F8, 0x3E8 or 0x2E8. Only sio0 through sio3 (COM1 through COM4) can be used as 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 to use. For example, to make sio1 (COM2) the console:
device sio1 flags 0x10
or
device sio1 flags 0x30
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.
To drop into the kernel debugger from the serial console, compile a custom kernel with the following options. Note that while this is useful for remote diagnostics, it is also dangerous if a spurious BREAK is generated on the serial port.
options BREAK_TO_DEBUGGER options DDB
While this is not required, it is possible to get a login prompt over the serial line. First, make sure that the boot messages are displayed and it is possible to enter the kernel debugging session through the serial console.
Open /etc/ttys with a text editor and locate the lines:
ttyu0 "/usr/libexec/getty std.9600" unknown off secure ttyu1 "/usr/libexec/getty std.9600" unknown off secure ttyu2 "/usr/libexec/getty std.9600" unknown off secure ttyu3 "/usr/libexec/getty std.9600" unknown off secure
ttyu0 through ttyu3 correspond to COM1 through COM4. Change off to on for the desired port. If the speed of the serial port has been changed, change std.9600 to match the new setting.
The terminal type can also be changed from unknown to the actual type of the serial terminal.
After editing the file, type 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 how to 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, the settings in the boot loader will override the settings in the boot block.
The boot loader and the kernel to use the serial console can be specified by writing one line in /boot/loader.conf:
console="comconsole"
This will take effect regardless of the settings in the boot block discussed in the previous section.
This line should be the first line of /boot/loader.conf so as to see boot messages on the serial console as early as possible.
Likewise, to specify the internal console:
console="vidconsole"
If the boot loader environment variable console is not
set, the boot loader, and subsequently the kernel, will use whichever console is
indicated by -h in the boot block.
The console can be specified in /boot/loader.conf.local or in /boot/loader.conf.
See loader.conf(5) for more information.
Note: At the moment, the boot loader has no option equivalent to
-Pin 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.
The boot loader needs to be compiled in order to use a serial port other than sio0 for the serial console. Follow the procedure described in .
While most systems will boot without a keyboard, quite a few will not boot without a graphics adapter. Machines with AMI BIOSes can be configured to boot with no graphics adapter installed 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 there is no display hardware in the system. With these machines, leave some kind of graphics card plugged in, even if it is just a junky mono board. A monitor does not need to be attached. One might also try installing an AMI BIOS.