From 5fd821448c04c6c23433c7635b9b38d5fb6fd54a Mon Sep 17 00:00:00 2001 From: Donald Yandt <10255876+TorontoMedia@users.noreply.github.com> Date: Mon, 18 Jul 2022 09:53:50 -0400 Subject: [PATCH] docs: update working with source --- documentation/working-with-the-source.md | 312 ++++++++++++++++++----- 1 file changed, 251 insertions(+), 61 deletions(-) diff --git a/documentation/working-with-the-source.md b/documentation/working-with-the-source.md index bc21b37..798673e 100644 --- a/documentation/working-with-the-source.md +++ b/documentation/working-with-the-source.md @@ -7,64 +7,173 @@ You can use the [source repository](https://github.com/firewalld/firewalld) dire To check out the source repository, you can use: - git clone https://github.com/firewalld/firewalld.git +```sh +git clone https://github.com/firewalld/firewalld.git +``` This will create a local copy of the repository. -Change into the firewalld base directory of the repository and set the following environment variables: +## Language Translations + +Firewalld uses GNU gettext for localization support. Translations can be done +using [Fedora's Weblate][1] instance. Translations are periodically merged into +the main firewalld repository. + +[1]: https://translate.stg.fedoraproject.org/projects/firewalld/ + +## Dependencies - export FIREWALLD_DEVEL_ENV=$(pwd)/src - export PYTHONPATH=$FIREWALLD_DEVEL_ENV +These are the runtime dependencies: -Install the following requirements or packages: +``` + linux >= 5.3 + python3-dbus + python3-gobject + python3-nftables >= 0.9.4 +``` - desktop-file-utils: /usr/bin/desktop-file-install - gettext - intltool - glib2: /usr/bin/glib-compile-schemas - glib2-devel: /usr/share/aclocal/gsettings.m4 - systemd-units - iptables - ebtables - ipset +In addition to the runtime dependencies some others are needed to build from +source: -For use with Python 3: +``` + desktop-file-utils: /usr/bin/desktop-file-install + gettext + intltool + glib2: /usr/bin/glib-compile-schemas + glib2-devel: /usr/share/aclocal/gsettings.m4 + systemd-units +``` - python3-dbus - python3-slip-dbus - python3-decorator - python3-gobject +**Note**: python2 is _not_ supported. -For use with Python 2: +## Optional Dependencies - dbus-python - python-slip-dbus (http://fedorahosted.org/python-slip) - python-decorator - pygobject3-base (non-cairo parts of pygobject3) +These dependencies may enhance firewalld's functionality, but they are not +required. + +``` + ebtables + ipset + iptables + polkit + python3-capng (libcap-ng-python3) +``` To be able to create man pages and documentation from docbook files: - docbook-style-xsl +``` + docbook-style-xsl + libxslt +``` +## Build the Source -Use +Use the usual autoconf/automake incantation to generate makefiles + +```sh +./autogen.sh +./configure +``` - ./autogen.sh +You can use a specific python interpreter by passing the PYTHON variable. This +is also used by the testsuite. -in the base directory to create for example src/firewall/config/__init__.py +```sh +./configure PYTHON=/path/to/python3 +``` Use - make +```sh +make +``` to create the documentation and to update the po files. -## Start the Daemon +## Run the Testsuite + +Use + +```sh +make check +``` + +to run the testsuite. Tests are run inside network namespaces and do not +interfere with the host's running firewalld. They can also be run in parallel +by passing flags to autotest. + +```sh +make check TESTSUITEFLAGS="-j4" +``` + +The testsuite also uses keywords to allow running a subset of tests that +exercise a specific area. +For example: + +```sh +make check TESTSUITEFLAGS="-k rich -j4" +``` + +Output: + +```sh + 24: rich rules audit ok + 25: rich rules priority ok + 26: rich rules bad ok + 53: rich rules audit ok + 23: rich rules good ok + 55: rich rules bad ok + 74: remove forward-port after reload ok +``` + +You can get a list of tests and keywords + +```sh +make -C src/tests check TESTSUITEFLAGS="-l" +``` + +Or just the keywords + +```sh +make -C src/tests check TESTSUITEFLAGS="-l" \ + |awk '/^[[:space:]]*[[:digit:]]+/{getline; print $0}' \ + |tr ' ' '\n' |sort |uniq +``` + +There are integration tests. Currently this includes NetworkManager. These may +be _destructive_ to the host. Run them in a disposable VM or container. + +```sh +make check-integration +``` + +There is also a check-container target that will run the testsuite inside +various podman/docker containers. This is useful for coverage of multiple +distributions. It also runs tests that may be destructive to the host such as +integration tests. + +```sh +make check-container TESTSUITEFLAGS="-j4" +``` +## Runtime + +As user root you can start the firewall daemon and clients in the terminal for debugging + +### Set the Runtime Environment + +Change into the firewalld base directory of the repository and set the following environment variables: + +```sh +export FIREWALLD_DEVEL_ENV=$(pwd)/src +export PYTHONPATH=$FIREWALLD_DEVEL_ENV +``` -As user root you can start the firewall daemon in a termal for debugging: +### Start the Daemon - cd src - ./firewalld --nofork --debug +```sh +cd src +./firewalld --nofork --debug +``` Different debug levels are supported here. The default is debug level `1` if `--debug` is added to the command line. Higher debug levels can be specified with `--debug=`. The higher the debug level the more output. The highest debug level is `10`. @@ -79,15 +188,89 @@ The debug levels: | 5 - 9 | Currently unused | 10 | + Introspection XML data | -## Use Command Line Clients +### Use Command Line Clients You can also use the command line clients like `firewall-cmd` from the source repo: - cd src - ./firewall-cmd --state +```sh +cd src +./firewall-cmd --state +``` Also the GUI tools like firewall-config can be started directly in the src directory. +## OCI Container Image + +As part of the `dist` build target an OCI container image is generated. This is +distributed alongside the normal release tarball. It can be used to run +firewalld from a container. The containerized firewalld will _not_ integrate +with the host (e.g. podman, libvirt, NetworkManager). + +To manually load the container image into your environment: + +```sh +podman load -i .../path/to/firewalld-oci-.tar +``` + +To fetch the image from quay.io: + +```sh +podman pull quay.io/firewalld/firewalld: +``` + +where `` is optional, the latest version will be used if omitted. + +To start the daemon/container: + +```sh +podman run -d --network host --privileged \ + --name my-firewalld firewalld +``` + +Firewalld's configuration will live inside the container. Therefore +users may want to occasionally `podman commit` the image. + +Using firewalld's CLI should be done via podman exec after the +daemon/container has been started: + +```sh +podman exec my-firewalld firewall-cmd ... +``` + +### Container Integration with Host + +The same container image can be used to integrate with the host's running +NetworkManager, podman, libvirt, etc. This requires the host to have a dbus +policy for firewalld. + +A dbus policy can be obtained from the firewalld source code tree at location +`config/FirewallD.conf`. + +```sh +cp config/FirewallD.conf /usr/share/dbus-1/system.d/FirewallD.conf +``` + +Once the dbus policy is in place the container could be started as such: + +```sh +podman run -d -v /run/dbus/system_bus_socket:/run/dbus/system_bus_socket \ + --network host --privileged \ + --name my-firewalld firewalld \ + firewalld --nofork --nopid +``` + +The only addition are: volume mount, explicit CMD. + +The some approach can be use to store firewalld's configuration files on the +host. + +```sh +podman run -d -v /run/dbus/system_bus_socket:/run/dbus/system_bus_socket \ + -v /etc/firewalld:/etc/firewalld \ + --network host --privileged \ + --name my-firewalld firewalld \ + firewalld --nofork --nopid +``` ## RPM package @@ -96,36 +279,43 @@ For Fedora and RHEL based distributions, there is a spec file in the source repo ## Links - Homepage: http://firewalld.org - Report a bug: https://github.com/firewalld/firewalld/issues - Git repo browser: https://github.com/firewalld/firewalld - Git repo: https://github.com/firewalld/firewalld.git - Documentation: https://fedoraproject.org/wiki/FirewallD +Homepage: [http://firewalld.org](http://firewalld.org) + +Report a bug: [https://github.com/firewalld/firewalld/issues](https://github.com/firewalld/firewalld/issues) + +Git repo browser: [https://github.com/firewalld/firewalld](https://github.com/firewalld/firewalld) + +Git repo: [https://github.com/firewalld/firewalld.git](https://github.com/firewalld/firewalld.git) + +Documentation: [https://fedoraproject.org/wiki/FirewallD](https://fedoraproject.org/wiki/FirewallD) ## Mailing lists - For usage: https://fedorahosted.org/mailman/listinfo/firewalld-users - For development: https://fedorahosted.org/mailman/listinfo/firewalld-devel +For usage: [https://fedorahosted.org/mailman/listinfo/firewalld-users](https://fedorahosted.org/mailman/listinfo/firewalld-users) + +For development: [https://fedorahosted.org/mailman/listinfo/firewalld-devel](https://fedorahosted.org/mailman/listinfo/firewalld-devel) + +## Internet Relay Chat +For usage: #firewalld [irc.libera.chat:6697](irc://irc.libera.chat:6697/%23firewalld) ## Directory Structure - config/ Configuration files - config/icmptypes/ Predefined ICMP types - config/services/ Predefined services - config/xmlschema/ XML Schema checks for config files - config/zones/ Predefined zones - config/ipsets/ Predefined ipsets - doc/ Documentation - doc/man/ Base directory for man pages - doc/man/man1/ Man(1) pages - doc/man/man5/ Man(5) pages - patches/ Common patches - po/ Translations - shell-completion/ Base directory for auto completion scripts - shell-completion/bash/ Bash auto completion scripts - src/ Source tree - src/firewall/ Import tree for the sevice and all applications - src/icons/ Icons in the sizes: 16, 22, 24, 32, 48 and scalable - src/tests/ Test scripts +| Directory | Content | +| ----------------- | ----------------------------------------------------- | +| config/ | Configuration files | +| config/icmptypes/ | Predefined ICMP types | +| config/services/ | Predefined services | +| config/zones/ | Predefined zones | +| config/ipsets/ | Predefined ipsets | +| doc/ | Documentation | +| doc/man/ | Base directory for man pages | +| doc/man/man1/ | Man(1) pages | +| doc/man/man5/ | Man(5) pages | +| po/ | Translations | +| shell-completion/ | Base directory for auto completion scripts | +| src/ | Source tree | +| src/firewall/ | Import tree for the sevice and all applications | +| src/icons/ | Icons in the sizes: 16, 22, 24, 32, 48 and scalable | +| src/tests/ | Testsuite |