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 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 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 de‐
40 fault, 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 ig‐
61 nored.
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 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 a. The security context that will be assigned to
164 the file (i.e. returned as context).
165 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 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
180 Each line within the substitution files (.subs and .subs_dist) has the
181 form:
182 subs_pathname pathname
183 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 Example:
193 # ./contexts/files/file_contexts.subs
194 # pathname subs_pathname
195 /myweb /var/www
196 /myspool /var/spool/mail
197 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 /var/www/index.html
203
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 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 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
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)
230Security Enhanced Linux 01 Dec 2011 selabel_file(5)