selinux_restorecon(3)

📦
version 3.11 · 4 versions
, in centos-stream 10, fedora 44

💖 selinux_restorecon — restore file(s) default SELinux security contexts 💖

okay bestie, gather round, because this is the selinux_restorecon(3) page from the SELinux API documentation and it's literally the glow-up your file labels have been waiting for ✨

🌸 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)), and it does it based on these two icons 👑:

  • 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 SHA256 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 SHA256 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. no cap, we're leaving those attrs alone 🙈
    • SELINUX_RESTORECON_IGNORE_DIGEST — force the checking of labels even if the stored SHA256 digest matches the specfile entries SHA256 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. it's giving "look but don't touch" 💅
    • 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 SHA256 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. if it's not there, it's not our problem 🫶
    • 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 SHA256 digest will not have been written to the security.sehash extended attribute.
    • SELINUX_RESTORECON_SET_USER_ROLE — Set the user and role component of the security context too.
    • SELINUX_RESTORECON_COUNT_RELABELED — Count the number of relabeled files or the number that would be relabeled if SELINUX_RESTORECON_NOCHANGE was not set.
    • SELINUX_RESTORECON_SKIP_MULTILINK — Skip any non-directory files that have more than one hard link. Use this option when relabeling untrusted directories that might contain hard links to files owned by others. 🚩 lowkey a safety girlie

The behavior regarding the checking and updating of the SHA256 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. bestie. link the library. i'm begging 😭

⭐ RETURN VALUE ⭐

On success, zero is returned. On error, -1 is returned and errno is set appropriately. that's the whole vibe check, 0 good, -1 not good 💀

🎀 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 SHA256 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 /
  1. Should any of the specfile entries have changed, then when selinux_restorecon() is run again with the SELINUX_RESTORECON_RECURSE flag set, new SHA256 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).
  2. /sys and in-memory filesystems do not support the security.sehash extended attribute and are automatically excluded from any relabeling checks. they said "not invited to the party" 🌈
  3. 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 👑

and that's the whole page, bestie 🫶 from the Security Enhanced Linux girlies, dated 20 Oct 2015, dropping selinux_restorecon(3) — go forth and relabel responsibly ✨💖🎀

📦 where this page comes from