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_con‐
128 texts.subs_dist
129 Where {SELINUXTYPE} is the entry from the selinux configuration file
131 config (see selinux_config(5)).
132 Only the file_contexts file is mandatory, the remainder are optional.
134 The entries within the file contexts series of files are shown in the
136 FILE FORMAT section.
137
140 Each line within the file_contexts and the two customization files
141 (.local and .homedirs) is as follows:
142 pathname [file_type] context
144 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 a. The security context that will be assigned to
159 the file (i.e. returned as context).
160 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 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
175 Each line within the substitution files (.subs and .subs_dist) has the
176 form:
177 subs_pathname pathname
178 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 Example:
188 # ./contexts/files/file_contexts.subs
189 # pathname subs_pathname
190 /myweb /var/www
191 /myspool /var/spool/mail
192 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 /var/www/index.html
198
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 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 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
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)
225Security Enhanced Linux 01 Dec 2011 selabel_file(5)