{{Template:Note}} It is OK to wait until <code>%postun</code> (rather than <code>%preun</code>) to remove policy modules because the <code>mymodule.pp</code>

+

It is OK to wait until <code>%postun</code> (rather than <code>%preun</code>) to remove policy modules because the <code>mymodule.pp</code> files are used only at module installation time and are not needed after that point, so it doesn't matter if the files are removed before the policy module is uninstalled.

−

files are used only at module installation time and are not needed after that point, so it doesn't matter if the files

+

−

are removed before the policy module is uninstalled.

+

−

{{Template:Note}} Using <code>semodule -i</code> (''install'') rather than <code>semodule -u</code> (''upgrade'') ensures that your policy module will be loaded even if there is an existing module installed with a higher version number; using the ''upgrade'' option in such a situation would result in the module not getting loaded, but <code>semodule -l</code> showing that a module <code>mymodule</code> is loaded, which could lead to some confusing bug reports for <code>myapp</code>.

+

Using <code>semodule -i</code> (''install'') rather than <code>semodule -u</code> (''upgrade'') ensures that your policy module will be loaded even if there is an existing module installed with a higher version number; using the ''upgrade'' option in such a situation would result in the module not getting loaded, but <code>semodule -l</code> showing that a module <code>mymodule</code> is loaded, which could lead to some confusing bug reports for <code>myapp</code>.

−

{{Template:Warning}} Note that you mustn't do a <code>condrestart</code> in <code>%postun</code> to transition a dæmon process back to the unconfined domain

+

