diff options
Diffstat (limited to 'usr/src/man/man5')
| -rw-r--r-- | usr/src/man/man5/Makefile | 12 | ||||
| -rw-r--r-- | usr/src/man/man5/beastie.4th.5 | 143 | ||||
| -rw-r--r-- | usr/src/man/man5/brand.4th.5 | 112 | ||||
| -rw-r--r-- | usr/src/man/man5/check-password.4th.5 | 130 | ||||
| -rw-r--r-- | usr/src/man/man5/color.4th.5 | 103 | ||||
| -rw-r--r-- | usr/src/man/man5/delay.4th.5 | 113 | ||||
| -rw-r--r-- | usr/src/man/man5/gptzfsboot.5 | 157 | ||||
| -rw-r--r-- | usr/src/man/man5/loader.4th.5 | 206 | ||||
| -rw-r--r-- | usr/src/man/man5/loader.5 | 785 | ||||
| -rw-r--r-- | usr/src/man/man5/menu.4th.5 | 306 | ||||
| -rw-r--r-- | usr/src/man/man5/menusets.4th.5 | 359 | ||||
| -rw-r--r-- | usr/src/man/man5/pxeboot.5 | 110 | ||||
| -rw-r--r-- | usr/src/man/man5/version.4th.5 | 115 | ||||
| -rw-r--r-- | usr/src/man/man5/zfsloader.5 | 99 |
14 files changed, 2750 insertions, 0 deletions
diff --git a/usr/src/man/man5/Makefile b/usr/src/man/man5/Makefile index 62a46e52fd..422ce7435f 100644 --- a/usr/src/man/man5/Makefile +++ b/usr/src/man/man5/Makefile @@ -29,17 +29,21 @@ MANFILES= Intro.5 \ audit_binfile.5 \ audit_remote.5 \ audit_syslog.5 \ + brand.4th.5 \ brands.5 \ byteorder.5 \ cancellation.5 \ charmap.5 \ + check-password.4th.5 \ condition.5 \ + color.4th.5 \ crypt_bsdbf.5 \ crypt_bsdmd5.5 \ crypt_sha256.5 \ crypt_sha512.5 \ crypt_sunmd5.5 \ crypt_unix.5 \ + delay.4th.5 \ device_clean.5 \ dhcp.5 \ environ.5 \ @@ -52,6 +56,7 @@ MANFILES= Intro.5 \ fnmatch.5 \ formats.5 \ fsattr.5 \ + gptzfsboot.5 \ grub.5 \ gss_auth_rules.5 \ hal.5 \ @@ -69,6 +74,8 @@ MANFILES= Intro.5 \ lf64.5 \ lfcompile.5 \ lfcompile64.5 \ + loader.5 \ + loader.4th.5 \ locale.5 \ lx.5 \ man.5 \ @@ -78,6 +85,8 @@ MANFILES= Intro.5 \ mdoc.5 \ me.5 \ mech_spnego.5 \ + menu.4th.5 \ + menusets.4th.5 \ mm.5 \ ms.5 \ mutex.5 \ @@ -111,6 +120,7 @@ MANFILES= Intro.5 \ pkcs11_tpm.5 \ privileges.5 \ prof.5 \ + pxeboot.5 \ rbac.5 \ regex.5 \ regexp.5 \ @@ -130,7 +140,9 @@ MANFILES= Intro.5 \ threads.5 \ timerfd.5 \ trusted_extensions.5 \ + version.4th.5 \ vgrindefs.5 \ + zfsloader.5 \ zones.5 \ zpool-features.5 diff --git a/usr/src/man/man5/beastie.4th.5 b/usr/src/man/man5/beastie.4th.5 new file mode 100644 index 0000000000..8f2f40bd74 --- /dev/null +++ b/usr/src/man/man5/beastie.4th.5 @@ -0,0 +1,143 @@ +.\" Copyright (c) 2011-2012 Devin Teske +.\" 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 AUTHOR 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 AUTHOR 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 Apr 22, 2017 +.Dt BEASTIE.4TH 5 +.Os +.Sh NAME +.Nm beastie.4th +.Nd loader ASCII art boot module +.Sh DESCRIPTION +The file that goes by the name of +.Nm +is a set of commands designed to draw the ASCII art FreeBSD mascot +.Nd known simply as +.Ic beastie +.Nd to the right of the boot loader menu. In illumos based systems, the +distribution specific logo is used. +The commands of +.Nm +by themselves are not enough for most uses. +Please refer to the +examples below for the most common situations, and to +.Xr loader 5 +for additional commands. +.Pp +Before using any of the commands provided in +.Nm , +it must be included +through the command: +.Pp +.Dl include beastie.4th +.Pp +This line is present in the default +.Pa /boot/loader.rc +file, so it is not needed (and should not be re-issued) in a normal setup. +.Pp +The commands provided by it are: +.Pp +.Bl -tag -width disable-module_module -compact -offset indent +.It Ic draw-beastie +Draws the logo. +.Pp +The logo that is drawn is configured by setting the +.Ic loader_logo +variable in +.Xr loader.conf 4 . +.Pp +The position of the logo can be configured by setting the +.Ic loader_logo_x +and +.Ic loader_logo_y +variables in +.Xr loader.conf 4 . +The default values are 46 (x) and 4 (y). +.Pp +.It Ic clear-beastie +Clears the screen of beastie. +.Pp +.It Ic beastie-start +Initializes the interactive boot loader menu. +.Pp +The +.Ic loader_delay +variable can be configured in +.Xr loader.conf 4 +to the number of seconds you would like to delay loading the boot menu. +During the delay the user can press Ctrl-C to fall back to +.Ic autoboot +or ENTER to proceed. +The default behavior is to not delay. +.El +.Pp +The environment variables that effect its behavior are: +.Bl -tag -width bootfile -offset indent +.It Va loader_logo +Selects the desired logo in the beastie boot menu. +.It Va loader_logo_x +Sets the desired column position of the logo. Default is 46. +.It Va loader_logo_y +Sets the desired row position of the logo. Default is 4. +.It Va beastie_disable +If set to +.Dq YES , +the beastie boot menu will be skipped. +The beastie boot menu is always skipped if running non-x86 hardware. +.It Va loader_delay +If set to a number higher than zero, introduces a delay before starting the +beastie boot menu. During the delay the user can press either Ctrl-C to skip +the menu or ENTER to proceed to the menu. The default is to not delay when +loading the menu. +.El +.Sh FILES +.Bl -tag -width /boot/forth/loader.4th -compact +.It Pa /boot/zfsloader +The +.Xr zfsloader 5 . +.It Pa /boot/forth/beastie.4th +.Nm +itself. +.It Pa /boot/loader.rc +.Xr loader 5 +bootstrapping script. +.El +.Sh EXAMPLES +Standard i386 +.Pa /boot/loader.rc : +.Pp +.Bd -literal -offset indent -compact +include /boot/forth/beastie.4th +beastie-start +.Ed +.Pp +Set a different logo in +.Xr loader.conf 4 : +.Pp +.Bd -literal -offset indent -compact +loader_logo="beastie" +.Ed +.Sh SEE ALSO +.Xr loader.conf 4 , +.Xr loader 5 , +.Xr loader.4th 5 diff --git a/usr/src/man/man5/brand.4th.5 b/usr/src/man/man5/brand.4th.5 new file mode 100644 index 0000000000..ce74b382a6 --- /dev/null +++ b/usr/src/man/man5/brand.4th.5 @@ -0,0 +1,112 @@ +.\" Copyright (c) 2011 Devin Teske +.\" 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 AUTHOR 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 AUTHOR 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 Apr 22, 2017 +.Dt BRAND.4TH 5 +.Os +.Sh NAME +.Nm brand.4th +.Nd loader ASCII art boot module +.Sh DESCRIPTION +The file that goes by the name of +.Nm +is a set of commands designed to draw the ASCII art illumos brand above the +boot loader menu. +The commands of +.Nm +by themselves are not enough for most uses. +Please refer to the +examples below for the most common situations, and to +.Xr loader 5 +for additional commands. +.Pp +Before using any of the commands provided in +.Nm , +it must be included +through the command: +.Pp +.Dl include brand.4th +.Pp +This line is present in the default +.Pa /boot/forth/menu.rc +file, so it is not needed (and should not be re-issued) in a normal setup. +.Pp +The commands provided by it are: +.Pp +.Bl -tag -width disable-module_module -compact -offset indent +.It Ic draw-brand +Draws the illumos brand. +.Pp +The brand that is drawn is configured by setting the +.Ic loader_brand +variable in +.Xr loader.conf 4 +to one of +.Dq Li illumos +(the default) or +.Dq Li none . +.Pp +The position of the logo can be configured by setting the +.Ic loader_brand_x +and +.Ic loader_brand_y +variables in +.Xr loader.conf 4 . +The default values are 2 (x) and 1 (y). +.El +.Pp +The environment variables that effect its behavior are: +.Bl -tag -width bootfile -offset indent +.It Va loader_brand +Selects the desired brand in the beastie boot menu. Possible values are: +.Dq Li illumos +(default) or +.Dq Li none . +.It Va loader_brand_x +Sets the desired column position of the brand. Default is 2. +.It Va loader_brand_y +Sets the desired row position of the brand. Default is 1. +.El +.Sh FILES +.Bl -tag -width /boot/forth/loader.4th -compact +.It Pa /boot/zfsloader +The +.Xr zfsloader 5 . +.It Pa /boot/forth/brand.4th +.Nm +itself. +.It Pa /boot/loader.rc +.Xr loader 4 +bootstrapping script. +.El +.Sh EXAMPLES +Set illumos brand in +.Xr loader.conf 4 : +.Pp +.Bd -literal -offset indent -compact +loader_brand="illumos" +.Ed +.Sh SEE ALSO +.Xr loader.conf 4 , +.Xr loader 5 diff --git a/usr/src/man/man5/check-password.4th.5 b/usr/src/man/man5/check-password.4th.5 new file mode 100644 index 0000000000..3446df9799 --- /dev/null +++ b/usr/src/man/man5/check-password.4th.5 @@ -0,0 +1,130 @@ +.\" Copyright (c) 2011-2015 Devin Teske +.\" 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 AUTHOR 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 AUTHOR 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 Apr 22, 2017 +.Dt CHECK-PASSWORD.4TH 5 +.Os +.Sh NAME +.Nm check-password.4th +.Nd loader password-checking boot module +.Sh DESCRIPTION +The file that goes by the name of +.Nm +is a set of commands designed to do one or more of the following: +.Pp +.Dl o Prevent booting without password +.Dl o Prevent modification of boot options without password +.Pp +The commands of +.Nm +by themselves are not enough for most uses. +Please refer to the +examples below for the most common situations, and to +.Xr loader 5 +for additional commands. +.Pp +Before using any of the commands provided in +.Nm , +it must be included +through the command: +.Pp +.Dl include check-password.4th +.Pp +This line is present in +.Pa /boot/forth/loader.4th +file, so it is not needed (and should not be re-issued) in a normal setup. +.Pp +The commands provided by it are: +.Pp +.Bl -tag -width disable-module_module -compact -offset indent +.It Ic check-password +Multi-purpose function that can protect the interactive boot menu, +prevent boot without password +.Pq depending on Xr loader.conf 4 settings . +.Pp +First checks +.Va bootlock_password +and if-set, the user cannot continue until the correct password is entered. +.Pp +Last, checks +.Va password +and if-set, tries to +.Ic autoboot +and only prompts for password on failure or user-interrupt. +See +.Xr loader.conf 4 +for additional information. +.El +.Pp +The environment variables that effect its behavior are: +.Bl -tag -width bootlock_password -offset indent +.It Va bootlock_password +Sets the bootlock password (up to 16 characters long) that is required by +.Ic check-password +to be entered before the system is allowed to boot. +.It Va password +Sets the password (up to 16 characters long) that is required by +.Ic check-password +before the user is allowed to visit the boot menu. +.El +.Sh FILES +.Bl -tag -width /boot/forth/check-password.4th -compact +.It Pa /boot/zfsloader +The +.Xr zfsloader 5 . +.It Pa /boot/forth/check-password.4th +.Nm +itself. +.It Pa /boot/loader.rc +.Xr loader 5 +bootstrapping script. +.El +.Sh EXAMPLES +Standard i386 +.Pa /boot/loader.rc : +.Pp +.Bd -literal -offset indent -compact +include /boot/forth/loader.4th +check-password +.Ed +.Pp +Set a password in +.Xr loader.conf 4 +to prevent modification of boot options: +.Pp +.Bd -literal -offset indent -compact +password="abc123" +.Ed +.Pp +Set a password in +.Xr loader.conf 4 +to prevent booting without password: +.Pp +.Bd -literal -offset indent -compact +bootlock_password="boot" +.Ed +.Sh SEE ALSO +.Xr loader.conf 4 , +.Xr loader 5 , +.Xr loader.4th 5 diff --git a/usr/src/man/man5/color.4th.5 b/usr/src/man/man5/color.4th.5 new file mode 100644 index 0000000000..7031034d3d --- /dev/null +++ b/usr/src/man/man5/color.4th.5 @@ -0,0 +1,103 @@ +.\" Copyright (c) 2011-2013 Devin Teske +.\" 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 AUTHOR 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 AUTHOR 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 Apr 22, 2017 +.Dt COLOR.4TH 5 +.Os +.Sh NAME +.Nm color.4th +.Nd loader color-detection boot module +.Sh DESCRIPTION +The file that goes by the name of +.Nm +is a set of commands designed to simplify color logic. +The commands of +.Nm +by themselves are not enough for most uses. +Please refer to the +examples below for the most common situations, and to +.Xr loader 5 +for additional commands. +.Pp +Before using any of the commands provided in +.Nm , +it must be included +through the command: +.Pp +.Dl include color.4th +.Pp +This line is present in +.Pa /boot/forth/loader.4th +file, so it is not needed (and should not be re-issued) in a normal setup. +.Pp +The commands provided by it are: +.Pp +.Bl -tag -width disable-module_module -compact -offset indent +.It Ic loader_color? +Returns FALSE if the +.Ic loader_color +environment variable is set to +.Dq NO +(case-insensitive) or +.Dq 0 . +Otherwise returns TRUE +.Pq unless booting serial . +.El +.Pp +The environment variables that effect its behavior are: +.Bl -tag -width bootfile -offset indent +.It Va loader_color +If set to +.Dq NO +(case-insensitive) or +.Dq 0 , +causes +.Ic loader_color? +to return FALSE, indicating to many modules that color should not be used. +.El +.Sh FILES +.Bl -tag -width /boot/forth/loader.4th -compact +.It Pa /boot/zfsloader +The +.Xr zfsloader 5 . +.It Pa /boot/forth/color.4th +.Nm +itself. +.It Pa /boot/loader.rc +.Xr loader 5 +bootstrapping script. +.El +.Sh EXAMPLES +Standard i386 +.Pa /boot/loader.conf : +.Pp +Use color where applicable: +.Pp +.Bd -literal -offset indent -compact +loader_color="YES" +.Ed +.Sh SEE ALSO +.Xr loader.conf 4 , +.Xr loader 5 , +.Xr loader.4th 5 diff --git a/usr/src/man/man5/delay.4th.5 b/usr/src/man/man5/delay.4th.5 new file mode 100644 index 0000000000..4c6da7071d --- /dev/null +++ b/usr/src/man/man5/delay.4th.5 @@ -0,0 +1,113 @@ +.\" Copyright (c) 2011 Devin Teske +.\" 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 AUTHOR 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 AUTHOR 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 Apr 22, 2017 +.Dt DELAY.4TH 5 +.Os +.Sh NAME +.Nm delay.4th +.Nd loader debugging boot module +.Sh DESCRIPTION +The file that goes by the name of +.Nm +is a set of commands designed to add debugging capabilities to +.Xr loader 5 . +The commands of +.Nm +by themselves are not enough for most uses. +Please refer to the +examples below for the most common situations, and to +.Xr loader 5 +for additional commands. +.Pp +Before using any of the commands provided in +.Nm , +it must be included +through the command: +.Pp +.Dl include delay.4th +.Pp +This line is present in +.Pa /boot/forth/beastie.4th +file, so it is not needed (and should not be re-issued) in a normal setup. +.Pp +The commands provided by it are: +.Pp +.Bl -tag -width disable-module_module -compact -offset indent +.It Ic delay_execute +Executes the [string] procedure stored in the +.Ic delay_command +environment variable after +.Ic loader_delay +seconds. +.Pp +If the optional +.Ic delay_showdots +environment variable is set, a continuous series of dots is printed. +.Pp +During the duration, the user can either press Ctrl-C (or Esc) to abort or +ENTER to proceed immediately. +.El +.Pp +The environment variables that effect its behavior are: +.Bl -tag -width bootfile -offset indent +.It Va delay_command +The command to be executed by +.Ic delay_execute . +.It Va loader_delay +The duration (in seconds) to delay before executing +.Ic delay_command . +.It Va delay_showdots +If set, will cause +.Ic delay_execute +to print a continuous series of dots during the delay duration. +.El +.Sh FILES +.Bl -tag -width /boot/forth/loader.4th -compact +.It Pa /boot/zfsloader +The +.Xr zfsloader 5 . +.It Pa /boot/forth/delay.4th +.Nm +itself. +.It Pa /boot/loader.rc +.Xr loader 5 +bootstrapping script. +.El +.Sh EXAMPLES +Introducing a 5-second delay before including another file from +.Pa /boot/loader.rc : +.Pp +.Bd -literal -offset indent -compact +include /boot/forth/delay.4th +set delay_command="include /boot/forth/other.4th" +set delay_showdots +set loader_delay=5 +delay_execute +.Ed +.Sh SEE ALSO +.Xr loader.conf 4 , +.Xr beastie.4th 5 , +.Xr loader 5 , +.Xr loader.4th 5 diff --git a/usr/src/man/man5/gptzfsboot.5 b/usr/src/man/man5/gptzfsboot.5 new file mode 100644 index 0000000000..e74ef30d32 --- /dev/null +++ b/usr/src/man/man5/gptzfsboot.5 @@ -0,0 +1,157 @@ +.\" Copyright (c) 2014 Andriy Gapon <avg@FreeBSD.org> +.\" 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 AUTHORS 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 AUTHORS 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 Apr 21, 2017 +.Dt GPTZFSBOOT 5 +.Os +.Sh NAME +.Nm gptzfsboot +.Nd disk bootcode for BIOS-based computers +.Sh DESCRIPTION +.Nm +is used on BIOS-based computers to boot from a filesystem on disk device. +Depending on disk partitioning and boot file system, the +.Nm +is installed in a +.Cm zfs pool boot area +or +.Cm boot +partition of a disk with +.Xr installboot 1M . +.Ss IMPLEMENTATION NOTES +The GPT standard allows a variable number of partitions, but +.Nm +only boots from tables with 128 partitions or less. +.Ss BOOTING +.Nm +tries to find all ZFS pools that are composed of BIOS-visible +hard disks or partitions on them. +.Nm +looks for ZFS device labels on all visible disks and in discovered +supported partitions for all supported partition scheme types. +Disks are probed in BIOS defined order. +After a disk is probed and +.Nm +determines that the whole disk is not a ZFS pool member, the +individual partitions are probed in their partition table order. +Currently GPT and MBR partition schemes are supported. +.Pp +The default boot partition is recorded into +.Nm +binary by +.Xr installboot 1M +and the default boot file system is determined at run time. +.Nm +does support booting from the +.Cm ZFS , +.Cm UFS +and +.Cm PCFS +file systems. +.Pp +The filesystem specified by the +.Cm bootfs +property of the ZFS pool is used as a default boot filesystem. +If the +.Cm bootfs +property is not set, then the root filesystem of the pool is used as +the default. +.Xr zfsloader 5 +is loaded from the boot filesystem. +If +.Pa /boot/config +is present in the boot filesystem, boot options are read from it. +.Pp +The ZFS GUIDs of the boot pool and boot file system are made available to +.Xr zfsloader 8 . +.Ss USAGE +Normally +.Nm +will boot in fully automatic mode. +However, it is possible to interrupt the automatic boot process and +interact with +.Nm +through a prompt. +.Pp +The filesystem specification and the path to +.Xr zfsloader 5 +is specified as +.Pp +.Sm off +.Oo zfs:pool/filesystem: Oc Oo /path/to/loader Oc +.Sm on +.Pp +Both the filesystem and the path can be specified. +If only a path is specified, then the default filesystem is used. +If only a pool and filesystem are specified, then +.Pa /boot/zfsloader +is used as a path. +.Pp +Additionally, the +.Nm +does support two commands to get information about the system. +.Ic ?directoryname +can be used to list the content of named directory and +.Ic status +command can be used to query information about discovered devices. +The output format for ZFS pools is similar to that of +.Cm zpool status +.Pq see Xr zpool 1M . +.Pp +The configured or automatically determined ZFS boot filesystem is +stored in the +.Xr zfsloader 5 +.Cm loaddev +variable, and also set as the initial value of the +.Cm currdev +variable. +.Sh FILES +.Bl -tag -width /boot/gptzfsboot -compact +.It Pa /boot/config +parameters for the boot block +.Pq optional +.It Pa /boot/gptzfsboot +boot code binary +.El +.Sh EXAMPLES +.Nm +is installed in combination with a +.Dq protective MBR +.Po +see +.Xr installboot 1M +.Pc . +To install +.Nm +on the +.Pa c0t0d0s0 +drive: +.Bd -literal -offset indent +installboot /boot/pmbr /boot/gptzfsboot /dev/rdsk/c0t0d0s0 +.Ed +.Sh SEE ALSO +.Xr installboot 1M , +.Xr zpool 1M , +.Xr loader 5 , +.Xr zfsloader 5 diff --git a/usr/src/man/man5/loader.4th.5 b/usr/src/man/man5/loader.4th.5 new file mode 100644 index 0000000000..0e6dd01413 --- /dev/null +++ b/usr/src/man/man5/loader.4th.5 @@ -0,0 +1,206 @@ +.\" Copyright (c) 1999 Daniel C. Sobral +.\" 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 AUTHOR 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 AUTHOR 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 Apr 22, 2017 +.Dt LOADER.4TH 5 +.Os +.Sh NAME +.Nm loader.4th +.Nd loader.conf processing tools +.Sh DESCRIPTION +The file that goes by the name of +.Nm +is a set of commands designed to manipulate +.Xr loader.conf 4 +files. +The default +.Pa /boot/loader.rc +includes +.Nm +and uses one of its commands to automatically read and process +the standard +.Xr loader.conf 4 +files. +Other commands exists to help the user specify alternate +configurations. +.Pp +The commands of +.Nm +by themselves are not enough for most uses. +Please refer to the +examples below for the most common situations, and to +.Xr loader 5 +for additional commands. +.Pp +Before using any of the commands provided in +.Nm , +it must be included +through the command: +.Pp +.Dl include loader.4th +.Pp +This line is present in the default +.Pa /boot/loader.rc +file, so it is not needed (and should not be re-issued) in a normal setup. +.Pp +The commands provided by it are: +.Bl -tag -width disable-module_module -compact -offset indent +.It Ic boot +.It Ic boot Ar kernelname Op Cm ... +.It Ic boot Ar directory Op Cm ... +.It Ic boot Fl flag Cm ... +Boot as specified by the +.Xr loader.conf 4 +files read. +.Pp +Depending on the arguments passed, it can override boot flags and +either the kernel name or the search path for kernel and modules. +.Pp +.It Ic boot-conf +.It Ic boot-conf Ar kernelname Op Cm ... +.It Ic boot-conf Ar directory Op Cm ... +.It Ic boot-conf Fl flag Cm ... +Works like +.Ic boot +described above, but instead of booting immediately, uses +.Ic autoboot , +so it can be stopped. +.Pp +.It Ic start +Reads +.Pa /boot/defaults/loader.conf , +all other +.Xr loader.conf 4 +files specified in it, then loads the desired kernel and modules +.Pq if not already loaded . +After which you can use the +.Ic boot +or +.Ic autoboot +commmands or simply exit (provided +.Va autoboot_delay +is not set to NO) to boot the system. +.Ic start +is the command used in the default +.Pa /boot/loader.rc +file +.Pq see Xr loader 5 . +.Pp +.It Ic initialize +Initialize the support library so commands can be used without executing +.Ic start +first. +Like +.Ic start , +it reads +.Pa /boot/defaults/loader.conf +and all other +.Xr loader.conf 4 +files specified in it +.Pq but does not load kernel or modules . +Returns a flag on the stack to indicate +if any configuration files were successfully loaded. +.Pp +.It Ic read-conf Ar filename +Reads and processes a +.Xr loader.conf 4 +file. +Does not proceed to boot. +.Pp +.It Ic enable-module Ar module +Enables the loading of +.Ar module . +.Pp +.It Ic disable-module Ar module +Disables the loading of +.Ar module . +.Pp +.It Ic toggle-module Ar module +Toggles the loading of +.Ar module +on and off. +.Pp +.It Ic show-module Ar module +Shows the information gathered in the +.Xr loader.conf 4 +files about the module +.Ar module . +.Pp +.It Ic show-module-options +Shows all modules defined in current +.Xr loader.conf 4 +configuration. +.Pp +.It Ic retry +Used inside +.Xr loader.conf 4 +files to specify the action after a module loading fails. +.Pp +.It Ic ignore +Used inside +.Xr loader.conf 4 +files to specify the action after a module loading fails. +.It Ic try-include Ar file Op Ar +Process script files if they exist. +Each file, in turn, is completely read into memory, +and then each of its lines is passed to the command line interpreter. +If any error is returned by the interpreter, the try-include +command aborts immediately, without reading any other files, and +silently returns without error. +.El +.Sh FILES +.Bl -tag -width /boot/forth/loader.4th -compact +.It Pa /boot/zfsloader +The +.Xr zfsloader 5 . +.It Pa /boot/forth/loader.4th +.Nm +itself. +.It Pa /boot/loader.rc +.Xr loader 5 +bootstrapping script. +.It Pa /boot/defaults/loader.conf +File loaded by the +.Ic start +command. +.El +.Sh EXAMPLES +Standard +.Pa /boot/loader.rc : +.Pp +.Bd -literal -offset indent -compact +include /boot/forth/loader.4th +start +.Ed +.Pp +Read an additional configuration file and then proceed to boot: +.Pp +.Bd -literal -offset indent -compact +unload +read-conf /boot/special.conf +boot-conf +.Ed +.Sh SEE ALSO +.Xr loader.conf 4 , +.Xr loader 5 diff --git a/usr/src/man/man5/loader.5 b/usr/src/man/man5/loader.5 new file mode 100644 index 0000000000..ef651b02a1 --- /dev/null +++ b/usr/src/man/man5/loader.5 @@ -0,0 +1,785 @@ +.\" Copyright (c) 1999 Daniel C. Sobral +.\" 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 AUTHOR 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 AUTHOR 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 Apr 20, 2017 +.Dt LOADER 5 +.Os +.Sh NAME +.Nm loader +.Nd kernel bootstrapping final stage +.Sh DESCRIPTION +The +.Nm +is the final stage of +.Nm illumos Ns 's +kernel bootstrapping process. The actual name for the stage depends on +the platform. On IA32 (i386) architectures with BIOS firmware, it is a +.Pa BTX +client and named +.Nm zfsloader . +It is linked statically to libstand and usually located in the directory +.Pa /boot . +.Pp +.Nm +supports booting from +.Cm ZFS , +.Cm UFS , +.Cm PCFS , +.Cm HSFS +and +.Cm NFS +file systems. Additionally, +.Nm +can load files from the +.Cm TFTP +file service. The NFS and TFTP based boot is enabled via +.Xr pxeboot 5 . +The +.Nm +also does support uncompressing gzip files while reading. The uncompression +will happen automatically if the compressed file is stored without .gz +suffix or if the file is accessed by leaving out the .gz suffix from the name. +If the file is referred by full name, including .gz suffix, then the file +content is read as is and the uncompression is not performed. +.Pp +.Nm +provides a scripting language that can be used to +automate tasks, do pre-configuration or assist in recovery +procedures. +This scripting language is roughly divided in +two main components. +The smaller one is a set of commands +designed for direct use by the casual user, called "builtin +commands" for historical reasons. +The main drive behind these commands is user-friendliness. +The bigger component is an +.Tn ANS +Forth compatible Forth interpreter based on FICL, by +.An John Sadler . +.Pp +During initialization, +.Nm +will probe for a console and set the +.Va console +variable, or set it to serial console +.Pq Do Li ttya Dc - Dq Li ttyd +if the previous boot stage used that. +If multiple consoles are selected, they will be listed separated by commas. +Then, devices are probed, +.Va currdev +and +.Va loaddev +are set, and +.Va COLUMNS , +.Va LINES , +and +.Va ISADIR +are set. +Next, +.Tn FICL +is initialized, the builtin words are added to its vocabulary. +The inner interpreter +.Nm +will use with +.Tn FICL +is then set to +.Ic interpret , +which is +.Tn FICL Ns 's +default. +After that, +.Pa /boot/loader.rc +is processed if available. +These files are processed through the +.Ic include +command, which reads all of them into memory before processing them, +making disk changes possible. +.Pp +At this point, if an +.Ic autoboot +has not been tried, and if +.Va autoboot_delay +is not set to +.Dq Li NO +(not case sensitive), then an +.Ic autoboot +will be tried. +If the system gets past this point, +.Va prompt +will be set and +.Nm +will engage interactive mode. +Please note that historically even when +.Va autoboot_delay +is set to +.Dq Li 0 +user will be able to interrupt autoboot process by pressing some key +on the console while kernel and modules are being loaded. +In some +cases such behaviour may be undesirable, to prevent it set +.Va autoboot_delay +to +.Dq Li -1 , +in this case +.Nm +will engage interactive mode only if +.Ic autoboot +has failed. +.Ss Builtin Commands +In +.Nm , +builtin commands take parameters from the command line. +If an error condition occurs, an exception will be generated, +which can be intercepted using +.Tn ANS +Forth exception handling +words. +If not intercepted, an error message will be displayed and +the interpreter's state will be reset, emptying the stack and restoring +interpreting mode. +.Pp +The builtin commands available are: +.Pp +.Bl -tag -width Ds -compact +.It Ic autoboot Op Ar seconds Op Ar prompt +Proceeds to bootstrap the system after a number of seconds, if not +interrupted by the user. +Displays a countdown prompt +warning the user the system is about to be booted, +unless interrupted by a key press. +The kernel will be loaded first if necessary. +Defaults to 10 seconds. +.Pp +.It Ic bcachestat +Displays statistics about disk cache usage. +For debugging only. +.Pp +.It Ic boot +.It Ic boot Ar kernelname Op Cm ... +.It Ic boot Fl flag Cm ... +Immediately proceeds to bootstrap the system, loading the kernel +if necessary. +Any flags or arguments are passed to the kernel, but they +must precede the kernel name, if a kernel name is provided. +.Pp +.Em WARNING : +The behavior of this builtin is changed if +.Xr loader.4th 5 +is loaded. +.Pp +.It Ic chain Ar device +Chain load another boot loader from the specified device. Device can be either +disk name or partition. +.Pp +.It Ic echo Xo +.Op Fl n +.Op Aq message +.Xc +Displays text on the screen. +A new line will be printed unless +.Fl n +is specified. +.Pp +.It Ic heap +Displays memory usage statistics. +For debugging purposes only. +.Pp +.It Ic help Op topic Op subtopic +Shows help messages read from +.Pa /boot/loader.help . +The special topic +.Em index +will list the topics available. +.Pp +.It Ic include Ar file Op Ar +Process script files. +Each file, in turn, is completely read into memory, +and then each of its lines is passed to the command line interpreter. +If any error is returned by the interpreter, the include +command aborts immediately, without reading any other files, and +returns an error itself (see +.Sx ERRORS ) . +.Pp +.It Ic load Xo +.Op Fl t Ar type +.Ar file Cm ... +.Xc +Loads a kernel or file of opaque contents tagged as being of the type +.Ar type . +Kernel and modules can be either in a.out or ELF format. +Any arguments passed after the name of the file to be loaded +will be passed as arguments to that file. +.Pp +.It Ic ls Xo +.Op Fl l +.Op Ar path +.Xc +Displays a listing of files in the directory +.Ar path , +or the root directory if +.Ar path +is not specified. +If +.Fl l +is specified, file sizes will be shown too. +.Pp +.It Ic lsdev Op Fl v +Lists all of the devices from which it may be possible to load modules. +If +.Fl v +is specified, more details are printed. +.Pp +.It Ic lsmod Op Fl v +Displays loaded modules. +If +.Fl v +is specified, more details are shown. +.Pp +.It Ic more Ar file Op Ar +Display the files specified, with a pause at each +.Va LINES +displayed. +.Pp +.It Ic read Xo +.Op Fl t Ar seconds +.Op Fl p Ar prompt +.Op Va variable +.Xc +Reads a line of input from the terminal, storing it in +.Va variable +if specified. +A timeout can be specified with +.Fl t , +though it will be canceled at the first key pressed. +A prompt may also be displayed through the +.Fl p +flag. +.Pp +.It Ic reboot +Immediately reboots the system. +.Pp +.It Ic set Ar variable +.It Ic set Ar variable Ns = Ns Ar value +Set loader's environment variables. +.Pp +.It Ic show Op Va variable +Displays the specified variable's value, or all variables and their +values if +.Va variable +is not specified. +.Pp +.It Ic unload +Remove all modules from memory. +.Pp +.It Ic unset Va variable +Removes +.Va variable +from the environment. +.Pp +.It Ic \&? +Lists available commands. +.El +.Ss Builtin Environment Variables +The +.Nm +has actually two different kinds of +.Sq environment +variables. +There are ANS Forth's +.Em environmental queries , +and a separate space of environment variables used by builtins, which +are not directly available to Forth words. +It is the latter type that this section covers. +.Pp +Environment variables can be set and unset through the +.Ic set +and +.Ic unset +builtins, and can have their values interactively examined through the +use of the +.Ic show +builtin. +Their values can also be accessed as described in +.Sx BUILTIN PARSER . +.Pp +Notice that these environment variables are not inherited by any shell +after the system has been booted. +.Pp +A few variables are set automatically by +.Nm . +Others can affect the behavior of either +.Nm +or the kernel at boot. +Some options may require a value, +while others define behavior just by being set. +Both types of builtin variables are described below. +.Bl -tag -width bootfile +.It Va autoboot_delay +Number of seconds +.Ic autoboot +will wait before booting. +If this variable is not defined, +.Ic autoboot +will default to 10 seconds. +.Pp +If set to +.Dq Li NO , +no +.Ic autoboot +will be automatically attempted after processing +.Pa /boot/loader.rc , +though explicit +.Ic autoboot Ns 's +will be processed normally, defaulting to 10 seconds delay. +.Pp +If set to +.Dq Li 0 , +no delay will be inserted, but user still will be able to interrupt +.Ic autoboot +process and escape into the interactive mode by pressing some key +on the console while kernel and +modules are being loaded. +.Pp +If set to +.Dq Li -1 , +no delay will be inserted and +.Nm +will engage interactive mode only if +.Ic autoboot +has failed for some reason. +.It Va boot_ask +Will set +.Xr kernel 1M +.Fl a +option. +.It Va boot_debug +Will set +.Xr kernel 1M +.Fl d +option. +.It Va boot_kmdb +Will set +.Xr kernel 1M +.Fl k +option. +.It Va boot_reconfigure +Will set +.Xr kernel 1M +.Fl r +option. +.It Va boot_single +Will set +.Xr kernel 1M +.Fl s +option. +.It Va boot_verbose +Will set +.Xr kernel 1M +.Fl v +option. +.It Va boot-args +Will set custom arguments for the kernel. If set in +.Nm +configuration, the +.Nm +startup will parse the +.Va boot-args +value to set boot prefixed variables listed above, any unrecognized options +are added to kernel command line verbatim. +.It Va bootfile +The name of the kernel. +.It Va console +Defines the current console or consoles. +Multiple consoles may be specified. +In that case, the first listed console will become the default console for +the +.Xr kernel 1M . +.It Va currdev +Selects the default device. +Syntax for devices is odd. +.It Va interpret +Has the value +.Dq Li ok +if the Forth's current state is interpreting. +.It Va LINES +Define the number of lines on the screen, to be used by the pager. +.It Va module_path +Sets the list of directories which will be searched for modules +named in a load command or implicitly required by a dependency. +The default value for this variable is +.Dq Li /platform/i86pc/${ISADIR} +.It Va prompt +Value of +.Nm Ns 's +prompt. +Defaults to +.Dq Li "${interpret}" . +If variable +.Va prompt +is unset, the default prompt is +.Ql > . +.It Va os_console +If set, the value is used to set +.Xr kernel 1M +.Va console +property. +.El +.Pp +Other variables are used for loader or to set kernel properties or for +informational purposes. +.Ss Builtin Parser +When a builtin command is executed, the rest of the line is taken +by it as arguments, and it is processed by a special parser which +is not used for regular Forth commands. +.Pp +This special parser applies the following rules to the parsed text: +.Bl -enum +.It +All backslash characters are preprocessed. +.Bl -bullet +.It +\eb , \ef , \er , \en and \et are processed as in C. +.It +\es is converted to a space. +.It +\ev is converted to +.Tn ASCII +11. +.It +\ez is just skipped. +Useful for things like +.Dq \e0xf\ez\e0xf . +.It +\e0xN and \e0xNN are replaced by the hex N or NN. +.It +\eNNN is replaced by the octal NNN +.Tn ASCII +character. +.It +\e" , \e' and \e$ will escape these characters, preventing them from +receiving special treatment in Step 2, described below. +.It +\e\e will be replaced with a single \e . +.It +In any other occurrence, backslash will just be removed. +.El +.It +Every string between non-escaped quotes or double-quotes will be treated +as a single word for the purposes of the remaining steps. +.It +Replace any +.Li $VARIABLE +or +.Li ${VARIABLE} +with the value of the environment variable +.Va VARIABLE . +.It +Space-delimited arguments are passed to the called builtin command. +Spaces can also be escaped through the use of \e\e . +.El +.Pp +An exception to this parsing rule exists, and is described in +.Sx Builtins And FORTH . +.Ss Builtins And FORTH +All builtin words are state-smart, immediate words. +If interpreted, they behave exactly as described previously. +If they are compiled, though, +they extract their arguments from the stack instead of the command line. +.Pp +If compiled, the builtin words expect to find, at execution time, the +following parameters on the stack: +.D1 Ar addrN lenN ... addr2 len2 addr1 len1 N +where +.Ar addrX lenX +are strings which will compose the command line that will be parsed +into the builtin's arguments. +Internally, these strings are concatenated in from 1 to N, +with a space put between each one. +.Pp +If no arguments are passed, a 0 +.Em must +be passed, even if the builtin accepts no arguments. +.Pp +While this behavior has benefits, it has its trade-offs. +If the execution token of a builtin is acquired (through +.Ic ' +or +.Ic ['] ) , +and then passed to +.Ic catch +or +.Ic execute , +the builtin behavior will depend on the system state +.Bf Em +at the time +.Ic catch +or +.Ic execute +is processed! +.Ef +This is particularly annoying for programs that want or need to +handle exceptions. +In this case, the use of a proxy is recommended. +For example: +.Dl : (boot) boot ; +.Ss FICL +.Tn FICL +is a Forth interpreter written in C, in the form of a forth +virtual machine library that can be called by C functions and vice +versa. +.Pp +In +.Nm , +each line read interactively is then fed to +.Tn FICL , +which may call +.Nm +back to execute the builtin words. +The builtin +.Ic include +will also feed +.Tn FICL , +one line at a time. +.Pp +The words available to +.Tn FICL +can be classified into four groups. +The +.Tn ANS +Forth standard words, extra +.Tn FICL +words, extra +.Fx +words, and the builtin commands; +the latter were already described. +The +.Tn ANS +Forth standard words are listed in the +.Sx STANDARDS +section. +The words falling in the two other groups are described in the +following subsections. +.Ss FICL Extra Words +.Bl -tag -width wid-set-super +.It Ic .env +.It Ic .ver +.It Ic -roll +.It Ic 2constant +.It Ic >name +.It Ic body> +.It Ic compare +This is the STRING word set's +.Ic compare . +.It Ic compile-only +.It Ic endif +.It Ic forget-wid +.It Ic parse-word +.It Ic sliteral +This is the STRING word set's +.Ic sliteral . +.It Ic wid-set-super +.It Ic w@ +.It Ic w! +.It Ic x. +.It Ic empty +.It Ic cell- +.It Ic -rot +.El +.Ss Loader Extra Words +.Bl -tag -width XXXXXXXX +.It Ic \&$ Pq -- +Evaluates the remainder of the input buffer, after having printed it first. +.It Ic \&% Pq -- +Evaluates the remainder of the input buffer under a +.Ic catch +exception guard. +.It Ic .# +Works like +.Ic "." +but without outputting a trailing space. +.It Ic fclose Pq Ar fd -- +Closes a file. +.It Ic fkey Pq Ar fd -- char +Reads a single character from a file. +.It Ic fload Pq Ar fd -- +Processes a file +.Em fd . +.It Ic fopen Pq Ar addr len mode Li -- Ar fd +Opens a file. +Returns a file descriptor, or \-1 in case of failure. +The +.Ar mode +parameter selects whether the file is to be opened for read access, write +access, or both. +The constants +.Dv O_RDONLY , O_WRONLY , +and +.Dv O_RDWR +are defined in +.Pa /boot/forth/support.4th , +indicating read only, write only, and read-write access, respectively. +.It Xo +.Ic fread +.Pq Ar fd addr len -- len' +.Xc +Tries to read +.Em len +bytes from file +.Em fd +into buffer +.Em addr . +Returns the actual number of bytes read, or -1 in case of error or end of +file. +.It Ic heap? Pq -- Ar cells +Return the space remaining in the dictionary heap, in cells. +This is not related to the heap used by dynamic memory allocation words. +.It Ic inb Pq Ar port -- char +Reads a byte from a port. +.It Ic key Pq -- Ar char +Reads a single character from the console. +.It Ic key? Pq -- Ar flag +Returns +.Ic true +if there is a character available to be read from the console. +.It Ic ms Pq Ar u -- +Waits +.Em u +microseconds. +.It Ic outb Pq Ar port char -- +Writes a byte to a port. +.It Ic seconds Pq -- Ar u +Returns the number of seconds since midnight. +.It Ic tib> Pq -- Ar addr len +Returns the remainder of the input buffer as a string on the stack. +.El +.Ss Loader Defined Environmental Queries +.Bl -tag -width Ds +.It arch-i386 +.Ic TRUE +if the architecture is IA32. +.It loader_version +.Nm +version. +.El +.Ss Errors +The following values are thrown by +.Nm : +.Bl -tag -width XXXXX -offset indent +.It 100 +Any type of error in the processing of a builtin. +.It -1 +.Ic Abort +executed. +.It -2 +.Ic Abort" +executed. +.It -56 +.Ic Quit +executed. +.It -256 +Out of interpreting text. +.It -257 +Need more text to succeed -- will finish on next run. +.It -258 +.Ic Bye +executed. +.It -259 +Unspecified error. +.El +.Sh FILES +.Bl -tag -width /boot/defaults/loader.conf -compact +.It Pa /boot/defaults/loader.conf +.It Pa /boot/conf.d/* +.It Pa /boot/loader.conf +.It Pa /boot/loader.conf.local +.Nm +configuration files, as described in +.Xr loader.conf 5 . +.It Pa /boot/loader.help +Loaded by +.Ic help . +Contains the help messages. +.It Pa /boot/loader.rc +.Nm +bootstrapping script. +.It Pa /boot/forth/loader.4th +Extra builtin-like words. +.It Pa /boot/forth/support.4th +.Pa loader.conf +processing words. +.It Pa /boot/zfsloader +.Nm +itself. +.El +.Sh EXAMPLES +Boot in single user mode: +.Pp +.Dl boot -s +.Pp +Load the kernel, a boot_archive, and then autoboot in five seconds. +Notice that a kernel must be loaded before any other +.Ic load +command is attempted. +.Bd -literal -offset indent +load /platform/i86pc/kernel/amd64/unix +load -t rootfs /platform/i86pc/amd64/boot_archive +autoboot 5 +.Ed +.Sh SEE ALSO +.Xr boot 1M , +.Xr btxld 1onbld , +.Xr loader.conf 5 +.Sh STANDARDS +For the purposes of ANS Forth compliance, loader is an +.Bf Em +ANS Forth System with Environmental Restrictions, Providing +.Ef +.Bf Li +.No .( , +.No :noname , +.No ?do , +parse, pick, roll, refill, to, value, \e, false, true, +.No <> , +.No 0<> , +compile\&, , erase, nip, tuck +.Ef +.Em and +.Li marker +.Bf Em +from the Core Extensions word set, Providing the Exception Extensions +word set, Providing the Locals Extensions word set, Providing the +Memory-Allocation Extensions word set, Providing +.Ef +.Bf Li +\&.s, +bye, forget, see, words, +\&[if], +\&[else] +.Ef +.Em and +.Li [then] +.Bf Em +from the Programming-Tools extension word set, Providing the +Search-Order extensions word set. +.Ef diff --git a/usr/src/man/man5/menu.4th.5 b/usr/src/man/man5/menu.4th.5 new file mode 100644 index 0000000000..e4644008ed --- /dev/null +++ b/usr/src/man/man5/menu.4th.5 @@ -0,0 +1,306 @@ +.\" Copyright (c) 2011-2013 Devin Teske +.\" 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 AUTHOR 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 AUTHOR 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 Apr 22, 2017 +.Dt MENU.4TH 5 +.Os +.Sh NAME +.Nm menu.4th +.Nd loader dynamic menu boot module +.Sh DESCRIPTION +The file that goes by the name of +.Nm +is a set of commands designed to display a dynamic menu system managed through +a system of carefully named environment variables. +The commands of +.Nm +by themselves are not enough for most uses. +Please refer to the +examples below for the most common situations, and to +.Xr loader 5 +for additional commands. +.Pp +Before using any of the commands provided in +.Nm , +it must be included +through the command: +.Pp +.Dl include menu.4th +.Pp +This line is present in the default +.Pa /boot/forth/menu.rc +file, so it is not needed (and should not be re-issued) in a normal setup. +.Pp +The commands provided by it are: +.Pp +.Bl -tag -width disable-module_module -compact -offset indent +.It Ic menu-init +Draws the menu bounding box and initializes some internal state variables. +This should be called before any other menu-related functions. +.It Ic menu-display +Displays the menu (configured via the below documented environment variables) +and blocks on keyboard input, awaiting user action. +.It Ic menu-erase +Clears the screen area within the menu bounding box. +.It Ic menu-redraw +Calls +.Ic menu-erase +and then redraws the menu. +.It Ic menu-unset +Unsets the environment variables associated with individual menu items, +clearing the way for a new menu. +.It Ic menu-clear +Calls +.Ic menu-unset +and then +.Ic menu-erase . +.El +.Pp +The environment variables that effect its behavior are: +.Bl -tag -width bootfile -offset indent +.It Va loader_color +If set to +.Dq Li NO +(case-insensitive) or +.Dq Li 0 , +causes the menu to be displayed without color. +The default is to use ANSI coloring whenever possible. +If serial boot is enabled, color is disabled by default. +Color features include the use of ANSI bold for numbers appearing to the left +of menuitems and the use of special +.Dq Li ansi +variables described below. +.It Va autoboot_delay +Number of seconds +.Ic menu-display +will wait before executing +.Va menu_timeout_command +.Ic ( boot +by default) unless a key is pressed. +If set to +.Dq Li NO +(case-insensitive) +.Ic menu-display +will wait for user input and never execute +.Ic menu_timeout_command . +If set to +.Dq Li -1 , +.Ic menu-display +will boot immediately, preventing both interruption of the +.Ic autoboot +process and escaping to the loader prompt. +Default is +.Dq Li 10 . +See +.Xr loader 8 +for additional information. +.It Va menu_timeout_command +The command to be executed after +.Va autoboot_delay +seconds if a key is not pressed. +The default is +.Ic boot . +.It Va loader_menu_frame +Sets the desired box style to draw around the boot menu. +Possible values are: +.Dq Li single +.Pq the default , +.Dq Li double , +and +.Dq Li none . +.It Va loader_menu_timeout_x +Sets the desired column position of the timeout countdown text. +Default is 4. +.It Va loader_menu_timeout_y +Sets the desired row position of the timeout countdown text. +Default is 23. +.It Va loader_menu_title +The text to display above the menu. +Default is +.Dq Li "Welcome to FreeBSD" . +.It Va loader_menu_title_align +Default is to align +.Ic loader_menu_title +centered above the menu. This can be set to +.Dq Li left +or +.Dq Li right +to instead display the title left-or-right justified +.Pq respectively . +.It Va loader_menu_x +Sets the desired column position of the boot menu. +Default is 5. +.It Va loader_menu_y +Sets the desired row position of the boot menu. +Default is 10. +.It Va menu_caption[x] +The text to be displayed for the numbered menuitem +.Dq Li x . +.It Va menu_command[x] +The command to be executed when the number associated with menuitem +.Dq Li x +is pressed. +See the list of included FICL words below for some ideas. +.It Va menu_keycode[x] +An optional decimal ASCII keycode to be associated with menuitem +.Dq Li x . +When pressed, will cause the execution of +.Va menu_command[x] . +.It Va ansi_caption[x] +If +.Va loader_color +is set +.Pq enabled by default , +use this caption for menuitem +.Dq Li x +instead of +.Va menu_caption[x] . +.It Va toggled_text[x] +For menuitems where +.Va menu_command[x] +is set to +.Dq Li toggle_menuitem +(or a derivative thereof), the text displayed +will toggle between this and +.Va menu_caption[x] . +.It Va toggled_ansi[x] +Like +.Va toggled_text[x] +except used when +.Va loader_color +is enabled +.Pq default . +.It Va menu_caption[x][y] +For menuitems where +.Va menu_command[x] +is set to +.Dq Li cycle_menuitem +(or a derivative thereof), the text displayed will cycle between this and other +.Va menu_caption[x][y] +entries. +.It Va ansi_caption[x][y] +Like +.Va menu_caption[x][y] +except used when +.Va loader_color +is enabled +.Pq default . +.It Va menu_acpi +When set to a number +.Dq Li x +associated with a given menuitem, that menuitem will allow to select +acpi-user-options +.Pq see Xr eeprom 1M . +.It Va menu_options +When set to a number +.Dq Li x , +a single blank-line and an +.Dq Li Options +header are inserted between +.Va menu_caption[x-1] +and +.Va menu_caption[x] +(if configured). +.It Va menu_reboot +If set, adds a built-in +.Dq Li Reboot +menuitem to the end of the last configured menuitem. +If +.Va menu_options +is configured, the +.Dq Li Reboot +menuitem will be inserted before the +.Dq Options +separator. +.El +.Pp +In addition, it provides the following FICL words: +.Pp +.Bl -tag -width disable-module_module -compact -offset indent +.It Ic arch-i386? ( -- BOOL ) +Returns true (-1) on i386 and false (0) otherwise. +.It Ic acpipresent? ( -- BOOL ) +Returns true (-1) if ACPI is present and false (0) otherwise. +.It Ic acpienabled? ( -- BOOL ) +Returns true (-1) if ACPI is enabled and false (0) otherwise. +.It Ic toggle_menuitem ( N -- N ) +Toggles menuitem +.Dq Li N +between +.Va menu_caption[x] +and +.Va toggled_text[x] +(where +.Dq Li N +represents the ASCII decimal value for +.Dq Li x ) . +.It Ic cycle_menuitem ( N -- N ) +Cycles menuitem +.Dq Li N +between +.Va menu_caption[x][y] +entries (where +.Va N +represents the ASCII decimal value for +.Va x ) . +.El +.Pp +For all values of +.Dq Li x +above, use any number between 1 through 9. Sorry, double-digits are not +currently supported. +.Sh FILES +.Bl -tag -width /boot/forth/loader.4th -compact +.It Pa /boot/zfsloader +The +.Xr zfsloader 5 . +.It Pa /boot/forth/menu.4th +.Nm +itself. +.It Pa /boot/loader.rc +.Xr loader 5 +bootstrapping script. +.El +.Sh EXAMPLES +A simple boot menu: +.Pp +.Bd -literal -offset indent -compact +include /boot/forth/menu.4th +menu-init +set menu_caption[1]="Boot" +set menu_command[1]="boot" +set menu_options=2 +set menu_caption[2]="Option: NO" +set toggled_text[2]="Option: YES" +set menu_command[2]="toggle_menuitem" +set menu_timeout_command="boot" +set menu_reboot +menu-display +.Ed +.Sh SEE ALSO +.Xr eeprom 1M , +.Xr loader.conf 4 , +.Xr beastie.4th 5 , +.Xr loader 5 , +.Xr loader.4th 5 diff --git a/usr/src/man/man5/menusets.4th.5 b/usr/src/man/man5/menusets.4th.5 new file mode 100644 index 0000000000..b2584e2030 --- /dev/null +++ b/usr/src/man/man5/menusets.4th.5 @@ -0,0 +1,359 @@ +.\" Copyright (c) 2012 Devin Teske +.\" 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 AUTHOR 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 AUTHOR 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 Apr 22, 2017 +.Dt MENUSETS.4TH 5 +.Os +.Sh NAME +.Nm menusets.4th +.Nd loader dynamic submenu boot module +.Sh DESCRIPTION +The file that goes by the name of +.Nm +is a set of commands designed to add submenu functionality to the dynamic menu +system provided by +.Xr menu.4th 5 . +Submenus are managed through a system of carefully named environment variables. +The commands of +.Nm +by themselves are not enough for most uses. +Please refer to the examples below for the most common situations, and to +.Xr menu.4th 5 +for additional commands. +.Pp +Before using any of the commands provided in +.Nm , +it must be included +through the command: +.Pp +.Dl include menusets.4th +.Pp +This line is present in the default +.Pa /boot/forth/menu-commands.4th +file, so it is not needed (and should not be re-issued) in a normal setup. +.Pp +The commands provided by it are: +.Pp +.Bl -tag -width menuset-loadinitial -compact -offset indent +.It Ic menuset-loadsetnum +Takes a single integer on the stack to identify the menuset environment +variables to be activated (see environment variables below). +.It Ic menuset-loadinitial +If $menuset_initial is set, passes the value to menuset-loadsetnum. +The value must be a number. +.It Ic menusets-unset +Unsets the environment variables associated with all menusets. +Increments starting at 1 and stops at the first unconfigured menuset. +A menuset is considered configured if the caption for item 1 is set. +.El +.Pp +The environment variables that effect its behavior are: +.Bl -tag -width bootfile -offset indent +.It Va menuset_initial +Number to pass to menuset-loadsetnum when menuset-loadinitial is called. +.It Va menuset_nameN +Used to give a name to a menuset. +.El +.Pp +When a menuset is NOT given a name (the default), +menuset N is comprised of the following environment variables: +.Pp +.Bl -tag -width menusetN_caption[x][y] -compact -offset indent +.It Va ansisetN_caption[x] +-> ansi_caption[x] +.It Va ansisetN_caption[x][y] +-> ansi_caption[x][y] +.It Va menusetN_acpi +-> menu_acpi +.It Va menusetN_caption[x] +-> menu_caption[x] +.It Va menusetN_caption[x][y] +-> menu_caption[x][y] +.It Va menusetN_command[x] +-> menu_command[x] +.It Va menusetN_init +-> +.Dq Li evaluated +.It Va menusetN_init[x] +-> menu_init[x] +.It Va menusetN_keycode[x] +-> menu_keycode[x] +.It Va menusetN_options +-> menu_options +.It Va menusetN_optionstext +-> menu_optionstext +.It Va menusetN_reboot +-> menu_reboot +.It Va toggledsetN_ansi[x] +-> toggled_ansi[x] +.It Va toggledsetN_text[x] +-> toggled_text[x] +.El +.Pp +When you choose to give a menuset a name (by setting $menuset_nameN), +menuset N is instead comprised of the following environment variables: +.Pp +.Bl -tag -width NAMEmenu_caption[x][y] -compact -offset indent +.It Va NAMEansi_caption[x] +-> ansi_caption[x] +.It Va NAMEansi_caption[x][y] +-> ansi_caption[x][y] +.It Va NAMEmenu_acpi +-> menu_acpi +.It Va NAMEmenu_caption[x] +-> menu_caption[x] +.It Va NAMEmenu_caption[x][y] +-> menu_caption[x][y] +.It Va NAMEmenu_command[x] +-> menu_command[x] +.It Va NAMEmenu_init +-> +.Dq Li evaluated +.It Va NAMEmenu_init[x] +-> menu_init[x] +.It Va NAMEmenu_keycode[x] +-> menu_keycode[x] +.It Va NAMEmenu_options +-> menu_options +.It Va NAMEmenu_optionstext +-> menu_optionstext +.It Va NAMEmenu_reboot +-> menu_reboot +.It Va NAMEtoggled_ansi[x] +-> toggled_ansi[x] +.It Va NAMEtoggled_text[x] +-> toggled_text[x] +.El +.Pp +where +.Dq Li NAME +is the value of $menuset_nameN. +In the case of $NAMEmenu_init ($menusetN_init when $menuset_nameN is unset), +the value is evaluated as an FICL statement. +This can be used to dynamically adjust the menuset variables right before the +menu is activated. +.Pp +In addition, +.Nm +provides the following FICL words: +.Pp +.Bl -tag -width menuset -compact -offset indent +.It Ic menuset-checksetnum ( N -- ) +Given a single integer on the stack, sets a global variable +.Va menuset_use_name +to a boolean based on whether $menuset_nameN is set (true) or not (false). +Also sets $affix temporary variable (prefix or infix depending on +menuset_use_name). +Automatically called by menuset-loadsetnum and menusets-unset. +.It Ic menuset-loadvar ( -- ) +Used indirectly to shorten syntax and mitigate dictionary size. +Requires the following temporary environment variables: +.Pp +.Bl -tag -width affix -compact -offset indent +.It Va type +should be set to one of: menu toggled ansi +.It Va var +should be set to one of: caption command keycode text ... +.It Va affix +either a prefix (menuset_use_name is true) or infix (menuset_use_name is false) +.El +.Pp +If the global +.Va menuset_use_name +is true, the variable ${type}_${var} is made to +equal the value of the variable ${affix}${type}_${var} +(note: in this case menuset-checksetnum has set $affix to $menuset_nameN). +Otherwise (when +.Va menuset_use_name +is false), the variable ${type}_${var} is made to +equal the value of the variable ${type}set${affix}_${var} +(note: in this case menuset-checksetnum has set $affix to N). +.Pp +Both the global variable +.Va menuset_use_name +and the environment variable $affix are automatically handled by +menuset-checksetnum above (which is automatically called by +menuset-loadsetnum). +.It Ic menuset-unloadvar ( -- ) +Used indirectly to shorten syntax and mitigate dictionary size. +Like menuset-loadvar except it unsets the menuset variable. +If global +.Va menuset_use_name +is true ($affix is $menuset_nameN), +variable ${affix}${type}_${var} is unset. +Otherwise, $affix is N and variable ${type}set${affix}_${var} is unset. +.It Ic menuset-loadmenuvar ( -- ) +Sets $type to +.Dq menu +and calls menuset-loadvar. +.It Ic menuset-unloadmenuvar ( -- ) +Sets $type to +.Dq menu +and calls menuset-unloadvar. +.It Ic menuset-loadxvar ( -- ) +Like menuset-loadvar except it takes an additional temporary variable $x. +If the global +.Va menuset_use_name +is true (making $affix equal $menuset_nameN), +sets variable ${type}_${var}[${x}] to variable ${affix}${type}_${var}[${x}]. +Otherwise ($affix being N), sets the same variable to instead +${type}set{affix}_${var}[${x}]. +.It Ic menuset-unloadxvar ( -- ) +Like menuset-loadxvar except it unsets the menuset variable. +If global +.Va menuset_use_name +is true, unsets ${affix}${type}_${var}[${x}]. +Otherwise, unsets ${type}set${affix}_${var}[${x}]. +.It Ic menuset-loadansixvar ( -- ) +Sets $type to +.Dq ansi +and calls menuset-loadxvar +.It Ic menuset-unloadansixvar ( -- ) +Sets $type to +.Dq ansi +and calls menuset-unloadxvar +.It Ic menuset-loadmenuxvar ( -- ) +Sets $type to +.Dq ansi +and calls menuset-loadxvar +.It Ic menuset-unloadmenuxvar ( -- ) +Sets $type to +.Dq ansi +and calls menuset-unloadxvar +.It Ic menuset-loadtoggledxvar ( -- ) +Sets $type to +.Dq toggled +and calls menuset-loadxvar +.It Ic menuset-unloadtoggledxvar ( -- ) +Sets $type to +.Dq toggled +and calls menuset-unloadxvar +.It Ic menuset-loadxyvar ( -- ) +Like menuset-loadxvar except it takes an additional temporary variable $y. +If the global +.Va menuset_use_name +is true ($affix is $menuset_nameN), +sets variable ${type}_${var}[${x}][${y}] to ${affix}${type}_${var}[${x}][${y}]. +Otherwise ($affix is N) sets the same variable to instead +${type}set${affix}_${var}[${x}][${y}]. +.It Ic menuset-unloadxyvar ( -- ) +Like menuset-loadxyvar except it unsets the menuset variable. +If the global +.Va menuset_use_name +is true, unsets ${affix}${type}_${var}[${x}][${y}]. +Otherwise, unsets ${type}set${affix}_${var}[${x}][${y}]. +.It Ic menuset-loadansixyvar ( -- ) +Sets $type to +.Dq ansi +and calls menuset-loadxyvar. +.It Ic menuset-unloadansixyvar ( -- ) +Sets $type to +.Dq ansi +and calls menuset-unloadxyvar. +.It Ic menuset-loadmenuxyvar ( -- ) +Sets $type to +.Dq menu +and calls menuset-loadxyvar. +.It Ic menuset-unloadmenuxyvar ( -- ) +Sets $type to +.Dq menu +and calls menuset-unloadxyvar. +.It Ic menuset-setnum-namevar ( N -- C-Addr/U ) +Takes a single integer on the stack and replaces it with a string (in c-addr/u +format) whose value is +.Dq menuset_nameN . +For example, if given 1 returns +.Dq menuset_name1 . +.It Ic menuset-cleanup ( N -- ) +Unsets all the various temporary variables, currently +.Va type , +.Va var , +.Va x , +.Va y , +and +.Va affix . +.El +.Pp +For all values of +.Dq Li x +above, use any number between 1 through 9. Sorry, double-digits are not +currently supported. +For all values of +.Dq Li N +above, use any number between 1 and 65535. +.Sh FILES +.Bl -tag -width /boot/menu-commands.4th -compact +.It Pa /boot/zfsloader +The +.Xr zfsloader 5 . +.It Pa /boot/forth/menu.4th +Dynamic menu module. +.It Pa /boot/forth/menu-commands.4th +Contains the goto_menu command. +.It Pa /boot/forth/menusets.4th +.Nm +itself. +.It Pa /boot/loader.rc +.Xr loader 5 +bootstrapping script. +.El +.Sh EXAMPLES +A simple boot menu with a submenu: +.Pp +.Bd -literal -offset indent -compact +include /boot/forth/menu.4th +include /boot/forth/menu-commands.4th +menu-init +set menuset1_caption[1]="Boot" +set menuset1_command[1]="boot" +set menuset1_caption[2]="Submenu..." +set menuset1_command[2]="2 goto_menu" +set menuset2_caption[1]="Back" +set menuset2_command[1]="1 goto_menu" +set menuset_initial=2 +menuset-loadinitial +menu-display +.Ed +.Pp +The same boot menu with named menusets: +.Pp +.Bd -literal -offset indent -compact +include /boot/forth/menu.4th +include /boot/forth/menu-commands.4th +menu-init +set menuset_name1=main +set mainmenu_caption[1]="Boot" +set mainmenu_command[1]="boot" +set mainmenu_caption[2]="Submenu..." +set mainmenu_command[2]="2 goto_menu" +set menuset_name2=sub +set submenu_caption[1]="Back" +set submenu_command[1]="1 goto_menu" +.Ed +.Sh SEE ALSO +.Xr loader.conf 4 , +.Xr beastie.4th 5 , +.Xr loader 5 , +.Xr loader.4th 5 , +.Xr menu.4th 5 diff --git a/usr/src/man/man5/pxeboot.5 b/usr/src/man/man5/pxeboot.5 new file mode 100644 index 0000000000..b6ddfa9f5f --- /dev/null +++ b/usr/src/man/man5/pxeboot.5 @@ -0,0 +1,110 @@ +.\" Copyright (c) 1999 Doug White +.\" 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 AUTHOR 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 AUTHOR 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 Apr 21, 2017 +.Dt PXEBOOT 5 +.Os +.Sh NAME +.Nm pxeboot +.Nd Preboot Execution Environment (PXE) bootloader +.Sh DESCRIPTION +The +.Nm +bootloader is a modified version of the system third-stage bootstrap +.Xr loader 5 +configured to run under Intel's Preboot Execution Environment (PXE) system. +PXE is a form of smart boot ROM, built into Ethernet cards, and +Ethernet-equipped motherboards. +PXE supports DHCP configuration and provides low-level NIC access services. +The +.Nm +bootloader retrieves the kernel, modules, +and other files either via NFS over UDP or by TFTP, +selectable through DHCP options. +.Pp +The +.Nm +binary is loaded just like any other boot file, +by specifying it in the DHCP server's configuration file. +Below is a sample configuration for the ISC DHCP v2 server: +.Bd -literal -offset indent +option domain-name "example.com"; +option routers 10.0.0.1; +option subnet-mask 255.255.255.0; +option broadcast-address 10.0.0.255; +option domain-name-servers 10.0.0.1; +server-name "DHCPserver"; +server-identifier 10.0.0.1; + +default-lease-time 120; +max-lease-time 120; + +subnet 10.0.0.0 netmask 255.255.255.0 { + filename "pxeboot"; + range 10.0.0.10 10.0.0.254; +} + +.Ed +.Pp +.Nm +recognizes +.Va next-server +and +.Va option root-path +directives as the server and path to NFS mount for file requests, +respectively, or the server to make TFTP requests to. +Note that +.Nm +expects to fetch +.Pa /boot/loader.rc +from the specified server before loading any other files. +.Pp +.Nm +defaults to a conservative 1024 byte NFS data packet size. +This may be changed by setting the +.Va nfs.read_size +variable in +.Pa /boot/loader.conf . +Valid values range from 1024 to 4096 bytes. +.Pp +.Nm +defaults to use NFS, to use TFTP loading, DHCP server must provide +option +.Va 150 . +TFTP block size can be controlled by setting the +.Va tftp.blksize +variable in +.Pa /boot/loader.conf . +Valid values range from 8 to 9008 bytes. +.Pp +In all other respects, +.Nm +acts just like +.Xr loader 5 . +.Pp +For further information on Intel's PXE specifications and Wired for +Management (WfM) systems, see +.Li http://www.intel.com/design/archives/wfm/ . +.Sh SEE ALSO +.Xr loader 5 diff --git a/usr/src/man/man5/version.4th.5 b/usr/src/man/man5/version.4th.5 new file mode 100644 index 0000000000..a0d9729294 --- /dev/null +++ b/usr/src/man/man5/version.4th.5 @@ -0,0 +1,115 @@ +.\" Copyright (c) 2011-2013 Devin Teske +.\" 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 AUTHOR 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 AUTHOR 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 Apr 22, 2017 +.Dt VERSION.4TH 5 +.Os +.Sh NAME +.Nm version.4th +.Nd loader version string boot module +.Sh DESCRIPTION +The file that goes by the name of +.Nm +is a set of commands designed to draw the boot loader +version at the bottom-right of the screen. +The commands of +.Nm +by themselves are not enough for most uses. +Please refer to the +examples below for the most common situations, and to +.Xr loader 5 +for additional commands. +.Pp +Before using any of the commands provided in +.Nm , +it must be included +through the command: +.Pp +.Dl include version.4th +.Pp +This line is present in the default +.Pa /boot/forth/menu.rc +file, so it is not needed (and should not be re-issued) in a normal setup. +.Pp +The commands provided by it are: +.Pp +.Bl -tag -width disable-module_module -compact -offset indent +.It Ic print_version +Prints the contents of the +.Va loader_version +environment variable right-justified at the column +.Va loader_version_x +and row +.Va loader_version_y . +.El +.Pp +The environment variables that effect its behavior are: +.Bl -tag -width bootfile -offset indent +.It Va loader_version +Set automatically by +.Xr loader 5 , +but you can override it by setting in +.Xr loader.conf 4 . +This should be the version of boot loader used. +.It Va loader_version_x +Sets the desired ending column position of +.Va loader_version . +Default is 80. +.It Va loader_version_y +Sets the desired ending row position of +.Va loader_version . +Default is 24. +.It Va loader_color +If set to +.Dq Li NO +(case-insensitive) or +.Dq Li 0 , +causes the version to be printed without color +.Pq default is ANSI Cyan . +.El +.Sh FILES +.Bl -tag -width /boot/version.4th -compact +.It Pa /boot/zfsloader +The +.Xr zfsloader 5 . +.It Pa /boot/forth/version.4th +.Nm +itself. +.It Pa /boot/loader.rc +.Xr loader 5 +bootstrapping script. +.El +.Sh EXAMPLES +Override +.Xr loader 5 +version in +.Xr loader.conf 5 : +.Pp +.Bd -literal -offset indent -compact +loader_version="loader 1.1" +.Ed +.Sh SEE ALSO +.Xr loader.conf 4 , +.Xr color.4th 5 , +.Xr loader 5 diff --git a/usr/src/man/man5/zfsloader.5 b/usr/src/man/man5/zfsloader.5 new file mode 100644 index 0000000000..f6b56a9245 --- /dev/null +++ b/usr/src/man/man5/zfsloader.5 @@ -0,0 +1,99 @@ +.\" Copyright (c) 2014 Andriy Gapon <avg@FreeBSD.org> +.\" 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 AUTHOR 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 AUTHOR 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 Apr 20, 2017 +.Dt ZFSLOADER 5 +.Os +.Sh NAME +.Nm zfsloader +.Nd kernel bootstrapping final stage +.Sh DESCRIPTION +.Nm +is an extended variant of +.Xr loader 5 +with added support for booting from ZFS. +This document describes only differences from +.Xr loader 5 . +.Ss ZFS Features +.Nm +supports the following format for specifying ZFS filesystems which +can be used wherever +.Xr loader 5 +refers to a device specification: +.Pp +.Ar zfs:pool/filesystem: +.Pp +where +.Pa pool/filesystem +is a ZFS filesystem name as described in +.Xr zfs 1M . +.Pp +If the variable +.Va fstype +is not set, but +.Va currdev +refers to a ZFS filesystem, then +.Nm +will instruct kernel to use that filesystem as the root filesystem. +.Ss ZFS Command Extensions +.Bl -tag -width Ds -compact +.It Ic lsdev Op Fl v +Lists ZFS pools in addition to disks and partitions. +Adding +.Fl v +shows more ZFS pool details in a format that resembles +.Nm zpool Cm status +output. +.Pp +.It Ic lszfs Ar filesystem +A ZFS extended command that can be used to explore the ZFS filesystem +hierarchy in a pool. +Lists the immediate children of the +.Ar filesystem . +The filesystem hierarchy is rooted at a filesystem with the same name +as the pool. +.El +.Sh FILES +.Bl -tag -width /boot/zfsloader -compact +.It Pa /boot/zfsloader +.Nm +itself. +.El +.Sh EXAMPLES +Set the default device used for loading a kernel from a ZFS filesystem: +.Bd -literal -offset indent +set currdev=zfs:rpool/ROOT/knowngood: +.Ed +.Sh SEE ALSO +.Xr zfs 1M , +.Xr zpool 1M , +.Xr gptzfsboot 5 , +.Xr loader 5 +.Sh NOTES +Although setting the +.Va currdev +as shown in the example above is supported, it is advisable to use loader +beadm command or boot environment menu instead. The reason is, the beadm +or menu selection will also instruct loader to clean up the currently set +configuration and load configuration from the new boot environment. |