Re: [PATCH v2 1/5] policycoreutils: Add examples to man pages

From: James Carter <jwcart2@gmail.com>
To: Petr Lautrbach <plautrba@redhat.com>
Cc: Vit Mojzis <vmojzis@redhat.com>, selinux@vger.kernel.org
Subject: Re: [PATCH v2 1/5] policycoreutils: Add examples to man pages
Date: Thu, 8 Jun 2023 15:51:53 -0400	[thread overview]
Message-ID: <CAP+JOzRJVk-5F5x3QRqwyjKAh3FACGJnhgzhEZ=a9-mMhB7HZA@mail.gmail.com> (raw)
In-Reply-To: <87sfb5hv06.fsf@redhat.com>

On Tue, Jun 6, 2023 at 4:19 AM Petr Lautrbach <plautrba@redhat.com> wrote:
>
> Vit Mojzis <vmojzis@redhat.com> writes:
>
> > While at it, remove trailing whitespaces.
> >
> > Signed-off-by: Vit Mojzis <vmojzis@redhat.com>
> >
>
> For these five patches:
> Acked-by: Petr Lautrbach <lautrbach@redhat.com>
>
>
These five patches have been merged.
Thanks,
Jim

>
> > ---
> >  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 e07db2c8..c3cc5c9b 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 e04528e6..51d12a4d 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 bf26e161..892a5062 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
>