[DSE-Dev] Bug#1096015: semanage.conf.5: Some remarks and a patch with editorial changes for this man page
Bjarni Ingi Gislason
bjarniig at simnet.is
Sat Feb 15 09:27:16 GMT 2025
Package: libsemanage-common
Version: 3.7-2.1
Severity: minor
Tags: patch
* What led up to the situation?
Checking for defects with a new version
test-[g|n]roff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z < "man page"
[Use "groff -e ' $' -e '\\~$' <file>" to find obvious trailing spaces.]
["test-groff" is a script in the repository for "groff"; is not shipped]
(local copy and "troff" slightly changed by me).
[The fate of "test-nroff" was decided in groff bug #55941.]
* What was the outcome of this action?
an.tmac:<stdin>:7: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:50: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:61: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
troff:<stdin>:81: warning: trailing space in the line
troff:<stdin>:82: warning: trailing space in the line
an.tmac:<stdin>:92: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:115: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:117: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an-end-check:<stdin>: Warning: Different number of .RS and .RE calls, an-RS-open=1 at end of file
* What outcome did you expect instead?
No output (no warnings).
-.-
General remarks and further material, if a diff-file exist, are in the
attachments.
-- System Information:
Debian Release: trixie/sid
APT prefers testing
APT policy: (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.12.12-amd64 (SMP w/2 CPU threads; PREEMPT)
Locale: LANG=is_IS.iso88591, LC_CTYPE=is_IS.iso88591 (charmap=ISO-8859-1), LANGUAGE not set
Shell: /bin/sh linked to /usr/bin/dash
Init: sysvinit (via /sbin/init)
-- no debconf information
-------------- next part --------------
Input file is semanage.conf.5
Output from "mandoc -T lint semanage.conf.5": (shortened list)
1 input text line longer than 80 bytes: Each line should con...
1 input text line longer than 80 bytes: If the argument begi...
1 input text line longer than 80 bytes: If the argument does...
1 input text line longer than 80 bytes: If the cache is igno...
1 input text line longer than 80 bytes: In order to compile ...
1 input text line longer than 80 bytes: It can be set to "de...
1 input text line longer than 80 bytes: It can be set to eit...
2 input text line longer than 80 bytes: It controls whether ...
1 input text line longer than 80 bytes: It should be in the ...
1 input text line longer than 80 bytes: List, separated by "...
1 input text line longer than 80 bytes: Management library w...
1 input text line longer than 80 bytes: Please note that sin...
1 input text line longer than 80 bytes: Specify an alternati...
1 input text line longer than 80 bytes: Specify how the SELi...
1 input text line longer than 80 bytes: The SELinux manageme...
1 input text line longer than 80 bytes: The target platform ...
1 input text line longer than 80 bytes: This option override...
2 input text line longer than 80 bytes: When set to "true", ...
1 input text line longer than 80 bytes: Whether or not to en...
1 input text line longer than 80 bytes: Whether or not to ig...
1 input text line longer than 80 bytes: command and it can b...
1 input text line longer than 80 bytes: command. It can be s...
1 input text line longer than 80 bytes: either "true" or "fa...
1 input text line longer than 80 bytes: file is usually loca...
1 input text line longer than 80 bytes: option with semodule...
1 input text line longer than 80 bytes: to be used through a...
1 input text line longer than 80 bytes: will set the policy ...
1 skipping paragraph macro: PP after SH
1 skipping paragraph macro: PP empty
1 skipping paragraph macro: sp after PP
5 whitespace at end of input line
-.-.
Output from "test-groff -mandoc -t -ww -z semanage.conf.5": (shortened list)
6 Use macro '.B' for one argument or split argument.
6 .BR is for at least 2 arguments, got 1
2 trailing space in the line
-.-.
Remove space characters (whitespace) at the end of lines.
Use "git apply ... --whitespace=fix" to fix extra space issues, or use
global configuration "core.whitespace".
Number of lines affected is
5
-.-.
Change '-' (\-) to '\(en' (en-dash) for a (numeric) range.
GNU gnulib has recently (2023-06-18) updated its
"build_aux/update-copyright" to recognize "\(en" in man pages.
semanage.conf.5:103:It should be in the range 0-9. A value of 0 means no compression. By default the bzip block size is set to 9 (actual block
-.-.
Wrong distance between sentences in the input file.
Separate the sentences and subordinate clauses; each begins on a new
line. See man-pages(7) ("Conventions for source file layout") and
"info groff" ("Input Conventions").
The best procedure is to always start a new sentence on a new line,
at least, if you are typing on a computer.
Remember coding: Only one command ("sentence") on each (logical) line.
E-mail: Easier to quote exactly the relevant lines.
Generally: Easier to edit the sentence.
Patches: Less unaffected text.
Search for two adjacent words is easier, when they belong to the same line,
and the same phrase.
The amount of space between sentences in the output can then be
controlled with the ".ss" request.
Mark a final abbreviation point as such by suffixing it with "\&".
Some sentences (etc.) do not begin on a new line.
13:parameter. Anything after the "#" symbol is ignored similarly to empty lines.
21:Specify how the SELinux Management library should interact with the SELinux policy store. When set to "direct", the SELinux
32:Specify an alternative root path to use for the store. The default is "/"
36:Specify an alternative store_root path to use. The default is "/var/lib/selinux"
40:Specify an alternative directory that contains HLL to CIL compilers. The default value is "/usr/libexec/selinux/hll".
44:Whether or not to ignore the cache of CIL modules compiled from HLL. It can be set to either "true" or "false" and is set to "false" by default.
51:will set the policy version to POLICYDB_VERSION_MAX, as defined in <sepol/policydb/policydb.h>. Change this setting if a different
56:The target platform to generate policies for. Valid values are "selinux" and "xen", and is set to "selinux" by default.
62:command. It can be set to either "0" (disabled) or "1" (enabled) and by default it is enabled. There might be a large
72:either "true" or "false". By default it is set to "false" (the previous version is deleted).
86:Whether or not to enable the use getpwent() to obtain a list of home directories to label. It can be set to either "true" or "false".
93:command and it can be set to either "false" or "true". By default the genhomedircon functionality is enabled (equivalent
99:It can be set to "deny", "reject" or "allow". By default the setting from the policy is taken.
103:It should be in the range 0-9. A value of 0 means no compression. By default the bzip block size is set to 9 (actual block
108:When set to "true", the bzip algorithm shall try to reduce its system memory usage. It can be set to either "true" or "false" and
113:When set to "true", HLL files will be removed after compilation into CIL. In order to delete HLL files already compiled into CIL,
118:option with semodule. The remove-hll option can be set to either "true" or "false"
-.-.
Split lines longer than 80 characters into two or more lines.
Appropriate break points are the end of a sentence and a subordinate
clause; after punctuation marks.
Line 1, length 84
.TH semanage.conf "5" "September 2011" "semanage.conf" "Linux System Administration"
Line 8, length 105
file is usually located under the directory /etc/selinux and it is used for run-time configuration of the
Line 12, length 137
Each line should contain a configuration parameter followed by the equal sign ("=") and then followed by the configuration value for that
Line 21, length 123
Specify how the SELinux Management library should interact with the SELinux policy store. When set to "direct", the SELinux
Line 22, length 100
Management library writes to the SELinux policy module store directly (this is the default setting).
Line 24, length 145
If the argument begins with "/" (as in "/foo/bar"), it represents the path to a named socket that should be used to connect the policy management
Line 26, length 143
If the argument does not begin with a "/" (as in "example.com:4242"), it should be interpreted as the name of a remote policy management server
Line 27, length 143
to be used through a TCP connection (default port is 4242 unless a different one is specified after the server name using the colon to separate
Line 40, length 117
Specify an alternative directory that contains HLL to CIL compilers. The default value is "/usr/libexec/selinux/hll".
Line 44, length 144
Whether or not to ignore the cache of CIL modules compiled from HLL. It can be set to either "true" or "false" and is set to "false" by default.
Line 45, length 84
If the cache is ignored, then all CIL modules are recompiled from their HLL modules.
Line 51, length 130
will set the policy version to POLICYDB_VERSION_MAX, as defined in <sepol/policydb/policydb.h>. Change this setting if a different
Line 56, length 119
The target platform to generate policies for. Valid values are "selinux" and "xen", and is set to "selinux" by default.
Line 62, length 117
command. It can be set to either "0" (disabled) or "1" (enabled) and by default it is enabled. There might be a large
Line 71, length 125
It controls whether the previous module directory is saved after a successful commit to the policy store and it can be set to
Line 72, length 92
either "true" or "false". By default it is set to "false" (the previous version is deleted).
Line 76, length 130
It controls whether the previously linked module is saved (with name "base.linked") after a successful commit to the policy store.
Line 77, length 111
It can be set to either "true" or "false" and by default it is set to "false" (the previous module is deleted).
Line 81, length 82
List, separated by ";", of directories to ignore when setting up users homedirs.
Line 86, length 133
Whether or not to enable the use getpwent() to obtain a list of home directories to label. It can be set to either "true" or "false".
Line 93, length 120
command and it can be set to either "false" or "true". By default the genhomedircon functionality is enabled (equivalent
Line 98, length 124
This option overrides the kernel behavior for handling permissions defined in the kernel but missing from the actual policy.
Line 99, length 94
It can be set to "deny", "reject" or "allow". By default the setting from the policy is taken.
Line 103, length 122
It should be in the range 0-9. A value of 0 means no compression. By default the bzip block size is set to 9 (actual block
Line 108, length 129
When set to "true", the bzip algorithm shall try to reduce its system memory usage. It can be set to either "true" or "false" and
Line 113, length 129
When set to "true", HLL files will be removed after compilation into CIL. In order to delete HLL files already compiled into CIL,
Line 118, length 82
option with semodule. The remove-hll option can be set to either "true" or "false"
Line 121, length 143
Please note that since this option deletes all HLL files, an updated HLL compiler will not be able to recompile the original HLL file into CIL.
Line 122, length 98
In order to compile the original HLL file into CIL, the same HLL file will need to be reinstalled.
Line 137, length 84
The SELinux management library was written by Tresys Technology LLC and Red Hat Inc.
-.-.
The name of a man page is typeset in bold and the section in roman
(see man-pages(7)).
131:semanage(8)
-.-.
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
semanage.conf.5:22:Management library writes to the SELinux policy module store directly (this is the default setting).
semanage.conf.5:24:If the argument begins with "/" (as in "/foo/bar"), it represents the path to a named socket that should be used to connect the policy management
semanage.conf.5:26:If the argument does not begin with a "/" (as in "example.com:4242"), it should be interpreted as the name of a remote policy management server
semanage.conf.5:72:either "true" or "false". By default it is set to "false" (the previous version is deleted).
semanage.conf.5:76:It controls whether the previously linked module is saved (with name "base.linked") after a successful commit to the policy store.
semanage.conf.5:77:It can be set to either "true" or "false" and by default it is set to "false" (the previous module is deleted).
-.-.
Use thousand markers to make large numbers easy to read
104:size value is obtained after multiplication by 100000).
-.-.
Remove quotes when there is a printable
but no space character between them
and the quotes are not for emphasis (markup),
for example as an argument to a macro.
1:.TH semanage.conf "5" "September 2011" "semanage.conf" "Linux System Administration"
-.-.
Trailing space in a macro call.
Remove with "sed -i -e 's/ *$//'"
20:.B module-store
48:.B policy-version
85:.B usepasswd
-.-.
Section headings (.SH and .SS) do not need quoting.
129:.SH "SEE ALSO"
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z ":
an.tmac:<stdin>:7: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:50: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:61: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
troff:<stdin>:81: warning: trailing space in the line
troff:<stdin>:82: warning: trailing space in the line
an.tmac:<stdin>:92: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:115: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:117: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an-end-check:<stdin>: Warning: Different number of .RS and .RE calls, an-RS-open=1 at end of file
-------------- next part --------------
--- semanage.conf.5 2025-02-15 08:40:28.660920237 +0000
+++ semanage.conf.5.new 2025-02-15 09:17:34.129031674 +0000
@@ -1,66 +1,96 @@
-.TH semanage.conf "5" "September 2011" "semanage.conf" "Linux System Administration"
+.TH semanage.conf 5 "September 2011" semanage.conf \
+"Linux System Administration"
.SH NAME
semanage.conf \- global configuration file for the SELinux Management library
.SH DESCRIPTION
-.PP
The
-.BR semanage.conf
-file is usually located under the directory /etc/selinux and it is used for run-time configuration of the
+.B semanage.conf
+file is usually located under the directory /etc/selinux
+and it is used for run-time configuration of the
behavior of the SELinux Management library.
.PP
-Each line should contain a configuration parameter followed by the equal sign ("=") and then followed by the configuration value for that
-parameter. Anything after the "#" symbol is ignored similarly to empty lines.
+Each line should contain a configuration parameter
+followed by the equal sign ("=")
+and then followed by the configuration value for that parameter.
+Anything after the "#" symbol is ignored similarly to empty lines.
.PP
The following parameters are allowed:
.RS
.TP
-.B module-store
-Specify how the SELinux Management library should interact with the SELinux policy store. When set to "direct", the SELinux
-Management library writes to the SELinux policy module store directly (this is the default setting).
+.B module-store
+Specify how the SELinux Management library should interact with the
+SELinux policy store.
+When set to "direct",
+the SELinux Management library writes to the SELinux policy module store
+directly
+(this is the default setting).
Otherwise a socket path or a server name can be used for the argument.
-If the argument begins with "/" (as in "/foo/bar"), it represents the path to a named socket that should be used to connect the policy management
-server.
-If the argument does not begin with a "/" (as in "example.com:4242"), it should be interpreted as the name of a remote policy management server
-to be used through a TCP connection (default port is 4242 unless a different one is specified after the server name using the colon to separate
-the two fields).
+If the argument begins with "/"
+(as in "/foo/bar"),
+it represents the path to a named socket
+that should be used to connect the policy management server.
+If the argument does not begin with a "/"
+(as in "example.com:4242"),
+it should be interpreted as the name of a remote policy management server
+to be used through a TCP connection
+(default port is 4242
+unless a different one is specified after the server name using the colon
+to separate the two fields).
.TP
.B root
-Specify an alternative root path to use for the store. The default is "/"
+Specify an alternative root path to use for the store.
+The default is "/"
.TP
.B store-root
-Specify an alternative store_root path to use. The default is "/var/lib/selinux"
+Specify an alternative store_root path to use.
+The default is "/var/lib/selinux"
.TP
.B compiler-directory
-Specify an alternative directory that contains HLL to CIL compilers. The default value is "/usr/libexec/selinux/hll".
+Specify an alternative directory that contains HLL to CIL compilers.
+The default value is "/usr/libexec/selinux/hll".
.TP
.B ignore-module-cache
-Whether or not to ignore the cache of CIL modules compiled from HLL. It can be set to either "true" or "false" and is set to "false" by default.
-If the cache is ignored, then all CIL modules are recompiled from their HLL modules.
+Whether or not to ignore the cache of CIL modules compiled from HLL.
+It can be set to either "true" or "false"
+and is set to "false" by default.
+If the cache is ignored,
+then all CIL modules are recompiled from their HLL modules.
.TP
-.B policy-version
-When generating the policy, by default
-.BR semanage
-will set the policy version to POLICYDB_VERSION_MAX, as defined in <sepol/policydb/policydb.h>. Change this setting if a different
-version needs to be set for the policy.
+.B policy-version
+When generating the policy,
+by default
+.B semanage
+will set the policy version to POLICYDB_VERSION_MAX,
+as defined in <sepol/policydb/policydb.h>.
+Change this setting
+if a different version needs to be set for the policy.
.TP
.B target-platform
-The target platform to generate policies for. Valid values are "selinux" and "xen", and is set to "selinux" by default.
+The target platform to generate policies for.
+Valid values are "selinux" and "xen",
+and is set to "selinux" by default.
.TP
.B expand-check
Whether or not to check "neverallow" rules when executing all
-.BR semanage
-command. It can be set to either "0" (disabled) or "1" (enabled) and by default it is enabled. There might be a large
-penalty in execution time if this option is enabled.
+.B semanage
+command.
+It can be set to either "0"
+(disabled)
+or "1"
+(enabled)
+and by default it is enabled.
+There might be a large penalty in execution time
+if this option is enabled.
.TP
.B file-mode
@@ -68,70 +98,105 @@ By default the permission mode for the r
.TP
.B save-previous
-It controls whether the previous module directory is saved after a successful commit to the policy store and it can be set to
-either "true" or "false". By default it is set to "false" (the previous version is deleted).
+It controls
+whether the previous module directory is saved after a successful commit
+to the policy store
+and it can be set to either "true" or "false".
+By default it is set to "false"
+(the previous version is deleted).
.TP
.B save-linked
-It controls whether the previously linked module is saved (with name "base.linked") after a successful commit to the policy store.
-It can be set to either "true" or "false" and by default it is set to "false" (the previous module is deleted).
+It controls
+whether the previously linked module is saved
+(with name "base.linked")
+after a successful commit to the policy store.
+It can be set to either "true" or "false"
+and by default
+it is set to "false"
+(the previous module is deleted).
.TP
.B ignoredirs
-List, separated by ";", of directories to ignore when setting up users homedirs.
-Some distributions use this to stop labeling /root as a homedir.
+List,
+separated by ";",
+of directories to ignore
+when setting up users homedirs.
+Some distributions use this to stop labeling /root as a homedir.
.TP
-.B usepasswd
-Whether or not to enable the use getpwent() to obtain a list of home directories to label. It can be set to either "true" or "false".
+.B usepasswd
+Whether or not to enable the use
+.BR getpwent ()
+to obtain a list of home directories to label.
+It can be set to either "true" or "false".
By default it is set to "true".
.TP
.B disable-genhomedircon
It controls whether or not the genhomedircon function is executed when using the
-.BR semanage
-command and it can be set to either "false" or "true". By default the genhomedircon functionality is enabled (equivalent
-to this option set to "false").
+.B semanage
+command
+and it can be set to either "false" or "true".
+By default the genhomedircon functionality is enabled
+(equivalent to this option set to "false").
.TP
.B handle-unknown
-This option overrides the kernel behavior for handling permissions defined in the kernel but missing from the actual policy.
-It can be set to "deny", "reject" or "allow". By default the setting from the policy is taken.
+This option overrides the kernel behavior for handling permissions
+defined in the kernel
+but missing from the actual policy.
+It can be set to "deny",
+"reject" or "allow".
+By default the setting from the policy is taken.
.TP
.B bzip-blocksize
-It should be in the range 0-9. A value of 0 means no compression. By default the bzip block size is set to 9 (actual block
-size value is obtained after multiplication by 100000).
+It should be in the range 0\(en9.
+A value of 0 means no compression.
+By default the bzip block size is set to 9
+(actual block size value is obtained after multiplication by 100,000).
.TP
.B bzip-small
-When set to "true", the bzip algorithm shall try to reduce its system memory usage. It can be set to either "true" or "false" and
-by default it is set to "false".
+When set to "true",
+the bzip algorithm shall try to reduce its system memory usage.
+It can be set to either "true" or "false"
+and by default it is set to "false".
.TP
.B remove-hll
-When set to "true", HLL files will be removed after compilation into CIL. In order to delete HLL files already compiled into CIL,
+When set to "true",
+HLL files will be removed after compilation into CIL.
+In order to delete HLL files already compiled into CIL,
modules will need to be recompiled with the
-.BR ignore-module-cache
+.B ignore-module-cache
option set to 'true' or using the
-.BR ignore-module-cache
-option with semodule. The remove-hll option can be set to either "true" or "false"
+.B ignore-module-cache
+option with semodule.
+The remove-hll option can be set to either "true" or "false"
and by default it is set to "false".
-Please note that since this option deletes all HLL files, an updated HLL compiler will not be able to recompile the original HLL file into CIL.
-In order to compile the original HLL file into CIL, the same HLL file will need to be reinstalled.
+Please note
+that since this option deletes all HLL files,
+an updated HLL compiler will not be able to recompile the original HLL
+file into CIL.
+In order to compile the original HLL file into CIL,
+the same HLL file will need to be reinstalled.
.TP
.B optimize-policy
-When set to "true", the kernel policy will be optimized upon rebuilds.
+When set to "true",
+the kernel policy will be optimized upon rebuilds.
It can be set to either "true" or "false" and by default it is set to "false".
+.RE
-.SH "SEE ALSO"
+.SH SEE ALSO
.TP
-semanage(8)
-.PP
+.BR semanage (8)
.SH AUTHOR
This manual page was written by Guido Trentalancia <guido at trentalancia.com>.
-The SELinux management library was written by Tresys Technology LLC and Red Hat Inc.
+The SELinux management library was written by Tresys Technology LLC
+and Red Hat Inc.
-------------- next part --------------
Any program (person), that produces man pages, should check the output
for defects by using (both groff and nroff)
[gn]roff -mandoc -t -ww -b -z -K utf8 <man page>
The same goes for man pages that are used as an input.
For a style guide use
mandoc -T lint
-.-
Any "autogenerator" should check its products with the above mentioned
'groff', 'mandoc', and additionally with 'nroff ...'.
It should also check its input files for too long (> 80) lines.
This is just a simple quality control measure.
The "autogenerator" may have to be corrected to get a better man page,
the source file may, and any additional file may.
Common defects:
Not removing trailing spaces (in in- and output).
The reason for these trailing spaces should be found and eliminated.
"git" has a "tool" to point out whitespace,
see for example "git-apply(1)" and git-config(1)")
Not beginning each input sentence on a new line.
Line length and patch size should thus be reduced.
The script "reportbug" uses 'quoted-printable' encoding when a line is
longer than 1024 characters in an 'ascii' file.
See man-pages(7), item "semantic newline".
-.-
The difference between the formatted output of the original and patched file
can be seen with:
nroff -mandoc <file1> > <out1>
nroff -mandoc <file2> > <out2>
diff -d -u <out1> <out2>
and for groff, using
\"printf '%s\n%s\n' '.kern 0' '.ss 12 0' | groff -mandoc -Z - \"
instead of 'nroff -mandoc'
Add the option '-t', if the file contains a table.
Read the output from 'diff -d -u ...' with 'less -R' or similar.
-.-.
If 'man' (man-db) is used to check the manual for warnings,
the following must be set:
The option \"-warnings=w\"
The environmental variable:
export MAN_KEEP_STDERR=yes (or any non-empty value)
or
(produce only warnings):
export MANROFFOPT=\"-ww -b -z\"
export MAN_KEEP_STDERR=yes (or any non-empty value)
-.-
More information about the SELinux-devel
mailing list