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
22       security  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
40       default, 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
61                     ignored.
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_con‐
128              texts.subs_dist
129
130       Where {SELINUXTYPE} is the entry from the  selinux  configuration  file
131       config (see selinux_config(5)).
132
133       Only the file_contexts file is mandatory, the remainder are optional.
134
135       The  entries  within the file contexts series of files are shown in the
136       FILE FORMAT section.
137

FILE FORMAT

File Contexts Format

140       Each line within the file_contexts  and  the  two  customization  files
141       (.local and .homedirs) is as follows:
142
143              pathname [file_type] context
144
145       Where:
146              pathname
147                     An  entry  that  defines  the pathname that may be in the
148                     form of a regular expression.
149              file_type
150                     An optional file type consisting of:
151                            -b - Block Device      -c - Character Device
152                            -d - Directory         -p - Named Pipe
153                            -l - Symbolic Link     -s - Socket
154                            -- - Ordinary file
155              context
156                     This entry can be either:
157
158                            a.  The security context that will be assigned  to
159                                the file (i.e. returned as context).
160
161                            b.  A  value  of  <<none>> can be used to indicate
162                                that the matching  files  should  not  be  re-
163                                labeled and causes selabel_lookup(3) to return
164                                -1 with errno set to ENOENT.
165
166       Example:
167              # ./contexts/files/file_contexts
168              # pathname file_type  context
169              /.*                   system_u:object_r:default_t:s0
170              /[^/]+        --      system_u:object_r:etc_runtime_t:s0
171              /tmp/.*               <<none>>
172
173

Substitution File Format

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

NOTES

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

SEE ALSO

218       selinux(8), selabel_open(3), selabel_lookup(3), selabel_stats(3),
219       selabel_close(3), selinux_set_callback(3),
220       selinux_file_context_path(3), freecon(3), selinux_config(5), lstat(2),
221       selinux_file_context_subs_path(3),
222       selinux_file_context_subs_dist_path(3),
223       selinux_file_context_homedir_path(3),
224       selinux_file_context_local_path(3), semodule(8), genhomedircon(8)
225
226
227
228Security Enhanced Linux           01 Dec 2011                  selabel_file(5)
Impressum