Bug 180493 - FreeBSD Handbook: Setting up the serial console: single user mode
Summary: FreeBSD Handbook: Setting up the serial console: single user mode
Status: Open
Alias: None
Product: Documentation
Classification: Unclassified
Component: Books & Articles (show other bugs)
Version: Latest
Hardware: Any Any
: Normal Affects Some People
Assignee: freebsd-doc (Nobody)
URL: https://github.com/freebsd/freebsd-do...
Keywords: needs-patch
Depends on:
Blocks: handbook-2022
  Show dependency treegraph
 
Reported: 2013-07-12 15:30 UTC by ahamiltonwright
Modified: 2022-12-30 14:09 UTC (History)
0 users

See Also:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description ahamiltonwright 2013-07-12 15:30:00 UTC
I have these lines in /boot/loader.conf in order to enable a sometimes-installed serial console device:

boot_multicons="YES"
boot_serial="YES"
comconsole_speed="19200"
console="comconsole,vidconsole"


A side effect of these lines is that entering single-user mode produces a prompt only on the external console.  This was extremely confusing when attempting to boot single-user, as all messages prior to the single-user prompt are produced on the vid terminal (and on the external console), however at the moment that single-user mode is entered, the mirroring ceases.  While it is now clear what happened, the effect is that single-user mode appears to be unavailable.

I have no /boot.config file that would indicate which console is meant to be used for messages.

Fix: 

I would suggest adding some text to the handbook page "Setting up the Serial Console"
http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/serialconsole-setup.html#serialconsole-loader

Currently, these page makes no comment regarding single-user mode whatsoever.  Informing the user that configuring the console may well have repercussions on entry to single-user mode will lessen confusion in the future.


 I would therefore suggest adding the following text into section 26.6.6 "Setting up the Console from the Boot Loader", subsection 26.6.6.1 "Setting Up the Serial Console":


Note that entry to single-user mode will only honour input on one console, even if multiple consoles are indicated using the <tt>console</tt> boot option.  Care must be taken that the first named console is available to the system manager entering single-user mode.


I will note that the first sentence in this section "The boot loader and the kernel to use the serial console can be specified by writing one line in /boot/loader.conf" seems very poorly written -- I do not understand what this line is attempting to say.



Additionally, there is already a section "26.6.7 Caveats"; a note here indicating possible effects on single-user boot would probably not go amiss.
How-To-Repeat: Add these lines to /boot/loader.conf, attempt to boot single user.
Comment 1 Eitan Adler freebsd_committer freebsd_triage 2017-12-31 08:00:55 UTC
For bugs matching the following criteria:

Status: In Progress Changed: (is less than) 2014-06-01

Reset to default assignee and clear in-progress tags.

Mail being skipped
Comment 2 Graham Perrin freebsd_committer freebsd_triage 2022-12-29 03:08:50 UTC
Triage: 

* remove the summary line tag
* …

<https://wiki.freebsd.org/Bugzilla>

----

Whilst here, speeding through comment #0:

> … already a section "… Caveats"; …

The word    caveat    no longer appears in this chapter of the book.
Comment 3 ahamiltonwright 2022-12-30 14:09:07 UTC
In the nine years since I reported this bug and suggested the included text, the entire section on consoles has been rewritten.

I would still suggest that some comment as to how single-user mode is affected by setting up multiple consoles be included in the handbook, as this is still not very clear in the console configuration section:  https://github.com/freebsd/freebsd-doc/blob/main/documentation/content/en/books/handbook/serialcomms/_index.adoc#serialconsole-setup

My guess is that single-user mode ends up on the console indicated with -h in /boot.config (if present), however with the addition of dual console mode I have no idea whether this results in two separate consoles from which one can log in to single-user mode.

I no longer have the device I was using as an external serial console however, so can no longer test whatever advice is being given.