1selinux_restorecon(3)      SELinux API documentation     selinux_restorecon(3)
2
3
4

NAME

6       selinux_restorecon - restore file(s) default SELinux security contexts
7

SYNOPSIS

9       #include <selinux/restorecon.h>
10
11       int selinux_restorecon(const char *pathname,
12                              unsigned int restorecon_flags);
13
14       int selinux_restorecon_parallel(const char *pathname,
15                                       unsigned int restorecon_flags,
16                                       size_t nthreads);
17

DESCRIPTION

19       selinux_restorecon()   restores   file  default  security  contexts  on
20       filesystems that support extended attributes (see xattr(7)), based on:
21
22              pathname containing a directory or file to be relabeled.
23              If this is a directory and the restorecon_flags SELINUX_RESTORE‐
24              CON_RECURSE  has  been set (for descending through directories),
25              then selinux_restorecon() will write an SHA256 digest  of  spec‐
26              file    entries   calculated   by   selabel_get_digests_all_par‐
27              tial_matches(3) to an extended attribute of security.sehash once
28              the  relabeling  has  been completed successfully (see the NOTES
29              section for details).
30              These digests will be checked should selinux_restorecon() be re‐
31              run  with  the  restorecon_flags SELINUX_RESTORECON_RECURSE flag
32              set. If any of the specfile entries had been updated, the digest
33              will  also be updated. However if the digest is the same, no re‐
34              labeling checks will take place.
35              The restorecon_flags that can be used to manage the usage of the
36              SHA256 digest are:
37                     SELINUX_RESTORECON_SKIP_DIGEST
38                     SELINUX_RESTORECON_IGNORE_DIGEST
39
40              restorecon_flags contains the labeling option/rules as follows:
41
42
43                     SELINUX_RESTORECON_SKIP_DIGEST Do not check or update any
44                     extended attribute security.sehash entries.
45
46                     SELINUX_RESTORECON_IGNORE_DIGEST force  the  checking  of
47                     labels even if the stored SHA256 digest matches the spec‐
48                     file entries SHA256 digest. The specfile  entries  digest
49                     will be written to the security.sehash extended attribute
50                     once relabeling has been completed successfully  provided
51                     the  SELINUX_RESTORECON_NOCHANGE  flag  has not been set,
52                     and no errors have been skipped during the file tree walk
53                     due to the SELINUX_RESTORECON_COUNT_ERRORS flag.
54
55                     SELINUX_RESTORECON_NOCHANGE  don't change any file labels
56                     (passive check) or update the digest in the  security.se‐
57                     hash extended attribute.
58
59                     SELINUX_RESTORECON_SET_SPECFILE_CTX  If  set,  reset  the
60                     files label to match the default  specfile  context.   If
61                     not set only reset the files "type" component of the con‐
62                     text to match the default specfile context.
63
64                     SELINUX_RESTORECON_RECURSE change file and directory  la‐
65                     bels  recursively (descend directories) and if successful
66                     write an SHA256 digest of the specfile entries to an  ex‐
67                     tended attribute as described in the NOTES section.
68
69                     SELINUX_RESTORECON_VERBOSE log file label changes.
70                            Note   that   if   SELINUX_RESTORECON_VERBOSE  and
71                            SELINUX_RESTORECON_PROGRESS flags  are  set,  then
72                            SELINUX_RESTORECON_PROGRESS will take precedence.
73
74                     SELINUX_RESTORECON_PROGRESS  show  progress by outputting
75                     the number of files in 1k blocks processed to stdout.  If
76                     the SELINUX_RESTORECON_MASS_RELABEL flag is also set then
77                     the approximate percentage complete will be shown.
78
79                     SELINUX_RESTORECON_MASS_RELABEL generally set when  rela‐
80                     beling the entire OS, that will then show the approximate
81                     percentage complete. The SELINUX_RESTORECON_PROGRESS flag
82                     must also be set.
83
84                     SELINUX_RESTORECON_REALPATH convert passed-in pathname to
85                     the canonical pathname using realpath(3).
86
87                     SELINUX_RESTORECON_XDEV prevent descending into  directo‐
88                     ries  that  have a different device number than the path‐
89                     name entry from which the descent began.
90
91                     SELINUX_RESTORECON_ADD_ASSOC attempt to add  an  associa‐
92                     tion  between  an  inode and a specification. If there is
93                     already an association for the  inode  and  it  conflicts
94                     with the specification, then use the last matching speci‐
95                     fication.
96
97                     SELINUX_RESTORECON_ABORT_ON_ERROR abort on errors  during
98                     the file tree walk.
99
100                     SELINUX_RESTORECON_SYSLOG_CHANGES  log  any label changes
101                     to syslog(3).
102
103                     SELINUX_RESTORECON_LOG_MATCHES log what specfile  context
104                     matched each file.
105
106                     SELINUX_RESTORECON_IGNORE_NOENTRY  ignore  files  that do
107                     not exist.
108
109                     SELINUX_RESTORECON_IGNORE_MOUNTS do not read /proc/mounts
110                     to  obtain  a  list of non-seclabel mounts to be excluded
111                     from relabeling checks.
112                     Setting SELINUX_RESTORECON_IGNORE_MOUNTS is useful  where
113                     there  is  a  non-seclabel  fs mounted with a seclabel fs
114                     mounted on a directory below this.
115
116                     SELINUX_RESTORECON_CONFLICT_ERROR  to  treat  conflicting
117                     specifications,  such as where two hardlinks for the same
118                     inode have different contexts, as errors.
119
120                     SELINUX_RESTORECON_COUNT_ERRORS Count, but otherwise  ig‐
121                     nore, errors during the file tree walk. Only makes a dif‐
122                     ference if the SELINUX_RESTORECON_ABORT_ON_ERROR flag  is
123                     clear.  Call selinux_restorecon_get_skipped_errors(3) for
124                     fetching  the  ignored  (skipped)   error   count   after
125                     selinux_restorecon(3)  or  selinux_restorecon_parallel(3)
126                     completes with success. In case any errors  were  skipped
127                     during  the  file  tree walk, the specfile entries SHA256
128                     digest will not have been written to the  security.sehash
129                     extended attribute.
130
131              The  behavior  regarding the checking and updating of the SHA256
132              digest described above is the default behavior. It  is  possible
133              to change this by first calling selabel_open(3) and not enabling
134              the SELABEL_OPT_DIGEST  option,  then  calling  selinux_restore‐
135              con_set_sehandle(3)  to set the handle to be used by selinux_re‐
136              storecon(3).
137
138              If the pathname is a directory path, then it is possible to  set
139              directories  to be excluded from the path by calling selinux_re‐
140              storecon_set_exclude_list(3) with a NULL terminated list  before
141              calling selinux_restorecon(3).
142
143              By  default selinux_restorecon(3) reads /proc/mounts to obtain a
144              list of non-seclabel  mounts  to  be  excluded  from  relabeling
145              checks unless the SELINUX_RESTORECON_IGNORE_MOUNTS flag has been
146              set.
147
148       selinux_restorecon_parallel() is similar to selinux_restorecon(3),  but
149       accepts  another  parameter that allows to run relabeling over multiple
150       threads:
151
152              nthreads specifies the number of threads to use during  relabel‐
153              ing.  When  set  to  1,  the  behavior  is  the  same as calling
154              selinux_restorecon(3).  When set to 0, the function will try  to
155              use  as  many threads as there are online CPU cores. When set to
156              any other number, the function will try to use the given  number
157              of threads.
158
159              Note that to use the parallel relabeling capability, the calling
160              process must be linked with the libpthread  library  (either  at
161              compile time or dynamically at run time). Otherwise the function
162              will print a warning and fall back to the single threaded mode.
163

