0010-policycoreutils-Add-examples-to-man-pages.patch

From 10cfbd2825e12efdc0faa872987d5987e02e7eae Mon Sep 17 00:00:00 2001
From: Vit Mojzis <vmojzis@redhat.com>
Date: Thu, 1 Jun 2023 16:39:11 +0200
Subject: [PATCH] policycoreutils: Add examples to man pages

While at it, remove trailing whitespaces.

Signed-off-by: Vit Mojzis <vmojzis@redhat.com>
Acked-by: Petr Lautrbach <lautrbach@redhat.com>
---
 policycoreutils/scripts/fixfiles.8          | 34 +++++++++++++--------
 policycoreutils/secon/secon.1               | 12 ++++++--
 policycoreutils/semodule/semodule.8         | 14 ++++-----
 policycoreutils/setfiles/restorecon.8       |  9 ++++++
 policycoreutils/setfiles/restorecon_xattr.8 |  7 +++++
 policycoreutils/setfiles/setfiles.8         |  9 ++++++
 policycoreutils/setsebool/setsebool.8       | 16 +++++++---
 7 files changed, 74 insertions(+), 27 deletions(-)

diff --git a/policycoreutils/scripts/fixfiles.8 b/policycoreutils/scripts/fixfiles.8
index 9a317d91..928b8200 100644
--- a/policycoreutils/scripts/fixfiles.8
+++ b/policycoreutils/scripts/fixfiles.8
@@ -14,7 +14,7 @@ fixfiles \- fix file SELinux security contexts.
 .B fixfiles
 .I [\-v] [\-F] [\-B | \-N time ] [\-T nthreads] { check | restore | verify }
 
-.B fixfiles 
+.B fixfiles
 .I [\-v] [\-F] [\-T nthreads] \-R rpmpackagename[,rpmpackagename...] { check | restore | verify }
 
 .B fixfiles
@@ -31,7 +31,7 @@ This manual page describes the
 script.
 .P
 This script is primarily used to correct the security context
-database (extended attributes) on filesystems.  
+database (extended attributes) on filesystems.
 .P
 It can also be run at any time to relabel when adding support for
 new policy, or  just check whether the file contexts are all
@@ -41,29 +41,29 @@ option.  You can use the \-R flag to use rpmpackages as an alternative.
 The file /etc/selinux/fixfiles_exclude_dirs can contain a list of directories
 excluded from relabeling.
 .P
-.B fixfiles onboot 
+.B fixfiles onboot
 will setup the machine to relabel on the next reboot.
 
 .SH "OPTIONS"
-.TP 
+.TP
 .B \-B
 If specified with onboot, this fixfiles will record the current date in the /.autorelabel file, so that it can be used later to speed up labeling. If used with restore, the restore will only affect files that were modified today.
 .TP
 .B \-F
 Force reset of context to match file_context for customizable files
 
-.TP 
+.TP
 .B \-f
 Clear /tmp directory with out prompt for removal.
 
-.TP 
+.TP
 .B \-R rpmpackagename[,rpmpackagename...]
 Use the rpm database to discover all files within the specified packages and restore the file contexts.
 .TP
 .B \-C PREVIOUS_FILECONTEXT
 Run a diff on  the PREVIOUS_FILECONTEXT file to the currently installed one, and restore the context of all affected files.
 
-.TP 
+.TP
 .B \-N time
 Only act on files created after the specified date.  Date must be specified in
 "YYYY\-MM\-DD HH:MM" format.  Date field will be passed to find \-\-newermt command.
@@ -83,19 +83,28 @@ Use parallel relabeling, see
 
 .SH "ARGUMENTS"
 One of:
-.TP 
+.TP
 .B check | verify
 print any incorrect file context labels, showing old and new context, but do not change them.
-.TP 
+.TP
 .B restore
 change any incorrect file context labels.
-.TP 
+.TP
 .B relabel
 Prompt for removal of contents of /tmp directory and then change any incorrect file context labels to match the install file_contexts file.
-.TP 
-.B [[dir/file] ... ] 
+.TP
+.B [[dir/file] ... ]
 List of files or directories trees that you wish to check file context on.
 
+.SH EXAMPLE
+.nf
+Relabel the whole filesystem, except paths listed in /etc/selinux/fixfiles_exclude_dirs
+# fixfiles relabel
+Schedule the machine to relabel on the next boot and force relabeling of customizable types
+# fixfiles -F onboot
+Check labeling of all files from the samba package (while not changing any labels)
+# fixfiles -R samba check
+
 .SH "AUTHOR"
 This man page was written by Richard Hally <rhally@mindspring.com>.
 The script  was written by Dan Walsh <dwalsh@redhat.com>
