1selabel_file(5) SELinux API documentation selabel_file(5)
2
6 selabel_file - userspace SELinux labeling interface and configuration
7 file format for the file contexts backend
8
10 #include <selinux/label.h>
11 int selabel_lookup(struct selabel_handle *hnd,
13 char **context,
14 const char *path, int mode);
15 int selabel_lookup_raw(struct selabel_handle *hnd,
17 char **context,
18 const char *path, int mode);
19
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 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 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 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 selabel_lookup_raw(3) behaves identically to selabel_lookup(3) but does
43 not perform context translation.
44 The FILES section details the configuration files used to determine a
46 file context.
47
49 In addition to the global options described in selabel_open(3), this
50 backend recognizes the following options:
51 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 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 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
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 If SELABEL_OPT_BASEONLY is set, then the following files will be pro‐
81 cessed:
82 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 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 If the SELABEL_OPT_BASEONLY is not set, then the following files will
94 be processed:
95 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 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 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 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 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 Where {SELINUXTYPE} is the entry from the selinux configuration file
130 config (see selinux_config(5)).
131 Only the file_contexts file is mandatory, the remainder are optional.
133 The entries within the file contexts series of files are shown in the
135 FILE FORMAT section.
136
139 Each line within the file_contexts and the two customization files
140 (.local and .homedirs) is as follows:
141 pathname [file_type] context
143 Where:
145 pathname
146 An entry that defines the pathname that may be in the
147 form of a regular expression.
148 file_type
149 An optional file type consisting of:
150 -b - Block Device -c - Character Device
151 -d - Directory -p - Named Pipe
152 -l - Symbolic Link -s - Socket
153 -- - Ordinary file
154 context
155 This entry can be either:
156 a. The security context that will be assigned to
158 the file (i.e. returned as context).
159 b. A value of <<none>> can be used to indicate
161 that the matching files should not be re-
162 labeled and causes selabel_lookup(3) to return
163 -1 with errno set to ENOENT.
164 Example:
166 # ./contexts/files/file_contexts
167 # pathname file_type context
168 /.* system_u:object_r:default_t:s0
169 /[^/]+ -- system_u:object_r:etc_runtime_t:s0
170 /tmp/.* <<none>>
171
174 Each line within the substitution files (.subs and .subs_dist) has the
175 form:
176 subs_pathname pathname
177 Where:
179 pathname
180 A path that matches an entry in one or more of the file
181 contexts policy configuration file.
182 subs_pathname
183 The path that will be aliased (considered equivalent)
184 with pathname by the look up process.
185 Example:
187 # ./contexts/files/file_contexts.subs
188 # pathname subs_pathname
189 /myweb /var/www
190 /myspool /var/spool/mail
191 Using the above example, when selabel_lookup(3) is passed a path
193 of /myweb/index.html the function will substitute the /myweb
194 component with /var/www, therefore the path used is:
195 /var/www/index.html
197
199 1. If contexts are to be validated, then the global option SELA‐
200 BEL_OPT_VALIDATE must be set before calling selabel_open(3). If
201 this is not set, then it is possible for an invalid context to be
202 returned.
203 2. If the size of file contexts series of files contain many entries,
205 then selabel_open(3) may have a delay as it reads in the files, and
206 if requested validates the entries.
207 3. Depending on the version of SELinux it is possible that a file_con‐
209 texts.template file may also be present, however this is now depre‐
210 cated.
211 The template file has the same format as the file_contexts file and
212 may also contain the keywords HOME_ROOT, HOME_DIR, ROLE and USER.
213 This functionality has now been moved to the policy store and man‐
214 aged by semodule(8) and genhomedircon(8).
215
217 selinux(8), selabel_open(3), selabel_lookup(3), selabel_stats(3),
218 selabel_close(3), selinux_set_callback(3),
219 selinux_file_context_path(3), freecon(3), selinux_config(5), lstat(2),
220 selinux_file_context_subs_path(3),
221 selinux_file_context_subs_dist_path(3),
222 selinux_file_context_homedir_path(3),
223 selinux_file_context_local_path(3), semodule(8), genhomedircon(8)
224Security Enhanced Linux 01 Dec 2011 selabel_file(5)