mirror of
https://github.com/SELinuxProject/selinux
synced 2025-03-11 04:37:29 +00:00
0b691d1afe
Currently, if the SELINUX_RESTORECON_ABORT_ON_ERROR flag is clear, then selinux_restorecon[_parallel]() does not abort the file tree walk upon an error, but the function itself fails the same, with the same (-1) return value. This in turn is reported by the setfiles(8) utility to its parent process with the same exit code (255). In libguestfs we want to proceed after setfiles(8) fails *at most* with such errors that occur during the file tree walk. We need setfiles(8) to exit with a distinct exit status in that situation. For this, introduce the SELINUX_RESTORECON_COUNT_ERRORS flag, and the corresponding selinux_restorecon_get_skipped_errors() function, for selinux_restorecon[_parallel]() to count, but otherwise ignore, errors during the file tree walk. When no other kind of error occurs, the relabeling functions will return zero, and the caller can fetch the number of errors ignored during the file tree walk with selinux_restorecon_get_skipped_errors(). Importantly, when at least one such error is skipped, we don't write partial match digests for subdirectories, as any masked error means that any subdirectory may not have been completely relabeled. Cc: "Richard W.M. Jones" <rjones@redhat.com> Cc: Petr Lautrbach <plautrba@redhat.com> Bugzilla: https://bugzilla.redhat.com/show_bug.cgi?id=1794518 Signed-off-by: Laszlo Ersek <lersek@redhat.com>
309 lines
8.5 KiB
Groff
309 lines
8.5 KiB
Groff
.TH "selinux_restorecon" "3" "20 Oct 2015" "Security Enhanced Linux" "SELinux API documentation"
|
|
|
|
.SH "NAME"
|
|
selinux_restorecon \- restore file(s) default SELinux security contexts
|
|
.
|
|
.SH "SYNOPSIS"
|
|
.B #include <selinux/restorecon.h>
|
|
.sp
|
|
.BI "int selinux_restorecon(const char *" pathname ,
|
|
.in +\w'int selinux_restorecon('u
|
|
.br
|
|
.BI "unsigned int " restorecon_flags ");"
|
|
.in
|
|
.sp
|
|
.BI "int selinux_restorecon_parallel(const char *" pathname ,
|
|
.in +\w'int selinux_restorecon_parallel('u
|
|
.br
|
|
.BI "unsigned int " restorecon_flags ","
|
|
.br
|
|
.BI "size_t " nthreads ");"
|
|
.in
|
|
.
|
|
.SH "DESCRIPTION"
|
|
.BR selinux_restorecon ()
|
|
restores file default security contexts on filesystems that support extended
|
|
attributes (see
|
|
.BR xattr (7)),
|
|
based on:
|
|
.sp
|
|
.RS
|
|
.IR pathname
|
|
containing a directory or file to be relabeled.
|
|
.br
|
|
If this is a directory and the
|
|
.IR restorecon_flags
|
|
.B SELINUX_RESTORECON_RECURSE
|
|
has been set (for descending through directories), then
|
|
.BR selinux_restorecon ()
|
|
will write an SHA1 digest of specfile entries calculated by
|
|
.BR selabel_get_digests_all_partial_matches (3)
|
|
to an extended attribute of
|
|
.IR security.sehash
|
|
once the relabeling has been completed successfully (see the
|
|
.B NOTES
|
|
section for details).
|
|
.br
|
|
These digests will be checked should
|
|
.BR selinux_restorecon ()
|
|
be rerun with the
|
|
.IR restorecon_flags
|
|
.B SELINUX_RESTORECON_RECURSE
|
|
flag set. If any of the specfile entries had been updated, the digest
|
|
will also be updated. However if the digest is the same, no relabeling checks
|
|
will take place.
|
|
.br
|
|
The
|
|
.IR restorecon_flags
|
|
that can be used to manage the usage of the SHA1 digest are:
|
|
.RS
|
|
.B SELINUX_RESTORECON_SKIP_DIGEST
|
|
.br
|
|
.B SELINUX_RESTORECON_IGNORE_DIGEST
|
|
.RE
|
|
.sp
|
|
.IR restorecon_flags
|
|
contains the labeling option/rules as follows:
|
|
.sp
|
|
.RS
|
|
.sp
|
|
.B SELINUX_RESTORECON_SKIP_DIGEST
|
|
Do not check or update any extended attribute
|
|
.IR security.sehash
|
|
entries.
|
|
.sp
|
|
.B SELINUX_RESTORECON_IGNORE_DIGEST
|
|
force the checking of labels even if the stored SHA1 digest matches the
|
|
specfile entries SHA1 digest. The specfile entries digest will be written to the
|
|
.IR security.sehash
|
|
extended attribute once relabeling has been completed successfully provided the
|
|
.B SELINUX_RESTORECON_NOCHANGE
|
|
flag has not been set, and no errors have been skipped during the file tree walk
|
|
due to the
|
|
.B SELINUX_RESTORECON_COUNT_ERRORS
|
|
flag.
|
|
.sp
|
|
.B SELINUX_RESTORECON_NOCHANGE
|
|
don't change any file labels (passive check) or update the digest in the
|
|
.IR security.sehash
|
|
extended attribute.
|
|
.sp
|
|
.B SELINUX_RESTORECON_SET_SPECFILE_CTX
|
|
If set, reset the files label to match the default specfile context.
|
|
If not set only reset the files "type" component of the context to match the
|
|
default specfile context.
|
|
.sp
|
|
.B SELINUX_RESTORECON_RECURSE
|
|
change file and directory labels recursively (descend directories)
|
|
and if successful write an SHA1 digest of the specfile entries to an
|
|
extended attribute as described in the
|
|
.B NOTES
|
|
section.
|
|
.sp
|
|
.B SELINUX_RESTORECON_VERBOSE
|
|
log file label changes.
|
|
.RS
|
|
Note that if
|
|
.B SELINUX_RESTORECON_VERBOSE
|
|
and
|
|
.B SELINUX_RESTORECON_PROGRESS
|
|
flags are set, then
|
|
.B SELINUX_RESTORECON_PROGRESS
|
|
will take precedence.
|
|
.RE
|
|
.sp
|
|
.B SELINUX_RESTORECON_PROGRESS
|
|
show progress by outputting the number of files in 1k blocks processed
|
|
to stdout. If the
|
|
.B SELINUX_RESTORECON_MASS_RELABEL
|
|
flag is also set then the approximate percentage complete will be shown.
|
|
.sp
|
|
.B SELINUX_RESTORECON_MASS_RELABEL
|
|
generally set when relabeling the entire OS, that will then show the
|
|
approximate percentage complete. The
|
|
.B SELINUX_RESTORECON_PROGRESS
|
|
flag must also be set.
|
|
.sp
|
|
.B SELINUX_RESTORECON_REALPATH
|
|
convert passed-in
|
|
.I pathname
|
|
to the canonical pathname using
|
|
.BR realpath (3).
|
|
.sp
|
|
.B SELINUX_RESTORECON_XDEV
|
|
prevent descending into directories that have a different device number than
|
|
the
|
|
.I pathname
|
|
entry from which the descent began.
|
|
.sp
|
|
.B SELINUX_RESTORECON_ADD_ASSOC
|
|
attempt to add an association between an inode and a specification. If there
|
|
is already an association for the inode and it conflicts with the
|
|
specification, then use the last matching specification.
|
|
.sp
|
|
.B SELINUX_RESTORECON_ABORT_ON_ERROR
|
|
abort on errors during the file tree walk.
|
|
.sp
|
|
.B SELINUX_RESTORECON_SYSLOG_CHANGES
|
|
log any label changes to
|
|
.BR syslog (3).
|
|
.sp
|
|
.B SELINUX_RESTORECON_LOG_MATCHES
|
|
log what specfile context matched each file.
|
|
.sp
|
|
.B SELINUX_RESTORECON_IGNORE_NOENTRY
|
|
ignore files that do not exist.
|
|
.sp
|
|
.B SELINUX_RESTORECON_IGNORE_MOUNTS
|
|
do not read
|
|
.B /proc/mounts
|
|
to obtain a list of non-seclabel mounts to be excluded from relabeling checks.
|
|
.br
|
|
Setting
|
|
.B SELINUX_RESTORECON_IGNORE_MOUNTS
|
|
is useful where there is a non-seclabel fs mounted with a seclabel fs mounted
|
|
on a directory below this.
|
|
.sp
|
|
.B SELINUX_RESTORECON_CONFLICT_ERROR
|
|
to treat conflicting specifications, such as where two hardlinks for the
|
|
same inode have different contexts, as errors.
|
|
.sp
|
|
.B SELINUX_RESTORECON_COUNT_ERRORS
|
|
Count, but otherwise ignore, errors during the file tree walk. Only makes a
|
|
difference if the
|
|
.B SELINUX_RESTORECON_ABORT_ON_ERROR
|
|
flag is clear. Call
|
|
.BR selinux_restorecon_get_skipped_errors (3)
|
|
for fetching the ignored (skipped) error count after
|
|
.BR selinux_restorecon (3)
|
|
or
|
|
.BR selinux_restorecon_parallel (3)
|
|
completes with success. In case any errors were skipped during the file tree
|
|
walk, the specfile entries SHA1 digest will not have been written to the
|
|
.IR security.sehash
|
|
extended attribute.
|
|
.RE
|
|
.sp
|
|
The behavior regarding the checking and updating of the SHA1 digest described
|
|
above is the default behavior. It is possible to change this by first calling
|
|
.BR selabel_open (3)
|
|
and not enabling the
|
|
.B SELABEL_OPT_DIGEST
|
|
option, then calling
|
|
.BR selinux_restorecon_set_sehandle (3)
|
|
to set the handle to be used by
|
|
.BR selinux_restorecon (3).
|
|
.sp
|
|
If the
|
|
.I pathname
|
|
is a directory path, then it is possible to set directories to be excluded
|
|
from the path by calling
|
|
.BR selinux_restorecon_set_exclude_list (3)
|
|
with a
|
|
.B NULL
|
|
terminated list before calling
|
|
.BR selinux_restorecon (3).
|
|
.sp
|
|
By default
|
|
.BR selinux_restorecon (3)
|
|
reads
|
|
.B /proc/mounts
|
|
to obtain a list of non-seclabel mounts to be excluded from relabeling checks
|
|
unless the
|
|
.B SELINUX_RESTORECON_IGNORE_MOUNTS
|
|
flag has been set.
|
|
.RE
|
|
.sp
|
|
.BR selinux_restorecon_parallel()
|
|
is similar to
|
|
.BR selinux_restorecon (3),
|
|
but accepts another parameter that allows to run relabeling over multiple
|
|
threads:
|
|
.sp
|
|
.RS
|
|
.IR nthreads
|
|
specifies the number of threads to use during relabeling. When set to 1,
|
|
the behavior is the same as calling
|
|
.BR selinux_restorecon (3).
|
|
When set to 0, the function will try to use as many threads as there are
|
|
online CPU cores. When set to any other number, the function will try to use
|
|
the given number of threads.
|
|
.sp
|
|
Note that to use the parallel relabeling capability, the calling process
|
|
must be linked with the
|
|
.B libpthread
|
|
library (either at compile time or dynamically at run time). Otherwise the
|
|
function will print a warning and fall back to the single threaded mode.
|
|
.
|
|
.SH "RETURN VALUE"
|
|
On success, zero is returned. On error, \-1 is returned and
|
|
.I errno
|
|
is set appropriately.
|
|
.
|
|
.SH "NOTES"
|
|
.IP "1." 4
|
|
To improve performance when relabeling file systems recursively (e.g. the
|
|
.IR restorecon_flags
|
|
.B SELINUX_RESTORECON_RECURSE
|
|
flag is set)
|
|
.BR selinux_restorecon ()
|
|
will write a calculated SHA1 digest of the specfile entries returned by
|
|
.BR selabel_get_digests_all_partial_matches (3)
|
|
to an extended attribute named
|
|
.IR security.sehash
|
|
for each directory in the
|
|
.IR pathname
|
|
path.
|
|
.IP "2." 4
|
|
To check the extended attribute entry use
|
|
.BR getfattr (1) ,
|
|
for example:
|
|
.sp
|
|
.RS
|
|
.RS
|
|
getfattr -e hex -n security.sehash /
|
|
.RE
|
|
.RE
|
|
.IP "3." 4
|
|
Should any of the specfile entries have changed, then when
|
|
.BR selinux_restorecon ()
|
|
is run again with the
|
|
.B SELINUX_RESTORECON_RECURSE
|
|
flag set, new SHA1 digests will be calculated and all files automatically
|
|
relabeled depending on the settings of the
|
|
.B SELINUX_RESTORECON_SET_SPECFILE_CTX
|
|
flag (provided
|
|
.B SELINUX_RESTORECON_NOCHANGE
|
|
is not set).
|
|
.IP "4." 4
|
|
.B /sys
|
|
and in-memory filesystems do not support the
|
|
.IR security.sehash
|
|
extended attribute and are automatically excluded from any relabeling checks.
|
|
.IP "5." 4
|
|
By default
|
|
.B stderr
|
|
is used to log output messages and errors. This may be changed by calling
|
|
.BR selinux_set_callback (3)
|
|
with the
|
|
.B SELINUX_CB_LOG
|
|
.I type
|
|
option.
|
|
.
|
|
.SH "SEE ALSO"
|
|
.BR selabel_get_digests_all_partial_matches (3),
|
|
.br
|
|
.BR selinux_restorecon_set_sehandle (3),
|
|
.br
|
|
.BR selinux_restorecon_default_handle (3),
|
|
.br
|
|
.BR selinux_restorecon_get_skipped_errors (3),
|
|
.br
|
|
.BR selinux_restorecon_set_exclude_list (3),
|
|
.br
|
|
.BR selinux_restorecon_set_alt_rootpath (3),
|
|
.br
|
|
.BR selinux_restorecon_xattr (3),
|
|
.br
|
|
.BR selinux_set_callback (3)
|