Note that you mustn't do a <code>condrestart</code> in <code>%postun</code> to transition a dæmon process back to the unconfined domain '''after''' the module has been unloaded. You first have to transition the dæmon domain, '''then''' remove the policy module. Otherwise the process may end up in an odd state and can't be killed until SELinux is disabled:

−

'''after''' the module has been unloaded. You first have to transition the dæmon domain, '''then''' remove the policy module.

+

<pre>

−

Otherwise the process may end up in an odd state and can't be killed until SELinux is disabled:

+

%post selinux

−

<pre>%post selinux

+

/usr/sbin/setsebool myapp_disable_trans 0 &> /dev/null || :

/usr/sbin/setsebool myapp_disable_trans 0 &> /dev/null || :

Line 232:

Line 258:

for selinuxvariant in %{selinux_variants}

for selinuxvariant in %{selinux_variants}

do

do

−

/usr/sbin/semodule -s ${selinuxvariant} -r mymodule &> /dev/null || :

+

/usr/sbin/semodule -s ${selinuxvariant} -r mymodule &> /dev/null || :

−

done</pre>

+

done

+

</pre>

+

Now that <code>*_disable_trans</code> booleans aren't used any more, this arrangement would have to be replaced with one that checked whether the dæmon was running at the start of <code>%postun</code>, stopped the dæmon, removed the module, then

+

restarted the dæmon if it had originally been running.

== Policy Revisions ==

== Policy Revisions ==

Line 269:

Line 298:

packages older than the version containing <code>mymodule</code>.

packages older than the version containing <code>mymodule</code>.

Let's say for example that <code>mymodule</code> is included in <code>selinux-policy</code> version 3.0.1:

Let's say for example that <code>mymodule</code> is included in <code>selinux-policy</code> version 3.0.1:

−

<pre>Obsoletes: myapp-selinux

+

<pre>

−

Conflicts: selinux-policy < 3.0.1</pre>

+

Obsoletes: myapp-selinux

+

Conflicts: selinux-policy < 3.0.1

+

</pre>

Using ''Conflicts'' rather a versioned dependency of ''selinux-policy >= 3.0.1'' is necessary in order to

Using ''Conflicts'' rather a versioned dependency of ''selinux-policy >= 3.0.1'' is necessary in order to

allow <code>myapp</code> to be installed without <code>selinux-policy</code> for those people not using SELinux.

allow <code>myapp</code> to be installed without <code>selinux-policy</code> for those people not using SELinux.

Line 276:

Line 307:

== Examples ==

== Examples ==

−

The following packages in Fedora ["Extras"] include SELinux policy modules:

Packaging SELinux Policy Modules

Fedora Core 5 introduced a new SELinux feature: loadable policy modules.
Policy modules allow an SELinux policy for an application to be developed alongside and packaged with the application itself,
rather than having to integrate the policy with the monolithic base policy, as was the case for Fedora Core 4 and earlier releases.
This page presents guidelines for how to package a policy module alongside your application in the same source RPM package.

Policy modules can also be used in Red Hat Enterprise Linux 5 and clones.

Note that developing the actual SELinux policy for your application is outside the scope of this document.

Separate Subpackage?

One of the first decisions to be made is whether to have a separate subpackage for your SELinux policy module.
There are advantages each way.

Having everything in one package is easier to maintain and you can always be sure that the SELinux policy installed on a system is a version of the policy appropriate for the version of the main application itself

Having a separate subpackage for the SELinux policy means that the main application package does not need to have a dependency on the selinux-policy package, and installation/upgrades of the main application will be quicker because the scriptlets needed to install the SELinux policy module will not need to be run on systems not using your SELinux policy package

Either approach is OK, choose whichever is most appropriate for you and your package.

For the remainder of this document, the examples will assume that the main application being packaged is called myapp,
there is a separate myapp-selinux subpackage for the SELinux policy module,
and the SELinux policy module is called mymodule.
If you are creating an integrated package rather than using a subpackage for the SELinux policy module,
everything that applies to myapp-selinux should be applied to myapp instead, unless otherwise noted.

Separate Package Altogether?

Another possibility is to have an entirely separate package for the SELinux policy module.
This has the advantages of keeping the spec files much simpler and easier to read,
allows for separate maintainers of the main and -selinux packages, and
selinux packages can be updated without pushing new builds of the main package.
However, care would have to be taken to make sure that the selinux package is updated with
the main package as needed.

On the other hand, policy modules can be thought of as being rather like kernel modules,
in that they're things that are useful and usable whilst still under development but that ideally
should eventually become unnecessary because they get merged into the
main upstream project. So a separate package should be a short-lived package really,
and should probably get special permission to be included, as with kernel modules (see Packaging:KernelModules ).

So combining the SELinux policy module with the main package SRPM is preferred for now,
though this topic is open for discussion for anyone with strong views on it.

Build Dependencies

The /usr/share/selinux/devel/policyhelp requirement is necessary to extract
the version number of the selinux-policy package being built against, which
is used to enforce a minimum version requirement on selinux-policy when the
built package is installed. The policyhelp file itself can be found in either
the selinux-policy, selinux-policy-devel, or selinux-policy-doc
package (depending on OS release), which is why we cannot simply use a package name unless
we are prepared to sacrifice spec file portability.

Runtime Dependencies

As the compiled policy module packages (mymodule.pp) will be installed into these directories:

it is necessary for the myapp-selinux package to have a dependency on selinux-policy in order to
satisfy directory ownership requirements.

However, a straightforward dependency on that package is not quite enough.
Policy modules compiled using one version of selinux-policy may not work with older selinux-policy versions
(see this example for instance).
So the dependency needs to be a versioned dependency, requiring that the version of selinux-policy on the
target system is at least as new as the version of selinux-policy that the package was built with.

There is no particularly clean and straighforward way of determining the current policy version at the moment,
but this hack works for all selinux-policy packages since Fedora Core 5 was released:

If you are not building an integrated package,
then the myapp-selinux package needs to have a dependency on the myapp package.
This is necessary to ensure that the packages are installed in the correct order if both packages are installed in the same
rpm transaction, which in turn is necessary in order to ensure that the post-install scriptlet of the myapp-selinux
package can set the correct file contexts. Whilst this is only strictly necessary if your policy module includes file
context specifications, it's good practice to do this anyway and it might get forgotten if at some time new file contexts
were added to your policy. It also makes sense to make this dependency a fully-versioned dependency, to ensure that the
myapp-selinux package gets updated whenever the end user updates the main myapp package.

Requires: %{name} = %{version}-%{release}

Building the Policy Modules

You should build your policy module for all of the base policies supported in the distribution version you are targeting.
For Fedora Core 5 and 6, this means the mls, strict, and targeted policies.

%global selinux_variants mls strict targeted

If you would rather not hardcode the variants, you could use this approach:

The source code for your SELinux policy module will include at least a type enforcement rules file (mymodule.te),
and possibly also a file contexts file (mymodule.fc) and an interface file (mymodule.if).
You could include each of these as separate source files:

Source2: mymodule.te
Source3: mymodule.fc
Source4: mymodule.if

or you might bundle them together as a tarball:

Source2: mymodule-0.1.tar.bz2

Either way is OK but separate source files is probably better for packages aiming to go into Fedora because the
policy files themselves can be maintained in Fedora CVS.

To compile the policy files, copy them into an empty directory in %prep and use /usr/share/selinux/devel/Makefile in %build:

If there is nothing in your policy that is specific to a particular base policy, it is likely
that the compiled policy files will be identical to each other, so in order to save space and
not install duplicate files, you might want to link identical files together at the end of %install:

It's better to use a program like hardlink to check that the files are identical rather than simply
assuming that they will be be, as macros you use in your policy sources might have base-policy-specific
elements.

The %files list

It's useful to include your policy sources as documentation in the myapp-selinux package,
not only because it may help users of your package understand the policy, but also to keep rpmlint quiet about
missing documentation :-)

The %{_datadir}/selinux/* directories into which the mymodule.pp files are installed are owned by the
selinux-policy package, so your package should not own those directories itself; just include the mymodule.pp files
themselves in the %files list:

Scriptlets

The post-install and post-uninstall scripts of the myapp-selinux package are responsible for
the linking and unlinking respectively of your policy module with each of the base policies.
This is done using the semodule command.
Usually, target systems will only have one of the base policies installed, so it's important
that the scriptlets don't produce spurious error messages nor return failure exit codes that
would break an RPM transaction.

In addition to installing the policy module, you will probably need your scriptlets to fix up
some file contexts if your policy module includes any file contexts specifications.
The fixfiles command can be used to fix the file contexts of all files in a specified package,
and is useful to use in scriptlets. This may not be sufficient in all cases though, as you may want
to set contexts of files not actually included in the myapp package itself, such as log or cache
files created by myapp. In these cases, the restorecon command may be useful.
There may also be other things usefully done in the scriptlets, such as restarting the server
dæmon if myapp is a server. Doing a condrestart of the server's initscript after installing the policy module
will ensure that it runs in your confined domain.
So think carefully about what needs to be done in your scriplets as they will usually need more customisation
than any of the other examples in this document.

Don't forget to add scriptlet dependencies for any commands used in the scriptlets.
If you use fixfiles -R myapp in a scriptlet, there should be a dependency of myapp for that scriptlet.

It is OK to wait until %postun (rather than %preun) to remove policy modules because the mymodule.pp files are used only at module installation time and are not needed after that point, so it doesn't matter if the files are removed before the policy module is uninstalled.

Using semodule -i (install) rather than semodule -u (upgrade) ensures that your policy module will be loaded even if there is an existing module installed with a higher version number; using the upgrade option in such a situation would result in the module not getting loaded, but semodule -l showing that a module mymodule is loaded, which could lead to some confusing bug reports for myapp.

Note that you mustn't do a condrestart in %postun to transition a dæmon process back to the unconfined domain after the module has been unloaded. You first have to transition the dæmon domain, then remove the policy module. Otherwise the process may end up in an odd state and can't be killed until SELinux is disabled:

Now that *_disable_trans booleans aren't used any more, this arrangement would have to be replaced with one that checked whether the dæmon was running at the start of %postun, stopped the dæmon, removed the module, then
restarted the dæmon if it had originally been running.

Policy Revisions

Be sure to increase the policy version number in the mymodule.te file whenever you make changes to the policy sources.
Whilst the use of semodule -i to install the module means that version number checking isn't done by semodule at
install-time, it will be useful to know the exact version of the policy being used if you receive any bug reports,
and this can be checked using semodule -l.

The actual version numbering used for the policy module can be totally independent of the version numbering of the
main application, since either may change without a change being needed for the other.
It is conventional to use a three-part version number like 1.4.7 (see the output of semodule -l)
but what you use is up to you; just be sure to bump the version number every time there is a change to the polioy.

Version number comparisons are done using strverscmp() so in theory any character that can be used there
is OK in a version number, but for sanity's sake it's best to stick with [0-9a-z.] .
Upstream reference policy versioning is x.y.z, where z is incremented every
time the module changes, y is incremented on a upstream release if the
module has changed since the last release (i.e. z != 0), and x is
incremented on major changes to the module.
Policy modules in development should probably have x = 0, with version 1 reserved for the first appearance
in the upstream policy.

Obsoletes

If your policy module is stable and there are no apparent issues with it, it's a good idea to submit it for
inclusion in the upstream reference policy .
That way, all distributions using SELinux will benefit from your
work, not just the users of your myapp-selinux package.

Once the policy module is included upstream, there is no longer any need to ship the standalone module
and in fact it is unlikely to be usable since any types it defines would conflict with those in the upstream policy.
In order to maintain an upgrade path in this situation, the first version of the myapp package designed to
work with the new upstream policy module should obsolete the myapp-selinux package and conflict with selinux-policy
packages older than the version containing mymodule.
Let's say for example that mymodule is included in selinux-policy version 3.0.1:

Obsoletes: myapp-selinux
Conflicts: selinux-policy < 3.0.1

Using Conflicts rather a versioned dependency of selinux-policy >= 3.0.1 is necessary in order to
allow myapp to be installed without selinux-policy for those people not using SELinux.

The use of restorecon in one example's scriptlets and fixfiles in the other example is
to indicate that there's no one right way of doing things rather than some subtly different requirements between separate and integrated packages.