1selabel_file(5)            SELinux API documentation           selabel_file(5)
2
3
4

NAME

6       selabel_file  -  userspace SELinux labeling interface and configuration
7       file format for the file contexts backend
8

SYNOPSIS

10       #include <selinux/label.h>
11
12       int selabel_lookup(struct selabel_handle *hnd,
13                          char **context,
14                          const char *path, int mode);
15
16       int selabel_lookup_raw(struct selabel_handle *hnd,
17                          char **context,
18                          const char *path, int mode);
19

DESCRIPTION

21       The file contexts backend maps from pathname/mode combinations into se‐
22       curity  contexts.  It  is used to find the appropriate context for each
23       file when relabeling a file system. The returned context must be  freed
24       using freecon(3).
25       selabel_lookup(3)  describes  the  function  with  its return and error
26       codes, however the following errno is clarified further  for  the  file
27       contexts backend:
28
29              ENOENT No context corresponding to the path and mode was found -
30                     This will also be returned when the file contexts  series
31                     of files have a context of <<none>> against the path (see
32                     the FILE FORMAT section).
33
34       The path argument should be set to the full pathname of the file  whose
35       assigned  context  is being checked. The mode argument should be set to
36       the mode bits of the file, as determined by lstat(2). mode may be zero,
37       however full matching may not occur.
38
39       Any  messages  generated by selabel_lookup(3) are sent to stderr by de‐
40       fault, although this can be changed by selinux_set_callback(3).
41
42       selabel_lookup_raw(3) behaves identically to selabel_lookup(3) but does
43       not perform context translation.
44
45       The  FILES  section details the configuration files used to determine a
46       file context.
47

OPTIONS

49       In addition to the global options described  in  selabel_open(3),  this
50       backend recognizes the following options:
51
52              SELABEL_OPT_PATH
53                     A  non-null  value  for this option specifies a path to a
54                     file that will be opened in lieu  of  the  standard  file
55                     contexts  file.  This value is also used as the base name
56                     for determining the names of local customization files.
57
58              SELABEL_OPT_BASEONLY
59                     A non-null value for this option indicates that any local
60                     customizations to the file contexts mapping should be ig‐
61                     nored.
62
63              SELABEL_OPT_SUBSET
64                     A non-null value for this option is interpreted as a path
65                     prefix, for example "/etc".  Only file context specifica‐
66                     tions with starting with a first  component  that  prefix
67                     matches  the  given prefix are loaded.  This may increase
68                     lookup performance, however any attempt to look up a path
69                     not  starting with the given prefix may fail.  This opti‐
70                     mization  is  no  longer  required  due  to  the  use  of
71                     file_contexts.bin files and is deprecated.
72

FILES

74       The  file context files used to retrieve the default context depends on
75       the SELABEL_OPT_PATH parameter passed to selabel_open(3). If NULL, then
76       the  SELABEL_OPT_PATH value will default to the active policy file con‐
77       texts location (as returned by selinux_file_context_path(3)), otherwise
78       the actual SELABEL_OPT_PATH value specified is used.
79
80       If  SELABEL_OPT_BASEONLY  is set, then the following files will be pro‐
81       cessed:
82
83              1.  The mandatory file contexts file that is  either  the  fully
84                  qualified  file name from SELABEL_OPT_PATH.value or if NULL,
85                  then the path returned by selinux_file_context_path(3).
86
87              2.  The optional local and distribution substitution files  that
88                  perform path aliasing on the 'in memory' version of the file
89                  contexts file.
90                  These files have the same name as the  mandatory  file  con‐
91                  texts file with the extensions .subs and .subs_dist added.
92
93       If  the  SELABEL_OPT_BASEONLY is not set, then the following files will
94       be processed:
95
96              1.  The mandatory file contexts file that is  either  the  fully
97                  qualified  file name from SELABEL_OPT_PATH.value or if NULL,
98                  then the path returned by selinux_file_context_path(3).
99
100              2.  The optional local customizations file  that  has  the  same
101                  name  as the mandatory file contexts file with the extension
102                  .local added.
103                  selinux_file_context_local_path(3) will return  the  default
104                  path to this file.
105
106              3.  The  optional  user  home directory customizations file that
107                  has the same name as the mandatory file contexts  file  with
108                  the extension .homedirs added.
109                  selinux_file_context_homedir_path(3) will return the default
110                  path to this file.
111
112              4.  The optional local and distribution substitution files  that
113                  perform  any path aliasing on the 'in memory' version of the
114                  file contexts file  (and  the  .local  and/or  .homedirs  if
115                  present).  These  files  have the same name as the mandatory
116                  file contexts file with the extensions .subs and  .subs_dist
117                  added.
118                  selinux_file_context_subs_path(3)    and   selinux_file_con‐
119                  text_subs_dist_path(3) will  return  the  default  paths  to
120                  these files.
121
122       The default file context series of files are:
123             /etc/selinux/{SELINUXTYPE}/contexts/files/file_contexts
124             /etc/selinux/{SELINUXTYPE}/contexts/files/file_contexts.local
125             /etc/selinux/{SELINUXTYPE}/contexts/files/file_contexts.homedirs
126             /etc/selinux/{SELINUXTYPE}/contexts/files/file_contexts.subs
127             /etc/selinux/{SELINUXTYPE}/contexts/files/file_contexts.subs_dist
128
129       Where  {SELINUXTYPE}  is  the entry from the selinux configuration file
130       config (see selinux_config(5)).
131
132       Only the file_contexts file is mandatory, the remainder are optional.
133
134       The entries within the file contexts series of files are shown  in  the
135       FILE FORMAT section.
136

FILE FORMAT

File Contexts Format

139       Each  line  within  the  file_contexts  and the two customization files
140       (.local and .homedirs) is as follows:
141
142              pathname [file_type] context
143
144       Where:
145              pathname
146                     An entry that defines the path to be labeled.   May  con‐
147                     tain  either a fully qualified path, or a Perl compatible
148                     regular expression  (PCRE),  describing  fully  qualified
149                     path(s).   The  only  PCRE  flag  in use is PCRE2_DOTALL,
150                     which causes a wildcard '.' to match anything,  including
151                     a  new line.  Strings representing paths are processed as
152                     bytes (as opposed to  Unicode),  meaning  that  non-ASCII
153                     characters are not matched by a single wildcard.
154              file_type
155                     An optional file type consisting of:
156                            -b - Block Device      -c - Character Device
157                            -d - Directory         -p - Named Pipe
158                            -l - Symbolic Link     -s - Socket
159                            -- - Ordinary file
160              context
161                     This entry can be either:
162
163                            a.  The  security context that will be assigned to
164                                the file (i.e. returned as context).
165
166                            b.  A value of <<none>> can be  used  to  indicate
167                                that  the  matching files should not be re-la‐
168                                beled and causes selabel_lookup(3)  to  return
169                                -1 with errno set to ENOENT.
170
171       Example:
172              # ./contexts/files/file_contexts
173              # pathname file_type  context
174              /.*                   system_u:object_r:default_t:s0
175              /[^/]+        --      system_u:object_r:etc_runtime_t:s0
176              /tmp/.*               <<none>>
177
178

Substitution File Format

180       Each  line within the substitution files (.subs and .subs_dist) has the
181       form:
182              subs_pathname pathname
183
184       Where:
185              pathname
186                     A path that matches an entry in one or more of  the  file
187                     contexts policy configuration file.
188              subs_pathname
189                     The  path  that  will  be aliased (considered equivalent)
190                     with pathname by the look up process.
191
192       Example:
193              # ./contexts/files/file_contexts.subs
194              # pathname  subs_pathname
195              /myweb      /var/www
196              /myspool    /var/spool/mail
197
198              Using the above example, when selabel_lookup(3) is passed a path
199              of  /myweb/index.html  the  function  will substitute the /myweb
200              component with /var/www, therefore the path used is:
201
202                     /var/www/index.html
203

NOTES

205       1.  If contexts are to be  validated,  then  the  global  option  SELA‐
206           BEL_OPT_VALIDATE  must  be  set  before calling selabel_open(3). If
207           this is not set, then it is possible for an invalid context  to  be
208           returned.
209
210       2.  If  the size of file contexts series of files contain many entries,
211           then selabel_open(3) may have a delay as it reads in the files, and
212           if requested validates the entries.
213
214       3.  Depending on the version of SELinux it is possible that a file_con‐
215           texts.template file may also be present, however this is now depre‐
216           cated.
217           The template file has the same format as the file_contexts file and
218           may also contain the keywords HOME_ROOT, HOME_DIR, ROLE  and  USER.
219           This  functionality has now been moved to the policy store and man‐
220           aged by semodule(8) and genhomedircon(8).
221

SEE ALSO

223       selinux(8), selabel_open(3), selabel_lookup(3), selabel_stats(3),
224       selabel_close(3), selinux_set_callback(3),
225       selinux_file_context_path(3), freecon(3), selinux_config(5), lstat(2),
226       selinux_file_context_subs_path(3),
227       selinux_file_context_subs_dist_path(3),
228       selinux_file_context_homedir_path(3),
229       selinux_file_context_local_path(3), semodule(8), genhomedircon(8)
230
231
232
233Security Enhanced Linux           01 Dec 2011                  selabel_file(5)
Impressum