From 79c52d8e971c32d0a19c1bf65d5b8183f852cadc Mon Sep 17 00:00:00 2001 From: "Kelvin M. Klann" Date: Thu, 23 Mar 2023 16:47:40 -0300 Subject: docs: clarify and improve links and items Changes: * Add titles to referenced issues/discussions * Use relative links for paths * Separate repo paths from installed paths * Turn some links and items into lists to make them stand out --- .github/pull_request_template.md | 9 ++++++--- CONTRIBUTING.md | 26 ++++++++++++++++++-------- README.md | 37 +++++++++++++++++++++++++++---------- 3 files changed, 51 insertions(+), 21 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 1947cb00f..faa2a4108 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -2,8 +2,11 @@ If your PR isn't about profiles or you have no idea how to do one of these, skip If you submit a PR for new profiles or changing profiles, please do the following: -- The ordering of options follow the rules described in [/usr/share/doc/firejail/profile.template](https://github.com/netblue30/firejail/blob/master/etc/templates/profile.template). -- Order the arguments of options alphabetically. You can easily do this with [sort.py](https://github.com/netblue30/firejail/tree/master/contrib/sort.py). +- The ordering of options follow the rules described in + [etc/templates/profile.template](../blob/master/etc/templates/profile.template) + (/usr/share/doc/firejail/profile.template when installed). +- Order the arguments of options alphabetically. You can easily do this with + [sort.py](../blob/master/contrib/sort.py). The path to it depends on your distro: @@ -13,4 +16,4 @@ If you submit a PR for new profiles or changing profiles, please do the followin | Debian/Ubuntu/Mint | `/usr/lib/x86_64-linux-gnu/firejail/sort.py` | | local git clone | `contrib/sort.py` | -See also [CONTRIBUTING.md](/CONTRIBUTING.md). +See also [CONTRIBUTING.md](../blob/master/CONTRIBUTING.md). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 55d8974c4..e1f533dde 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,8 +7,10 @@ Welcome to firejail, and thank you for your interest in contributing! We welcome issues, whether to ask a question, provide information, request a new profile or feature, or to report a suspected bug or problem. -If you want to request a program profile that we don't already have, please add a comment in -our [dedicated issue](https://github.com/netblue30/firejail/issues/1139). +If you want to request a program profile that we don't already have, please add +a comment in our dedicated issue: + +- [Profile requests](https://github.com/netblue30/firejail/issues/1139) When submitting a bug report, please provide the following information so that we can handle the report more easily: @@ -22,11 +24,15 @@ we can handle the report more easily: let us know if it runs correctly or not. - You may also try disabling various options provided in `/etc/firejail/` until you find out which one causes problems. It will significantly help to find solution for your issue. -Please note: if you are running Debian, Ubuntu, Linux Mint, or another related +Please note: If you are running Debian, Ubuntu, Linux Mint, or another related distribution and you installed firejail from your distro's repositories, please -ensure that **both** of the following were installed: -`firejail` and `firejail-profiles`. A common source of issues is that -firejail-profiles was not installed when installing firejail. +ensure that **all** of the following packages were installed: + +- firejail +- firejail-profiles + +A common source of issues is that firejail-profiles was not installed when +installing firejail. ## Security vulnerabilities @@ -37,8 +43,12 @@ See [SECURITY.md](SECURITY.md). Pull requests with enhancements, bugfixes or new profiles are very welcome. If you want to write a new profile, the easiest way to do this is to use the -[profile template](https://github.com/netblue30/firejail/blob/master/etc/templates/profile.template). -If you have already written a profile, please make sure it follows the rules described in the template. +profile template: + +- [etc/templates/profile.template](etc/templates/profile.template) + +If you have already written a profile, please make sure it follows the rules +described in the template. If you add a new command, here's the checklist: diff --git a/README.md b/README.md index d03f4776a..a157651c3 100644 --- a/README.md +++ b/README.md @@ -189,23 +189,35 @@ PulseAudio changes. Start your programs the way you are used to: desktop manager menus, file manager, desktop launchers. The integration applies to any program supported by default by Firejail. There are about 250 default applications in current Firejail version, and the number goes up with every new release. -We keep the application list in [/etc/firejail/firecfg.config](https://github.com/netblue30/firejail/blob/master/src/firecfg/firecfg.config) file. + +We keep the application list in +[src/firecfg/firecfg.config](src/firecfg/firecfg.config) +(/etc/firejail/firecfg.config when installed). ## Security profiles -Most Firejail command line options can be passed to the sandbox using profile files. -You can find the profiles for all supported applications in [/etc/firejail](https://github.com/netblue30/firejail/tree/master/etc) directory. +Most Firejail command line options can be passed to the sandbox using profile +files. + +You can find the profiles for all supported applications in [etc/](etc/) +(/etc/firejail/ when installed). + +We also keep a list of profile fixes for previous released versions in +[etc-fixes/](etc-fixes/). -If you keep additional Firejail security profiles in a public repository, please give us a link: +If you keep additional Firejail security profiles in a public repository, +please give us a link: * * -Use this issue to request new profiles: [#1139](https://github.com/netblue30/firejail/issues/1139) +Use this issue to request new profiles: -You can also use this tool to get a list of syscalls needed by a program: [contrib/syscalls.sh](contrib/syscalls.sh). +* [Profile requests](https://github.com/netblue30/firejail/issues/1139) -We also keep a list of profile fixes for previous released versions in [etc-fixes](https://github.com/netblue30/firejail/tree/master/etc-fixes) directory. +You can also use this tool to get a list of syscalls needed by a program: + +* [contrib/syscalls.sh](contrib/syscalls.sh) ## Latest released version: 0.9.72 @@ -257,13 +269,18 @@ We also keep a list of profile fixes for previous released versions in [etc-fixe $ strace /usr/bin/transmission-qt 2>&1 | grep open | grep etc ``` -We keep the list of groups in [src/include/etc_groups.h](https://github.com/netblue30/firejail/blob/master/src/include/etc_groups.h) +We keep the list of groups in +[src/include/etc_groups.h](src/include/etc_groups.h). + +Discussion: -Discussion: +* [private-etc rework](https://github.com/netblue30/firejail/discussions/5610) ### Profile Statistics -A small tool to print profile statistics. Compile and install as usual. The tool is installed in /usr/lib/firejail directory. +A small tool to print profile statistics. Compile and install as usual. +The tool is installed in the /usr/lib/firejail directory. + Run it over the profiles in /etc/profiles: ```console -- cgit v1.2.3-54-g00ecf