.\"	$NetBSD: boothowto.9,v 1.8 2018/07/19 11:09:38 wiz Exp $
.\"
.\" Copyright (c) 2009 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd July 14, 2018
.Dt BOOTHOWTO 9
.Os
.Sh NAME
.Nm boothowto ,
.Nm BOOT_FLAG
.Nd flags passed to kernel during boot or shutdown
.Sh SYNOPSIS
.In sys/reboot.h
.In sys/systm.h
.Vt extern int boothowto;
.In sys/boot_flag.h
.Vt #define BOOT_FLAG(arg, retval) ...
.Sh DESCRIPTION
The
.Va boothowto
variable contains flags passed to the kernel by the boot loader (see
.Xr boot 8 ) ,
or the
.Xr reboot 2
system call.
The value is interpreted as a bit mask, with bits defined by the
.Dq Sy RB_ Ns No *
and
.Dq Sy AB_ Ns No *
symbols in
.In sys/reboot.h .
The value is made available via the
.Xr sysctl 7
variable
.Va kern.boothowto .
.Pp
The
.Dv BOOT_FLAG
macro defined in
.In sys/boot_flag.h
is used by many boot loaders to convert command line options into
.Va boothowto
flags.
Note that not all boot loaders use this macro, and some boot loaders
may have incompatible options.
.Pp
Where possible, flags set by the
.Xr reboot 2
system call will be passed to the new kernel after a reboot;
the extent to which this is possible is machine dependent.
.Pp
In the following tables,
each flag is listed with
its symbolic name,
the corresponding numeric value defined in
.In sys/reboot.h ,
and the option letter (if any) understood by the
.Dv BOOT_FLAG
macro.
.
.Ss Flags that affect booting or shutting down
The following flags affect actions taken during system boot
or shutdown.
.Bl -column RB_INITNAMEA 0x00000000 \&-x
.It Dv RB_AUTOBOOT Ta Li 0 Ta Ta
The default if no other flags are set.
Causes the system to boot in the normal way.
.It Dv RB_ASKNAME Ta Li 0x00000001 Ta Fl a Ta
This flag causes various parts of the system to prompt:
.Bl -bullet -compact
.It
The boot loader may prompt for the name or location of the
kernel to be booted.
.It
The kernel will prompt for the root file system device.
.It
The kernel will prompt for the root file system type.
.It
The kernel will prompt for the location of the dump device.
.It
The kernel will prompt for the path to the
.Xr init 8
program.
.El
Some subsystems set this flag when they are unable to automatically
make a decision.
.It Dv RB_SINGLE Ta Li 0x00000002 Ta Fl s Ta
Boot in single-user mode.
If this flag is set, the kernel passes the
.Fl s
option to
.Xr init 8 .
.It Dv RB_NOSYNC Ta Li 0x00000004 Ta Ta
If this flag is set, then some parts of the shutdown process will
be less graceful than usual:
.Bl -bullet -compact
.It
Disks will not be synced
(see
.Xr sync 2
and
.Xr cpu_reboot 9 ) .
.It
Devices will not be detached (see
.Xr autoconf 9 ) .
.\" actually, see config_detach_all, but that is undocumented
.It
File systems will not be unmounted (see
.Xr cpu_reboot 9 ,
and
.Xr vfs_shutdown 9 ) .
.It
The time of day clock will not be set (see
.Xr resettodr 9 ) .
.El
.It Dv RB_HALT Ta Li 0x00000008 Ta Fl b Ta
If this flag is set, then
.Xr reboot 2
will cause the system to halt instead of rebooting.
This flag may be set at boot time, and cannot be cleared by
.Xr reboot 2 .
.It Dv RB_INITNAME Ta Li 0x00000010 Ta Ta
This flag is obsolete.
It was previously used to cause the kernel to prompt for the name of the
.Xr init 8
program, but that function is now controlled by the
.Dv RB_ASKNAME
flag.
.It Dv RB_KDB Ta Li 0x00000040 Ta Fl d Ta
Gives control to a kernel debugger early in the boot sequence.
See
.Xr ddb 4
and
.Dq "options KGDB"
in
.Xr options 4 .
.It Dv RB_RDONLY Ta Li 0x00000080 Ta Ta
This flag is deprecated.
It previously caused the kernel to mount the root file system
in read-only mode, but now that is the default, and this flag
has no effect.
.It Dv RB_DUMP Ta Li 0x00000100 Ta Ta
Causes the kernel to dump memory to the dump device during shutdown.
See
.Xr savecore 8 ,
.Xr cpu_reboot 9 ,
and
.Xr dumpsys 9 .
.It Dv RB_MINIROOT Ta Li 0x00000200 Ta Fl m Ta
This flag informs the kernel that a mini-root file system is present
in memory.
See
.Xr md 4 ,
and
.Xr mdsetimage 8 .
.It Dv RB_STRING Ta Li 0x00000400 Ta Ta
This flag indicates that a boot string is present.
The string may be provided by
.Xr reboot 2
and will be passed to the boot loader if possible.
.It Dv RB_POWERDOWN Ta Li (RB_HALT|0x800) Ta Ta
This flag is used in conjunction with
.Dv RB_HALT .
If this flag is set, then then system will be powered down if possible.
If powerdown is not supported, then the system will halt.
.It Dv RB_USERCONF Ta Li 0x00001000 Ta Fl c Ta
This flag causes the kernel to invoke the
.Xr userconf 4
device configuration manager early in the boot sequence.
.El
.
.Ss Flags that affect verbosity
The following flags affect the verbosity of messages printed by the kernel.
These flags are used by several functions described in
.Xr kprintf 9
to control whether output is sent to the console, the system log,
.\" the /dev/log device driver is undocumented
both, or neither.
The use of flags that increase verbosity simultaneously with
the use of flags that decrease verbosity,
is not well defined.
.Bl -column RB_INITNAMEA 0x00000000 \&-x
.It Dv AB_NORMAL Ta Li 0 Ta Ta
The default, if none of the other
.Dv AB_*
flags is set, is that ordinary kernel messages are sent
both to the console and to the system log.
.It Dv AB_QUIET Ta Li 0x00010000 Ta Fl q Ta
Boot quietly.
Ordinary kernel messages are sent to the system log,
but not to the console.
Messages printed with
.Xr aprint_naive 9
are sent to the console, but not to the system log.
.It Dv AB_VERBOSE Ta Li 0x00020000 Ta Fl v Ta
Boot verbosely.
Some messages will be printed that would otherwise not be printed.
Both ordinary kernel messages, and messages printed with
.Xr aprint_verbose 9 ,
will be sent both to the console and to the system log.
If this flag is not set, then messages printed with
.Xr aprint_verbose 9
will be sent only to the system log.
.It Dv AB_SILENT Ta Li 0x00040000 Ta Fl z Ta
Boot silently.
Most kernel messages will be sent only to the system log, not to the console.
The
.Fn aprint_*
functions display a spinning symbol on the console.
.It Dv AB_DEBUG Ta Li 0x00080000 Ta Fl x Ta
Boot with debug messages.
.El
.
.Ss Machine-dependent flags
The following flags have machine-dependent meanings.
.Bl -column RB_INITNAMEA 0x00000000 \&-x
.It Dv RB_MD1 Ta Li 0x10000000 Ta Fl 1 Ta
Some ports use this flag to disable multiprocessor mode,
making them use only a single CPU.
The zaurus port uses this flag to enable the serial console.
.It Dv RB_MD2 Ta Li 0x20000000 Ta Fl 2 Ta
The i386 and amd64 ports use this flag to disable
.Xr acpi 4 .
.It Dv RB_MD3 Ta Li 0x40000000 Ta Fl 3 Ta
This flag is currently not used by any ports.
.It Dv RB_MD4 Ta Li 0x80000000 Ta Fl 4 Ta
This flag is currently not used by any ports.
.El
.
.Sh SEE ALSO
.\" sets boothowto
.Xr reboot 2 ,
.\" RB_KDB
.Xr ddb 4 ,
.\" RB_USERCONF
.Xr userconf 4 ,
.\" sysctl kern.boothowto
.Xr sysctl 7 ,
.\" sets boothowto
.Xr boot 8 ,
.Xr crash 8 ,
.\" RB_SINGLE, RB_INITNAME
.Xr init 8 ,
.\" reboot/poweroff/halt calls reboot(2)
.Xr reboot 8 ,
.\" useful after RB_DUMP
.Xr savecore 8 ,
.\" RB_NOSYNC
.Xr sync 8 ,
.\" RB_NOSYNC, RB_HALT, RB_DUMP
.Xr cpu_reboot 9 ,
.\" aprint_*() functions use AB_* flags
.Xr kprintf 9
.Sh HISTORY
The
.Va boothowto
variable appeared in
.Bx 4.0 .
The
.Sy BOOT_FLAG
macro appeared in
.Nx 1.6 .
.Pp
The
.Dv RB_DFLTROOT
option is now
.Em obsolete .