-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
This patch looks good to me. acked.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
iEYEARECAAYFAk7dH10ACgkQrlYvE4MpobP9+gCgwA9vIB0CZDaOxlPMqcst8O4t
MrAAoIJCN/tM2RhMTNVG4OyJ6tvbGfE8
=kdhu
-----END PGP SIGNATURE-----
>From 775aff7a23c3a54db225c3fb6ebe9d1a4b367f5b Mon Sep 17 00:00:00 2001
From: Richard Haines <richard_c_haines@xxxxxxxxxxxxxx>
Date: Thu, 1 Dec 2011 16:22:05 +0000
Subject: [PATCH 45/48] libselinux: Updated selabel_file(5) man page
Updated selabel_file(5) with file context configuration file format and
added file_contexts(5) man page that links to it. selabel_file(5) also
describes the .local, .homedirs, .subs and .subs_dist configuration file
formats.
Signed-off-by: Richard Haines <richard_c_haines@xxxxxxxxxxxxxx>
Signed-off-by: Eric Paris <eparis@xxxxxxxxxx>
---
libselinux/man/man5/file_contexts.5 | 1 +
libselinux/man/man5/selabel_file.5 | 203 +++++++++++++++++++++++++++++++----
2 files changed, 185 insertions(+), 19 deletions(-)
create mode 100644 libselinux/man/man5/file_contexts.5
diff --git a/libselinux/man/man5/file_contexts.5 b/libselinux/man/man5/file_contexts.5
new file mode 100644
index 0000000..9c022d8
--- /dev/null
+++ b/libselinux/man/man5/file_contexts.5
@@ -0,0 +1 @@
+.so man5/selabel_file.5
diff --git a/libselinux/man/man5/selabel_file.5 b/libselinux/man/man5/selabel_file.5
index 6cce99e..d0ecae9 100644
--- a/libselinux/man/man5/selabel_file.5
+++ b/libselinux/man/man5/selabel_file.5
@@ -1,35 +1,49 @@
.\" Hey Emacs! This file is -*- nroff -*- source.
.\"
.\" Author: Eamon Walsh (ewalsh@xxxxxxxxxxxxx) 2007
-.TH "selabel_file" "5" "18 Jun 2007" "" "SELinux API documentation"
+.TH "selabel_file" "5" "01 Dec 2011" "Security Enhanced Linux" "SELinux API documentation"
.SH "NAME"
-selabel_file \- userspace SELinux labeling interface: file contexts backend.
+selabel_file \- userspace SELinux labeling interface and configuration file format for the file contexts backend.
.SH "SYNOPSIS"
-.B #include <selinux/selinux.h>
-
.B #include <selinux/label.h>
.sp
.BI "int selabel_lookup(struct selabel_handle *" hnd ,
.in +\w'int selabel_lookup('u
.BI "security_context_t *" context ,
-
+.br
+.BI "const char *" path ", int " mode ");"
+.in
+.sp
+.BI "int selabel_lookup_raw(struct selabel_handle *" hnd ,
+.in +\w'int selabel_lookup('u
+.BI "security_context_t *" context ,
+.br
.BI "const char *" path ", int " mode ");"
.SH "DESCRIPTION"
-The file contexts backend maps from pathname/mode combinations into security contexts. It is used to find the appropriate context for each file when relabeling a file system.
-
-The
-.I path
-argument should be set to the full pathname of the file whose assigned context is being checked. The
-.I mode
-argument should be set to the mode bits of the file, as determined by
-.BR lstat (2).
+The file contexts backend maps from pathname/mode combinations into security contexts. It is used to find the appropriate context for each file when relabeling a file system. The returned \fIcontext\fR must be freed using \fBfreecon\fR(3).
+.br
+\fBselabel_lookup\fR(3) describes the function with its return and error codes, however the following \fIerrno\fR is clarified further for the file contexts backend:
+.RS
+.TP
+.B ENOENT
+No context corresponding to the \fIpath\fR and \fImode\fR was found - This will also be returned when the file contexts series of files have a context of \fB<<none>>\fR against the \fIpath\fR (see the \fBFILE FORMAT\fR section).
+.RE
+.sp
+The \fIpath\fR argument should be set to the full pathname of the file whose assigned context is being checked. The \fImode\fR argument should be set to the mode bits of the file, as determined by \fBlstat\fR(2). \fImode\fR may be zero, however full matching may not occur.
+.sp
+Any messages generated by \fBselabel_lookup\fR are sent to \fIstderr\fR by default, although this can be changed by \fBselinux_set_callback\fR(3).
+.sp
+.B selabel_lookup_raw
+behaves identically to \fBselabel_lookup\fR but does not perform context translation.
+.sp
+The \fBFILES\fR section details the configuration files used to determine a file context.
.SH "OPTIONS"
In addition to the global options described in
.BR selabel_open (3),
this backend recognizes the following options:
-
+.RS
.TP
.B SELABEL_OPT_PATH
A non-null value for this option specifies a path to a file that will be opened in lieu of the standard file contexts file. This value is also used as the base name for determining the names of local customization files.
@@ -39,10 +53,161 @@ A non-null value for this option indicates that any local customizations to the
.TP
.B SELABEL_OPT_SUBSET
A non-null value for this option is interpreted as a path prefix, for example "/etc". Only file context specifications starting with the given prefix are loaded. This may increase lookup performance, however any attempt to look up a path not starting with the given prefix will fail.
+.RE
-.SH "SEE ALSO"
-.BR selabel_open (3),
-.BR selabel_lookup (3),
-.BR selabel_stats (3),
-.BR selinux (8)
+.SH "FILES"
+The file context files used to retrieve the default context depends on the \fBSELABEL_OPT_PATH\fR parameter passed to \fBselabel_open\fR(3). If \fINULL\fR, then the \fBSELABEL_OPT_PATH\fR value will default to the active policy file contexts location (as returned by \fBselinux_file_context_path\fR(3)), otherwise the actual \fBSELABEL_OPT_PATH\fR value specified is used.
+.sp
+If \fBSELABEL_OPT_BASEONLY\fR is set, then the following files will be processed:
+.RS
+.IP "1." 4
+The mandatory file contexts file that is either the fully qualified file name from \fISELABEL_OPT_PATH.value\fR or if \fINULL\fR, then the path returned by \fBselinux_file_context_path\fR(3).
+.IP "2." 4
+The optional local and distribution substitution files that perform any substitutions on the 'in memory' version of the file contexts file.
+.br
+These files have the same name as the mandatory file contexts file with the extensions \fI.subs\fR and \fI.subs_dist\fR added.
+.RE
+.sp
+If the \fBSELABEL_OPT_BASEONLY\fR is not set, then the following files will be processed:
+.RS
+.IP "1." 4
+The mandatory file contexts file that is either the fully qualified file name from \fISELABEL_OPT_PATH.value\fR or if \fINULL\fR, then the path returned by \fBselinux_file_context_path\fR(3).
+.IP "2." 4
+The optional local customizations file that has the same name as the mandatory file contexts file with the extension \fI.local\fR added.
+.br
+\fBselinux_file_context_local_path\fR(3) will return the default path to this file.
+.IP "3." 4
+The optional user home directory customizations file that has the same name as the mandatory file contexts file with the extension \fI.homedirs\fR added.
+.br
+\fBselinux_file_context_homedir_path\fR(3) will return the default path to this file.
+.IP "4." 4
+The optional local and distribution substitution files that perform any substitutions on the 'in memory' version of the file contexts file (and the \fI.local\fR and/or \fI.homedirs\fR if present). These files have the same name as the mandatory file contexts file with the extensions \fI.subs\fR and \fI.subs_dist\fR added.
+.br
+\fBselinux_file_context_subs_path\fR(3) and \fBselinux_file_context_subs_dist_path\fR(3) will return the default paths to these files.
+.RE
+.sp
+The default file context series of files are:
+.RS
+.I /etc/selinux/{SELINUXTYPE}/contexts/files/file_contexts
+.br
+.I /etc/selinux/{SELINUXTYPE}/contexts/files/file_contexts.local
+.br
+.I /etc/selinux/{SELINUXTYPE}/contexts/files/file_contexts.homedirs
+.br
+.I /etc/selinux/{SELINUXTYPE}/contexts/files/file_contexts.subs
+.br
+.I /etc/selinux/{SELINUXTYPE}/contexts/files/file_contexts.subs_dist
+.RE
+.sp
+Where \fI{SELINUXTYPE}\fR is the entry from the selinux configuration file \fIconfig\fR (see \fBselinux_config\fR(5)).
+.sp
+Only the \fIfile_contexts\fR file is mandatory, the remainder are optional.
+.sp
+The entries within the file contexts series of files are shown in the \fBFILE FORMAT\fR section.
+
+.SH "FILE FORMAT"
+.sp
+.SH "File Contexts Format"
+.sp
+Each line within the \fIfile_contexts\fR and the two customization files (\fI.local\fR and \fI.homedirs\fR) is as follows:
+.sp
+.RS
+.I pathname [file_type] context
+.RE
+.sp
+Where:
+.br
+.RS
+.I pathname
+.RS
+An entry that defines the pathname that may be in the form of a regular expression.
+.RE
+.I file_type
+.RS
+An optional file type consisting of:
+.RS
+\fI\-b\fR \- Block Device \fI\-c\fR \- Character Device
+.br
+\fI\-d\fR \- Directory \fI\-p\fR \- Named Pipe
+.br
+\fI\-l\fR \- Symbolic Link \fI\-s\fR \- Socket
+.br
+\fI\-\-\fR \- Ordinary file
+.RE
+.RE
+.I context
+.RS
+This entry can be either:
+.RS
+.IP "a." 4
+The security context that will be assigned to the file (i.e. returned as \fIcontext\fR).
+.IP "b." 4
+A value of \fB<<none>>\fR can be used to indicate that the matching files should not be re-labeled and causes \fBselabel_lookup\fR(3) to return \-1 with \fIerrno\fR set to \fBENOENT\fR.
+.RE
+.RE
+.RE
+.sp
+Example:
+.RS
+# ./contexts/files/file_contexts
+.br
+# pathname file_type context
+.br
+/.* system_u:object_r:default_t:s0
+.br
+/[^/]+ -- system_u:object_r:etc_runtime_t:s0
+.br
+/tmp/.* <<none>>
+.RE
+.sp
+.SH "Substitution File Format"
+.sp
+Each line within the substitution files (\fI.subs\fR and \fI.subs_dist\fR) is:
+.RS
+.I pathname subs_pathname
+.RE
+.sp
+Where:
+.RS
+.I pathname
+.RS
+A path that matches an entry in one or more of the file contexts files.
+.RE
+.I subs_pathname
+.RS
+The path that will be substituted for pathname by the look up process.
+.RE
+.RE
+.sp
+Example:
+.RS
+# ./contexts/files/file_contexts.subs
+.br
+# pathname subs_pathname
+.br
+/myweb /var/www
+.br
+/myspool /var/spool/mail
+.sp
+Using the above example, when \fBselabel_lookup\fR is passed a path of \fI/myweb/index.html\fR the function will substitute the \fI/myweb\fR component with \fI/var/www\fR, therefore the path used is:
+.sp
+.RS
+.I /var/www/index.html
+.RE
+.RE
+.sp
+
+.SH "NOTES"
+.IP "1." 4
+If contexts are to be validated, then the global option \fBSELABEL_OPT_VALIDATE\fR must be set before calling \fBselabel_open\fR(3). If this is not set, then it is possible for an invalid context to be returned.
+.IP "2." 4
+If the size of file contexts series of files contain many entries, then \fBselabel_open\fR(3) may have a delay as it reads in the files, and if
+requested validates the entries. If possible use the \fBSELABEL_OPT_SUBSET\fR option to reduce the number of entries processed.
+.IP "3." 4
+Depending on the version of SELinux it is possible that a \fIfile_contexts.template\fR file may also be present, however this is now deprecated.
+.br
+The template file has the same format as the \fIfile_contexts\fR file and may also contain the keywords \fBHOME_ROOT\fR, \fBHOME_DIR\fR, \fBROLE\fR and \fBUSER\fR. This functionality has now been moved to the policy store and managed by \fBsemodule\fR(8) and \fBgenhomedircon\fR(8).
+
+.SH "SEE ALSO"
+.BR selinux "(8), " selabel_open "(3), " selabel_lookup "(3), " selabel_stats "(3), " selabel_close "(3), " selinux_set_callback "(3), " selinux_file_context_path "(3), " freecon "(3), " selinux_config "(5), " lstat "(2), "selinux_file_context_subs_path "(3), " selinux_file_context_subs_dist_path "(3), " selinux_file_context_homedir_path "(3), "selinux_file_context_local_path "(3), " semodule "(8), " genhomedircon "(8) "
--
1.7.7.4
