Differences between revisions 1 and 60 (spanning 59 versions)
Revision 1 as of 2015-01-10 18:56:16
Size: 2345
Editor: UlrikeUhlig
Comment: Import quick howto contribute to upstream from http://apparmor.451f.org/2014/12/23/how-to-contribute-to-the-apparmor-upstream-profiles/
Revision 60 as of 2017-03-19 00:12:33
Size: 7827
Editor: PaulWise
Comment: prefer RSA
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
<<Navigation(siblings)>> ## page was renamed from AppArmor/ContributeUpstream
#language en
~-[[DebianWiki/EditorGuide#translation|Translation(s)]]: none-~

## <<Navigation(siblings)>>
'''[[AppArmor/Contribute | Contribute]]''' [[AppArmor/Contribute/Upstream| Upstream]] -- [[AppArmor/Contribute/MergeProfileFromUpstream | MergeProfileFromUpstream]] -- [[AppArmor/Contribute/MergeToUpstream | MergeToUpstream]] -- [[AppArmor/Contribute/ImportProfileFromExtra | ImportProfileFromExtra]] -- [[AppArmor/Contribute/FirstTimeProfileImport | FirstTimeProfileImport]]
Line 5: Line 10:
We want to keep our delta with upstream as low as possible. That is why if you want to submit a new or patch an existing profile, this should be done directly upstream. == Create a new AppArmor profile, or modify an existing one ==
Line 7: Line 12:
== Get in touch with upstream == We want to keep our delta with upstream as low as possible. Then, if you want to submit a new profile or modify an existing one, this should be done '''upstream first'''.
Line 9: Line 14:
You should always ask for review of your patch on the [[https://lists.ubuntu.com/mailman/listinfo/apparmor|upstream mailing list]]. This process will also allow for better cross-distribution sharing and maintenance of profiles.
Line 11: Line 16:
== Documentation == == Debian / Upstream relationship ==
Line 13: Line 18:
The !AppArmor wiki provides instructions on how to create new profiles. Every distribution has adopted a different strategy to handle their profiles.
Most of Debian's !AppArmor profiles are imported directly from the upstream repositories. The development of profiles takes place in Git at Launchpad:
Line 15: Line 21:
== Quick howto contribute to upstream AppArmor profiles ==  * https://launchpad.net/apparmor-profiles
 * https://code.launchpad.net/~apparmor-dev/apparmor-profiles/+git/apparmor-profiles
Line 17: Line 24:
If you want to contribute to [[https://code.launchpad.net/~apparmor-dev/apparmor-profiles/|existing/upstream AppArmor profiles]], you need to [[https://login.launchpad.net/|create an account on Canonical’s launchpad]] and to upload a [[https://help.launchpad.net/YourAccount/CreatingAnSSHKeyPair|SSH key]] to be able to push your changes. Ubuntu and openSUSE ship !AppArmor by default. For Ubuntu, who base their profiles on the same upstream source, once a profile is "ready", it is [[https://wiki.ubuntu.com/ApparmorProfileMigration | taken out of the profile development branch and inserted directly into the corresponding package]]: e.g. the !AppArmor profile for `evince` is included into Ubuntu's evince package.
Line 19: Line 26:
You will also need to install Canonical’s version control system, called Bazaar: In Debian, on the long run, a profile should also be delivered in the package that ships the software it is confining. This is already the case for [[https://wiki.debian.org/AppArmor/Progress#Included_in_the_corresponding_package|some packages]]. However, for now package maintainers can still rely on the Debian !AppArmor packaging team which provides additional profiles via the DebianPkg:apparmor-profiles-extra package.

||<style="background-color: lightgrey;">Upstream ||<style="background-color: lightgrey;">Debian source package ||<style="background-color: lightgrey;">Debian binary package ||<style="background-color: lightgrey;">Ubuntu source package ||<style="background-color: lightgrey;">Ubuntu binary package ||
|| [[https://launchpad.net/apparmor|apparmor]] || DebianPts:apparmor || DebianPkg:apparmor and DebianPkg:apparmor-profiles || [[http://packages.ubuntu.com/source/apparmor|apparmor]] || [[http://packages.ubuntu.com/apparmor|apparmor]] ||
|| [[https://code.launchpad.net/~apparmor-dev/apparmor-profiles/+git/apparmor-profiles|apparmor-profiles]] || DebianPts:apparmor-profiles-extra || DebianPkg:apparmor-profiles-extra || [[http://packages.ubuntu.com/source/apparmor-profiles|apparmor-profiles]] || [[http://packages.ubuntu.com/apparmor-profiles|apparmor-profiles]] ||
|| - || DebianPts:apparmor-profiles-extra || DebianPkg:apparmor-profiles-extra || [[https://launchpad.net/ubuntu/+source/evince|evince]] || [[http://packages.ubuntu.com/evince|evince]]||
|| [[https://www.github.com/ioerror/tlsdate/|tlsdate]] || DebianPts:tlsdate || DebianPkg:tlsdate || [[https://launchpad.net/ubuntu/+source/tlsdate|tlsdate]] || [[http://packages.ubuntu.com/tlsdate|tlsdate]]||

Note: we merely use `evince` and `tlsdate` as example packages in this table. The tlsdate upstream tarball includes an own !AppArmor profile, whereas the evince upstream tarball does not. The evince Ubuntu binary package is shipped with its own !AppArmor profile, whereas in Debian, this profile is shipped in the apparmor-profiles-extra-package.

== Generate and update your profiles ==

[[http://blog.cboltz.de/uploads/osc12/apparmor-english-2012-v2.pdf | The AppArmor crashcourse]] by Christian Boltz contains information on how to create a profile from scratch using [[DebianMan:8/aa-logprof | aa-logprof]] and [[DebianMan:8/aa-genprof | aa-genprof]].

Please consult the "External links" section on the bottom of this page for more information on this topic.

== Test your profiles ==

See [[AppArmor/Debug|Debugging a profile]].

== Quick howto contribute to upstream AppArmor profiles using Git ==

[[#Debian_.2F_Upstream_relationship|Upstream AppArmor profiles live in many different repositories.]] This documentation focuses on contributing to profiles that live in the [[https://code.launchpad.net/~apparmor-dev/apparmor-profiles/+git/apparmor-profiles | upstream apparmor-profiles repository]], but the procedure is quite similar for the other repositories.

If you want to contribute to existing/upstream AppArmor profiles, you need to:

 1. [[https://login.launchpad.net/|create an account on Canonical's launchpad]];
 2. upload a [[https://help.launchpad.net/YourAccount/CreatingAnSSHKeyPair|SSH key]] to be able to push your changes.

You will also need to install the Git version control system:
Line 22: Line 58:
apt-get install bzr apt-get install git
Line 28: Line 64:
mkdir apparmor-dev
cd apparmor-dev
bzr branch lp:apparmor-profiles master
ls master
git clone git+ssh://git.launchpad.net/apparmor-profiles
cd apparmor-profiles
ls
Line 34: Line 69:
Define your identity like this: Create a topic branch:
Line 37: Line 72:
bzr whoami "My Name <my@email.com>"
}}}

Bazaar does not handle branches like Git does, unfortunately. It is a little bit weird in first place that you will need to create a directory where you would create a copy of the master branch. You would then work on this branch and later ask for a merge into the master branch.

{{{
mkdir myname
bzr branch master myname/pidgin
ls myname/pidgin
git checkout -b BRANCHNAME origin/master
Line 50: Line 77:
Once done, you can commit and push the changes to your distant repository: Once done, you can commit the changes to your local repository:
Line 53: Line 80:
bzr ci
bzr push
git add -p && git commit
Line 57: Line 83:
Then, you need to connect to Launchpad’s web interface. Go to your page, and look for the branch you just pushed. Click on “change branch details” and link the branch to apparmor-profiles. Then you will be able to request a merge through the webinterface. Add a remote to push your changes:
Line 59: Line 85:
[[AppArmor/PackageMaintainers#Debian_.2F_Upstream_relationship|Note that upstream AppArmor profiles also live in other repositories.]] {{{
git remote add USERNAME git+ssh://USERNAME@git.launchpad.net/~USERNAME/REPOSITORY
}}}

In ~/.ssh/config you might want to add

{{{
Host git.launchpad.net
HostName git.launchpad.net
User USERNAME
Port 22
IdentityFile ~/.ssh/id_rsa_launchpad
}}}

Now, to push the changes to your remote repository, by creating a remote
branch directly:

{{{
git push USERNAME BRANCHNAME
}}}

Then you will be able to request a merge through the web interface.

(More details in the upstream documentation: https://help.launchpad.net/Code/Git)

== Get in touch with upstream ==

Get in contact with upstream over the [[https://lists.ubuntu.com/mailman/listinfo/apparmor|AppArmor upstream mailing list]].
It's where you can discuss anything that is not a merge request with the rest of the AppArmor community.

In order to get a new profile into the upstream apparmor-profiles package, you should [[https://help.ubuntu.com/community/ReportingBugs|file a bug against apparmor over at Launchpad]].

== Inform the Debian AppArmor Packaging team ==

When you feel the need to create a new profile or to modify an existing one, we encourage you to [[AppArmor/Reportbug | report a bug with the usertag "new-profile" or "modify-profile"]] to the Debian BTS, in order to inform the Debian !AppArmor Packaging Team.

== External documentation about profiles ==

The [[http://wiki.apparmor.net/index.php/Main_Page|AppArmor wiki]] provides numerous documentation on how to contribute upstream.
Here are some useful links:

 * [[https://wiki.ubuntu.com/AppArmor#Introduction|Introduction to profile contents]]
 * [[http://wiki.apparmor.net/index.php/QuickProfileLanguage | Introduction to the AppArmor profile language]] explains how to match files and what the different permissions mean.
 * [[http://wiki.apparmor.net/index.php/Profiles|Upstream documentation on creating and modifying profiles]]
 * [[http://wiki.apparmor.net/index.php/Launchpadtutorial|Detailed instructions using Launchpad and Bazaar]]
 * [[http://wiki.apparmor.net/index.php/CommitPolicy|Upstream Commit and Patch policy]]

Translation(s): none

Contribute Upstream -- MergeProfileFromUpstream -- ?MergeToUpstream -- ?ImportProfileFromExtra -- FirstTimeProfileImport


Create a new AppArmor profile, or modify an existing one

We want to keep our delta with upstream as low as possible. Then, if you want to submit a new profile or modify an existing one, this should be done upstream first.

This process will also allow for better cross-distribution sharing and maintenance of profiles.

Debian / Upstream relationship

Every distribution has adopted a different strategy to handle their profiles. Most of Debian's AppArmor profiles are imported directly from the upstream repositories. The development of profiles takes place in Git at Launchpad:

Ubuntu and openSUSE ship AppArmor by default. For Ubuntu, who base their profiles on the same upstream source, once a profile is "ready", it is taken out of the profile development branch and inserted directly into the corresponding package: e.g. the AppArmor profile for evince is included into Ubuntu's evince package.

In Debian, on the long run, a profile should also be delivered in the package that ships the software it is confining. This is already the case for some packages. However, for now package maintainers can still rely on the Debian AppArmor packaging team which provides additional profiles via the apparmor-profiles-extra package.

Upstream

Debian source package

Debian binary package

Ubuntu source package

Ubuntu binary package

apparmor

apparmor

apparmor and apparmor-profiles

apparmor

apparmor

apparmor-profiles

apparmor-profiles-extra

apparmor-profiles-extra

apparmor-profiles

apparmor-profiles

-

apparmor-profiles-extra

apparmor-profiles-extra

evince

evince

tlsdate

tlsdate

tlsdate

tlsdate

tlsdate

Note: we merely use evince and tlsdate as example packages in this table. The tlsdate upstream tarball includes an own AppArmor profile, whereas the evince upstream tarball does not. The evince Ubuntu binary package is shipped with its own AppArmor profile, whereas in Debian, this profile is shipped in the apparmor-profiles-extra-package.

Generate and update your profiles

The AppArmor crashcourse by Christian Boltz contains information on how to create a profile from scratch using aa-logprof and aa-genprof.

Please consult the "External links" section on the bottom of this page for more information on this topic.

Test your profiles

See Debugging a profile.

Quick howto contribute to upstream AppArmor profiles using Git

Upstream AppArmor profiles live in many different repositories. This documentation focuses on contributing to profiles that live in the upstream apparmor-profiles repository, but the procedure is quite similar for the other repositories.

If you want to contribute to existing/upstream AppArmor profiles, you need to:

  1. create an account on Canonical's launchpad;

  2. upload a SSH key to be able to push your changes.

You will also need to install the Git version control system:

apt-get install git

Go to or create a repository where you want to checkout the modifications:

git clone git+ssh://git.launchpad.net/apparmor-profiles
cd apparmor-profiles
ls

Create a topic branch:

git checkout -b BRANCHNAME origin/master

Then, start modifying the profiles using a text editor and test them. Testing is done through dis/enabling the profile. Once done, you can commit the changes to your local repository:

git add -p && git commit

Add a remote to push your changes:

git remote add USERNAME git+ssh://USERNAME@git.launchpad.net/~USERNAME/REPOSITORY

In ~/.ssh/config you might want to add

Host git.launchpad.net
HostName git.launchpad.net
User USERNAME
Port 22
IdentityFile ~/.ssh/id_rsa_launchpad

Now, to push the changes to your remote repository, by creating a remote branch directly:

git push USERNAME BRANCHNAME

Then you will be able to request a merge through the web interface.

(More details in the upstream documentation: https://help.launchpad.net/Code/Git)

Get in touch with upstream

Get in contact with upstream over the AppArmor upstream mailing list. It's where you can discuss anything that is not a merge request with the rest of the AppArmor community.

In order to get a new profile into the upstream apparmor-profiles package, you should file a bug against apparmor over at Launchpad.

Inform the Debian AppArmor Packaging team

When you feel the need to create a new profile or to modify an existing one, we encourage you to report a bug with the usertag "new-profile" or "modify-profile" to the Debian BTS, in order to inform the Debian AppArmor Packaging Team.

External documentation about profiles

The AppArmor wiki provides numerous documentation on how to contribute upstream. Here are some useful links: