Resurrect usage.hlp and securelevel.hlp from sysinstall(8) and integrate them

into bsdconfig(8).

Approved by:	adrian (co-mentor) (implicit)

usr.sbin/bsdconfig/bsdconfig

@@ -37,7 +37,8 @@ f_include $BSDCFG_SHARE/strings.subr
 
 BSDCFG_LIBE="/usr/libexec/bsdconfig"
 f_include_lang $BSDCFG_LIBE/include/messages.subr
-f_include_help $BSDCFG_LIBE/include/bsdconfig.hlp
+f_include_help BSDCONFIG $BSDCFG_LIBE/include/bsdconfig.hlp
+f_include_help USAGE     $BSDCFG_LIBE/include/usage.hlp
 
 ############################################################ FUNCTIONS
 
@@ -141,12 +142,13 @@ dialog_menu_main()
 	local menu_list size
 
 	menu_list="
-		'X' '$msg_exit' '$msg_exit_bsdconfig'
+		'X' '$msg_exit'  '$msg_exit_bsdconfig'
+		'1' '$msg_usage' '$msg_quick_start_how_to_use_this_menu_system'
 	" # END-QUOTE
 
 	local sanitize_awk="{ gsub(/'/, \"'\\\\''\"); print }"
 
-	local menuitem menu_title menu_help menu_selection index=1
+	local menuitem menu_title menu_help menu_selection index=2
 	for menuitem in $( ls -d [0-9][0-9][0-9].* ); do
 		[ $index -lt ${#DIALOG_MENU_TAGS} ] || break
 		tag=$( f_substr "$DIALOG_MENU_TAGS" $index 1 )
@@ -187,7 +189,7 @@ dialog_menu_main()
 		--ok-label \"\$msg_ok\"                 \
 		--cancel-label \"\$msg_exit_bsdconfig\" \
 		--help-button                           \
-	${USE_XDIALOG:+--help \"\$( f_include_help )\"} \
+		${USE_XDIALOG:+--help \"\$( f_include_help BSDCONFIG )\"} \
 		--menu \"\$prompt\" $size $menu_list    \
 		2>&1 >&$DIALOG_TERMINAL_PASSTHRU_FD
 	)
@@ -300,7 +302,7 @@ while :; do
 
 	if [ $retval -eq 2 ]; then
 		# The Help button was pressed
-		f_show_msg "%s" "$( f_include_help )"
+		f_show_msg "%s" "$( f_include_help BSDCONFIG )"
 		continue
 	elif [ $retval -ne 0 ]; then
 		f_die
@@ -311,6 +313,11 @@ while :; do
 	   break
 	   ;;
 
+	1) # Usage
+	   f_show_msg "%s" "$( f_include_help USAGE )"
+	   continue
+	   ;;
+
 	*) # Dynamically loaded menuitem
 	   cmd=$( eval echo \"\$menu_program$mtag\" )
 	   f_dprintf "cmd=[$cmd]"

usr.sbin/bsdconfig/include/Makefile

@@ -3,7 +3,7 @@
 NO_OBJ=
 
 FILESDIR=	${LIBEXECDIR}/bsdconfig/include
-FILES=		bsdconfig.hlp messages.subr
+FILES=		bsdconfig.hlp messages.subr usage.hlp
 
 beforeinstall:
 	mkdir -p ${DESTDIR}${FILESDIR}

usr.sbin/bsdconfig/include/messages.subr

@@ -51,11 +51,13 @@ msg_permission_denied="%s: %s: Permission denied"
 msg_please_enter_password="Please enter your password for sudo(8):"
 msg_please_enter_username_password="Please enter a username and password for sudo(8):"
 msg_previous_syntax_errors="%s: Not overwriting \`%s' due to previous syntax errors"
+msg_quick_start_how_to_use_this_menu_system="Quick start - How to use this menu system"
 msg_secure_mode_requires_x11="Secure-mode requires X11 (use \`-X')!"
 msg_secure_mode_requires_root="Secure-mode requires root-access!"
 msg_sorry_try_again="Sorry, try again."
 msg_try_sudo_only_this_once="Try sudo(8) only this once"
 msg_unknown_user="Unknown user: %s"
+msg_usage="Usage"
 msg_user_disallowed="User disallowed: %s"
 msg_yes="Yes"
 msg_you_are_not_root_but="You are not root but %s can use sudo(8).\nWhat would you like to do?"

usr.sbin/bsdconfig/include/usage.hlp

@@ -0,0 +1,64 @@
+HOW TO USE THIS SYSTEM
+======================
+
+[press the PageDown key to go to the next screen when you finish
+ reading this one]
+
+The following keys are recognized in most of the dialogs you'll
+encounter during this installation:
+
+KEY             ACTION
+---             ------
+SPACE           Select or toggle the current item.
+ENTER           Finish with a menu or item.
+UP ARROW        Move to previous item (or up, in a text display box).
+DOWN ARROW      Move to next item (or down, in a text display box).
+TAB             Move to next item or group.
+RIGHT ARROW     Move to next item or group (same as TAB).
+SHIFT-TAB       Move to previous item or group.
+LEFT ARROW      Move to previous item or group (same as SHIFT-TAB).
+PAGE UP         In text display boxes, scrolls up one page.
+PAGE DOWN       In text display boxes, scrolls down one page.
+F1              Display associated help text.
+
+If you see small "^(-)" or "v(+)" symbols at the edges of a menu, it
+means that there are more items above or below the current one that
+aren't being shown (due to insufficient screen space).  In text
+display boxes, the amount of text above the current point will be
+displayed as a percentage in the lower right corner.  Using the
+Up/Down arrow keys will cause the object to scroll by line.  The
+PageUp and PageDown keys will scroll by entire screens.
+
+Selecting OK in a menu will confirm whatever action it's controlling.
+Selecting Cancel will cancel the operation and generally return you to
+the previous menu. Use TAB to move the cursor around and select the
+buttons.
+
+Most screens offer a Help button - USE IT!  It generally offers useful
+context-specific hints on what to do and if you're at all unsure about
+what to do at a given configuration menu, choose Help!
+
+
+SPECIAL FEATURES:
+=================
+
+It is possible to select a menu item by typing the first character of
+its name, if unique.  This will generally be an item number.
+
+The console driver contains a scroll-back buffer for reviewing things
+that may have scrolled off the screen.  To use scroll-back, press the
+"Scroll Lock" key on your keyboard and use the arrow or Page Up/Page
+Down keys to move through the saved text.  To leave scroll-back mode,
+press the Scroll Lock key again.  This feature is most useful for
+reading back through your boot messages (go ahead, try it now!) though
+it's also useful when dealing with sub-shells or other "expert modes"
+that don't use menus and tend to scroll their output off the top of
+the screen.
+
+FreeBSD also supports multiple "virtual consoles" which you can use
+in order to have several active sessions at once.  Use ALT-F<n> to
+switch between screens, where `F<n>' is the function key corresponding
+to the screen you wish to see.  By default, the system comes with 8
+virtual consoles enabled - you can enable more by editing the
+/etc/ttys file and turning the "off" field to "on" in the relevant vty
+entries (up to 12).

usr.sbin/bsdconfig/security/include/Makefile

@@ -3,7 +3,7 @@
 NO_OBJ=
 
 FILESDIR=	${LIBEXECDIR}/bsdconfig/130.security/include
-FILES=		messages.subr
+FILES=		messages.subr securelevel.hlp
 
 beforeinstall:
 	mkdir -p ${DESTDIR}${FILESDIR}

usr.sbin/bsdconfig/security/include/securelevel.hlp

@@ -0,0 +1,40 @@
+This menu allows you to configure the Securelevel mechanism in FreeBSD.
+
+Securelevels may be used to limit the privileges assigned to the
+root user in multi-user mode, which in turn may limit the effects of
+a root compromise, at the cost of reducing administrative functions.
+Refer to the security(7) and init(8) manual pages for complete details.
+
+   -1    Permanently insecure mode - always run the system in level 0
+         mode.  This is the default initial value.
+
+   0     Insecure mode - immutable and append-only flags may be turned
+         off.  All devices may be read or written subject to their
+         permissions.
+
+   1     Secure mode - the system immutable and system append-only
+         flags may not be turned off; disks for mounted file systems,
+         /dev/mem, /dev/kmem and /dev/io (if your platform has it)
+         may not be opened for writing; kernel modules (see kld(4))
+         may not be loaded or unloaded.
+
+   2     Highly secure mode - same as secure mode, plus disks may not
+         be opened for writing (except by mount(2)) whether mounted or
+         not.  This level precludes tampering with file systems by
+         unmounting them, but also inhibits running newfs(8) while the
+         system is multi-user.
+
+         In addition, kernel time changes are restricted to less than
+         or equal to one second.  Attempts to change the time by more
+         than this will log the message ``Time adjustment clamped to +1
+         second''.
+
+   3     Network secure mode - same as highly secure mode, plus IP
+         packet filter rules (see ipfw(8), ipfirewall(4) and pfctl(8))
+         cannot be changed and dummynet(4) or pf(4) configuration
+         cannot be adjusted.
+
+Securelevels must be used in combination with careful system design and
+application of protective mechanisms to prevent system configuration
+files from being modified in a way that compromises the protections of
+the securelevel variable upon reboot.

usr.sbin/bsdconfig/security/kern_securelevel

@@ -36,6 +36,7 @@ f_include $BSDCFG_SHARE/sysrc.subr
 
 BSDCFG_LIBE="/usr/libexec/bsdconfig" APP_DIR="130.security"
 f_include_lang $BSDCFG_LIBE/$APP_DIR/include/messages.subr
+f_include_help SECURELEVEL $BSDCFG_LIBE/$APP_DIR/include/securelevel.hlp
 
 ipgm=$( f_index_menu_selection $BSDCFG_LIBE/$APP_DIR/INDEX "$pgm" )
 [ $? -eq $SUCCESS -a "$ipgm" ] && pgm="$ipgm"
@@ -74,6 +75,8 @@ dialog_menu_main()
 		--hline \"\$hline\"                \
 		--ok-label \"\$msg_ok\"            \
 		--cancel-label \"\$msg_cancel\"    \
+		--help-button                      \
+		${USE_XDIALOG:+--help \"\$( f_include_help SECURELEVEL )\"} \
 		--menu \"\$prompt\" $size          \
 		$menu_list                         \
 		2>&1 >&$DIALOG_TERMINAL_PASSTHRU_FD
@@ -109,11 +112,21 @@ f_mustberoot_init
 #
 # Launch application main menu
 #
-dialog_menu_main
-retval=$?
-mtag=$( f_dialog_menutag )
+while :; do
+	dialog_menu_main
+	retval=$?
+	mtag=$( f_dialog_menutag )
 
-[ $retval -eq 0 ] || f_die
+	if [ $retval -eq 2 ]; then
+		# The Help button was pressed
+		f_show_msg "%s" "$( f_include_help SECURELEVEL )"
+		continue
+	elif [ $retval -ne 0 ]; then
+		f_die
+	fi
+
+	break
+done
 
 case "$mtag" in
 "$msg_disabled")

usr.sbin/bsdconfig/share/common.subr

@@ -179,41 +179,37 @@ f_include_lang()
 	fi
 }
 
-# f_include_help [$file]
+# f_include_help NAME [$file]
 #
-# When given an argument, cache the contents of a language help-file (to later
-# be retrieved by executing again without arguments).
+# When given both arguments, cache the contents of a language help-file to
+# later be retrieved by executing again with only the first argument.
 #
 # Automatically takes $LANG and $LC_ALL into consideration when reading $file
 # (suffix ".$LC_ALL" or ".$LANG" will automatically be added prior to loading
 # the language help-file).
 #
-# No error is produced if (a) a language has been requested (by setting either
-# $LANG or $LC_ALL in the environment) and (b) the language help-file does not
-# exist -- in which case we will fall back to loading $file without-suffix.
+# If a language has been requested by setting either $LANG or $LC_ALL in the
+# environment and the language-specific help-file does not exist we will fall
+# back to $file without-suffix.
 #
 # If the language help-file does not exist, an error is cached in place of the
 # help-file contents.
 #
-# When called without arguments, the cached value (if any) is produced. Each
-# time this function is called, the cache is overwritten with the newly loaded
-# contents.
-#
 f_include_help()
 {
-	local file="$1"
+	local name="$1" file="$2"
 
 	if [ "$file" ]; then
 		local lang="${LANG:-$LC_ALL}"
 
-		f_dprintf "lang=[$lang]"
+		f_dprintf "name=[$name] lang=[$lang]"
 		if [ -f "$file.$lang" ]; then
-			setvar HELP_$$ "$( cat "$file.$lang" 2>&1 )"
+			setvar HELP_${name}_$$ "$( cat "$file.$lang" 2>&1 )"
 		else
-			setvar HELP_$$ "$( cat "$file" 2>&1 )"
+			setvar HELP_${name}_$$ "$( cat "$file" 2>&1 )"
 		fi
 	else
-		eval echo \"\$HELP_$$\"
+		eval echo \"\$HELP_${name}_$$\"
 	fi
 }