@@ -103,4 +112,3 @@ The script  was written by Dan Walsh <dwalsh@redhat.com>
 .SH "SEE ALSO"
 .BR setfiles (8),
 .BR restorecon (8)
-
diff --git a/policycoreutils/secon/secon.1 b/policycoreutils/secon/secon.1
index 501b5cb8..c0e8b05a 100644
--- a/policycoreutils/secon/secon.1
+++ b/policycoreutils/secon/secon.1
@@ -107,16 +107,24 @@ then the context will be read from stdin.
 .br
 If there is no argument,
 .B secon
-will try reading a context from stdin, if that is not a tty, otherwise 
+will try reading a context from stdin, if that is not a tty, otherwise
 .B secon
 will act as though \fB\-\-self\fR had been passed.
 .PP
 If none of \fB\-\-user\fR, \fB\-\-role\fR, \fB\-\-type\fR, \fB\-\-level\fR or
 \fB\-\-mls\-range\fR is passed.
 Then all of them will be output.
+
+.SH EXAMPLE
+.nf
+Show SElinux context of the init process
+# secon --pid 1
+Parse the type portion of given security context
+# secon -t system_u:object_r:httpd_sys_rw_content_t:s0
+
 .PP
 .SH SEE ALSO
 .BR chcon (1)
 .SH AUTHORS
 .nf
-James Antill (james.antill@redhat.com) 
+James Antill (james.antill@redhat.com)
diff --git a/policycoreutils/semodule/semodule.8 b/policycoreutils/semodule/semodule.8
index c56e580f..01757b00 100644
--- a/policycoreutils/semodule/semodule.8
+++ b/policycoreutils/semodule/semodule.8
@@ -1,5 +1,5 @@
 .TH SEMODULE "8" "Nov 2005" "Security Enhanced Linux" NSA
-.SH NAME 
+.SH NAME
 semodule \- Manage SELinux policy modules.
 
 .SH SYNOPSIS
@@ -8,7 +8,7 @@ semodule \- Manage SELinux policy modules.
 .SH DESCRIPTION
 .PP
 semodule is the tool used to manage SELinux policy modules,
-including installing, upgrading, listing and removing modules.  
+including installing, upgrading, listing and removing modules.
 semodule may also be used to force a rebuild of policy from the
 module store and/or to force a reload of policy without performing
 any other transaction.  semodule acts on module packages created
@@ -39,7 +39,7 @@ install/replace a module package
 .B  \-u,\-\-upgrade=MODULE_PKG
 deprecated, alias for --install
 .TP
-.B  \-b,\-\-base=MODULE_PKG   
+.B  \-b,\-\-base=MODULE_PKG
 deprecated, alias for --install
 .TP
 .B  \-r,\-\-remove=MODULE_NAME
@@ -77,7 +77,7 @@ name of the store to operate on
 .B  \-n,\-\-noreload,\-N
 do not reload policy after commit
 .TP
-.B  \-h,\-\-help        
+.B  \-h,\-\-help
 prints help message and quit
 .TP
 .B \-P,\-\-preserve_tunables
@@ -92,7 +92,7 @@ Use an alternate path for the policy root
 .B \-S,\-\-store-path
 Use an alternate path for the policy store root
 .TP
-.B  \-v,\-\-verbose     
+.B  \-v,\-\-verbose
 be verbose
 .TP
 .B  \-c,\-\-cil
@@ -131,8 +131,6 @@ $ semodule \-B
 $ semodule \-d alsa
 # Install a module at a specific priority.
 $ semodule \-X 100 \-i alsa.pp
-# List all modules.
-$ semodule \-\-list=full
 # Set an alternate path for the policy root
 $ semodule \-B \-p "/tmp"
 # Set an alternate path for the policy store root
@@ -143,6 +141,8 @@ $ semodule \-X 400 \-\-hll \-E puppet \-\-cil \-E wireshark
 # Check whether a module in "localmodule.pp" file is same as installed module "localmodule"
 $ /usr/libexec/selinux/hll/pp localmodule.pp | sha256sum
 $ semodule -l -m | grep localmodule
+# Translate binary module file into CIL (useful for debugging installation errors)
+$ /usr/libexec/selinux/hll/pp alsa.pp > alsa.cil
 .fi
 
 .SH SEE ALSO