RETURN VALUE

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

NOTES

169       1.  To  improve  performance  when  relabeling file systems recursively
170           (e.g. the restorecon_flags SELINUX_RESTORECON_RECURSE flag is  set)
171           selinux_restorecon()  will  write a calculated SHA256 digest of the
172           specfile   entries   returned    by    selabel_get_digests_all_par‐
173           tial_matches(3)  to an extended attribute named security.sehash for
174           each directory in the pathname path.
175
176       2.  To check the extended attribute entry use getfattr(1), for example:
177
178                  getfattr -e hex -n security.sehash /
179
180       3.  Should  any  of  the  specfile  entries  have  changed,  then  when
181           selinux_restorecon()  is  run again with the SELINUX_RESTORECON_RE‐
182           CURSE flag set, new SHA256 digests will be calculated and all files
183           automatically   relabeled   depending   on   the  settings  of  the
184           SELINUX_RESTORECON_SET_SPECFILE_CTX flag (provided SELINUX_RESTORE‐
185           CON_NOCHANGE is not set).
186
187       4.  /sys  and  in-memory filesystems do not support the security.sehash
188           extended attribute and are automatically excluded from any relabel‐
189           ing checks.
190
191       5.  By  default  stderr is used to log output messages and errors. This
192           may  be  changed  by  calling  selinux_set_callback(3)   with   the
193           SELINUX_CB_LOG type option.
194

SEE ALSO

196       selabel_get_digests_all_partial_matches(3),
197       selinux_restorecon_set_sehandle(3),
198       selinux_restorecon_default_handle(3),
199       selinux_restorecon_get_skipped_errors(3),
200       selinux_restorecon_set_exclude_list(3),
201       selinux_restorecon_set_alt_rootpath(3),
202       selinux_restorecon_xattr(3),
203       selinux_set_callback(3)
204
205
206
207Security Enhanced Linux           20 Oct 2015            selinux_restorecon(3)
Impressum