From Fedora Project Wiki

(Draft.)
Line 4: Line 4:
 
== Configuring the Development Environment ==
 
== Configuring the Development Environment ==
  
{{admon/note|TODO|The goal of this section is to help people setup their system to build SELinux policy and Fedora Modules. Any temporary hacks that are required should be called out in admon/important notes.}}
+
The goal of this section is to help people setup their system to build SELinux policy and Fedora Modules.
  
=== Building RPMs and Fedora Modules ===
+
=== Building Fedora Modules ===
  
{{admon/note|TODO|This subsection should cover the general installation and setup of the tools and packages necessary to build both RPMs and Fedora Modules.}}
+
Module build is facilitated by the fm-oschestrator (''module-build-service'' package), which is controlled by a set of ''fedpkg'' commands.  
 
 
TODO - discussion/explanation
 
  
 
<pre>
 
<pre>
# dnf install module-build-service
+
# dnf install fedpkg module-build-service
 
</pre>
 
</pre>
  
=== Building SELinux Policy ===
+
=== Building SELinux Policy modules and RPMs ===
  
{{admon/note|TODO|This subsection should cover the general installation and setup of the tools and packages necessary to build SELinux policy.}}
+
SELinux policy module build is a multi step process covered by a Makefile provided by ''selinux-policy-devel'' pacakge together with all the necessary tools. Since the finished module will be packaged in an rpm, we also need ''rpm-build'' package.  
  
TODO - discussion/explanation
+
The following is only necessary for local testing of the SELinux policy package since the build is otherwise done by the module-build-service.
  
 
<pre>
 
<pre>
 
# dnf install selinux-policy-devel rpm-build
 
# dnf install selinux-policy-devel rpm-build
 +
</pre>
 +
 +
=== FM repositories ===
 +
 +
By default dnf does not have access to FM repositories even though it is able to work with modules. Install "fedora-repos-modular-<fedora version>" package to gain acces to "Fedora Modular" modules.
 +
 +
<pre>
 +
# dnf install fedora-repos-modular-28
 
</pre>
 
</pre>
  
 
== Packaging SELinux Policy ==
 