diff --git a/policycoreutils/setfiles/restorecon.8 b/policycoreutils/setfiles/restorecon.8
index dbd55ce7..6160aced 100644
--- a/policycoreutils/setfiles/restorecon.8
+++ b/policycoreutils/setfiles/restorecon.8
@@ -224,6 +224,15 @@ and provided the
 option is NOT set and recursive mode is set, files will be relabeled as
 required with the digests then being updated provided there are no errors.
 
+.SH EXAMPLE
+.nf
+Fix labeling of /var/www/ including all sub-directories and list all context changes
+# restorecon -rv /var/www/
+List mislabeled files in user home directory and what the correct label should be
+# restorecon -nvr ~
+Fix labeling of files listed in file_list file, ignoring any that do not exist
+# restorecon -vif file_list
+
 .SH "AUTHOR"
 This man page was written by Dan Walsh <dwalsh@redhat.com>.
 Some of the content of this man page was taken from the setfiles
diff --git a/policycoreutils/setfiles/restorecon_xattr.8 b/policycoreutils/setfiles/restorecon_xattr.8
index 4b1ce304..09bfd8c4 100644
--- a/policycoreutils/setfiles/restorecon_xattr.8
+++ b/policycoreutils/setfiles/restorecon_xattr.8
@@ -112,6 +112,13 @@ If the option is not specified, then the default file_contexts will be used.
 .br
 the pathname of the directory tree to be searched.
 
+.SH EXAMPLE
+.nf
+List all paths that where assigned a checksum by "restorecon/setfiles -D"
+# restorecon_xattr -r /
+Remove all non-matching checksums
+# restorecon_xattr -rd /
+
 .SH "SEE ALSO"
 .BR restorecon (8),
 .BR setfiles (8)
diff --git a/policycoreutils/setfiles/setfiles.8 b/policycoreutils/setfiles/setfiles.8
index 36fe6b36..6071d9ba 100644
--- a/policycoreutils/setfiles/setfiles.8
+++ b/policycoreutils/setfiles/setfiles.8
@@ -289,6 +289,15 @@ and provided the
 option is NOT set, files will be relabeled as required with the digests then
 being updated provided there are no errors.
 
+.SH EXAMPLE
+.nf
+Fix labeling of /var/www/ including all sub-directories, using targeted policy file context definitions and list all context changes
+# setfiles -v /etc/selinux/targeted/contexts/files/file_contexts /var/www/
+List mislabeled files in user home directory and what the label should be based on targeted policy file context definitions
+# setfiles -nv /etc/selinux/targeted/contexts/files/file_contexts ~
+Fix labeling of files listed in file_list file, ignoring any that do not exist
+# setfiles -vif file_list /etc/selinux/targeted/contexts/files/file_contexts
+
 .SH "AUTHOR"
 This man page was written by Russell Coker <russell@coker.com.au>.
 The program was written by Stephen Smalley <sds@tycho.nsa.gov>
diff --git a/policycoreutils/setsebool/setsebool.8 b/policycoreutils/setsebool/setsebool.8
index 52936f5a..f54664fb 100644
--- a/policycoreutils/setsebool/setsebool.8
+++ b/policycoreutils/setsebool/setsebool.8
@@ -7,13 +7,13 @@ setsebool \- set SELinux boolean value
 .I "[ \-PNV ] boolean value | bool1=val1 bool2=val2 ..."
 
 .SH "DESCRIPTION"
-.B setsebool 
-sets the current state of a particular SELinux boolean or a list of booleans 
-to a given value. The value may be 1 or true or on to enable the boolean, or 0 or false or off to disable it. 
+.B setsebool
+sets the current state of a particular SELinux boolean or a list of booleans
+to a given value. The value may be 1 or true or on to enable the boolean, or 0 or false or off to disable it.
 
 Without the \-P option, only the current boolean value is
-affected; the boot-time default settings 
-are not changed. 
+affected; the boot-time default settings
+are not changed.
 
 If the \-P option is given, all pending values are written to
 the policy file on disk. So they will be persistent across reboots.
@@ -22,6 +22,12 @@ If the \-N option is given, the policy on disk is not reloaded into the kernel.
 
 If the \-V option is given, verbose error messages will be printed from semanage libraries.
 
+.SH EXAMPLE
+.nf
+Enable container_use_devices boolean (will return to persistent value after reboot)
+# setsebool container_use_devices 1
+Persistently enable samba_create_home_dirs and samba_enable_home_dirs booleans
+# setsebool -P samba_create_home_dirs=on samba_enable_home_dirs=on
 
 .SH AUTHOR
 This manual page was written by Dan Walsh <dwalsh@redhat.com>.
-- 
2.40.0