noble (3) selinux_restorecon.3.gz

Provided by: libselinux1-dev_3.5-2ubuntu2.1_amd64 bug

NAME

       selinux_restorecon - restore file(s) default SELinux security contexts

SYNOPSIS

       #include <selinux/restorecon.h>

       int selinux_restorecon(const char *pathname,
                              unsigned int restorecon_flags);

       int selinux_restorecon_parallel(const char *pathname,
                                       unsigned int restorecon_flags,
                                       size_t nthreads);

DESCRIPTION

       selinux_restorecon()  restores  file  default  security  contexts  on  filesystems  that support extended
       attributes (see xattr(7)), based on:

              pathname containing a directory or file to be relabeled.
              If this is a directory and the  restorecon_flags  SELINUX_RESTORECON_RECURSE  has  been  set  (for
              descending  through  directories), then selinux_restorecon() will write an SHA1 digest of specfile
              entries calculated by  selabel_get_digests_all_partial_matches(3)  to  an  extended  attribute  of
              security.sehash  once  the  relabeling  has been completed successfully (see the NOTES section for
              details).
              These digests will be checked should  selinux_restorecon()  be  rerun  with  the  restorecon_flags
              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.
              The restorecon_flags that can be used to manage the usage of the SHA1 digest are:
                     SELINUX_RESTORECON_SKIP_DIGEST
                     SELINUX_RESTORECON_IGNORE_DIGEST

              restorecon_flags contains the labeling option/rules as follows:

                     SELINUX_RESTORECON_SKIP_DIGEST  Do   not   check   or   update   any   extended   attribute
                     security.sehash entries.

                     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  security.sehash  extended  attribute  once  relabeling has been completed
                     successfully provided the SELINUX_RESTORECON_NOCHANGE flag has not been set, and no  errors
                     have  been  skipped  during  the  file tree walk due to the SELINUX_RESTORECON_COUNT_ERRORS
                     flag.

                     SELINUX_RESTORECON_NOCHANGE don't change any file labels  (passive  check)  or  update  the
                     digest in the security.sehash extended attribute.

                     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.

                     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 NOTES section.

                     SELINUX_RESTORECON_VERBOSE log file label changes.
                            Note  that  if  SELINUX_RESTORECON_VERBOSE and SELINUX_RESTORECON_PROGRESS flags are
                            set, then SELINUX_RESTORECON_PROGRESS will take precedence.

                     SELINUX_RESTORECON_PROGRESS show progress by outputting the number of files  in  1k  blocks
                     processed  to  stdout.  If  the  SELINUX_RESTORECON_MASS_RELABEL  flag is also set then the
                     approximate percentage complete will be shown.

                     SELINUX_RESTORECON_MASS_RELABEL generally set when relabeling the entire OS, that will then
                     show the approximate percentage complete. The SELINUX_RESTORECON_PROGRESS flag must also be
                     set.

                     SELINUX_RESTORECON_REALPATH convert passed-in pathname  to  the  canonical  pathname  using
                     realpath(3).

                     SELINUX_RESTORECON_XDEV  prevent  descending  into directories that have a different device
                     number than the pathname entry from which the descent began.

                     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.

                     SELINUX_RESTORECON_ABORT_ON_ERROR abort on errors during the file tree walk.

                     SELINUX_RESTORECON_SYSLOG_CHANGES log any label changes to syslog(3).

                     SELINUX_RESTORECON_LOG_MATCHES log what specfile context matched each file.

                     SELINUX_RESTORECON_IGNORE_NOENTRY ignore files that do not exist.

                     SELINUX_RESTORECON_IGNORE_MOUNTS do not read /proc/mounts to obtain a list of  non-seclabel
                     mounts to be excluded from relabeling checks.
                     Setting SELINUX_RESTORECON_IGNORE_MOUNTS is useful where there is a non-seclabel fs mounted
                     with a seclabel fs mounted on a directory below this.

                     SELINUX_RESTORECON_CONFLICT_ERROR to treat conflicting specifications, such  as  where  two
                     hardlinks for the same inode have different contexts, as errors.

                     SELINUX_RESTORECON_COUNT_ERRORS  Count,  but  otherwise ignore, errors during the file tree
                     walk. Only makes a difference if the SELINUX_RESTORECON_ABORT_ON_ERROR flag is clear.  Call
                     selinux_restorecon_get_skipped_errors(3)  for  fetching  the  ignored (skipped) error count
                     after selinux_restorecon(3) or 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 security.sehash extended attribute.

              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 selabel_open(3) and not enabling the
              SELABEL_OPT_DIGEST option, then calling selinux_restorecon_set_sehandle(3) to set the handle to be
              used by selinux_restorecon(3).

              If  the  pathname  is a directory path, then it is possible to set directories to be excluded from
              the path by calling selinux_restorecon_set_exclude_list(3) with  a  NULL  terminated  list  before
              calling selinux_restorecon(3).

              By  default selinux_restorecon(3) reads /proc/mounts to obtain a list of non-seclabel mounts to be
              excluded from relabeling checks unless the SELINUX_RESTORECON_IGNORE_MOUNTS flag has been set.

       selinux_restorecon_parallel() is similar to selinux_restorecon(3), but  accepts  another  parameter  that
       allows to run relabeling over multiple threads:

              nthreads  specifies the number of threads to use during relabeling. When set to 1, the behavior is
              the same as calling 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.

              Note that to use the parallel relabeling capability, the calling process must be linked  with  the
              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.

RETURN VALUE

       On success, zero is returned.  On error, -1 is returned and errno is set appropriately.

NOTES

       1.  To  improve  performance  when  relabeling  file  systems  recursively  (e.g.  the   restorecon_flags
           SELINUX_RESTORECON_RECURSE  flag  is set) selinux_restorecon() will write a calculated SHA1 digest of
           the specfile entries returned by selabel_get_digests_all_partial_matches(3) to an extended  attribute
           named security.sehash for each directory in the pathname path.

       2.  To check the extended attribute entry use getfattr(1), for example:

                  getfattr -e hex -n security.sehash /

       3.  Should any of the specfile entries have changed, then when selinux_restorecon() is run again with the
           SELINUX_RESTORECON_RECURSE flag set, new SHA1 digests will be calculated and all files  automatically
           relabeled  depending  on  the  settings  of  the  SELINUX_RESTORECON_SET_SPECFILE_CTX  flag (provided
           SELINUX_RESTORECON_NOCHANGE is not set).

       4.  /sys and in-memory filesystems  do  not  support  the  security.sehash  extended  attribute  and  are
           automatically excluded from any relabeling checks.

       5.  By  default  stderr  is  used  to  log  output  messages  and  errors. This may be changed by calling
           selinux_set_callback(3) with the SELINUX_CB_LOG type option.

SEE ALSO

       selabel_get_digests_all_partial_matches(3),
       selinux_restorecon_set_sehandle(3),
       selinux_restorecon_default_handle(3),
       selinux_restorecon_get_skipped_errors(3),
       selinux_restorecon_set_exclude_list(3),
       selinux_restorecon_set_alt_rootpath(3),
       selinux_restorecon_xattr(3),
       selinux_set_callback(3)