Add manual page for zbm-kcl

man/zbm-kcl.8

@@ -0,0 +1,210 @@
+.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings.  \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
+.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+.    ds -- \(*W-
+.    ds PI pi
+.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
+.    ds L" ""
+.    ds R" ""
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds -- \|\(em\|
+.    ds PI \(*p
+.    ds L" ``
+.    ds R" ''
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
+.    \" fudge factors for nroff and troff
+.if n \{\
+.    ds #H 0
+.    ds #V .8m
+.    ds #F .3m
+.    ds #[ \f1
+.    ds #] \fP
+.\}
+.if t \{\
+.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+.    ds #V .6m
+.    ds #F 0
+.    ds #[ \&
+.    ds #] \&
+.\}
+.    \" simple accents for nroff and troff
+.if n \{\
+.    ds ' \&
+.    ds ` \&
+.    ds ^ \&
+.    ds , \&
+.    ds ~ ~
+.    ds /
+.\}
+.if t \{\
+.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+.    \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+.    \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+.    \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+.    ds : e
+.    ds 8 ss
+.    ds o a
+.    ds d- d\h'-1'\(ga
+.    ds D- D\h'-1'\(hy
+.    ds th \o'bp'
+.    ds Th \o'LP'
+.    ds ae ae
+.    ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "zbm-kcl 8"
+.TH zbm-kcl 8 "2022-01-26" "1.12.0" "zbm-kcl"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH "NAME"
+zbm\-kcl \- manipulate kernel command lines for ZFS boot environments
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+\&\fBzbm-kcl\fR [\s-1OPTION\s0]... [\s-1FILESYSTEM\s0]
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+The \fBzbm-kcl\fR utility allows review and manipulation of the \fIorg.zfsbootmenu:commandline\fR property on \s-1ZFS\s0 filesystems. ZFSBootMenu reads this property, as set or inherited on each environment that it recognizes, to set the command line for the kernel that it boots.
+.PP
+When a filesystem is not specified, \fBzbm-kcl\fR will attempt to determine the root filesystem and operate on that.
+.PP
+With no options specified, \fBzbm-kcl\fR will print the current value of \fIorg.zfsbootmenu:commandline\fR on the selected filesystem and exit.
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+.IP "\fB\-a\fR \fIargument\fR" 4
+.IX Item "-a argument"
+Append the value of \fIargument\fR to the kernel command line. The value of \fIargument\fR can be a simple variable name for Boolean arguments or may take the form \fIvar=value\fR to provide a non-Boolean value. If \fIvalue\fR contains spaces, it may be surrounded by double quotes. In that case, surround the argument in single quotes to ensure that the double quotes are recorded in the property:
+.Sp
+.Vb 1
+\&  zbm\-kcl \-a \*(Aqvariable="some argument with spaces"\*(Aq
+.Ve
+.Sp
+This argument may be repeated any number of times.
+.IP "\fB\-r\fR \fIargument\fR" 4
+.IX Item "-r argument"
+Remove \fIargument\fR from the kernel command line. The value of \fIargument\fR can be a simple variable name, in which case all arguments of the form \fIargument\fR or \fIargument=<arbitrary\-value>\fR will be stripped. Alternatively, a specific argument may be selected by specifying \fIargument=<specific\-value>\fR.
+.Sp
+This argument may be repeated any number of times.
+.Sp
+\&\fB\s-1NOTE:\s0\fR All removal options are processed \fIbefore\fR any append options are processed, making it possible to replace an existing argument by combining removal and append options into a single invocation of \fBzbm-kcl\fR.
+.IP "\fB\-e\fR" 4
+.IX Item "-e"
+Open the contents of the command-line property in an interactive editor. If the environment defines \fI\f(CI$EDITOR\fI\fR, that will be used; otherwise, \fBvi\fR will be used by default. After making changes as desired, overwrite the (temporary) file that was opened and quit the editor. If the contents of the command-line property appear to have changed, \fBzbm-kcl\fR will apply those changes.
+.IP "\fB\-d\fR" 4
+.IX Item "-d"
+Delete the command-line property by calling
+.Sp
+.Vb 1
+\&  zfs inherit org.zfsbootmenu:commandline <filesystem>
+.Ve
+.Sp
+This allows the boot environment to inherit any command-line property that may be defined by some parent.
+.IP "\fB\-v\fR" 4
+.IX Item "-v"
+Increase the verbosity of \fBzbm-kcl\fR as it operates. This may be specified up to three times.
+.SH "EXAMPLES"
+.IX Header "EXAMPLES"
+Change the \fIloglevel\fR value on the currently booted environment by removing any existing value from the command line and appending the desired argument:
+.PP
+.Vb 1
+\&  zbm\-kcl \-a loglevel=7 \-r loglevel
+.Ve
+.PP
+Delete the entire command line from the \fIzroot/ROOT/void\fR boot environment, allowing it to inherit a command line set at \fIzroot\fR or \fIzroot/ROOT\fR if either of these defines a value:
+.PP
+.Vb 1
+\&  zbm\-kcl \-d zroot/ROOT/void
+.Ve
+.PP
+Allow interactive editing of the command line on the \fIzroot/ROOT\fR filesystem:
+.PP
+.Vb 1
+\&  zbm\-kcl \-e zroot/ROOT
+.Ve
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fBzfsbootmenu\fR(7)
+.SH "AUTHOR"
+.IX Header "AUTHOR"
+ZFSBootMenu Team <https://github.com/zbm\-dev/zfsbootmenu>

pod/zbm-kcl.8.pod

@@ -0,0 +1,77 @@
+=head1 NAME
+
+B<zbm-kcl> - manipulate kernel command lines for ZFS boot environments
+
+=head1 SYNOPSIS
+
+B<zbm-kcl> [OPTION]... [FILESYSTEM]
+
+=head1 DESCRIPTION
+
+The B<zbm-kcl> utility allows review and manipulation of the I<org.zfsbootmenu:commandline> property on ZFS filesystems. ZFSBootMenu reads this property, as set or inherited on each environment that it recognizes, to set the command line for the kernel that it boots.
+
+When a filesystem is not specified, B<zbm-kcl> will attempt to determine the root filesystem and operate on that.
+
+With no options specified, B<zbm-kcl> will print the current value of I<org.zfsbootmenu:commandline> on the selected filesystem and exit.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-a> I<argument>
+
+Append the value of I<argument> to the kernel command line. The value of I<argument> can be a simple variable name for Boolean arguments or may take the form I<var=value> to provide a non-Boolean value. If I<value> contains spaces, it may be surrounded by double quotes. In that case, surround the argument in single quotes to ensure that the double quotes are recorded in the property:
+
+  zbm-kcl -a 'variable="some argument with spaces"'
+
+This argument may be repeated any number of times.
+
+=item B<-r> I<argument>
+
+Remove I<argument> from the kernel command line. The value of I<argument> can be a simple variable name, in which case all arguments of the form I<argument> or I<argument=E<lt>arbitrary-valueE<gt>> will be stripped. Alternatively, a specific argument may be selected by specifying I<argument=E<lt>specific-valueE<gt>>.
+
+This argument may be repeated any number of times.
+
+B<NOTE:> All removal options are processed I<before> any append options are processed, making it possible to replace an existing argument by combining removal and append options into a single invocation of B<zbm-kcl>.
+
+=item B<-e>
+
+Open the contents of the command-line property in an interactive editor. If the environment defines I<$EDITOR>, that will be used; otherwise, B<vi> will be used by default. After making changes as desired, overwrite the (temporary) file that was opened and quit the editor. If the contents of the command-line property appear to have changed, B<zbm-kcl> will apply those changes.
+
+=item B<-d>
+
+Delete the command-line property by calling
+
+  zfs inherit org.zfsbootmenu:commandline <filesystem>
+
+This allows the boot environment to inherit any command-line property that may be defined by some parent.
+
+=item B<-v>
+
+Increase the verbosity of B<zbm-kcl> as it operates. This may be specified up to three times.
+
+=back
+
+=head1 EXAMPLES
+
+Change the I<loglevel> value on the currently booted environment by removing any existing value from the command line and appending the desired argument:
+
+  zbm-kcl -a loglevel=7 -r loglevel
+
+Delete the entire command line from the I<zroot/ROOT/void> boot environment, allowing it to inherit a command line set at I<zroot> or I<zroot/ROOT> if either of these defines a value:
+
+  zbm-kcl -d zroot/ROOT/void
+
+Allow interactive editing of the command line on the I<zroot/ROOT> filesystem:
+
+  zbm-kcl -e zroot/ROOT
+
+=head1 SEE ALSO
+
+B<zfsbootmenu>(7)
+
+=head1 AUTHOR
+
+ZFSBootMenu Team L<https://github.com/zbm-dev/zfsbootmenu>
+
+=cut

releng/pod2man.sh

@@ -6,9 +6,10 @@ release="${1?ERROR: no release version specified}"
 # Generate man pages from pod documentation
 zbmconfig="pod/generate-zbm.5.pod"
 zbmsystem="pod/zfsbootmenu.7.pod"
+zbmkcl="pod/zbm-kcl.8.pod"
 genzbm="bin/generate-zbm"
 
-for src in "${zbmconfig}" "${zbmsystem}" "${genzbm}"; do
+for src in "${zbmconfig}" "${zbmsystem}" "${zbmkcl}" "${genzbm}"; do
 	if [ ! -r "${src}" ]; then
 		echo "ERROR: POD source '${src}' does not exist"
 		exit 1
@@ -28,3 +29,6 @@ pod2man "${zbmsystem}" -c "ZFSBootMenu" \
 
 pod2man "${genzbm}" -c "generate-zbm" \
   -r "${release}" -s 8 -n generate-zbm > man/generate-zbm.8
+
+pod2man "${zbmkcl}" -c "zbm-kcl" \
+  -r "${release}" -s 8 -n zbm-kcl > man/zbm-kcl.8