== Packaging SELinux Policy ==
 +
{{admon/tip| Independent Policy Project | Please see the [https://docs.fedoraproject.org//en-US/Fedora/25/html/SELinux_Users_and_Administrators_Guide/Security-Enhanced_Linux-prioritizing_sepolicy_modules.html Independent Policy Project wiki] for in-depth guide on custom SELinux policy module packaging.}}
  
{{admon/note|TODO|The goal of this section is to help people understand how to package individual SELinux policy modules into a RPM; we should work closely with the Independent Policy Project (IPP), perhaps simply linking to IPP wiki docs if/when they exist.}}
+
From modularity point of view the SELinux policy needs to be available in the form of RPM package. It's up to the maintainer to choose weather the policy package is standalone or a sub-package of the corresponding software. The former is covered by the [https://fedoraproject.org/wiki/PackagingDrafts/SELinux_Independent_Policy Independent Policy Project (IPP) wiki]. The latter only differs in the RPM spec file and can be seen in the [https://src.fedoraproject.org/rpms/memcached memcached package].
  
=== SELinux Policy Packaging ===
+
=== SELinux Policy Priorities ===
  
{{admon/note|TODO|This subsection should provide a very brief introduction to SELinux policy packaging on Fedora and refer readers to the [[SELinux/IndependentPolicy]] page.}}
+
{{admon/tip| Documentation | For more information about SELinux policy module priorities please see [https://docs.fedoraproject.org//en-US/Fedora/25/html/SELinux_Users_and_Administrators_Guide/Security-Enhanced_Linux-prioritizing_sepolicy_modules.html SELinux Users and Administrators Guide].}}
  
=== SELinux Policy Priorities ===
+
Priority 200 should be used for all custom policy modules falling under IPP project regardless of the means of distribution (FM, RPM, ...). This value is set in the %selinux_modules_install macro and should not be overridden by package maintainers.
 +
 
 +
=== SELinux Base Policies ===
 +
 
 +
{{admon/note|TODO|This subsection should cover the different SELinux base policies, e.g. targeted vs MLS, and explain how to handle this in the specfiles.}}
  
{{admon/note|TODO|This subsection should cover the prioritized policy store, explaining the different levels used in Fedora.}}
+
Q - have we tried packaging both a MLS and targeted policy module in the memcached prototype?  If not, this is something we should do to verify that it works as expected.
  
Q - what priority do we expect policy developers/packagers to use here?
+
No, only targeted so far.
  
Q - is there anything else specific to SELinux Policy packaging in Fedora Modularity that we should mention?
 
  
 
=== Example SELinux Policy RPM specfile ===
 
=== Example SELinux Policy RPM specfile ===
  
{{admon/note|TODO|This subsection should provide an example SELinux policy module specfile with comments and annotations.}}
+
See [https://pagure.io/memcached-selinux/blob/master/f/memcached-selinux.spec memcached-selinux spec file] for example of standalone SELinux policy RPM spec file, or [https://src.fedoraproject.org/rpms/memcached/blob/master/f/memcached.spec memcached spec file] for example of SELinux policy subpackage.
 
 
TODO - we can use the memcached policy specfile here
 
  
 
== Bundling SELinux Policy RPMs in Fedora Modules ==
 
== Bundling SELinux Policy RPMs in Fedora Modules ==
  
{{admon/note|TODO|The goal of this section is to help users understand how to include SELinux policy inside of Fedora Modules, the lessons learned from the memcached prototype should be very helpful here.}}
+
{{admon/tip|Fedora Modularity Documentation| Please see the [https://docs.fedoraproject.org/en-US/modularity/making-modules/defining-modules/ Fedora Modularity Documentation] for complete guide on writing modulemd files}}
  
TODO - discussion/explanation
+
{{admon/note|Repositories| Please note that this Guidance document assumes two repositories. SELinux policy RPM repository (whether a sub-package or standalone package) is located in https://src.fedoraproject.org/rpms/ and the Fedora modularity module repository in https://src.fedoraproject.org/modules/ .}}
 +
 
 +
Including the policy RPM in a Fedora module is as simple as specifying the RPM source repository name and branch in the components section of the modulemd file.
 +
<pre>
 +
    components:
 +
        rpms:
 +
            foo: 
 +
                rationale: Primary component of this module. 
 +
                ref: master
 +
            foo-selinux:
 +
                rationale: Provides SELinux policy for foo 
 +
                ref: master
 +
</pre>
 +
 
 +
In case the SELinux policy RPM is a sub-package, this step is already done (the Module Build Service (MBS) will build the specified component including all sub-packages automatically.)
  
 
=== Adding the SELinux Policy to the Module Install Profiles ===
 
=== Adding the SELinux Policy to the Module Install Profiles ===
  
{{admon/note|TODO|This subsection should document the how the included SELinux policy should be handled by the various module installation profiles, paying special attention to the "normal" (install the policy) and "container" (DO NOT install the policy) use cases. If any special dnf configuration is needed it should be described here as well.}}
+
Including the SELinux policy module in the Fedora module makes no difference unless the policy module is part of one or more install profiles.
 +
 
 +
It is recommended to include the policy RPM in the '''default''' install profile. Depending on the primary component it may be useful to include an install profile without the policy module to be used for example inside a container. The policy does not take effect inside a container and would only bring unnecessary dependencies.
 +
 
 +
<pre>
 +
    profiles:
 +
        default:
 +
            rpms:
 +
                - foo
 +
                - foo-selinux
 +
        container:
 +
            rpms:
 +
                - foo
 +
</pre>
  
TODO - see what we did for the memcached prototype, especially the notes about adding the policy RPM to the profiles
+
Complete example ''modulemd'' file which includes SELinux policy module RPM (sub-package) can be seen in the [https://src.fedoraproject.org/modules/memcached/blob/master/f/memcached.yaml memcached module repository].
TODO - verify that the final decision was to add the policy packages to the default profile
 

Revision as of 12:08, 9 August 2018

Important.png
Work in progress
This page is a work in progress, see the inline TODO notes. We suggest visiting SELinuxModularity for more information.

Configuring the Development Environment

The goal of this section is to help people setup their system to build SELinux policy and Fedora Modules.

Building Fedora Modules

Module build is facilitated by the fm-oschestrator (module-build-service package), which is controlled by a set of fedpkg commands.

# dnf install fedpkg module-build-service

Building SELinux Policy modules and RPMs

SELinux policy module build is a multi step process covered by a Makefile provided by selinux-policy-devel pacakge together with all the necessary tools. Since the finished module will be packaged in an rpm, we also need rpm-build package.

The following is only necessary for local testing of the SELinux policy package since the build is otherwise done by the module-build-service.

# dnf install selinux-policy-devel rpm-build

FM repositories

By default dnf does not have access to FM repositories even though it is able to work with modules. Install "fedora-repos-modular-<fedora version>" package to gain acces to "Fedora Modular" modules.

# dnf install fedora-repos-modular-28

Packaging SELinux Policy

Idea.png
Independent Policy Project
Please see the Independent Policy Project wiki for in-depth guide on custom SELinux policy module packaging.

From modularity point of view the SELinux policy needs to be available in the form of RPM package. It's up to the maintainer to choose weather the policy package is standalone or a sub-package of the corresponding software. The former is covered by the Independent Policy Project (IPP) wiki. The latter only differs in the RPM spec file and can be seen in the memcached package.

SELinux Policy Priorities

Idea.png
Documentation
For more information about SELinux policy module priorities please see SELinux Users and Administrators Guide.

Priority 200 should be used for all custom policy modules falling under IPP project regardless of the means of distribution (FM, RPM, ...). This value is set in the %selinux_modules_install macro and should not be overridden by package maintainers.

SELinux Base Policies

Note.png
TODO
This subsection should cover the different SELinux base policies, e.g. targeted vs MLS, and explain how to handle this in the specfiles.

Q - have we tried packaging both a MLS and targeted policy module in the memcached prototype? If not, this is something we should do to verify that it works as expected.

No, only targeted so far.


Example SELinux Policy RPM specfile

See memcached-selinux spec file for example of standalone SELinux policy RPM spec file, or memcached spec file for example of SELinux policy subpackage.

Bundling SELinux Policy RPMs in Fedora Modules

Idea.png
Fedora Modularity Documentation
Please see the Fedora Modularity Documentation for complete guide on writing modulemd files
Note.png
Repositories
Please note that this Guidance document assumes two repositories. SELinux policy RPM repository (whether a sub-package or standalone package) is located in https://src.fedoraproject.org/rpms/ and the Fedora modularity module repository in https://src.fedoraproject.org/modules/ .

Including the policy RPM in a Fedora module is as simple as specifying the RPM source repository name and branch in the components section of the modulemd file.

    components:
        rpms:
            foo:  
                rationale: Primary component of this module.  
                ref: master
            foo-selinux:
                rationale: Provides SELinux policy for foo   
                ref: master

In case the SELinux policy RPM is a sub-package, this step is already done (the Module Build Service (MBS) will build the specified component including all sub-packages automatically.)

Adding the SELinux Policy to the Module Install Profiles

Including the SELinux policy module in the Fedora module makes no difference unless the policy module is part of one or more install profiles.

It is recommended to include the policy RPM in the default install profile. Depending on the primary component it may be useful to include an install profile without the policy module to be used for example inside a container. The policy does not take effect inside a container and would only bring unnecessary dependencies.

    profiles:
        default:
            rpms:
                - foo
                - foo-selinux
        container:
            rpms:
                - foo

Complete example modulemd file which includes SELinux policy module RPM (sub-package) can be seen in the memcached module repository.