policycoreutils/SOURCES/0013-policycoreutils-Add-examples-to-man-pages.patch
2023-11-07 12:21:38 +00:00

310 lines
11 KiB
Diff

From b580a630378623df1c87c5fab1ffd63a41b3501e 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
Content-type: text/plain
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 9a317d9181e2..928b82004b1a 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 501b5cb8c410..c0e8b05a6b66 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 c56e580f27b8..01757b005e4a 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 dbd55ce7c512..6160aced5922 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 4b1ce304d995..09bfd8c40ab4 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 36fe6b369548..6071d9ba3d38 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 52936f5a0ffb..f54664fb5c2a 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.41.0