Skip to content

Commit 20a8ac7

Browse files
ahesfordahesford
committed
Add manual page for zbm-kcl
1 parent 7477f0d commit 20a8ac7

File tree

3 files changed

+292
-1
lines changed

3 files changed

+292
-1
lines changed

‎man/zbm-kcl.8‎

Lines changed: 210 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,210 @@
1+
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
2+
.\"
3+
.\" Standard preamble:
4+
.\" ========================================================================
5+
.de Sp \" Vertical space (when we can't use .PP)
6+
.if t .sp .5v
7+
.if n .sp
8+
..
9+
.de Vb \" Begin verbatim text
10+
.ft CW
11+
.nf
12+
.ne \\$1
13+
..
14+
.de Ve \" End verbatim text
15+
.ft R
16+
.fi
17+
..
18+
.\" Set up some character translations and predefined strings. \*(-- will
19+
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
20+
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
21+
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
22+
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
23+
.\" nothing in troff, for use with C<>.
24+
.tr \(*W-
25+
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
26+
.ie n \{\
27+
. ds -- \(*W-
28+
. ds PI pi
29+
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30+
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
31+
. ds L" ""
32+
. ds R" ""
33+
. ds C` ""
34+
. ds C' ""
35+
'br\}
36+
.el\{\
37+
. ds -- \|\(em\|
38+
. ds PI \(*p
39+
. ds L" ``
40+
. ds R" ''
41+
. ds C`
42+
. ds C'
43+
'br\}
44+
.\"
45+
.\" Escape single quotes in literal strings from groff's Unicode transform.
46+
.ie \n(.g .ds Aq \(aq
47+
.el .ds Aq '
48+
.\"
49+
.\" If the F register is >0, we'll generate index entries on stderr for
50+
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
51+
.\" entries marked with X<> in POD. Of course, you'll have to process the
52+
.\" output yourself in some meaningful fashion.
53+
.\"
54+
.\" Avoid warning from groff about undefined register 'F'.
55+
.de IX
56+
..
57+
.nr rF 0
58+
.if \n(.g .if rF .nr rF 1
59+
.if (\n(rF:(\n(.g==0)) \{\
60+
. if \nF \{\
61+
. de IX
62+
. tm Index:\\$1\t\\n%\t"\\$2"
63+
..
64+
. if !\nF==2 \{\
65+
. nr % 0
66+
. nr F 2
67+
. \}
68+
. \}
69+
.\}
70+
.rr rF
71+
.\"
72+
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
73+
.\" Fear. Run. Save yourself. No user-serviceable parts.
74+
. \" fudge factors for nroff and troff
75+
.if n \{\
76+
. ds #H 0
77+
. ds #V .8m
78+
. ds #F .3m
79+
. ds #[ \f1
80+
. ds #] \fP
81+
.\}
82+
.if t \{\
83+
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
84+
. ds #V .6m
85+
. ds #F 0
86+
. ds #[ \&
87+
. ds #] \&
88+
.\}
89+
. \" simple accents for nroff and troff
90+
.if n \{\
91+
. ds ' \&
92+
. ds ` \&
93+
. ds ^ \&
94+
. ds , \&
95+
. ds ~ ~
96+
. ds /
97+
.\}
98+
.if t \{\
99+
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
100+
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
101+
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
102+
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
103+
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
104+
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
105+
.\}
106+
. \" troff and (daisy-wheel) nroff accents
107+
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
108+
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
109+
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
110+
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
111+
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
112+
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
113+
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
114+
.ds ae a\h'-(\w'a'u*4/10)'e
115+
.ds Ae A\h'-(\w'A'u*4/10)'E
116+
. \" corrections for vroff
117+
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
118+
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
119+
. \" for low resolution devices (crt and lpr)
120+
.if \n(.H>23 .if \n(.V>19 \
121+
\{\
122+
. ds : e
123+
. ds 8 ss
124+
. ds o a
125+
. ds d- d\h'-1'\(ga
126+
. ds D- D\h'-1'\(hy
127+
. ds th \o'bp'
128+
. ds Th \o'LP'
129+
. ds ae ae
130+
. ds Ae AE
131+
.\}
132+
.rm #[ #] #H #V #F C
133+
.\" ========================================================================
134+
.\"
135+
.IX Title "zbm-kcl 8"
136+
.TH zbm-kcl 8 "2022-01-26" "1.12.0" "zbm-kcl"
137+
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
138+
.\" way too many mistakes in technical documents.
139+
.if n .ad l
140+
.nh
141+
.SH "NAME"
142+
zbm\-kcl \- manipulate kernel command lines for ZFS boot environments
143+
.SH "SYNOPSIS"
144+
.IX Header "SYNOPSIS"
145+
\&\fBzbm-kcl\fR [\s-1OPTION\s0]... [\s-1FILESYSTEM\s0]
146+
.SH "DESCRIPTION"
147+
.IX Header "DESCRIPTION"
148+
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.
149+
.PP
150+
When a filesystem is not specified, \fBzbm-kcl\fR will attempt to determine the root filesystem and operate on that.
151+
.PP
152+
With no options specified, \fBzbm-kcl\fR will print the current value of \fIorg.zfsbootmenu:commandline\fR on the selected filesystem and exit.
153+
.SH "OPTIONS"
154+
.IX Header "OPTIONS"
155+
.IP "\fB\-a\fR \fIargument\fR" 4
156+
.IX Item "-a argument"
157+
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:
158+
.Sp
159+
.Vb 1
160+
\& zbm\-kcl \-a \*(Aqvariable="some argument with spaces"\*(Aq
161+
.Ve
162+
.Sp
163+
This argument may be repeated any number of times.
164+
.IP "\fB\-r\fR \fIargument\fR" 4
165+
.IX Item "-r argument"
166+
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.
167+
.Sp
168+
This argument may be repeated any number of times.
169+
.Sp
170+
\&\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.
171+
.IP "\fB\-e\fR" 4
172+
.IX Item "-e"
173+
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.
174+
.IP "\fB\-d\fR" 4
175+
.IX Item "-d"
176+
Delete the command-line property by calling
177+
.Sp
178+
.Vb 1
179+
\& zfs inherit org.zfsbootmenu:commandline <filesystem>
180+
.Ve
181+
.Sp
182+
This allows the boot environment to inherit any command-line property that may be defined by some parent.
183+
.IP "\fB\-v\fR" 4
184+
.IX Item "-v"
185+
Increase the verbosity of \fBzbm-kcl\fR as it operates. This may be specified up to three times.
186+
.SH "EXAMPLES"
187+
.IX Header "EXAMPLES"
188+
Change the \fIloglevel\fR value on the currently booted environment by removing any existing value from the command line and appending the desired argument:
189+
.PP
190+
.Vb 1
191+
\& zbm\-kcl \-a loglevel=7 \-r loglevel
192+
.Ve
193+
.PP
194+
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:
195+
.PP
196+
.Vb 1
197+
\& zbm\-kcl \-d zroot/ROOT/void
198+
.Ve
199+
.PP
200+
Allow interactive editing of the command line on the \fIzroot/ROOT\fR filesystem:
201+
.PP
202+
.Vb 1
203+
\& zbm\-kcl \-e zroot/ROOT
204+
.Ve
205+
.SH "SEE ALSO"
206+
.IX Header "SEE ALSO"
207+
\&\fBzfsbootmenu\fR(7)
208+
.SH "AUTHOR"
209+
.IX Header "AUTHOR"
210+
ZFSBootMenu Team <https://github.com/zbm\-dev/zfsbootmenu>

‎pod/zbm-kcl.8.pod‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
=head1 NAME
2+
3+
B<zbm-kcl> - manipulate kernel command lines for ZFS boot environments
4+
5+
=head1 SYNOPSIS
6+
7+
B<zbm-kcl> [OPTION]... [FILESYSTEM]
8+
9+
=head1 DESCRIPTION
10+
11+
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.
12+
13+
When a filesystem is not specified, B<zbm-kcl> will attempt to determine the root filesystem and operate on that.
14+
15+
With no options specified, B<zbm-kcl> will print the current value of I<org.zfsbootmenu:commandline> on the selected filesystem and exit.
16+
17+
=head1 OPTIONS
18+
19+
=over 4
20+
21+
=item B<-a> I<argument>
22+
23+
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:
24+
25+
zbm-kcl -a 'variable="some argument with spaces"'
26+
27+
This argument may be repeated any number of times.
28+
29+
=item B<-r> I<argument>
30+
31+
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>>.
32+
33+
This argument may be repeated any number of times.
34+
35+
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>.
36+
37+
=item B<-e>
38+
39+
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.
40+
41+
=item B<-d>
42+
43+
Delete the command-line property by calling
44+
45+
zfs inherit org.zfsbootmenu:commandline <filesystem>
46+
47+
This allows the boot environment to inherit any command-line property that may be defined by some parent.
48+
49+
=item B<-v>
50+
51+
Increase the verbosity of B<zbm-kcl> as it operates. This may be specified up to three times.
52+
53+
=back
54+
55+
=head1 EXAMPLES
56+
57+
Change the I<loglevel> value on the currently booted environment by removing any existing value from the command line and appending the desired argument:
58+
59+
zbm-kcl -a loglevel=7 -r loglevel
60+
61+
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:
62+
63+
zbm-kcl -d zroot/ROOT/void
64+
65+
Allow interactive editing of the command line on the I<zroot/ROOT> filesystem:
66+
67+
zbm-kcl -e zroot/ROOT
68+
69+
=head1 SEE ALSO
70+
71+
B<zfsbootmenu>(7)
72+
73+
=head1 AUTHOR
74+
75+
ZFSBootMenu Team L<https://github.com/zbm-dev/zfsbootmenu>
76+
77+
=cut

‎releng/pod2man.sh‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,10 @@ release="${1?ERROR: no release version specified}"
66
# Generate man pages from pod documentation
77
zbmconfig="pod/generate-zbm.5.pod"
88
zbmsystem="pod/zfsbootmenu.7.pod"
9+
zbmkcl="pod/zbm-kcl.8.pod"
910
genzbm="bin/generate-zbm"
1011

11-
for src in "${zbmconfig}" "${zbmsystem}" "${genzbm}"; do
12+
for src in "${zbmconfig}" "${zbmsystem}" "${zbmkcl}" "${genzbm}"; do
1213
if [ ! -r "${src}" ]; then
1314
echo "ERROR: POD source '${src}' does not exist"
1415
exit 1
@@ -28,3 +29,6 @@ pod2man "${zbmsystem}" -c "ZFSBootMenu" \
2829

2930
pod2man "${genzbm}" -c "generate-zbm" \
3031
-r "${release}" -s 8 -n generate-zbm > man/generate-zbm.8
32+
33+
pod2man "${zbmkcl}" -c "zbm-kcl" \
34+
-r "${release}" -s 8 -n zbm-kcl > man/zbm-kcl.8

0 commit comments

Comments
 (0)