Release 2.14.1

It has been broken since reporter improvements, because it effectivelly
1) didn't call remove functions in database
2) used empty repository identifier for web service

With those changes it also raises exception when you try to call id on
empty identifier

.pylintrc

@@ -82,6 +82,7 @@ limit-inference-results=100
 # List of plugins (as comma separated values of python module names) to load,
 # usually to register additional checkers.
 load-plugins=pylint.extensions.docparams,
+             pylint.extensions.bad_builtin,
              definition_order,
              import_order,
 
@@ -131,6 +132,8 @@ attr-naming-style=snake_case
 # style.
 #attr-rgx=
 
+bad-functions=print,
+
 # Bad variable names which should always be refused, separated by a comma.
 bad-names=foo,
           bar,

CONTRIBUTING.md

@@ -132,7 +132,7 @@ Again, the most checks can be performed by `tox` command, though some additional
 * For any path interactions `pathlib.Path` must be used.
 * Configuration interactions must go through `ahriman.core.configuration.Configuration` class instance.
 * In case if class load requires some actions, it is recommended to create class method which can be used for class instantiating.
-* The code must follow the exception safety, unless it is explicitly asked by end user. It means that most exceptions must be handled and printed to log, no other actions must be done (e.g. raising another exception).
+* The most (expected) exceptions must be handled and printed to log, allowing service to continue work. However, fatal and (in some cases) unexpected exceptions may lead to the application termination.
 * Exceptions without parameters should be raised without parentheses, e.g.:
 
     ```python

README.md

@@ -33,10 +33,12 @@ Every available option is described in the [documentation](https://ahriman.readt
 
 The application provides reasonable defaults which allow to use it out-of-box; however additional steps (like configuring build toolchain and sudoers) are recommended and can be easily achieved by following install instructions.
 
-## [FAQ](https://ahriman.readthedocs.io/en/stable/faq.html)
+## [FAQ](https://ahriman.readthedocs.io/en/stable/faq/index.html)
 
 ## Live demos
 
 * [Build status page](https://ahriman-demo.arcanis.me). You can log in as `demo` user by using `demo` password. However, you will not be able to run tasks. [HTTP API documentation](https://ahriman-demo.arcanis.me/api-docs) is also available.
 * [Repository index](https://repo.arcanis.me/arcanisrepo/x86_64/).
 * [Telegram feed](https://t.me/arcanisrepo).
+
+Do you have any success story? You can [share it](https://github.com/arcan1s/ahriman/issues/new?template=04-discussion.md)!

docs/ahriman.core.auth.rst

@@ -36,6 +36,14 @@ ahriman.core.auth.oauth module
    :no-undoc-members:
    :show-inheritance:
 
+ahriman.core.auth.pam module
+----------------------------
+
+.. automodule:: ahriman.core.auth.pam
+   :members:
+   :no-undoc-members:
+   :show-inheritance:
+
 Module contents
 ---------------
 

docs/ahriman.core.rst

@@ -52,6 +52,14 @@ ahriman.core.tree module
    :no-undoc-members:
    :show-inheritance:
 
+ahriman.core.util module
+------------------------
+
+.. automodule:: ahriman.core.util
+   :members:
+   :no-undoc-members:
+   :show-inheritance:
+
 ahriman.core.utils module
 -------------------------
 

docs/ahriman.models.rst

@@ -228,6 +228,14 @@ ahriman.models.result module
    :no-undoc-members:
    :show-inheritance:
 
+ahriman.models.scan\_paths module
+---------------------------------
+
+.. automodule:: ahriman.models.scan_paths
+   :members:
+   :no-undoc-members:
+   :show-inheritance:
+
 ahriman.models.sign\_settings module
 ------------------------------------
 

docs/configuration.rst

@@ -61,15 +61,17 @@ libalpm and AUR related configuration. Group name can refer to architecture, e.g
 
 Base authorization settings. ``OAuth`` provider requires ``aioauth-client`` library to be installed.
 
-* ``target`` - specifies authorization provider, string, optional, default ``disabled``. Allowed values are ``disabled``, ``configuration``, ``oauth``.
+* ``target`` - specifies authorization provider, string, optional, default ``disabled``. Allowed values are ``disabled``, ``configuration``, ``oauth``, ``pam``.
 * ``allow_read_only`` - allow requesting status APIs without authorization, boolean, required.
 * ``client_id`` - OAuth2 application client ID, string, required in case if ``oauth`` is used.
 * ``client_secret`` - OAuth2 application client secret key, string, required in case if ``oauth`` is used.
 * ``cookie_secret_key`` - secret key which will be used for cookies encryption, string, optional. It must be 32 bytes URL-safe base64-encoded and can be generated as following ``base64.urlsafe_b64encode(os.urandom(32)).decode("utf8")``. If not set, it will be generated automatically; note, however, that in this case, all sessions will be automatically invalidated during the service restart.
+* ``full_access_group`` - name of the secondary group (e.g. ``wheel``) to be used as admin group in the service, string, required in case if ``pam`` is used.
 * ``max_age`` - parameter which controls both cookie expiration and token expiration inside the service in seconds, integer, optional, default is 7 days.
 * ``oauth_icon`` - OAuth2 login button icon, string, optional, default is ``google``. Must be valid `Bootstrap icon <https://icons.getbootstrap.com/>`__ name.
 * ``oauth_provider`` - OAuth2 provider class name as is in ``aioauth-client`` (e.g. ``GoogleClient``, ``GithubClient`` etc), string, required in case if ``oauth`` is used.
 * ``oauth_scopes`` - scopes list for OAuth2 provider, which will allow retrieving user email (which is used for checking user permissions), e.g. ``https://www.googleapis.com/auth/userinfo.email`` for ``GoogleClient`` or ``user:email`` for ``GithubClient``, space separated list of strings, required in case if ``oauth`` is used.
+* ``permit_root_login`` - allow login as root user, boolean, optional, default ``no``.
 * ``salt`` - additional password hash salt, string, optional.
 
 Authorized users are stored inside internal database, if any of external providers (e.g. ``oauth``) are used, the password field for non-service users must be empty.
@@ -79,7 +81,9 @@ Authorized users are stored inside internal database, if any of external provide
 
 Build related configuration. Group name can refer to architecture, e.g. ``build:x86_64`` can be used for x86_64 architecture specific settings.
 
+* ``allowed_scan_paths`` - paths to be used for implicit dependencies scan, scape separated list of paths, optional.
 * ``archbuild_flags`` - additional flags passed to ``archbuild`` command, space separated list of strings, optional.
+* ``blacklisted_scan_paths`` - paths to be excluded for implicit dependencies scan, scape separated list of paths, optional. Normally all elements of this option must be child paths of any of ``allowed_scan_paths`` element.
 * ``build_command`` - default build command, string, required.
 * ``ignore_packages`` - list packages to ignore during a regular update (manual update will still work), space separated list of strings, optional.
 * ``include_debug_packages`` - distribute debug packages, boolean, optional, default ``yes``.
@@ -130,7 +134,7 @@ Web server settings. This feature requires ``aiohttp`` libraries to be installed
 * ``port`` - port to bind, integer, optional.
 * ``service_only`` - disable status routes (including logs), boolean, optional, default ``no``.
 * ``static_path`` - path to directory with static files, string, required.
-* ``templates`` - path to templates directories, space separated list of strings, required.
+* ``templates`` - path to templates directories, space separated list of paths, required.
 * ``unix_socket`` - path to the listening unix socket, string, optional. If set, server will create the socket on the specified address which can (and will) be used by application. Note, that unlike usual host/port configuration, unix socket allows to perform requests without authorization.
 * ``unix_socket_unsafe`` - set unsafe (o+w) permissions to unix socket, boolean, optional, default ``yes``. This option is enabled by default, because it is supposed that unix socket is created in safe environment (only web service is supposed to be used in unsafe), but it can be disabled by configuration.
 * ``wait_timeout`` - wait timeout in seconds, maximum amount of time to be waited before lock will be free, integer, optional.
@@ -252,7 +256,7 @@ Section name must be either ``email`` (plus optional architecture name, e.g. ``e
 * ``ssl`` - SSL mode for SMTP connection, one of ``ssl``, ``starttls``, ``disabled``, optional, default ``disabled``.
 * ``template`` - Jinja2 template name, string, required.
 * ``template_full`` - Jinja2 template name for full package description index, string, optional.
-* ``templates`` - path to templates directories, space separated list of strings, required.
+* ``templates`` - path to templates directories, space separated list of paths, required.
 * ``user`` - SMTP user to authenticate, string, optional.
 
 ``html`` type
@@ -265,7 +269,7 @@ Section name must be either ``html`` (plus optional architecture name, e.g. ``ht
 * ``link_path`` - prefix for HTML links, string, required.
 * ``path`` - path to html report file, string, required.
 * ``template`` - Jinja2 template name, string, required.
-* ``templates`` - path to templates directories, space separated list of strings, required.
+* ``templates`` - path to templates directories, space separated list of paths, required.
 
 ``remote-call`` type
 ^^^^^^^^^^^^^^^^^^^^
@@ -290,7 +294,7 @@ Section name must be either ``telegram`` (plus optional architecture name, e.g.
 * ``link_path`` - prefix for HTML links, string, required.
 * ``template`` - Jinja2 template name, string, required.
 * ``template_type`` - ``parse_mode`` to be passed to telegram API, one of ``MarkdownV2``, ``HTML``, ``Markdown``, string, optional, default ``HTML``.
-* ``templates`` - path to templates directories, space separated list of strings, required.
+* ``templates`` - path to templates directories, space separated list of paths, required.
 * ``timeout`` - HTTP request timeout in seconds, integer, optional, default is ``30``.
 
 ``upload`` group

docs/faq/backup.rst

@@ -0,0 +1,35 @@
+Backup and restore
+------------------
+
+The service provides several commands aim to do easy repository backup and restore. If you would like to move repository from the server ``server1.example.com`` to another ``server2.example.com`` you have to perform the following steps:
+
+#. 
+   On the source server ``server1.example.com`` run ``repo-backup`` command, e.g.:
+
+   .. code-block:: shell
+
+      ahriman repo-backup /tmp/repo.tar.gz
+
+   This command will pack all configuration files together with database file into the archive specified as command line argument (i.e. ``/tmp/repo.tar.gz``). In addition it will also archive ``cache`` directory (the one which contains local clones used by e.g. local packages) and ``.gnupg`` of the ``ahriman`` user.
+
+#. 
+   Copy created archive from source server ``server1.example.com`` to target ``server2.example.com``.
+
+#. 
+   Install package as usual on the target server ``server2.example.com`` if you didn't yet.
+
+#. 
+   Extract archive e.g. by using subcommand:
+
+   .. code-block:: shell
+
+      ahriman repo-restore /tmp/repo.tar.gz
+
+   An additional argument ``-o``/``--output`` can be used to specify extraction root (``/`` by default).
+
+#. 
+   Rebuild repository:
+
+   .. code-block:: shell
+
+      sudo -u ahriman ahriman repo-rebuild --from-database

docs/faq/distributed.rst

@@ -0,0 +1,320 @@
+Distributed builds
+------------------
+
+The service allows to run build on multiple machines and collect packages on main node. There are several ways to achieve it, this section describes officially supported methods.
+
+Remote synchronization and remote server call
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This setup requires at least two instances of the service:
+
+#. Web service (with opt-in authorization enabled), later will be referenced as ``master`` node.
+#. Application instances responsible for build, later will be referenced as ``worker`` nodes.
+
+In this example the following settings are assumed:
+
+* Repository architecture is ``x86_64``.
+* Master node address is ``master.example.com``.
+
+Master node configuration
+"""""""""""""""""""""""""
+
+The only requirements for the master node is that API must be available for worker nodes to call (e.g. port must be exposed to internet, or local network in case of VPN, etc) and file upload must be enabled:
+
+.. code-block:: ini
+
+   [web]
+   enable_archive_upload = yes
+
+In addition, the following settings are recommended for the master node:
+
+*
+  As it has been mentioned above, it is recommended to enable authentication (see :doc:`How to enable basic authorization <web>`) and create system user which will be used later. Later this user (if any) will be referenced as ``worker-user``.
+
+*
+  In order to be able to spawn multiple processes at the same time, wait timeout must be configured:
+
+  .. code-block:: ini
+
+     [web]
+     wait_timeout = 0
+
+Worker nodes configuration
+""""""""""""""""""""""""""
+
+#.
+   First of all, in this setup you need to split your repository into chunks manually, e.g. if you have repository on master node with packages ``A``, ``B`` and ``C``, you need to split them between all available workers, as example:
+
+   * Worker #1: ``A``.
+   * Worker #2: ``B`` and ``C``.
+
+   Hint: ``repo-tree`` subcommand provides ``--partitions`` argument.
+
+#.
+   Each worker must be configured to upload files to master node:
+
+   .. code-block:: ini
+
+      [upload]
+      target = remote-service
+
+      [remote-service]
+
+#.
+   Worker must be configured to access web on master node:
+
+   .. code-block:: ini
+
+      [status]
+      address = https://master.example.com
+      username = worker-user
+      password = very-secure-password
+
+   As it has been mentioned above, ``status.address`` must be available for workers. In case if unix socket is used, it can be passed in the same option as usual. Optional ``status.username``/``status.password`` can be supplied in case if authentication was enabled on master node.
+
+#.
+   Each worker must call master node on success:
+
+   .. code-block:: ini
+
+      [report]
+      target = remote-call
+
+      [remote-call]
+      manual = yes
+
+   After success synchronization (see above), the built packages will be put into directory, from which they will be read during manual update, thus ``remote-call.manual`` flag is required.
+
+#.
+   Change order of trigger runs. This step is required, because by default the report trigger is called before the upload trigger and we would like to achieve the opposite:
+
+   .. code-block:: ini
+
+      [build]
+      triggers = ahriman.core.gitremote.RemotePullTrigger ahriman.core.upload.UploadTrigger ahriman.core.report.ReportTrigger ahriman.core.gitremote.RemotePushTrigger
+
+In addition, the following settings are recommended for workers:
+
+*
+  You might want to wait until report trigger will be completed; in this case the following option must be set:
+
+  .. code-block:: ini
+
+     [remote-call]
+     wait_timeout = 0
+
+Dependency management
+"""""""""""""""""""""
+
+By default worker nodes don't know anything about master nodes packages, thus it will try to build each dependency by its own. However, using ``AHRIMAN_REPOSITORY_SERVER`` docker variable (or ``--server`` flag for setup command), it is possible to specify address of the master node for devtools configuration.
+
+Repository and packages signing
+"""""""""""""""""""""""""""""""
+
+You can sign packages on worker nodes and then signatures will be synced to master node. In order to do so, you need to configure worker node as following, e.g.:
+
+.. code-block:: ini
+
+   [sign]
+   target = package
+   key = 8BE91E5A773FB48AC05CC1EDBED105AED6246B39
+
+Note, however, that in this case, signatures will not be validated on master node and just will be copied to repository tree.
+
+If you would like to sign only database files (aka repository sign), it has to be configured only on master node as usual, e.g.:
+
+.. code-block:: ini
+
+   [sign]
+   target = repository
+   key = 8BE91E5A773FB48AC05CC1EDBED105AED6246B39
+
+Double node minimal docker example
+""""""""""""""""""""""""""""""""""
+
+Master node config (``master.ini``) as:
+
+.. code-block:: ini
+
+   [auth]
+   target = configuration
+
+   [web]
+   enable_archive_upload = yes
+   wait_timeout = 0
+
+
+Command to run master node:
+
+.. code-block:: shell
+
+   docker run --privileged -p 8080:8080 -e AHRIMAN_PORT=8080 -v master.ini:/etc/ahriman.ini.d/overrides.ini arcan1s/ahriman:latest web
+
+The user ``worker-user`` has been created additionally. Worker node config (``worker.ini``) as:
+
+.. code-block:: ini
+
+   [status]
+   address = http://172.17.0.1:8080
+   username = worker-user
+   password = very-secure-password
+
+   [upload]
+   target = remote-service
+
+   [remote-service]
+
+   [report]
+   target = remote-call
+
+   [remote-call]
+   manual = yes
+   wait_timeout = 0
+
+   [build]
+   triggers = ahriman.core.gitremote.RemotePullTrigger ahriman.core.upload.UploadTrigger ahriman.core.report.ReportTrigger ahriman.core.gitremote.RemotePushTrigger
+
+The address above (``http://172.17.0.1:8080``) is somewhat available for worker container.
+
+Command to run worker node:
+
+.. code-block:: shell
+
+   docker run --privileged -v worker.ini:/etc/ahriman.ini.d/overrides.ini -it arcan1s/ahriman:latest package-add ahriman --now
+
+The command above will successfully build ``ahriman`` package, upload it on master node and, finally, will update master node repository.
+
+Check proof-of-concept setup `here <https://github.com/arcan1s/ahriman/tree/master/recipes/distributed-manual>`__.
+
+Addition of new package and repository update
+"""""""""""""""""""""""""""""""""""""""""""""
+
+Just run on worker command as usual, the built packages will be automatically uploaded to master node. Note that automatic update process must be disabled on master node.
+
+Package removal
+"""""""""""""""
+
+This action must be done in two steps:
+
+#. Remove package on worker.
+#. Remove package on master node.
+
+Delegate builds to remote workers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This setup heavily uses upload feature described above and, in addition, also delegates build process automatically to build machines. Same as above, there must be at least two instances available (``master`` and ``worker``), however, all ``worker`` nodes must be run in the web service mode.
+
+Master node configuration
+"""""""""""""""""""""""""
+
+In addition to the configuration above, the worker list must be defined in configuration file (``build.workers`` option), i.e.:
+
+.. code-block:: ini
+
+   [build]
+   workers = https://worker1.example.com https://worker2.example.com
+
+   [web]
+   enable_archive_upload = yes
+   wait_timeout = 0
+
+In the example above, ``https://worker1.example.com`` and ``https://worker2.example.com`` are remote ``worker`` node addresses available for ``master`` node.
+
+In case if authentication is required (which is recommended way to setup it), it can be set by using ``status`` section as usual.
+
+Worker nodes configuration
+""""""""""""""""""""""""""
+
+It is required to point to the master node repository, otherwise internal dependencies will not be handled correctly. In order to do so, the ``--server`` argument (or ``AHRIMAN_REPOSITORY_SERVER`` environment variable for docker images) can be used.
+
+Also, in case if authentication is enabled, the same user with the same password must be created for all workers.
+
+It is also recommended to set ``web.wait_timeout`` to infinite in case of multiple conflicting runs and ``service_only`` to ``yes`` in order to disable status endpoints.
+
+Other settings are the same as mentioned above.
+
+Triple node minimal docker example
+""""""""""""""""""""""""""""""""""
+
+In this example, all instances are run on the same machine with address ``172.17.0.1`` with ports available outside of container. Master node config (``master.ini``) as:
+
+.. code-block:: ini
+
+   [auth]
+   target = configuration
+
+   [status]
+   username = builder-user
+   password = very-secure-password
+
+   [build]
+   workers = http://172.17.0.1:8081 http://172.17.0.1:8082
+
+   [web]
+   enable_archive_upload = yes
+   wait_timeout = 0
+
+Command to run master node:
+
+.. code-block:: shell
+
+   docker run --privileged -p 8080:8080 -e AHRIMAN_PORT=8080 -v master.ini:/etc/ahriman.ini.d/overrides.ini arcan1s/ahriman:latest web
+
+Worker nodes (applicable for all workers) config (``worker.ini``) as:
+
+.. code-block:: ini
+
+   [auth]
+   target = configuration
+
+   [status]
+   address = http://172.17.0.1:8080
+   username = builder-user
+   password = very-secure-password
+
+   [upload]
+   target = remote-service
+
+   [remote-service]
+
+   [report]
+   target = remote-call
+
+   [remote-call]
+   manual = yes
+   wait_timeout = 0
+
+   [web]
+   service_only = yes
+
+   [build]
+   triggers = ahriman.core.upload.UploadTrigger ahriman.core.report.ReportTrigger
+
+Command to run worker nodes (considering there will be two workers, one is on ``8081`` port and other is on ``8082``):
+
+.. code-block:: ini
+
+   docker run --privileged -p 8081:8081 -e AHRIMAN_PORT=8081 -v worker.ini:/etc/ahriman.ini.d/overrides.ini arcan1s/ahriman:latest web
+   docker run --privileged -p 8082:8082 -e AHRIMAN_PORT=8082 -v worker.ini:/etc/ahriman.ini.d/overrides.ini arcan1s/ahriman:latest web
+
+Unlike the previous setup, it doesn't require to mount repository root for ``worker`` nodes, because they don't use it anyway.
+
+Check proof-of-concept setup `here <https://github.com/arcan1s/ahriman/tree/master/recipes/distributed>`__.
+
+Addition of new package, package removal, repository update
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+In all scenarios, update process must be run only on ``master`` node. Unlike the manually distributed packages described above, automatic update must be enabled only for ``master`` node.
+
+Automatic worker nodes discovery
+""""""""""""""""""""""""""""""""
+
+Instead of setting ``build.workers`` option it is also possible to configure services to load worker list dynamically. To do so, the ``ahriman.core.distributed.WorkerLoaderTrigger`` and ``ahriman.core.distributed.WorkerTrigger`` must be used for ``master`` and ``worker`` nodes repsectively. See recipes for more details.
+
+Known limitations
+"""""""""""""""""
+
+* Workers don't support local packages. However, it is possible to build custom packages by providing sources by using ``ahriman.core.gitremote.RemotePullTrigger`` trigger.
+* No dynamic nodes discovery. In case if one of worker nodes is unavailable, the build process will fail.
+* No pkgrel bump on conflicts.
+* The identical user must be created for all workers. However, the ``master`` node user can be different from this one.

docs/faq/docker.rst

@@ -0,0 +1,115 @@
+Docker image
+------------
+
+We provide official images which can be found under:
+
+* docker registry ``arcan1s/ahriman``;
+* ghcr.io registry ``ghcr.io/arcan1s/ahriman``.
+
+These images are totally identical.
+
+Docker image is being updated on each commit to master as well as on each version. If you would like to use last (probably unstable) build you can use ``edge`` tag or ``latest`` for any tagged versions; otherwise you can use any version tag available.
+
+The default action (in case if no arguments provided) is ``repo-update``. Basically the idea is to run container, e.g.:
+
+.. code-block:: shell
+
+   docker run --privileged -v /path/to/local/repo:/var/lib/ahriman arcan1s/ahriman:latest
+
+``--privileged`` flag is required to make mount possible inside container. In order to make data available outside of container, you would need to mount local (parent) directory inside container by using ``-v /path/to/local/repo:/var/lib/ahriman`` argument, where ``/path/to/local/repo`` is a path to repository on local machine. In addition, you can pass own configuration overrides by using the same ``-v`` flag, e.g.:
+
+.. code-block:: shell
+
+   docker run --privileged -v /path/to/local/repo:/var/lib/ahriman -v /path/to/overrides/overrides.ini:/etc/ahriman.ini.d/10-overrides.ini arcan1s/ahriman:latest
+
+The action can be specified during run, e.g.:
+
+.. code-block:: shell
+
+   docker run --privileged -v /path/to/local/repo:/var/lib/ahriman arcan1s/ahriman:latest package-add ahriman --now
+
+For more details please refer to the docker FAQ.
+
+Environment variables
+^^^^^^^^^^^^^^^^^^^^^
+
+The following environment variables are supported:
+
+* ``AHRIMAN_ARCHITECTURE`` - architecture of the repository, default is ``x86_64``.
+* ``AHRIMAN_DEBUG`` - if set all commands will be logged to console.
+* ``AHRIMAN_FORCE_ROOT`` - force run ahriman as root instead of guessing by subcommand.
+* ``AHRIMAN_HOST`` - host for the web interface, default is ``0.0.0.0``.
+* ``AHRIMAN_MULTILIB`` - if set (default) multilib repository will be used, disabled otherwise.
+* ``AHRIMAN_OUTPUT`` - controls logging handler, e.g. ``syslog``, ``console``. The name must be found in logging configuration. Note that if ``syslog`` handler is used you will need to mount ``/dev/log`` inside container because it is not available there.
+* ``AHRIMAN_PACKAGER`` - packager name from which packages will be built, default is ``ahriman bot <ahriman@example.com>``.
+* ``AHRIMAN_PACMAN_MIRROR`` - override pacman mirror server if set.
+* ``AHRIMAN_PORT`` - HTTP server port if any, default is empty.
+* ``AHRIMAN_POSTSETUP_COMMAND`` - if set, the command which will be called (as root) after the setup command, but before any other actions.
+* ``AHRIMAN_PRESETUP_COMMAND`` - if set, the command which will be called (as root) right before the setup command.
+* ``AHRIMAN_REPOSITORY`` - repository name, default is ``aur-clone``.
+* ``AHRIMAN_REPOSITORY_SERVER`` - optional override for the repository URL. Useful if you would like to download packages from remote instead of local filesystem.
+* ``AHRIMAN_REPOSITORY_ROOT`` - repository root. Because of filesystem rights it is required to override default repository root. By default, it uses ``ahriman`` directory inside ahriman's home, which can be passed as mount volume.
+* ``AHRIMAN_UNIX_SOCKET`` - full path to unix socket which is used by web server, default is empty. Note that more likely you would like to put it inside ``AHRIMAN_REPOSITORY_ROOT`` directory (e.g. ``/var/lib/ahriman/ahriman/ahriman-web.sock``) or to ``/run/ahriman``.
+* ``AHRIMAN_USER`` - ahriman user, usually must not be overwritten, default is ``ahriman``.
+* ``AHRIMAN_VALIDATE_CONFIGURATION`` - if set (default) validate service configuration.
+
+You can pass any of these variables by using ``-e`` argument, e.g.:
+
+.. code-block:: shell
+
+   docker run --privileged -e AHRIMAN_PORT=8080 -v /path/to/local/repo:/var/lib/ahriman arcan1s/ahriman:latest
+
+Daemon service
+^^^^^^^^^^^^^^
+
+There is special ``repo-daemon`` subcommand which emulates systemd timer and will perform repository update periodically:
+
+.. code-block:: shell
+
+   docker run --privileged -v /path/to/local/repo:/var/lib/ahriman arcan1s/ahriman:latest repo-daemon
+
+This command uses same rules as ``repo-update``, thus, e.g. requires ``--privileged`` flag. Check also `examples <https://github.com/arcan1s/ahriman/tree/master/recipes/daemon>`__.
+
+Web service setup
+^^^^^^^^^^^^^^^^^
+
+For that you would need to have web container instance running forever; it can be achieved by the following command:
+
+.. code-block:: shell
+
+   docker run --privileged -p 8080:8080 -e AHRIMAN_PORT=8080 -e AHRIMAN_UNIX_SOCKET=/var/lib/ahriman/ahriman/ahriman-web.sock -v /path/to/local/repo:/var/lib/ahriman arcan1s/ahriman:latest
+
+Note about ``AHRIMAN_PORT`` environment variable which is required in order to enable web service. An additional port bind by ``-p 8080:8080`` is required to pass docker port outside of container.
+
+The ``AHRIMAN_UNIX_SOCKET`` variable is not required, however, highly recommended as it can be used for interprocess communications. If you set this variable you would like to be sure that this path is available outside of container if you are going to use multiple docker instances.
+
+If you are using ``AHRIMAN_UNIX_SOCKET`` variable, for every next container run it has to be passed also, e.g.:
+
+.. code-block:: shell
+
+   docker run --privileged -e AHRIMAN_UNIX_SOCKET=/var/lib/ahriman/ahriman/ahriman-web.sock -v /path/to/local/repo:/var/lib/ahriman arcan1s/ahriman:latest
+
+Otherwise, you would need to pass ``AHRIMAN_PORT`` and mount container network to the host system (``--net=host``), e.g.:
+
+.. code-block:: shell
+
+   docker run --privileged --net=host -e AHRIMAN_PORT=8080 -v /path/to/local/repo:/var/lib/ahriman arcan1s/ahriman:latest
+
+Simple server with authentication can be found in `examples <https://github.com/arcan1s/ahriman/tree/master/recipes/web>`__ too.
+
+Mutli-repository web service
+""""""""""""""""""""""""""""
+
+Idea is pretty same as to just run web service. However, it is required to run setup commands for each repository, except for one which is specified by ``AHRIMAN_REPOSITORY`` and ``AHRIMAN_ARCHITECTURE`` variables.
+
+In order to create configuration for additional repositories, the ``AHRIMAN_POSTSETUP_COMMAND`` variable should be used, e.g.:
+
+.. code-block:: shell
+
+   docker run --privileged -p 8080:8080 -e AHRIMAN_PORT=8080 -e AHRIMAN_UNIX_SOCKET=/var/lib/ahriman/ahriman/ahriman-web.sock -e AHRIMAN_POSTSETUP_COMMAND="ahriman --architecture x86_64 --repository aur-clone-v2 service-setup --build-as-user ahriman --packager 'ahriman bot <ahriman@example.com>'" -v /path/to/local/repo:/var/lib/ahriman arcan1s/ahriman:latest
+
+The command above will also create configuration for the repository named ``aur-clone-v2``.
+
+Note, however, that the command above is only required in case if the service is going to be used to run subprocesses. Otherwise, everything else (web interface, status, etc) will be handled as usual.
+
+Configuration `example <https://github.com/arcan1s/ahriman/tree/master/recipes/multirepo>`__.

docs/faq/examples.rst

@@ -0,0 +1,12 @@
+Use cases
+---------
+
+There is a collection of some specific recipes which can be found in `the repository <https://github.com/arcan1s/ahriman/tree/master/recipes>`__.
+
+Most of them can be run (``AHRIMAN_PASSWORD`` environment variable is required in the most setups) as simple as:
+
+.. code-block:: shell
+
+   AHRIMAN_PASSWORD=demo docker compose up
+
+Note, however, they are just an examples of specific configuration for specific cases and they are never intended to be used as is in real environment.

docs/faq/general.rst

@@ -0,0 +1,431 @@
+General topics
+--------------
+
+What is the purpose of the project
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This project has been created in order to maintain self-hosted Arch Linux user repository without manual intervention - checking for updates and building packages.
+
+How to install ahriman
+^^^^^^^^^^^^^^^^^^^^^^
+
+TL;DR
+
+.. code-block:: shell
+
+   yay -S ahriman
+   ahriman -a x86_64 -r aur-clone service-setup --packager "ahriman bot <ahriman@example.com>"
+   systemctl enable --now ahriman@x86_64-aur-clone.timer
+
+Long answer
+"""""""""""
+
+The idea is to install the package as usual, create working directory tree, create configuration for ``sudo`` and ``devtools``. Detailed description of the setup instruction can be found :doc:`here </setup>`.
+
+Run as daemon
+"""""""""""""
+
+The alternative way (though not recommended) is to run service instead of timer:
+
+.. code-block:: shell
+
+   systemctl enable --now ahriman-daemon@x86_64-aur-clone
+
+How to validate settings
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+There is special command which can be used in order to validate current configuration:
+
+.. code-block:: shell
+
+   ahriman service-config-validate --exit-code
+
+This command will print found errors, based on `cerberus <https://docs.python-cerberus.org/>`__, e.g.:
+
+.. code-block:: shell
+
+   auth
+                   ssalt: unknown field
+                   target: none or more than one rule validate
+                           oneof definition 0: unallowed value mapping
+                           oneof definition 1: field 'salt' is required
+                           oneof definition 2: unallowed value mapping
+                           oneof definition 2: field 'salt' is required
+                           oneof definition 2: field 'client_id' is required
+                           oneof definition 2: field 'client_secret' is required
+   gitremote
+                   pull_url: unknown field
+
+If an additional flag ``--exit-code`` is supplied, the application will return non-zero exit code, which can be used partially in scripts.
+
+What does "architecture specific" mean / How to configure for different architectures
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Some sections can be configured per architecture. The service will merge architecture specific values into common settings. In order to specify settings for specific architecture you must point it in section name.
+
+For example, the section
+
+.. code-block:: ini
+
+   [build]
+   build_command = extra-x86_64-build
+
+states that default build command is ``extra-x86_64-build``. But if there is section
+
+.. code-block:: ini
+
+   [build:i686]
+   build_command = extra-i686-build
+
+the ``extra-i686-build`` command will be used for ``i686`` architecture. You can also override settings for different repositories and architectures; in this case section names will be ``build:aur-clone`` (repository name only) and ``build:aur-clone:i686`` (both repository name and architecture).
+
+How to generate build reports
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Normally you would probably like to generate only one report for the specific type, e.g. only one email report. In order to do so you will need to have the following configuration:
+
+.. code-block:: ini
+
+   [report]
+   target = email
+
+   [email]
+   ...
+
+or in case of multiple architectures and *different* reporting settings:
+
+.. code-block:: ini
+
+   [report]
+   target = email
+
+   [email:i686]
+   ...
+
+   [email:x86_64]
+   ...
+
+But for some cases you would like to have multiple different reports with the same type (e.g. sending different templates to different addresses). For these cases you will need to specify section name in target and type in section, e.g. the following configuration can be used:
+
+.. code-block:: ini
+
+   [report]
+   target = email_1 email_2
+
+   [email_1]
+   type = email
+   ...
+
+   [email_2]
+   type = email
+   ...
+
+How to add new package
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: shell
+
+   sudo -u ahriman ahriman package-add ahriman --now
+
+``--now`` flag is totally optional and just run ``repo-update`` subcommand after the registering the new package. Thus the extended flow is the following:
+
+.. code-block:: shell
+
+   sudo -u ahriman ahriman package-add ahriman
+   sudo -u ahriman ahriman repo-update
+
+How to build package from local PKGBUILD
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+TL;DR
+
+.. code-block:: shell
+
+   sudo -u ahriman ahriman package-add /path/to/local/directory/with/PKGBUILD --now
+
+Before using this command you will need to create local directory, put ``PKGBUILD`` there and generate ``.SRCINFO`` by using ``makepkg --printsrcinfo > .SRCINFO`` command. These packages will be stored locally and *will be ignored* during automatic update; in order to update the package you will need to run ``package-add`` command again.
+
+How to copy package from another repository
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+As simple as add package from archive. Considering case when you would like to copy package ``package`` with version ``ver-rel`` from repository ``source-repository`` to ``target-respository`` (same architecture), the command will be following:
+
+.. code-block:: shell
+
+   sudo -u ahriman ahriman -r target-repository package-add /var/lib/ahriman/repository/source-repository/x86_64/package-ver-rel-x86_64.pkg.tar.zst
+
+In addition, you can remove source package as usual later.
+
+This feature in particular useful if for managing multiple repositories like ``[testing]`` and ``[extra]``.
+
+How to fetch PKGBUILDs from remote repository
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For that purpose you could use ``RemotePullTrigger`` trigger. To do so you will need to configure trigger as following:
+
+.. code-block:: ini
+
+   [remote-pull]
+   target = gitremote
+
+   [gitremote]
+   pull_url = https://github.com/username/repository
+
+During the next application run it will fetch repository from the specified URL and will try to find packages there which can be used as local sources.
+
+This feature can be also used to build packages which are not listed in AUR, the example of the feature use can be found `here <https://github.com/arcan1s/ahriman/tree/master/recipes/pull>`__.
+
+How to push updated PKGBUILDs to remote repository
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For that purpose you'd need to use another trigger called ``RemotePushTrigger``. Configure trigger as following:
+
+.. code-block:: ini
+
+   [remote-push]
+   target = gitremote
+
+   [gitremote]
+   push_url = https://github.com/username/repository
+
+Unlike ``RemotePullTrigger`` trigger, the ``RemotePushTrigger`` more likely will require authorization. It is highly recommended to use application tokens for that instead of using your password (e.g. for GitHub you can generate tokens `here <https://github.com/settings/tokens>`__ with scope ``public_repo``). Authorization can be supplied by using authorization part of the URL, e.g. ``https://key:token@github.com/username/repository``.
+
+How to change PKGBUILDs before build
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Well it is supported also. The recommended way is to patch specific function, e.g. by running
+
+.. code-block:: shell
+
+   sudo -u ahriman ahriman patch-add ahriman version
+
+This command will prompt for new value of the PKGBUILD variable ``version``. You can also write it to file and read from it:
+
+.. code-block:: shell
+
+   sudo -u ahriman ahriman patch-add ahriman version version.patch
+
+The command also supports arrays, but in this case you need to specify full array, e.g.
+
+.. code-block:: shell
+
+   sudo -u ahriman ahriman patch-add ahriman depends
+
+   Post new function or variable value below. Press Ctrl-D to finish:
+   (python python-aiohttp)
+   ^D
+
+will set depends PKGBUILD variable (exactly) to array ``["python", "python-aiohttp"]``.
+
+Alternatively you can create full-diff patches, which are calculated by using ``git diff`` from current PKGBUILD master branch:
+
+#.
+   Clone sources from AUR.
+
+#.
+   Make changes you would like to (e.g. edit ``PKGBUILD``, add external patches).
+
+#.
+   Run command
+
+   .. code-block:: shell
+
+      sudo -u ahriman ahriman patch-set-add /path/to/local/directory/with/PKGBUILD
+
+The last command will calculate diff from current tree to the ``HEAD`` and will store it locally. Patches will be applied on any package actions (e.g. it can be used for dependency management).
+
+It is also possible to create simple patch during package addition, e.g.:
+
+.. code-block:: shell
+
+   sudo -u ahriman ahriman package-add ahriman --variable PKGEXT=.pkg.tar.xz
+
+The ``--variable`` argument accepts variables in shell like format: quotation and lists are supported as usual, but functions are not. This feature is useful in particular in order to override specific makepkg variables during build.
+
+How to build package from official repository
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It is the same as adding any other package, but due to restrictions you must specify source explicitly, e.g.:
+
+.. code-block:: shell
+
+   sudo -u ahriman ahriman package-add pacman --source repository
+
+This feature is heavily depends on local pacman cache. In order to use this feature it is recommended to either run ``pacman -Sy`` before the interaction or use internal application cache with ``--refresh`` flag.
+
+Package build fails because it cannot validate PGP signature of source files
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+TL;DR
+
+.. code-block:: shell
+
+   sudo -u ahriman ahriman service-key-import ...
+
+How to update VCS packages
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Normally the service handles VCS packages correctly, however it requires additional dependencies:
+
+.. code-block:: shell
+
+   pacman -S breezy darcs mercurial subversion
+
+How to review changes before build
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In this scenario, the update process must be separated into several stages. First, it is required to check updates:
+
+.. code-block:: shell
+
+   sudo -u ahriman ahriman repo-check
+
+During the check process, the service will generate changes from the last known commit and will send it to remote service. In order to verify source files changes, the web interface or special subcommand can be used:
+
+.. code-block:: shell
+
+   ahriman package-changes ahriman
+
+After validation, the operator can run update process with approved list of packages, e.g.:
+
+.. code-block:: shell
+
+   sudo -u ahriman ahriman repo-update ahriman
+
+How to remove package
+^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: shell
+
+   sudo -u ahriman ahriman package-remove ahriman
+
+Also, there is command ``repo-remove-unknown`` which checks packages in AUR and local storage and removes ones which have been removed.
+
+Remove commands also remove any package files (patches, caches etc).
+
+How to sign repository
+^^^^^^^^^^^^^^^^^^^^^^
+
+Repository sign feature is available in several configurations. The recommended way is just to sign repository database file by single key instead of trying to sign each package. However, the steps are pretty same, just configuration is a bit different. For more details about options kindly refer to :doc:`configuration reference </configuration>`.
+
+#.
+   First you would need to create the key on your local machine:
+
+   .. code-block:: shell
+
+      gpg --full-generate-key
+
+   This command will prompt you for several questions. Most of them may be left default, but you will need to fill real name and email address with some data. Because at the moment the service doesn't support passphrases, it must be left blank.
+
+#.
+   The command above will generate key and print its fingerprint, something like ``8BE91E5A773FB48AC05CC1EDBED105AED6246B39``. Copy it.
+
+#.
+   Export your private key by using the fingerprint above:
+
+   .. code-block:: shell
+
+      gpg --export-secret-keys -a 8BE91E5A773FB48AC05CC1EDBED105AED6246B39 > repository-key.gpg
+
+#.
+
+   Copy the specified key to the build machine (i.e. where the service is running).
+
+#.
+   Import the specified key to the service user:
+
+   .. code-block:: shell
+
+      sudo -u ahriman gpg --import repository-key.gpg
+
+   Don't forget to remove the key from filesystem after import.
+
+#.
+   Change trust level to ``ultimate``:
+
+   .. code-block:: shell
+
+      sudo -u ahriman gpg --edit-key 8BE91E5A773FB48AC05CC1EDBED105AED6246B39
+
+   The command above will drop you into gpg shell, in which you will need to type ``trust``, choose ``5 = I trust ultimately``, confirm and exit ``quit``.
+
+#.
+   Proceed with service configuration according to the :doc:`configuration </configuration>`:
+
+   .. code-block:: ini
+
+      [sign]
+      target = repository
+      key = 8BE91E5A773FB48AC05CC1EDBED105AED6246B39
+
+
+How to rebuild packages after library update
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+TL;DR
+
+.. code-block:: shell
+
+   sudo -u ahriman ahriman repo-rebuild --depends-on python
+
+You can even rebuild the whole repository (which is particular useful in case if you would like to change packager) if you do not supply ``--depends-on`` option. This action will automatically increment ``pkgrel`` value; in case if you don't want to, the ``--no-increment`` option has to be supplied.
+
+However, note that you do not need to rebuild repository in case if you just changed signing option, just use ``repo-sign`` command instead.
+
+Automated broken dependencies detection
+"""""""""""""""""""""""""""""""""""""""
+
+After the success build the application extracts all linked libraries and used directories and stores them in database. During the check process, the application extracts pacman databases and checks if file names have been changed (e.g. new python release caused ``/usr/lib/python3.x`` directory renaming to ``/usr/lib/python3.y`` or soname for a linked library has been changed). In case if broken dependencies have been detected, the package will be added to the rebuild queue.
+
+In order to disable this check completely, the ``--no-check-files`` flag can be used.
+
+In addition, there is possibility to control paths which will be used for checking, by using options ``build.allowed_scan_paths`` and ``build.blacklisted_scan_paths``. Leaving ``build.allowed_scan_paths`` blank will effectively disable any check too.
+
+How to install built packages
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Add the following lines to your ``pacman.conf``:
+
+.. code-block:: ini
+
+   [repository]
+   Server = file:///var/lib/ahriman/repository/$repo/$arch
+
+(You might need to add ``SigLevel`` option according to the pacman documentation.)
+
+How to serve repository
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Easy. For example, nginx configuration (without SSL) will look like:
+
+.. code-block::
+
+   server {
+       listen 80;
+       server_name repo.example.com;
+
+       location / {
+           autoindex on;
+           root /var/lib/ahriman/repository;
+       }
+   }
+
+Example of the status page configuration is the following (status service is using 8080 port):
+
+.. code-block::
+
+   server {
+       listen 80;
+       server_name builds.example.com;
+
+       location / {
+           proxy_set_header Host $host;
+           proxy_set_header X-Real-IP $remote_addr;
+           proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+           proxy_set_header X-Forwarder-Proto $scheme;
+
+           proxy_pass http://127.0.0.1:8080;
+       }
+   }
+
+Some more examples can be found in configuration `recipes <https://github.com/arcan1s/ahriman/tree/master/recipes>`__.

docs/faq/index.rst

@@ -0,0 +1,17 @@
+FAQ
+===
+
+.. toctree::
+   :maxdepth: 2
+
+   general
+   docker
+   non-x86_64-setup
+   synchronization
+   reporting
+   distributed
+   maintenance-packages
+   web
+   backup
+   examples
+   misc

docs/faq/maintenance-packages.rst

@@ -0,0 +1,73 @@
+Maintenance packages
+--------------------
+
+Generate keyring package
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The application provides special plugin which generates keyring package. This plugin heavily depends on ``sign`` group settings, however it is possible to override them. The minimal package can be generated in the following way:
+
+#.
+   Edit configuration:
+
+   .. code-block:: ini
+
+      [keyring]
+      target = keyring-generator
+
+   By default it will use ``sign.key`` as trusted key and all other keys as packagers ones. For all available options refer to :doc:`configuration </configuration>`.
+
+#.
+   Create package source files:
+
+   .. code-block:: shell
+
+      sudo -u ahriman ahriman repo-create-keyring
+
+   This command will generate PKGBUILD, revoked and trusted listings and keyring itself and will register the package in database.
+
+#.
+   Build new package as usual:
+
+   .. code-block:: shell
+
+      sudo -u ahriman ahriman package-add aur-clone-keyring --source local --now
+
+   where ``aur-clone`` is your repository name.
+
+This plugin might have some issues, in case of any of them, kindly create `new issue <https://github.com/arcan1s/ahriman/issues/new/choose>`__.
+
+Generate mirrorlist package
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The application provides special plugin which generates mirrorlist package also. It is possible to distribute this package as usual later. The package can be generated in the following way:
+
+#.
+   Edit configuration:
+
+   .. code-block:: ini
+
+      [mirrorlist]
+      target = mirrorlist-generator
+
+      [mirrorlist-generator]
+      servers = https://repo.example.com/$arch
+
+   The ``mirrorlist-generator.servers`` must contain list of available mirrors, the ``$arch`` and ``$repo`` variables are supported. For more options kindly refer to :doc:`configuration </configuration>`.
+
+#.
+   Create package source files:
+
+   .. code-block:: shell
+
+      sudo -u ahriman ahriman repo-create-mirrorlist
+
+   This command will generate PKGBUILD and mirrorlist file and will register the package in database.
+
+#.
+   Build new package as usual:
+
+   .. code-block:: shell
+
+      sudo -u ahriman ahriman package-add aur-clone-mirrorlist --source local --now
+
+   where ``aur-clone`` is your repository name.

docs/faq/misc.rst

@@ -0,0 +1,100 @@
+Other topics
+------------
+
+How does it differ from %another-manager%?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Short answer - I do not know. Also for some references credits to `Alad <https://github.com/AladW>`__, he `did <https://wiki.archlinux.org/title/User:Alad/Local_repo_tools>`__ really good investigation of existing alternatives.
+
+`arch-repo-manager <https://github.com/Martchus/arch-repo-manager>`__
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+Looks actually pretty good, in case if I would find it, I would probably didn't start this project; the most of features (like web interface or additional helpers) are already implemented or planned to be. However, this project seems to be at early alpha stage (as for Nov 2022), written in C++ (not pro or con) and misses documentation.
+
+`archrepo2 <https://github.com/lilydjwg/archrepo2>`__
+"""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+Don't know, haven't tried it. But it lacks of documentation at least.
+
+* ``ahriman`` has web interface.
+* ``archrepo2`` doesn't have synchronization and reporting.
+* ``archrepo2`` actively uses direct shell calls and ``yaourt`` components.
+* ``archrepo2`` has constantly running process instead of timer process (it is not pro or con).
+
+`repoctl <https://github.com/cassava/repoctl>`__
+""""""""""""""""""""""""""""""""""""""""""""""""
+
+* ``ahriman`` has web interface.
+* ``repoctl`` does not have reporting feature.
+* ``repoctl`` does not support local packages and patches.
+* Some actions are not fully automated in ``repoctl`` (e.g. package update still requires manual intervention for the build itself).
+* ``repoctl`` has better AUR interaction features. With colors!
+* ``repoctl`` has much easier configuration and even completion.
+* ``repoctl`` is able to store old packages.
+* Ability to host repository from same command in ``repoctl`` vs external services (e.g. nginx) in ``ahriman``.
+
+`repod <https://gitlab.archlinux.org/archlinux/repod>`__
+""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+Official tool provided by distribution, has clean logic, but it is just a helper for ``repo-add``, e.g. it doesn't work with AUR and all packages builds have to be handled separately.
+
+`repo-scripts <https://github.com/arcan1s/repo-scripts>`__
+""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+Though originally I've created ahriman by trying to improve the project, it still lacks a lot of features:
+
+* ``ahriman`` has web interface.
+* ``ahriman`` has better reporting with template support.
+* ``ahriman`` has more synchronization features (there was only ``rsync`` based).
+* ``ahriman`` supports local packages and patches.
+* ``repo-scripts`` doesn't have dependency management.
+
+...and so on. ``repo-scripts`` also has bad architecture and bad quality code and uses out-of-dated ``yaourt`` and ``package-query``.
+
+`toolbox <https://github.com/chaotic-aur/toolbox>`__
+""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+It is automation tools for ``repoctl`` mentioned above. Except for using shell it looks pretty cool and also offers some additional features like patches, remote synchronization (isn't it?) and reporting.
+
+How to check service logs
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+By default, the service writes logs to ``journald`` which can be accessed by using ``journalctl`` command (logs are written to the journal of the user under which command is run). In order to retrieve logs for the process you can use the following command:
+
+.. code-block:: shell
+
+   sudo journalctl SYSLOG_IDENTIFIER=ahriman
+
+You can also ask to forward logs to ``stderr``, just set ``--log-handler`` flag, e.g.:
+
+.. code-block:: shell
+
+   ahriman --log-handler console ...
+
+You can even configure logging as you wish, but kindly refer to python ``logging`` module `configuration <https://docs.python.org/3/library/logging.config.html>`__.
+
+The application uses java concept to log messages, e.g. class ``Application`` imported from ``ahriman.application.application`` package will have logger called ``ahriman.application.application.Application``. In order to e.g. change logger name for whole application package it is possible to change values for ``ahriman.application`` package; thus editing ``ahriman`` logger configuration will change logging for whole application (unless there are overrides for another logger).
+
+Html customization
+^^^^^^^^^^^^^^^^^^
+
+It is possible to customize html templates. In order to do so, create files somewhere (refer to Jinja2 documentation and the service source code for available parameters) and prepend ``templates`` with value pointing to this directory.
+
+In addition, default html templates supports style customization out-of-box. In order to customize style, just put file named ``user-style.jinja2`` to the templates directory.
+
+Web API extension
+^^^^^^^^^^^^^^^^^
+
+The application loads web views dynamically, so it is possible relatively easy extend its API. In order to do so:
+
+#. Create view class which is derived from ``ahriman.web.views.base.BaseView`` class.
+#. Create implementation for this class.
+#. Put file into ``ahriman.web.views`` package.
+#. Restart application.
+
+For more details about implementation and possibilities, kindly refer to module documentation and source code and `aiohttp documentation <https://docs.aiohttp.org/en/stable/>`__.
+
+I did not find my question
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+`Create an issue <https://github.com/arcan1s/ahriman/issues>`__ with type **Question**.

docs/faq/non-x86_64-setup.rst

@@ -0,0 +1,99 @@
+Non-x86_64 architecture setup
+-----------------------------
+
+The following section describes how to setup ahriman with architecture different from x86_64, as example i686. For most cases you have base repository available, e.g. archlinux32 repositories for i686 architecture; in case if base repository is not available, steps are a bit different, however, idea remains the same.
+
+The example of setup with docker compose can be found `here <https://github.com/arcan1s/ahriman/tree/master/recipes/i686>`__.
+
+Physical server setup
+^^^^^^^^^^^^^^^^^^^^^
+
+In this example we are going to use files and packages which are provided by official repositories of the used architecture. Note, that versions might be different, thus you need to find correct versions on the distribution web site, e.g. `archlinux32 packages <https://www.archlinux32.org/packages/>`__.
+
+#.
+   First, considering having base Arch Linux system, we need to install keyring for the specified repositories, e.g.:
+
+   .. code-block:: shell
+
+      wget https://pool.mirror.archlinux32.org/i686/core/archlinux32-keyring-20230705-1.0-any.pkg.tar.zst
+      pacman -U archlinux32-keyring-20230705-1.0-any.pkg.tar.zst
+
+#.
+   In order to run ``devtools`` scripts for custom architecture they also need specific ``makepkg`` configuration, it can be retrieved by installing the ``devtools`` package of the distribution, e.g.:
+
+   .. code-block:: shell
+
+      wget https://pool.mirror.archlinux32.org/i686/extra/devtools-20221208-1.2-any.pkg.tar.zst
+      pacman -U devtools-20221208-1.2-any.pkg.tar.zst
+
+   Alternatively, you can create your own ``makepkg`` configuration and save it as ``/usr/share/devtools/makepkg.conf.d/i686.conf``.
+
+#.
+   Setup repository as usual:
+
+   .. code-block:: shell
+
+      ahriman -a i686 service-setup --mirror 'https://de.mirror.archlinux32.org/$arch/$repo'--no-multilib ...
+
+   In addition to usual options, you need to specify the following options:
+
+   * ``--mirror`` - link to the mirrors which will be used instead of official repositories.
+   * ``--no-multilib`` - in the example we are using i686 architecture for which multilib repository doesn't exist.
+
+#.
+   That's all Folks!
+
+Docker container setup
+^^^^^^^^^^^^^^^^^^^^^^
+
+There are two possible ways to achieve same setup, by using docker container. The first one is just mount required files inside container and run it as usual (with specific environment variables). Another one is to create own container based on official one:
+
+#.
+   Clone official container as base:
+
+   .. code-block:: dockerfile
+
+      FROM arcan1s/ahriman:latest
+
+#.
+   Init pacman keys. This command is required in order to populate distribution keys:
+
+   .. code-block:: dockerfile
+
+      RUN pacman-key --init
+
+#.
+   Install packages as it was described above:
+
+   .. code-block:: dockerfile
+
+      RUN pacman --noconfirm -Sy wget
+      RUN wget https://pool.mirror.archlinux32.org/i686/extra/devtools-20221208-1.2-any.pkg.tar.zst && pacman --noconfirm -U devtools-20221208-1.2-any.pkg.tar.zst
+      RUN wget https://pool.mirror.archlinux32.org/i686/core/archlinux32-keyring-20230705-1.0-any.pkg.tar.zst && pacman --noconfirm -U archlinux32-keyring-20230705-1.0-any.pkg.tar.zst
+
+#.
+   At that point you should have full ``Dockerfile`` like:
+
+   .. code-block:: dockerfile
+
+      FROM arcan1s/ahriman:latest
+
+      RUN pacman-key --init
+
+      RUN pacman --noconfirm -Sy wget
+      RUN wget https://pool.mirror.archlinux32.org/i686/extra/devtools-20221208-1.2-any.pkg.tar.zst && pacman --noconfirm -U devtools-20221208-1.2-any.pkg.tar.zst
+      RUN wget https://pool.mirror.archlinux32.org/i686/core/archlinux32-keyring-20230705-1.0-any.pkg.tar.zst && pacman --noconfirm -U archlinux32-keyring-20230705-1.0-any.pkg.tar.zst
+
+#.
+   After that you can build you own container, e.g.:
+
+   .. code-block:: shell
+
+      docker build --tag ahriman-i686:latest
+
+#.
+   Now you can run locally built container as usual with passing environment variables for setup command:
+
+   .. code-block:: shell
+
+      docker run --privileged -p 8080:8080 -e AHRIMAN_ARCHITECTURE=i686 -e AHRIMAN_PACMAN_MIRROR='https://de.mirror.archlinux32.org/$arch/$repo' -e AHRIMAN_MULTILIB= ahriman-i686:latest

docs/faq/reporting.rst

@@ -0,0 +1,99 @@
+Reporting
+---------
+
+How to report by email
+^^^^^^^^^^^^^^^^^^^^^^
+
+#.
+   Install dependencies:
+
+   .. code-block:: shell
+
+      yay -S --asdeps python-jinja
+
+#.
+   Configure the service:
+
+   .. code-block:: ini
+
+      [report]
+      target = email
+
+      [email]
+      host = smtp.example.com
+      link_path = http://example.com/aur-clone/x86_64
+      password = ...
+      port = 465
+      receivers = me@example.com
+      sender = me@example.com
+      user = me@example.com
+
+How to generate index page for S3
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+#.
+   Install dependencies:
+
+   .. code-block:: shell
+
+      yay -S --asdeps python-jinja
+
+#.
+   Configure the service:
+
+   .. code-block:: ini
+
+      [report]
+      target = html
+
+      [html]
+      path = /var/lib/ahriman/repository/aur-clone/x86_64/index.html
+      link_path = http://example.com/aur-clone/x86_64
+
+After these steps ``index.html`` file will be automatically synced to S3.
+
+How to post build report to telegram
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+#.
+   It still requires additional dependencies:
+
+   .. code-block:: shell
+
+      yay -S --asdeps python-jinja
+
+#.
+   Register bot in telegram. You can do it by starting chat with `@BotFather <https://t.me/botfather>`__. For more details please refer to `official documentation <https://core.telegram.org/bots>`__.
+
+#.
+   Optionally (if you want to post message in chat):
+
+   #. Create telegram channel.
+   #. Invite your bot into the channel.
+   #. Make your channel public
+
+#.
+   Get chat id if you want to use by numerical id or just use id prefixed with ``@`` (e.g. ``@ahriman``). If you are not using chat the chat id is your user id. If you don't want to make channel public you can use `this guide <https://stackoverflow.com/a/33862907>`__.
+
+#.
+   Configure the service:
+
+   .. code-block:: ini
+
+      [report]
+      target = telegram
+
+      [telegram]
+      api_key = aaAAbbBBccCC
+      chat_id = @ahriman
+      link_path = http://example.com/aur-clone/x86_64
+
+   ``api_key`` is the one sent by `@BotFather <https://t.me/botfather>`__, ``chat_id`` is the value retrieved from previous step.
+
+If you did everything fine you should receive the message with the next update. Quick credentials check can be done by using the following command:
+
+.. code-block:: shell
+
+   curl 'https://api.telegram.org/bot{api_key}/sendMessage?chat_id={chat_id}&text=hello'
+
+(replace ``{chat_id}`` and ``{api_key}`` with the values from configuration).

docs/faq/synchronization.rst

@@ -0,0 +1,131 @@
+Remote synchronization
+----------------------
+
+How to sync repository to another server
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+There are several choices:
+
+#.
+   Easy and cheap, just share your local files through the internet, e.g. for ``nginx``:
+
+   .. code-block::
+
+       server {
+           location / {
+               autoindex on;
+               root /var/lib/ahriman/repository/;
+           }
+       }
+
+#.
+   You can also upload your packages using ``rsync`` to any available server. In order to use it you would need to configure ahriman first:
+
+   .. code-block:: ini
+
+       [upload]
+       target = rsync
+
+       [rsync]
+       remote = 192.168.0.1:/srv/repo
+
+   After that just add ``/srv/repo`` to the ``pacman.conf`` as usual. You can also upload to S3 (``Server = https://s3.eu-central-1.amazonaws.com/repository/aur-clone/x86_64``) or to GitHub (``Server = https://github.com/ahriman/repository/releases/download/aur-clone-x86_64``).
+
+How to sync to S3
+^^^^^^^^^^^^^^^^^
+
+#.
+   Install dependencies:
+
+   .. code-block:: shell
+
+      pacman -S python-boto3
+
+#.
+   Create a bucket (e.g. ``repository``).
+
+#.
+   Create an user with write access to the bucket:
+
+   .. code-block::
+
+       {
+           "Version": "2012-10-17",
+           "Statement": [
+               {
+                   "Sid": "ListObjectsInBucket",
+                   "Effect": "Allow",
+                   "Action": [
+                       "s3:ListBucket"
+                   ],
+                   "Resource": [
+                       "arn:aws:s3:::repository"
+                   ]
+               },
+               {
+                   "Sid": "AllObjectActions",
+                   "Effect": "Allow",
+                   "Action": "s3:*Object",
+                   "Resource": [
+                       "arn:aws:s3:::repository/*"
+                   ]
+               }
+           ]
+       }
+
+#.
+   Create an API key for the user and store it.
+
+#.
+   Configure the service as following:
+
+   .. code-block:: ini
+
+       [upload]
+       target = s3
+
+       [s3]
+       access_key = ...
+       bucket = repository
+       region = eu-central-1
+       secret_key = ...
+
+S3 with SSL
+"""""""""""
+
+In order to configure S3 on custom domain with SSL (and some other features, like redirects), the CloudFront should be used.
+
+#. Configure S3 as described above.
+#. In bucket properties, enable static website hosting with hosting type "Host a static website".
+#. Go to AWS Certificate Manager and create public certificate on your domain. Validate domain as suggested.
+#. Go to CloudFront and create distribution. The following settings are required:
+
+   * Origin domain choose S3 bucket.
+   * Tick use website endpoint.
+   * Disable caching.
+   * Select issued certificate.
+
+#. Point DNS record to CloudFront address.
+
+How to sync to GitHub releases
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+#.
+   Create a repository.
+
+#.
+   `Create API key <https://github.com/settings/tokens>`__ with scope ``public_repo``.
+
+#.
+   Configure the service as following:
+
+   .. code-block:: ini
+
+       [upload]
+       target = github
+
+       [github]
+       owner = ahriman
+       password = ...
+       repository = repository
+       username = ahriman

docs/faq/web.rst

@@ -0,0 +1,145 @@
+Web service
+-----------
+
+How to setup web service
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+#. 
+   Install dependencies:
+
+   .. code-block:: shell
+
+      yay -S --asdeps python-aiohttp python-aiohttp-jinja2 python-aiohttp-apispec>=3.0.0 python-aiohttp-cors
+
+#. 
+   Configure service:
+
+   .. code-block:: ini
+
+      [web]
+      port = 8080
+
+#. 
+   Start the web service ``systemctl enable --now ahriman-web``.
+
+How to enable basic authorization
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+#. 
+   Install dependencies 😊:
+
+   .. code-block:: shell
+
+      yay -S --asdeps python-aiohttp-security python-aiohttp-session python-cryptography
+
+#. 
+   Configure the service to enable authorization:
+
+   .. code-block:: ini
+
+      [auth]
+      target = configuration
+      salt = somerandomstring
+
+   The ``salt`` parameter is optional, but recommended, and can be set to any (random) string.
+
+#.
+   In order to provide access for reporting from application instances you can (the recommended way) use unix sockets by the following configuration (note, that it requires ``python-requests-unixsocket2`` package to be installed):
+
+   .. code-block:: ini
+
+      [web]
+      unix_socket = /run/ahriman/ahriman-web.sock
+
+   This socket path must be available for web service instance and must be available for all application instances (e.g. in case if you are using docker container - see above - you need to make sure that the socket is passed to the root filesystem).
+
+   By the way, unix socket variable will be automatically set in case if ``--web-unix-socket`` argument is supplied to the ``setup`` subcommand.
+
+   Alternatively, you need to create user for the service:
+
+   .. code-block:: shell
+
+      sudo -u ahriman ahriman user-add -r full api
+
+   This command will ask for the password, just type it in stdin; **do not** leave the field blank, user will not be able to authorize, and finally configure the application:
+
+   .. code-block:: ini
+
+      [status]
+      username = api
+      password = pa55w0rd
+
+#.
+   Create end-user with password:
+
+   .. code-block:: shell
+
+      sudo -u ahriman ahriman user-add -r full my-first-user
+
+#.
+   Restart web service ``systemctl restart ahriman-web``.
+
+Using PAM authentication
+""""""""""""""""""""""""
+
+There is also ability to allow system users to log in. To do so, the following configuration have to be set:
+
+.. code-block:: ini
+
+   [auth]
+   target = pam
+   full_access_group = wheel
+
+With this setup, every user (except root) will be able to log in by using system password. If user belongs to the ``wheel`` group, the full access will be automatically granted. It is also possible to manually add, block user or change user rights via usual user management process.
+
+How to enable OAuth authorization
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+#. 
+   Create OAuth web application, download its ``client_id`` and ``client_secret``.
+
+#.
+   Guess what? Install dependencies:
+
+   .. code-block:: shell
+
+      yay -S --asdeps python-aiohttp-security python-aiohttp-session python-cryptography python-aioauth-client
+
+#. 
+   Configure the service:
+
+   .. code-block:: ini
+
+      [auth]
+      target = oauth
+      client_id = ...
+      client_secret = ...
+
+      [web]
+      address = https://example.com
+
+   Configure ``oauth_provider`` and ``oauth_scopes`` in case if you would like to use different from Google provider. Scope must grant access to user email. ``web.address`` is required to make callback URL available from internet.
+
+#. 
+   If you are not going to use unix socket, you also need to create service user (remember to set ``auth.salt`` option before if required):
+
+   .. code-block:: shell
+
+      sudo -u ahriman ahriman user-add --as-service -r full api
+
+#. 
+   Create end-user:
+
+   .. code-block:: shell
+
+      sudo -u ahriman ahriman user-add -r full my-first-user
+
+   When it will ask for the password leave it blank.
+
+#.
+   Restart web service ``systemctl restart ahriman-web``.
+
+How to implement own interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can write your own interface by using API which is provided by the web service. Full autogenerated API documentation is available at ``http://localhost:8080/api-docs``.

docs/index.rst

@@ -33,7 +33,7 @@ Contents
    setup
    configuration
    command-line
-   faq
+   faq/index
    migration
    architecture
    advanced-usage

package/archlinux/PKGBUILD

@@ -1,7 +1,7 @@
 # Maintainer: Evgeniy Alekseev
 
 pkgname='ahriman'
-pkgver=2.13.8
+pkgver=2.14.1
 pkgrel=1
 pkgdesc="ArcH linux ReposItory MANager"
 arch=('any')

package/share/ahriman/settings/ahriman.ini

@@ -34,6 +34,8 @@ allow_read_only = yes
 ; Cookie secret key to be used for cookies encryption. Must be valid 32 bytes URL-safe base64-encoded string.
 ; If not set, it will be generated automatically.
 ;cookie_secret_key =
+; Name of the secondary group to be used as admin group in the service.
+;full_access_group = wheel
 ; Authentication cookie expiration in seconds.
 ;max_age = 604800
 ; OAuth2 provider icon for the web interface.
@@ -42,12 +44,18 @@ allow_read_only = yes
 ;oauth_provider = GoogleClient
 ; Scopes list for OAuth2 provider. Required if oauth is used.
 ;oauth_scopes = https://www.googleapis.com/auth/userinfo.email
+; Allow login as root user (only if PAM is used).
+;permit_root_login = no
 ; Optional password salt.
 ;salt =
 
 [build]
+; List of paths to be used for implicit dependency scan
+allowed_scan_paths = /usr/lib
 ; List of additional flags passed to archbuild command.
 ;archbuild_flags =
+; List of paths to be excluded for implicit dependency scan. Usually they should be subpaths of allowed_scan_paths
+blacklisted_scan_paths = /usr/lib/cmake
 ; Path to build command
 ;build_command =
 ; List of packages to be ignored during automatic updates.

package/share/man/man1/ahriman.1

@@ -1,4 +1,4 @@
-.TH AHRIMAN "1" "2024\-05\-12" "ahriman" "Generated Python Manual"
+.TH AHRIMAN "1" "2024\-09\-04" "ahriman" "Generated Python Manual"
 .SH NAME
 ahriman
 .SH SYNOPSIS
@@ -391,7 +391,7 @@ PKGBUILD variable or function name. If variable is a function, it must end with
 path to file which contains function or variable value. If not set, the value will be read from stdin
 
 .SH COMMAND \fI\,'ahriman patch\-list'\/\fR
-usage: ahriman patch\-list [\-h] [\-e] [\-v VARIABLE] [package]
+usage: ahriman patch\-list [\-h] [\-e] [\-v VARIABLE] package
 
 list available patches for the package
 

package/share/zsh/site-functions/_ahriman

@@ -86,7 +86,7 @@ _shtab_ahriman_options=(
   {-a,--architecture}"[filter by target architecture (default\: None)]:architecture:"
   {-c,--configuration}"[configuration path (default\: \/etc\/ahriman.ini)]:configuration:"
   "--force[force run, remove file lock (default\: False)]"
-  {-l,--lock}"[lock file (default\: \/tmp\/ahriman.lock)]:lock:"
+  {-l,--lock}"[lock file (default\: ahriman.pid)]:lock:"
   "--log-handler[explicit log handler specification. If none set, the handler will be guessed from environment (default\: None)]:log_handler:(console syslog journald)"
   {-q,--quiet}"[force disable any logging (default\: False)]"
   {--report,--no-report}"[force enable or disable reporting to web service (default\: True)]:report:"
@@ -280,7 +280,7 @@ _shtab_ahriman_patch_list_options=(
   "(- : *)"{-h,--help}"[show this help message and exit]"
   {-e,--exit-code}"[return non-zero exit status if result is empty (default\: False)]"
   "*"{-v,--variable}"[if set, show only patches for specified PKGBUILD variables (default\: None)]:variable:"
-  ":package base (default\: None):"
+  ":package base:"
 )
 
 _shtab_ahriman_patch_remove_options=(

recipes/README.md

@@ -12,6 +12,7 @@ Collection of the examples of docker compose configuration files, which covers s
 * [Index](index): repository with index page generator enabled.
 * [Multi repo](multirepo): run web service with two separated repositories.
 * [OAuth](oauth): web service with OAuth (GitHub provider) authentication enabled.
+* [PAM](pam): web service with PAM authentication enabled.
 * [Pull](pull): normal service, but in addition with pulling packages from another source (e.g. GitHub repository).
 * [Sign](sign): create repository with database signing.
 * [Web](web): simple web service with authentication enabled.

recipes/pam/README.md

@@ -0,0 +1,6 @@
+# PAM
+
+1. Create system user `demo` with password from `AHRIMAN_PASSWORD` environment variable and group `wheel`.
+2. Setup repository named `ahriman-demo` with architecture `x86_64`.
+3. Start web server at port `8080`.
+4. Repository is available at `http://localhost:8080/repo`.

recipes/pam/compose.yml

@@ -0,0 +1,63 @@
+services:
+  backend:
+    image: arcan1s/ahriman:edge
+    privileged: true
+
+    environment:
+      AHRIMAN_DEBUG: yes
+      AHRIMAN_OUTPUT: console
+      AHRIMAN_PASSWORD: ${AHRIMAN_PASSWORD}
+      AHRIMAN_PORT: 8080
+      AHRIMAN_PRESETUP_COMMAND: useradd -d / -G wheel -M demo; (cat /run/secrets/password; echo; cat /run/secrets/password) | passwd demo
+      AHRIMAN_REPOSITORY: ahriman-demo
+      AHRIMAN_UNIX_SOCKET: /var/lib/ahriman/ahriman/ahriman.sock
+
+    configs:
+      - source: service
+        target: /etc/ahriman.ini.d/99-settings.ini
+    secrets:
+      - password
+
+    volumes:
+      - type: volume
+        source: repository
+        target: /var/lib/ahriman
+        volume:
+          nocopy: true
+
+    healthcheck:
+      test: curl --fail --silent --output /dev/null http://backend:8080/api/v1/info
+      interval: 10s
+      start_period: 30s
+
+    command: web
+
+  frontend:
+    image: nginx
+    ports:
+      - 8080:80
+
+    configs:
+      - source: nginx
+        target: /etc/nginx/conf.d/default.conf
+
+    volumes:
+      - type: volume
+        source: repository
+        target: /srv
+        read_only: true
+        volume:
+          nocopy: true
+
+configs:
+  nginx:
+    file: nginx.conf
+  service:
+    file: service.ini
+
+secrets:
+  password:
+    environment: AHRIMAN_PASSWORD
+
+volumes:
+  repository:

recipes/pam/nginx.conf

@@ -0,0 +1,18 @@
+server {
+    listen 80;
+
+    location /repo {
+        rewrite ^/repo/(.*) /$1 break;
+        autoindex on;
+        root /srv/ahriman/repository;
+    }
+
+    location / {
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarder-Proto $scheme;
+
+        proxy_pass http://backend:8080;
+    }
+}

recipes/pam/service.ini

@@ -0,0 +1,3 @@
+[auth]
+target = pam
+full_access_group = wheel

src/ahriman/__init__.py

@@ -17,4 +17,4 @@
 # You should have received a copy of the GNU General Public License
 # along with this program. If not, see <http://www.gnu.org/licenses/>.
 #
-__version__ = "2.13.8"
+__version__ = "2.14.1"

src/ahriman/application/handlers/patch.py

@@ -98,6 +98,7 @@ class Patch(Handler):
             PkgbuildPatch: created patch for the PKGBUILD function
         """
         if patch_path is None:
+            # pylint: disable=bad-builtin
             print("Post new function or variable value below. Press Ctrl-D to finish:", file=sys.stderr)
             patch = "".join(list(sys.stdin))
         else:

src/ahriman/application/handlers/update.py

@@ -77,5 +77,5 @@ class Update(Handler):
             Callable[[str], None]: in case if dry_run is set it will return print, logger otherwise
         """
         def inner(line: str) -> None:
-            return print(line) if dry_run else application.logger.info(line)
+            return print(line) if dry_run else application.logger.info(line)  # pylint: disable=bad-builtin
         return inner

src/ahriman/application/lock.py

@@ -75,7 +75,9 @@ class Lock(LazyLogging):
         """
         self.path: Path | None = None
         if args.lock is not None:
-            self.path = args.lock.with_stem(f"{args.lock.stem}_{repository_id.id}")
+            self.path = args.lock
+            if not repository_id.is_empty:
+                self.path = self.path.with_stem(f"{args.lock.stem}_{repository_id.id}")
             if not self.path.is_absolute():
                 # prepend full path to the lock file
                 self.path = Path("/") / "run" / "ahriman" / self.path

src/ahriman/core/alpm/pacman.py

@@ -43,7 +43,7 @@ class Pacman(LazyLogging):
         configuration(Configuration): configuration instance
         refresh_database(PacmanSynchronization): synchronize local cache to remote
         repository_id(RepositoryId): repository unique identifier
-        repository_path(RepositoryPaths): repository paths instance
+        repository_paths(RepositoryPaths): repository paths instance
     """
 
     def __init__(self, repository_id: RepositoryId, configuration: Configuration, *,
@@ -188,8 +188,8 @@ class Pacman(LazyLogging):
         Returns:
             dict[str, set[str]]: map of package name to its list of files
         """
-        def extract(tar: tarfile.TarFile, package_names: dict[str, str]) -> Generator[tuple[str, set[str]], None, None]:
-            for package_name, version in package_names.items():
+        def extract(tar: tarfile.TarFile, versions: dict[str, str]) -> Generator[tuple[str, set[str]], None, None]:
+            for package_name, version in versions.items():
                 path = Path(f"{package_name}-{version}") / "files"
                 try:
                     content = tar.extractfile(str(path))

src/ahriman/core/alpm/pacman_database.py

@@ -59,7 +59,8 @@ class PacmanDatabase(SyncHttpClient):
 
         self.sync_files_database = configuration.getboolean("alpm", "sync_files_database")
 
-    def copy(self, remote_path: Path, local_path: Path) -> None:
+    @staticmethod
+    def copy(remote_path: Path, local_path: Path) -> None:
         """
         copy local database file
 

src/ahriman/core/auth/auth.py

@@ -81,15 +81,18 @@ class Auth(LazyLogging):
             case AuthSettings.OAuth:
                 from ahriman.core.auth.oauth import OAuth
                 return OAuth(configuration, database)
+            case AuthSettings.PAM:
+                from ahriman.core.auth.pam import PAM
+                return PAM(configuration, database)
             case _:
                 return Auth(configuration)
 
-    async def check_credentials(self, username: str | None, password: str | None) -> bool:
+    async def check_credentials(self, username: str, password: str | None) -> bool:
         """
         validate user password
 
         Args:
-            username(str | None): username
+            username(str): username
             password(str | None): entered password
 
         Returns:
@@ -98,12 +101,12 @@ class Auth(LazyLogging):
         del username, password
         return True
 
-    async def known_username(self, username: str | None) -> bool:
+    async def known_username(self, username: str) -> bool:
         """
         check if user is known
 
         Args:
-            username(str | None): username
+            username(str): username
 
         Returns:
             bool: True in case if user is known and can be authorized and False otherwise

src/ahriman/core/auth/mapping.py

@@ -48,18 +48,18 @@ class Mapping(Auth):
         self.database = database
         self.salt = configuration.get("auth", "salt", fallback="")
 
-    async def check_credentials(self, username: str | None, password: str | None) -> bool:
+    async def check_credentials(self, username: str, password: str | None) -> bool:
         """
         validate user password
 
         Args:
-            username(str | None): username
+            username(str): username
             password(str | None): entered password
 
         Returns:
             bool: True in case if password matches, False otherwise
         """
-        if username is None or password is None:
+        if password is None:
             return False  # invalid data supplied
         user = self.get_user(username)
         return user is not None and user.check_credentials(password, self.salt)
@@ -76,12 +76,12 @@ class Mapping(Auth):
         """
         return self.database.user_get(username)
 
-    async def known_username(self, username: str | None) -> bool:
+    async def known_username(self, username: str) -> bool:
         """
         check if user is known
 
         Args:
-            username(str | None): username
+            username(str): username
 
         Returns:
             bool: True in case if user is known and can be authorized and False otherwise

src/ahriman/core/auth/pam.py

@@ -0,0 +1,131 @@
+#
+# Copyright (c) 2021-2024 ahriman team.
+#
+# This file is part of ahriman
+# (see https://github.com/arcan1s/ahriman).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+from grp import getgrnam
+from pwd import getpwnam
+
+from ahriman.core.auth.mapping import Mapping
+from ahriman.core.configuration import Configuration
+from ahriman.core.database import SQLite
+from ahriman.core.exceptions import CalledProcessError
+from ahriman.core.utils import check_output
+from ahriman.models.auth_settings import AuthSettings
+from ahriman.models.user_access import UserAccess
+
+
+class PAM(Mapping):
+    """
+    User authorization implementation by using default PAM
+
+    Attributes:
+        full_access_group(str): group name users of which have full access
+        permit_root_login(bool): permit login as root
+    """
+
+    def __init__(self, configuration: Configuration, database: SQLite,
+                 provider: AuthSettings = AuthSettings.PAM) -> None:
+        """
+        default constructor
+
+        Args:
+            configuration(Configuration): configuration instance
+            database(SQLite): database instance
+            provider(AuthSettings, optional): authorization type definition (Default value = AuthSettings.PAM)
+        """
+        Mapping.__init__(self, configuration, database, provider)
+        self.full_access_group = configuration.get("auth", "full_access_group")
+        self.permit_root_login = configuration.getboolean("auth", "permit_root_login", fallback=False)
+
+    @staticmethod
+    def group_members(group_name: str) -> list[str]:
+        """
+        extract current group members
+
+        Args:
+            group_name(str): group name
+
+        Returns:
+            list[str]: list of users which belong to the specified group. In case if group wasn't found, the empty list
+            will be returned
+        """
+        try:
+            group = getgrnam(group_name)
+        except KeyError:
+            return []
+        return group.gr_mem
+
+    async def check_credentials(self, username: str, password: str | None) -> bool:
+        """
+        validate user password
+
+        Args:
+            username(str): username
+            password(str | None): entered password
+
+        Returns:
+            bool: True in case if password matches, False otherwise
+        """
+        if password is None:
+            return False  # invalid data supplied
+        if not self.permit_root_login and username == "root":
+            return False  # login as root is not allowed
+        # the reason why do we call su here is that python-pam actually read shadow file
+        # and hence requires root privileges
+        try:
+            check_output("su", "--command", "true", "-", username, input_data=password)
+            return True
+        except CalledProcessError:
+            return await Mapping.check_credentials(self, username, password)
+
+    async def known_username(self, username: str) -> bool:
+        """
+        check if user is known
+
+        Args:
+            username(str): username
+
+        Returns:
+            bool: True in case if user is known and can be authorized and False otherwise
+        """
+        try:
+            _ = getpwnam(username)
+            return True
+        except KeyError:
+            return await Mapping.known_username(self, username)
+
+    async def verify_access(self, username: str, required: UserAccess, context: str | None) -> bool:
+        """
+        validate if user has access to requested resource
+
+        Args:
+            username(str): username
+            required(UserAccess): required access level
+            context(str | None): URI request path
+
+        Returns:
+            bool: True in case if user is allowed to do this request and False otherwise
+        """
+        # this method is basically inverted, first we check overrides in database and then fallback to the PAM logic
+        if (user := self.get_user(username)) is not None:
+            return user.verify_access(required)
+        # if username is in admin group, then we treat it as full access
+        if username in self.group_members(self.full_access_group):
+            return UserAccess.Full.permits(required)
+        # fallback to read-only accounts
+        return UserAccess.Read.permits(required)

src/ahriman/core/build_tools/sources.py

@@ -19,6 +19,7 @@
 #
 import shutil
 
+from collections.abc import Generator
 from pathlib import Path
 
 from ahriman.core.exceptions import CalledProcessError
@@ -38,10 +39,14 @@ class Sources(LazyLogging):
         DEFAULT_BRANCH(str): (class attribute) default branch to process git repositories.
             Must be used only for local stored repositories, use RemoteSource descriptor instead for real packages
         DEFAULT_COMMIT_AUTHOR(tuple[str, str]): (class attribute) default commit author to be used if none set
+        GITCONFIG(dict[str, str]): (class attribute) git config options to suppress annoying hints
     """
 
     DEFAULT_BRANCH = "master"  # default fallback branch
     DEFAULT_COMMIT_AUTHOR = ("ahriman", "ahriman@localhost")
+    GITCONFIG = {
+        "init.defaultBranch": DEFAULT_BRANCH,
+    }
 
     @staticmethod
     def changes(source_dir: Path, last_commit_sha: str | None) -> str | None:
@@ -106,15 +111,15 @@ class Sources(LazyLogging):
             instance.fetch_until(sources_dir, branch=branch)
         elif remote.git_url is not None:
             instance.logger.info("clone remote %s to %s using branch %s", remote.git_url, sources_dir, branch)
-            check_output("git", "clone", "--quiet", "--depth", "1", "--branch", branch, "--single-branch",
+            check_output(*instance.git(), "clone", "--quiet", "--depth", "1", "--branch", branch, "--single-branch",
                          remote.git_url, str(sources_dir), cwd=sources_dir.parent, logger=instance.logger)
         else:
             # it will cause an exception later
             instance.logger.error("%s is not initialized, but no remote provided", sources_dir)
 
         # and now force reset to our branch
-        check_output("git", "checkout", "--force", branch, cwd=sources_dir, logger=instance.logger)
-        check_output("git", "reset", "--quiet", "--hard", f"origin/{branch}",
+        check_output(*instance.git(), "checkout", "--force", branch, cwd=sources_dir, logger=instance.logger)
+        check_output(*instance.git(), "reset", "--quiet", "--hard", f"origin/{branch}",
                      cwd=sources_dir, logger=instance.logger)
 
         # move content if required
@@ -136,7 +141,7 @@ class Sources(LazyLogging):
             bool: True in case if there is any remote and false otherwise
         """
         instance = Sources()
-        remotes = check_output("git", "remote", cwd=sources_dir, logger=instance.logger)
+        remotes = check_output(*instance.git(), "remote", cwd=sources_dir, logger=instance.logger)
         return bool(remotes)
 
     @staticmethod
@@ -150,7 +155,7 @@ class Sources(LazyLogging):
         instance = Sources()
         if not (sources_dir / ".git").is_dir():
             # skip initializing in case if it was already
-            check_output("git", "init", "--quiet", "--initial-branch", instance.DEFAULT_BRANCH,
+            check_output(*instance.git(), "init", "--quiet", "--initial-branch", instance.DEFAULT_BRANCH,
                          cwd=sources_dir, logger=instance.logger)
 
         # extract local files...
@@ -220,7 +225,7 @@ class Sources(LazyLogging):
             return  # no changes to push, just skip action
 
         git_url, branch = remote.git_source()
-        check_output("git", "push", "--quiet", git_url, branch, cwd=sources_dir, logger=instance.logger)
+        check_output(*instance.git(), "push", "--quiet", git_url, branch, cwd=sources_dir, logger=instance.logger)
 
     def add(self, sources_dir: Path, *pattern: str, intent_to_add: bool = False) -> None:
         """
@@ -241,7 +246,7 @@ class Sources(LazyLogging):
         self.logger.info("found matching files %s", found_files)
         # add them to index
         args = ["--intent-to-add"] if intent_to_add else []
-        check_output("git", "add", *args, *[str(fn.relative_to(sources_dir)) for fn in found_files],
+        check_output(*self.git(), "add", *args, *[str(fn.relative_to(sources_dir)) for fn in found_files],
                      cwd=sources_dir, logger=self.logger)
 
     def commit(self, sources_dir: Path, message: str | None = None,
@@ -264,15 +269,16 @@ class Sources(LazyLogging):
         if message is None:
             message = f"Autogenerated commit at {utcnow()}"
         args = ["--message", message]
-        environment: dict[str, str] = {}
 
         if commit_author is None:
             commit_author = self.DEFAULT_COMMIT_AUTHOR
         user, email = commit_author
-        environment["GIT_AUTHOR_NAME"] = environment["GIT_COMMITTER_NAME"] = user
-        environment["GIT_AUTHOR_EMAIL"] = environment["GIT_COMMITTER_EMAIL"] = email
+        gitconfig = {
+            "user.email": email,
+            "user.name": user,
+        }
 
-        check_output("git", "commit", "--quiet", *args, cwd=sources_dir, logger=self.logger, environment=environment)
+        check_output(*self.git(gitconfig), "commit", "--quiet", *args, cwd=sources_dir, logger=self.logger)
 
         return True
 
@@ -290,7 +296,7 @@ class Sources(LazyLogging):
         args = []
         if sha is not None:
             args.append(sha)
-        return check_output("git", "diff", *args, cwd=sources_dir, logger=self.logger)
+        return check_output(*self.git(), "diff", *args, cwd=sources_dir, logger=self.logger)
 
     def fetch_until(self, sources_dir: Path, *, branch: str | None = None, commit_sha: str | None = None) -> None:
         """
@@ -306,18 +312,37 @@ class Sources(LazyLogging):
 
         commits_count = 1
         while commit_sha is not None:
-            command = ["git", "fetch", "--quiet", "--depth", str(commits_count)]
+            command = self.git() + ["fetch", "--quiet", "--depth", str(commits_count)]
             if branch is not None:
                 command += ["origin", branch]
             check_output(*command, cwd=sources_dir, logger=self.logger)  # fetch one more level
 
             try:
                 # check if there is an object in current git directory
-                check_output("git", "cat-file", "-e", commit_sha, cwd=sources_dir, logger=self.logger)
+                check_output(*self.git(), "cat-file", "-e", commit_sha, cwd=sources_dir, logger=self.logger)
                 commit_sha = None  # reset search
             except CalledProcessError:
                 commits_count += 1  # increase depth
 
+    def git(self, gitconfig: dict[str, str] | None = None) -> list[str]:
+        """
+        git command prefix
+
+        Args:
+            gitconfig(dict[str, str] | None, optional): additional git config flags if any (Default value = None)
+
+        Returns:
+            list[str]: git command prefix with valid default flags
+        """
+        gitconfig = gitconfig or {}
+
+        def configuration_flags() -> Generator[str, None, None]:
+            for option, value in (self.GITCONFIG | gitconfig).items():
+                yield "-c"
+                yield f"{option}=\"{value}\""
+
+        return ["git"] + list(configuration_flags())
+
     def has_changes(self, sources_dir: Path) -> bool:
         """
         check if there are changes in current git tree
@@ -329,7 +354,7 @@ class Sources(LazyLogging):
             bool: True if there are uncommitted changes and False otherwise
         """
         # there is --exit-code argument to diff, however, there might be other process errors
-        changes = check_output("git", "diff", "--cached", "--name-only", cwd=sources_dir, logger=self.logger)
+        changes = check_output(*self.git(), "diff", "--cached", "--name-only", cwd=sources_dir, logger=self.logger)
         return bool(changes)
 
     def head(self, sources_dir: Path, ref_name: str = "HEAD") -> str:
@@ -344,7 +369,7 @@ class Sources(LazyLogging):
             str: HEAD commit hash
         """
         # we might want to parse git files instead though
-        return check_output("git", "rev-parse", ref_name, cwd=sources_dir, logger=self.logger)
+        return check_output(*self.git(), "rev-parse", ref_name, cwd=sources_dir, logger=self.logger)
 
     def move(self, pkgbuild_dir: Path, sources_dir: Path) -> None:
         """
@@ -372,7 +397,7 @@ class Sources(LazyLogging):
         # create patch
         self.logger.info("apply patch %s from database at %s", patch.key, sources_dir)
         if patch.is_plain_diff:
-            check_output("git", "apply", "--ignore-space-change", "--ignore-whitespace",
+            check_output(*self.git(), "apply", "--ignore-space-change", "--ignore-whitespace",
                          cwd=sources_dir, input_data=patch.serialize(), logger=self.logger)
         else:
             patch.write(sources_dir / "PKGBUILD")

src/ahriman/core/configuration/schema.py

@@ -115,6 +115,7 @@ CONFIGURATION_SCHEMA: ConfigurationSchema = {
                         "oauth_provider",
                         "oauth_scopes",
                     ]},
+                    {"allowed": ["pam"], "dependencies": ["full_access_group"]},
                 ],
             },
             "allow_read_only": {
@@ -135,6 +136,10 @@ CONFIGURATION_SCHEMA: ConfigurationSchema = {
                 "minlength": 32,
                 "maxlength": 64,  # we cannot verify maxlength, because base64 representation might be longer than bytes
             },
+            "full_access_group": {
+                "type": "string",
+                "empty": False,
+            },
             "max_age": {
                 "type": "integer",
                 "coerce": "integer",
@@ -152,6 +157,10 @@ CONFIGURATION_SCHEMA: ConfigurationSchema = {
                 "type": "string",
                 "empty": False,
             },
+            "permit_root_login": {
+                "type": "boolean",
+                "coerce": "boolean",
+            },
             "salt": {
                 "type": "string",
             },
@@ -160,6 +169,14 @@ CONFIGURATION_SCHEMA: ConfigurationSchema = {
     "build": {
         "type": "dict",
         "schema": {
+            "allowed_scan_paths": {
+                "type": "list",
+                "coerce": "list",
+                "schema": {
+                    "type": "path",
+                    "coerce": "absolute_path",
+                },
+            },
             "archbuild_flags": {
                 "type": "list",
                 "coerce": "list",
@@ -168,6 +185,14 @@ CONFIGURATION_SCHEMA: ConfigurationSchema = {
                     "empty": False,
                 },
             },
+            "blacklisted_scan_paths": {
+                "type": "list",
+                "coerce": "list",
+                "schema": {
+                    "type": "path",
+                    "coerce": "absolute_path",
+                },
+            },
             "build_command": {
                 "type": "string",
                 "required": True,

src/ahriman/core/database/sqlite.py

@@ -27,6 +27,7 @@ from ahriman.core.configuration import Configuration
 from ahriman.core.database.migrations import Migrations
 from ahriman.core.database.operations import AuthOperations, BuildOperations, ChangesOperations, \
     DependenciesOperations, LogsOperations, PackageOperations, PatchOperations
+from ahriman.models.repository_id import RepositoryId
 
 
 # pylint: disable=too-many-ancestors
@@ -102,23 +103,26 @@ class SQLite(
             self.with_connection(lambda connection: Migrations.migrate(connection, configuration))
         paths.chown(self.path)
 
-    def package_clear(self, package_base: str) -> None:
+    def package_clear(self, package_base: str, repository_id: RepositoryId | None = None) -> None:
         """
         completely remove package from all tables
 
         Args:
             package_base(str): package base to remove
+            repository_id(RepositoryId, optional): repository unique identifier override (Default value = None)
 
         Examples:
             This method completely removes the package from all tables and must be used, e.g. on package removal::
 
             >>> database.package_clear("ahriman")
         """
-        self.build_queue_clear(package_base)
-        self.patches_remove(package_base, [])
-        self.logs_remove(package_base, None)
-        self.changes_remove(package_base)
-        self.dependencies_remove(package_base)
+        self.build_queue_clear(package_base, repository_id)
+        self.patches_remove(package_base, None)
+        self.logs_remove(package_base, None, repository_id)
+        self.changes_remove(package_base, repository_id)
+        self.dependencies_remove(package_base, repository_id)
+
+        self.package_remove(package_base, repository_id)
 
         # remove local cache too
         self._repository_paths.tree_clear(package_base)

src/ahriman/core/repository/executor.py

@@ -80,7 +80,8 @@ class Executor(PackageInfo, Cleaner):
                     # clear changes and update commit hash
                     self.reporter.package_changes_update(single.base, Changes(last_commit_sha))
                     # update dependencies list
-                    dependencies = PackageArchive(self.paths.build_directory, single, self.pacman).depends_on()
+                    package_archive = PackageArchive(self.paths.build_directory, single, self.pacman, self.scan_paths)
+                    dependencies = package_archive.depends_on()
                     self.reporter.package_dependencies_update(single.base, dependencies)
                     # update result set
                     result.add_updated(single)

src/ahriman/core/repository/repository_properties.py

@@ -29,6 +29,7 @@ from ahriman.models.packagers import Packagers
 from ahriman.models.pacman_synchronization import PacmanSynchronization
 from ahriman.models.repository_id import RepositoryId
 from ahriman.models.repository_paths import RepositoryPaths
+from ahriman.models.scan_paths import ScanPaths
 from ahriman.models.user import User
 from ahriman.models.user_access import UserAccess
 
@@ -46,6 +47,7 @@ class RepositoryProperties(LazyLogging):
         repo(Repo): repo commands wrapper instance
         reporter(Client): build status reporter instance
         repository_id(RepositoryId): repository unique identifier
+        scan_paths(ScanPaths): scan paths for the implicit dependencies
         sign(GPG): GPG wrapper instance
         triggers(TriggerLoader): triggers holder
         vcs_allowed_age(int): maximal age of the VCS packages before they will be checked
@@ -78,6 +80,11 @@ class RepositoryProperties(LazyLogging):
         self.reporter = Client.load(repository_id, configuration, database, report=report)
         self.triggers = TriggerLoader.load(repository_id, configuration)
 
+        self.scan_paths = ScanPaths(
+            allowed_paths=configuration.getpathlist("build", "allowed_scan_paths", fallback=[]),
+            blacklisted_paths=configuration.getpathlist("build", "blacklisted_scan_paths", fallback=[]),
+        )
+
     @property
     def architecture(self) -> str:
         """

src/ahriman/core/status/client.py

@@ -310,7 +310,7 @@ class Client:
     def set_unknown(self, package: Package) -> None:
         """
         set package status to unknown. Unlike other methods, this method also checks if package is known,
-        and - in case if it is - it silently skips updatd
+        and - in case if it is - it silently skips update
 
         Args:
             package(Package): current package properties

src/ahriman/core/status/local_client.py

@@ -184,7 +184,7 @@ class LocalClient(Client):
         Args:
             package_base(str): package base to remove
         """
-        self.database.package_clear(package_base)
+        self.database.package_clear(package_base, self.repository_id)
 
     def package_status_update(self, package_base: str, status: BuildStatusEnum) -> None:
         """

src/ahriman/core/status/watcher.py

@@ -140,7 +140,6 @@ class Watcher(LazyLogging):
         with self._lock:
             self._known.pop(package_base, None)
         self.client.package_remove(package_base)
-        self.package_logs_remove(package_base, None)
 
     def package_status_update(self, package_base: str, status: BuildStatusEnum) -> None:
         """

src/ahriman/models/auth_settings.py

@@ -30,11 +30,13 @@ class AuthSettings(StrEnum):
         Disabled(AuthSettings): (class attribute) authorization is disabled
         Configuration(AuthSettings): (class attribute) configuration based authorization
         OAuth(AuthSettings): (class attribute) OAuth based provider
+        PAM(AuthSettings): (class attribute) PAM based provider
     """
 
     Disabled = "disabled"
     Configuration = "configuration"
     OAuth = "oauth2"
+    PAM = "pam"
 
     @property
     def is_enabled(self) -> bool:
@@ -62,5 +64,7 @@ class AuthSettings(StrEnum):
                 return AuthSettings.Configuration
             case "oauth" | "oauth2":
                 return AuthSettings.OAuth
+            case "pam":
+                return AuthSettings.PAM
             case _:
                 return AuthSettings.Disabled

src/ahriman/models/package_archive.py

@@ -30,6 +30,7 @@ from ahriman.core.utils import walk
 from ahriman.models.dependencies import Dependencies
 from ahriman.models.filesystem_package import FilesystemPackage
 from ahriman.models.package import Package
+from ahriman.models.scan_paths import ScanPaths
 
 
 @dataclass
@@ -39,13 +40,15 @@ class PackageArchive:
 
     Attributes:
         package(Package): package descriptor
-        root(Path): path to root filesystem
         pacman(Pacman): alpm wrapper instance
+        root(Path): path to root filesystem
+        scan_paths(ScanPaths): scan paths holder
     """
 
     root: Path
     package: Package
     pacman: Pacman
+    scan_paths: ScanPaths
 
     @staticmethod
     def dynamic_needed(binary_path: Path) -> list[str]:
@@ -165,6 +168,10 @@ class PackageArchive:
             if any(package.package_name in base_packages for package in packages):
                 continue
 
+            # check path against the black/white listed
+            if not self.scan_paths.is_allowed(path):
+                continue
+
             # remove explicit dependencies
             packages = [package for package in packages if package.is_root_package(packages, include_optional=False)]
             # remove optional dependencies

src/ahriman/models/repository_id.py

@@ -41,9 +41,12 @@ class RepositoryId:
 
         Returns:
             str: unique id for this repository
+
+        Raises:
+            ValueError: if repository identifier is empty
         """
         if self.is_empty:
-            return ""
+            raise ValueError("Repository ID is called on empty repository identifier")
         return f"{self.architecture}-{self.name}"  # basically the same as used for command line
 
     @property

src/ahriman/models/repository_paths.py

@@ -113,7 +113,7 @@ class RepositoryPaths(LazyLogging):
         Returns:
             Path: full patch to devtools chroot directory
         """
-        # for the chroot directory devtools will create own tree, and we don"t have to specify architecture here
+        # for the chroot directory devtools will create own tree, and we don't have to specify architecture here
         return self.root / "chroot" / self.repository_id.name
 
     @property

src/ahriman/models/scan_paths.py

@@ -0,0 +1,58 @@
+#
+# Copyright (c) 2021-2024 ahriman team.
+#
+# This file is part of ahriman
+# (see https://github.com/arcan1s/ahriman).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True, kw_only=True)
+class ScanPaths:
+    """
+    paths used for scan filesystem
+
+    Attributes:
+        allowed_paths(list[Path]): list of whitelisted paths
+        blacklisted_paths(list[Path]): list of paths to be skipped from scan
+    """
+
+    allowed_paths: list[Path]
+    blacklisted_paths: list[Path]
+
+    def __post_init__(self) -> None:
+        """
+        compute relative to / paths
+        """
+        object.__setattr__(self, "allowed_paths", [path.relative_to("/") for path in self.allowed_paths])
+        object.__setattr__(self, "blacklisted_paths", [path.relative_to("/") for path in self.blacklisted_paths])
+
+    def is_allowed(self, path: Path) -> bool:
+        """
+        check whether path is allowed to scan or not
+
+        Args:
+            path(Path): path to be checked
+
+        Returns:
+            bool: ``True`` in case if :attr:`allowed_paths` contains element which is parent for the path and
+            :attr:`blacklisted_paths` doesn't and ``False`` otherwise
+        """
+        if any(path.is_relative_to(blacklisted) for blacklisted in self.blacklisted_paths):
+            return False  # path is blacklisted
+        # check if we actually have to check this path
+        return any(path.is_relative_to(allowed) for allowed in self.allowed_paths)

src/ahriman/models/waiter.py

@@ -67,7 +67,7 @@ class WaiterTaskFinished(WaiterResult):
         indicates whether the waiter completed with success or not
 
         Returns:
-            Literal[True]: always False
+            Literal[True]: always ``True``
         """
         return True
 
@@ -82,7 +82,7 @@ class WaiterTimedOut(WaiterResult):
         indicates whether the waiter completed with success or not
 
         Returns:
-            Literal[False]: always False
+            Literal[False]: always ``False``
         """
         return False
 
@@ -108,7 +108,7 @@ class Waiter:
         check if timer is out
 
         Returns:
-            bool: True in case current monotonic time is more than :attr:`start_time` and :attr:`wait_timeout`
+            bool: ``True`` in case current monotonic time is more than :attr:`start_time` and :attr:`wait_timeout`
             doesn't equal to 0
         """
         since_start = time.monotonic() - self.start_time
@@ -124,7 +124,7 @@ class Waiter:
             **kwargs(Params.kwargs): keyword arguments for check call
 
         Returns:
-            WaiterResult: consumed time in seconds
+            WaiterResult: waiter result object
         """
         while not (timed_out := self.is_timed_out()) and in_progress(*args, **kwargs):
             time.sleep(self.interval)

tests/ahriman/application/test_lock.py

@@ -14,6 +14,7 @@ from ahriman.core.configuration import Configuration
 from ahriman.core.exceptions import DuplicateRunError, UnsafeRunError
 from ahriman.models.build_status import BuildStatus, BuildStatusEnum
 from ahriman.models.internal_status import InternalStatus
+from ahriman.models.repository_id import RepositoryId
 
 
 def test_path(args: argparse.Namespace, configuration: Configuration) -> None:
@@ -30,6 +31,8 @@ def test_path(args: argparse.Namespace, configuration: Configuration) -> None:
     args.lock = Path("ahriman.pid")
     assert Lock(args, repository_id, configuration).path == Path("/run/ahriman/ahriman_x86_64-aur-clone.pid")
 
+    assert Lock(args, RepositoryId("", ""), configuration).path == Path("/run/ahriman/ahriman.pid")
+
     with pytest.raises(ValueError):
         args.lock = Path("/")
         assert Lock(args, repository_id, configuration).path  # special case

tests/ahriman/core/alpm/test_pacman_database.py

@@ -8,12 +8,12 @@ from ahriman.core.alpm.pacman_database import PacmanDatabase
 from ahriman.core.exceptions import PacmanError
 
 
-def test_copy(pacman_database: PacmanDatabase, mocker: MockerFixture) -> None:
+def test_copy(mocker: MockerFixture) -> None:
     """
     must copy loca database file
     """
     copy_mock = mocker.patch("shutil.copy")
-    pacman_database.copy(Path("remote"), Path("local"))
+    PacmanDatabase.copy(Path("remote"), Path("local"))
     copy_mock.assert_called_once_with(Path("remote"), Path("local"))
 
 

tests/ahriman/core/auth/conftest.py

@@ -2,6 +2,7 @@ import pytest
 
 from ahriman.core.auth.mapping import Mapping
 from ahriman.core.auth.oauth import OAuth
+from ahriman.core.auth.pam import PAM
 from ahriman.core.configuration import Configuration
 from ahriman.core.database import SQLite
 
@@ -35,3 +36,19 @@ def oauth(configuration: Configuration, database: SQLite) -> OAuth:
     """
     configuration.set("web", "address", "https://example.com")
     return OAuth(configuration, database)
+
+
+@pytest.fixture
+def pam(configuration: Configuration, database: SQLite) -> PAM:
+    """
+    PAM provider fixture
+
+    Args:
+        configuration(Configuration): configuration fixture
+        database(SQLite): database fixture
+
+    Returns:
+        PAM: PAM service instance
+    """
+    configuration.set_option("auth", "full_access_group", "wheel")
+    return PAM(configuration, database)

tests/ahriman/core/auth/test_auth.py

@@ -1,6 +1,7 @@
 from ahriman.core.auth import Auth
 from ahriman.core.auth.mapping import Mapping
 from ahriman.core.auth.oauth import OAuth
+from ahriman.core.auth.pam import PAM
 from ahriman.core.configuration import Configuration
 from ahriman.core.database import SQLite
 from ahriman.models.user import User
@@ -51,14 +52,22 @@ def test_load_oauth(configuration: Configuration, database: SQLite) -> None:
     assert isinstance(auth, OAuth)
 
 
+def test_load_pam(configuration: Configuration, database: SQLite) -> None:
+    """
+    must load pam validator if option set
+    """
+    configuration.set_option("auth", "target", "pam")
+    configuration.set_option("auth", "full_access_group", "wheel")
+    auth = Auth.load(configuration, database)
+    assert isinstance(auth, PAM)
+
+
 async def test_check_credentials(auth: Auth, user: User) -> None:
     """
     must pass any credentials
     """
     assert await auth.check_credentials(user.username, user.password)
-    assert await auth.check_credentials(None, "")
     assert await auth.check_credentials("", None)
-    assert await auth.check_credentials(None, None)
 
 
 async def test_known_username(auth: Auth, user: User) -> None:

tests/ahriman/core/auth/test_mapping.py

@@ -21,9 +21,7 @@ async def test_check_credentials_empty(mapping: Mapping) -> None:
     """
     must reject on empty credentials
     """
-    assert not await mapping.check_credentials(None, "")
     assert not await mapping.check_credentials("", None)
-    assert not await mapping.check_credentials(None, None)
 
 
 async def test_check_credentials_unknown(mapping: Mapping, user: User) -> None:
@@ -66,9 +64,8 @@ async def test_known_username(mapping: Mapping, user: User, mocker: MockerFixtur
 
 async def test_known_username_unknown(mapping: Mapping, user: User, mocker: MockerFixture) -> None:
     """
-    must not allow only known users
+    must not allow unknown users
     """
-    assert not await mapping.known_username(None)
     mocker.patch("ahriman.core.database.SQLite.user_get", return_value=None)
     assert not await mapping.known_username(user.password)
 

tests/ahriman/core/auth/test_pam.py

@@ -0,0 +1,118 @@
+from pytest_mock import MockerFixture
+
+from ahriman.core.auth.pam import PAM
+from ahriman.core.exceptions import CalledProcessError
+from ahriman.models.user import User
+from ahriman.models.user_access import UserAccess
+
+
+def test_group_members() -> None:
+    """
+    must return current group members
+    """
+    assert "root" in PAM.group_members("root")
+
+
+def test_group_members_unknown() -> None:
+    """
+    must return empty list for unknown group
+    """
+    assert not PAM.group_members("somerandomgroupname")
+
+
+async def test_check_credentials(pam: PAM, user: User, mocker: MockerFixture) -> None:
+    """
+    must correctly check user credentials via PAM
+    """
+    authenticate_mock = mocker.patch("ahriman.core.auth.pam.check_output")
+    mapping_mock = mocker.patch("ahriman.core.auth.mapping.Mapping.check_credentials")
+
+    assert await pam.check_credentials(user.username, user.password)
+    authenticate_mock.assert_called_once_with("su", "--command", "true", "-", user.username,
+                                              input_data=user.password)
+    mapping_mock.assert_not_called()
+
+
+async def test_check_credentials_empty(pam: PAM) -> None:
+    """
+    must reject on empty credentials
+    """
+    assert not await pam.check_credentials("", None)
+
+
+async def test_check_credentials_root(pam: PAM, user: User, mocker: MockerFixture) -> None:
+    """
+    must reject on root logon attempt
+    """
+    mocker.patch("ahriman.core.auth.pam.check_output")
+    assert not await pam.check_credentials("root", user.password)
+
+    pam.permit_root_login = True
+    assert await pam.check_credentials("root", user.password)
+
+
+async def test_check_credentials_mapping(pam: PAM, user: User, mocker: MockerFixture) -> None:
+    """
+    must correctly check user credentials via database if PAM rejected
+    """
+    mocker.patch("ahriman.core.auth.pam.check_output",
+                 side_effect=CalledProcessError(1, ["command"], "error"))
+    mapping_mock = mocker.patch("ahriman.core.auth.mapping.Mapping.check_credentials")
+
+    await pam.check_credentials(user.username, user.password)
+    mapping_mock.assert_called_once_with(pam, user.username, user.password)
+
+
+async def test_known_username(pam: PAM, user: User, mocker: MockerFixture) -> None:
+    """
+    must check if user exists in system
+    """
+    getpwnam_mock = mocker.patch("ahriman.core.auth.pam.getpwnam")
+    mapping_mock = mocker.patch("ahriman.core.auth.mapping.Mapping.known_username")
+
+    assert await pam.known_username(user.username)
+    getpwnam_mock.assert_called_once_with(user.username)
+    mapping_mock.assert_not_called()
+
+
+async def test_known_username_mapping(pam: PAM, user: User, mocker: MockerFixture) -> None:
+    """
+    must fallback to username checking to database if no user found in system
+    """
+    mocker.patch("ahriman.core.auth.pam.getpwnam", side_effect=KeyError)
+    mapping_mock = mocker.patch("ahriman.core.auth.mapping.Mapping.known_username")
+
+    await pam.known_username(user.username)
+    mapping_mock.assert_called_once_with(pam, user.username)
+
+
+async def test_verify_access(pam: PAM, user: User, mocker: MockerFixture) -> None:
+    """
+    must verify user access via PAM groups
+    """
+    mocker.patch("ahriman.core.auth.pam.PAM.get_user", return_value=None)
+    mocker.patch("ahriman.core.auth.pam.PAM.group_members", return_value=[user.username])
+    assert await pam.verify_access(user.username, UserAccess.Full, None)
+
+
+async def test_verify_access_readonly(pam: PAM, user: User, mocker: MockerFixture) -> None:
+    """
+    must set user access to read only if it doesn't belong to the admin group
+    """
+    mocker.patch("ahriman.core.auth.pam.PAM.get_user", return_value=None)
+    mocker.patch("ahriman.core.auth.pam.PAM.group_members", return_value=[])
+
+    assert not await pam.verify_access(user.username, UserAccess.Full, None)
+    assert not await pam.verify_access(user.username, UserAccess.Reporter, None)
+    assert await pam.verify_access(user.username, UserAccess.Read, None)
+
+
+async def test_verify_access_override(pam: PAM, user: User, mocker: MockerFixture) -> None:
+    """
+    must verify user access via database if there is override
+    """
+    mocker.patch("ahriman.core.auth.pam.PAM.get_user", return_value=user)
+    group_mock = mocker.patch("ahriman.core.auth.pam.PAM.group_members")
+
+    assert await pam.verify_access(user.username, user.access, None)
+    group_mock.assert_not_called()

tests/ahriman/core/build_tools/test_sources.py

@@ -74,7 +74,7 @@ def test_fetch_empty(remote_source: RemoteSource, mocker: MockerFixture) -> None
     check_output_mock.assert_not_called()
 
 
-def test_fetch_existing(remote_source: RemoteSource, mocker: MockerFixture) -> None:
+def test_fetch_existing(sources: Sources, remote_source: RemoteSource, mocker: MockerFixture) -> None:
     """
     must fetch new package via fetch command
     """
@@ -86,18 +86,19 @@ def test_fetch_existing(remote_source: RemoteSource, mocker: MockerFixture) -> N
     head_mock = mocker.patch("ahriman.core.build_tools.sources.Sources.head", return_value="sha")
 
     local = Path("local")
-    assert Sources.fetch(local, remote_source) == "sha"
+    assert sources.fetch(local, remote_source) == "sha"
     fetch_mock.assert_called_once_with(local, branch=remote_source.branch)
     check_output_mock.assert_has_calls([
-        MockCall("git", "checkout", "--force", remote_source.branch, cwd=local, logger=pytest.helpers.anyvar(int)),
-        MockCall("git", "reset", "--quiet", "--hard", f"origin/{remote_source.branch}",
+        MockCall(*sources.git(), "checkout", "--force", remote_source.branch,
+                 cwd=local, logger=pytest.helpers.anyvar(int)),
+        MockCall(*sources.git(), "reset", "--quiet", "--hard", f"origin/{remote_source.branch}",
                  cwd=local, logger=pytest.helpers.anyvar(int)),
     ])
     move_mock.assert_called_once_with(local.resolve(), local)
     head_mock.assert_called_once_with(local)
 
 
-def test_fetch_new(remote_source: RemoteSource, mocker: MockerFixture) -> None:
+def test_fetch_new(sources: Sources, remote_source: RemoteSource, mocker: MockerFixture) -> None:
     """
     must fetch new package via clone command
     """
@@ -107,19 +108,21 @@ def test_fetch_new(remote_source: RemoteSource, mocker: MockerFixture) -> None:
     head_mock = mocker.patch("ahriman.core.build_tools.sources.Sources.head", return_value="sha")
 
     local = Path("local")
-    assert Sources.fetch(local, remote_source) == "sha"
+    assert sources.fetch(local, remote_source) == "sha"
     check_output_mock.assert_has_calls([
-        MockCall("git", "clone", "--quiet", "--depth", "1", "--branch", remote_source.branch, "--single-branch",
-                 remote_source.git_url, str(local), cwd=local.parent, logger=pytest.helpers.anyvar(int)),
-        MockCall("git", "checkout", "--force", remote_source.branch, cwd=local, logger=pytest.helpers.anyvar(int)),
-        MockCall("git", "reset", "--quiet", "--hard", f"origin/{remote_source.branch}",
+        MockCall(*sources.git(), "clone", "--quiet", "--depth", "1", "--branch", remote_source.branch,
+                 "--single-branch", remote_source.git_url, str(local),
+                 cwd=local.parent, logger=pytest.helpers.anyvar(int)),
+        MockCall(*sources.git(), "checkout", "--force", remote_source.branch,
+                 cwd=local, logger=pytest.helpers.anyvar(int)),
+        MockCall(*sources.git(), "reset", "--quiet", "--hard", f"origin/{remote_source.branch}",
                  cwd=local, logger=pytest.helpers.anyvar(int))
     ])
     move_mock.assert_called_once_with(local.resolve(), local)
     head_mock.assert_called_once_with(local)
 
 
-def test_fetch_new_without_remote(mocker: MockerFixture) -> None:
+def test_fetch_new_without_remote(sources: Sources, mocker: MockerFixture) -> None:
     """
     must fetch nothing in case if no remote set
     """
@@ -129,10 +132,11 @@ def test_fetch_new_without_remote(mocker: MockerFixture) -> None:
     head_mock = mocker.patch("ahriman.core.build_tools.sources.Sources.head", return_value="sha")
 
     local = Path("local")
-    assert Sources.fetch(local, RemoteSource(source=PackageSource.Archive)) == "sha"
+    assert sources.fetch(local, RemoteSource(source=PackageSource.Archive)) == "sha"
     check_output_mock.assert_has_calls([
-        MockCall("git", "checkout", "--force", Sources.DEFAULT_BRANCH, cwd=local, logger=pytest.helpers.anyvar(int)),
-        MockCall("git", "reset", "--quiet", "--hard", f"origin/{Sources.DEFAULT_BRANCH}",
+        MockCall(*sources.git(), "checkout", "--force", sources.DEFAULT_BRANCH,
+                 cwd=local, logger=pytest.helpers.anyvar(int)),
+        MockCall(*sources.git(), "reset", "--quiet", "--hard", f"origin/{sources.DEFAULT_BRANCH}",
                  cwd=local, logger=pytest.helpers.anyvar(int))
     ])
     move_mock.assert_called_once_with(local.resolve(), local)
@@ -153,15 +157,15 @@ def test_fetch_relative(remote_source: RemoteSource, mocker: MockerFixture) -> N
     head_mock.assert_called_once_with(local)
 
 
-def test_has_remotes(mocker: MockerFixture) -> None:
+def test_has_remotes(sources: Sources, mocker: MockerFixture) -> None:
     """
     must ask for remotes
     """
     check_output_mock = mocker.patch("ahriman.core.build_tools.sources.check_output", return_value="origin")
 
     local = Path("local")
-    assert Sources.has_remotes(local)
-    check_output_mock.assert_called_once_with("git", "remote", cwd=local, logger=pytest.helpers.anyvar(int))
+    assert sources.has_remotes(local)
+    check_output_mock.assert_called_once_with(*sources.git(), "remote", cwd=local, logger=pytest.helpers.anyvar(int))
 
 
 def test_has_remotes_empty(mocker: MockerFixture) -> None:
@@ -172,7 +176,7 @@ def test_has_remotes_empty(mocker: MockerFixture) -> None:
     assert not Sources.has_remotes(Path("local"))
 
 
-def test_init(mocker: MockerFixture) -> None:
+def test_init(sources: Sources, mocker: MockerFixture) -> None:
     """
     must create empty repository at the specified path
     """
@@ -183,9 +187,9 @@ def test_init(mocker: MockerFixture) -> None:
     commit_mock = mocker.patch("ahriman.core.build_tools.sources.Sources.commit")
 
     local = Path("local")
-    Sources.init(local)
-    check_output_mock.assert_called_once_with("git", "init", "--quiet", "--initial-branch", Sources.DEFAULT_BRANCH,
-                                              cwd=local, logger=pytest.helpers.anyvar(int))
+    sources.init(local)
+    check_output_mock.assert_called_once_with(*sources.git(), "init", "--quiet", "--initial-branch",
+                                              sources.DEFAULT_BRANCH, cwd=local, logger=pytest.helpers.anyvar(int))
     add_mock.assert_called_once_with(local, "PKGBUILD", ".SRCINFO", "local")
     commit_mock.assert_called_once_with(local)
 
@@ -267,7 +271,7 @@ def test_patch_create_with_newline(mocker: MockerFixture) -> None:
     assert Sources.patch_create(Path("local"), "glob").endswith("\n")
 
 
-def test_push(package_ahriman: Package, mocker: MockerFixture) -> None:
+def test_push(package_ahriman: Package, sources: Sources, mocker: MockerFixture) -> None:
     """
     must correctly push files to remote repository
     """
@@ -277,11 +281,11 @@ def test_push(package_ahriman: Package, mocker: MockerFixture) -> None:
 
     commit_author = ("commit author", "user@host")
     local = Path("local")
-    Sources.push(local, package_ahriman.remote, "glob", commit_author=commit_author)
+    sources.push(local, package_ahriman.remote, "glob", commit_author=commit_author)
     add_mock.assert_called_once_with(local, "glob")
     commit_mock.assert_called_once_with(local, commit_author=commit_author)
     check_output_mock.assert_called_once_with(
-        "git", "push", "--quiet", package_ahriman.remote.git_url, package_ahriman.remote.branch,
+        *sources.git(), "push", "--quiet", package_ahriman.remote.git_url, package_ahriman.remote.branch,
         cwd=local, logger=pytest.helpers.anyvar(int))
 
 
@@ -308,7 +312,7 @@ def test_add(sources: Sources, mocker: MockerFixture) -> None:
     sources.add(local, "pattern1", "pattern2")
     glob_mock.assert_has_calls([MockCall("pattern1"), MockCall("pattern2")])
     check_output_mock.assert_called_once_with(
-        "git", "add", "1", "2", "1", "2", cwd=local, logger=sources.logger
+        *sources.git(), "add", "1", "2", "1", "2", cwd=local, logger=sources.logger
     )
 
 
@@ -323,7 +327,7 @@ def test_add_intent_to_add(sources: Sources, mocker: MockerFixture) -> None:
     sources.add(local, "pattern1", "pattern2", intent_to_add=True)
     glob_mock.assert_has_calls([MockCall("pattern1"), MockCall("pattern2")])
     check_output_mock.assert_called_once_with(
-        "git", "add", "--intent-to-add", "1", "2", "1", "2", cwd=local, logger=sources.logger
+        *sources.git(), "add", "--intent-to-add", "1", "2", "1", "2", cwd=local, logger=sources.logger
     )
 
 
@@ -350,13 +354,8 @@ def test_commit(sources: Sources, mocker: MockerFixture) -> None:
     user, email = sources.DEFAULT_COMMIT_AUTHOR
     assert sources.commit(local, message=message)
     check_output_mock.assert_called_once_with(
-        "git", "commit", "--quiet", "--message", message,
-        cwd=local, logger=sources.logger, environment={
-            "GIT_AUTHOR_NAME": user,
-            "GIT_AUTHOR_EMAIL": email,
-            "GIT_COMMITTER_NAME": user,
-            "GIT_COMMITTER_EMAIL": email,
-        }
+        *sources.git(), "-c", f"user.email=\"{email}\"", "-c", f"user.name=\"{user}\"",
+        "commit", "--quiet", "--message", message, cwd=local, logger=sources.logger
     )
 
 
@@ -383,13 +382,8 @@ def test_commit_author(sources: Sources, mocker: MockerFixture) -> None:
     user, email = author = ("commit author", "user@host")
     assert sources.commit(Path("local"), message=message, commit_author=author)
     check_output_mock.assert_called_once_with(
-        "git", "commit", "--quiet", "--message", message,
-        cwd=local, logger=sources.logger, environment={
-            "GIT_AUTHOR_NAME": user,
-            "GIT_AUTHOR_EMAIL": email,
-            "GIT_COMMITTER_NAME": user,
-            "GIT_COMMITTER_EMAIL": email,
-        }
+        *sources.git(), "-c", f"user.email=\"{email}\"", "-c", f"user.name=\"{user}\"",
+        "commit", "--quiet", "--message", message, cwd=local, logger=sources.logger
     )
 
 
@@ -404,13 +398,8 @@ def test_commit_autogenerated_message(sources: Sources, mocker: MockerFixture) -
     assert sources.commit(Path("local"))
     user, email = sources.DEFAULT_COMMIT_AUTHOR
     check_output_mock.assert_called_once_with(
-        "git", "commit", "--quiet", "--message", pytest.helpers.anyvar(str, strict=True),
-        cwd=local, logger=sources.logger, environment={
-            "GIT_AUTHOR_NAME": user,
-            "GIT_AUTHOR_EMAIL": email,
-            "GIT_COMMITTER_NAME": user,
-            "GIT_COMMITTER_EMAIL": email,
-        }
+        *sources.git(), "-c", f"user.email=\"{email}\"", "-c", f"user.name=\"{user}\"",
+        "commit", "--quiet", "--message", pytest.helpers.anyvar(str, strict=True), cwd=local, logger=sources.logger
     )
 
 
@@ -422,7 +411,7 @@ def test_diff(sources: Sources, mocker: MockerFixture) -> None:
 
     local = Path("local")
     assert sources.diff(local)
-    check_output_mock.assert_called_once_with("git", "diff", cwd=local, logger=sources.logger)
+    check_output_mock.assert_called_once_with(*sources.git(), "diff", cwd=local, logger=sources.logger)
 
 
 def test_diff_specific(sources: Sources, mocker: MockerFixture) -> None:
@@ -433,7 +422,7 @@ def test_diff_specific(sources: Sources, mocker: MockerFixture) -> None:
 
     local = Path("local")
     assert sources.diff(local, "hash")
-    check_output_mock.assert_called_once_with("git", "diff", "hash", cwd=local, logger=sources.logger)
+    check_output_mock.assert_called_once_with(*sources.git(), "diff", "hash", cwd=local, logger=sources.logger)
 
 
 def test_fetch_until(sources: Sources, mocker: MockerFixture) -> None:
@@ -450,10 +439,12 @@ def test_fetch_until(sources: Sources, mocker: MockerFixture) -> None:
     local = Path("local")
     sources.fetch_until(local, branch="master", commit_sha="sha")
     check_output_mock.assert_has_calls([
-        MockCall("git", "fetch", "--quiet", "--depth", "1", "origin", "master", cwd=local, logger=sources.logger),
-        MockCall("git", "cat-file", "-e", "sha", cwd=local, logger=sources.logger),
-        MockCall("git", "fetch", "--quiet", "--depth", "2", "origin", "master", cwd=local, logger=sources.logger),
-        MockCall("git", "cat-file", "-e", "sha", cwd=local, logger=sources.logger),
+        MockCall(*sources.git(), "fetch", "--quiet", "--depth", "1", "origin", "master",
+                 cwd=local, logger=sources.logger),
+        MockCall(*sources.git(), "cat-file", "-e", "sha", cwd=local, logger=sources.logger),
+        MockCall(*sources.git(), "fetch", "--quiet", "--depth", "2", "origin", "master",
+                 cwd=local, logger=sources.logger),
+        MockCall(*sources.git(), "cat-file", "-e", "sha", cwd=local, logger=sources.logger),
     ])
 
 
@@ -466,8 +457,9 @@ def test_fetch_until_first(sources: Sources, mocker: MockerFixture) -> None:
     local = Path("local")
     sources.fetch_until(local, branch="master")
     check_output_mock.assert_has_calls([
-        MockCall("git", "fetch", "--quiet", "--depth", "1", "origin", "master", cwd=local, logger=sources.logger),
-        MockCall("git", "cat-file", "-e", "HEAD", cwd=local, logger=sources.logger),
+        MockCall(*sources.git(), "fetch", "--quiet", "--depth", "1", "origin", "master",
+                 cwd=local, logger=sources.logger),
+        MockCall(*sources.git(), "cat-file", "-e", "HEAD", cwd=local, logger=sources.logger),
     ])
 
 
@@ -480,11 +472,27 @@ def test_fetch_until_all_branches(sources: Sources, mocker: MockerFixture) -> No
     local = Path("local")
     sources.fetch_until(local)
     check_output_mock.assert_has_calls([
-        MockCall("git", "fetch", "--quiet", "--depth", "1", cwd=local, logger=sources.logger),
-        MockCall("git", "cat-file", "-e", "HEAD", cwd=local, logger=sources.logger),
+        MockCall(*sources.git(), "fetch", "--quiet", "--depth", "1", cwd=local, logger=sources.logger),
+        MockCall(*sources.git(), "cat-file", "-e", "HEAD", cwd=local, logger=sources.logger),
     ])
 
 
+def test_git(sources: Sources) -> None:
+    """
+    must correctly generate git command
+    """
+    assert sources.git() == ["git", "-c", "init.defaultBranch=\"master\""]
+
+
+def test_git_overrides(sources: Sources) -> None:
+    """
+    must correctly generate git command with additional settings
+    """
+    assert sources.git({"user.email": "ahriman@localhost"}) == [
+        "git", "-c", "init.defaultBranch=\"master\"", "-c", "user.email=\"ahriman@localhost\""
+    ]
+
+
 def test_has_changes(sources: Sources, mocker: MockerFixture) -> None:
     """
     must correctly identify if there are changes
@@ -493,12 +501,12 @@ def test_has_changes(sources: Sources, mocker: MockerFixture) -> None:
 
     check_output_mock = mocker.patch("ahriman.core.build_tools.sources.check_output", return_value="M a.txt")
     assert sources.has_changes(local)
-    check_output_mock.assert_called_once_with("git", "diff", "--cached", "--name-only",
+    check_output_mock.assert_called_once_with(*sources.git(), "diff", "--cached", "--name-only",
                                               cwd=local, logger=sources.logger)
 
     check_output_mock = mocker.patch("ahriman.core.build_tools.sources.check_output", return_value="")
     assert not sources.has_changes(local)
-    check_output_mock.assert_called_once_with("git", "diff", "--cached", "--name-only",
+    check_output_mock.assert_called_once_with(*sources.git(), "diff", "--cached", "--name-only",
                                               cwd=local, logger=sources.logger)
 
 
@@ -510,7 +518,7 @@ def test_head(sources: Sources, mocker: MockerFixture) -> None:
     local = Path("local")
 
     assert sources.head(local) == "sha"
-    check_output_mock.assert_called_once_with("git", "rev-parse", "HEAD", cwd=local, logger=sources.logger)
+    check_output_mock.assert_called_once_with(*sources.git(), "rev-parse", "HEAD", cwd=local, logger=sources.logger)
 
 
 def test_head_specific(sources: Sources, mocker: MockerFixture) -> None:
@@ -521,7 +529,7 @@ def test_head_specific(sources: Sources, mocker: MockerFixture) -> None:
     local = Path("local")
 
     assert sources.head(local, "master") == "sha"
-    check_output_mock.assert_called_once_with("git", "rev-parse", "master", cwd=local, logger=sources.logger)
+    check_output_mock.assert_called_once_with(*sources.git(), "rev-parse", "master", cwd=local, logger=sources.logger)
 
 
 def test_move(sources: Sources, mocker: MockerFixture) -> None:
@@ -554,7 +562,7 @@ def test_patch_apply(sources: Sources, mocker: MockerFixture) -> None:
     local = Path("local")
     sources.patch_apply(local, patch)
     check_output_mock.assert_called_once_with(
-        "git", "apply", "--ignore-space-change", "--ignore-whitespace",
+        *sources.git(), "apply", "--ignore-space-change", "--ignore-whitespace",
         cwd=local, input_data=patch.value, logger=sources.logger
     )
 

tests/ahriman/core/database/test_sqlite.py

@@ -4,6 +4,7 @@ from pytest_mock import MockerFixture
 
 from ahriman.core.configuration import Configuration
 from ahriman.core.database import SQLite
+from ahriman.models.repository_id import RepositoryId
 
 
 def test_load(configuration: Configuration, mocker: MockerFixture) -> None:
@@ -35,7 +36,7 @@ def test_init_skip_migration(database: SQLite, configuration: Configuration, moc
     migrate_schema_mock.assert_not_called()
 
 
-def test_package_clear(database: SQLite, mocker: MockerFixture) -> None:
+def test_package_clear(database: SQLite, repository_id: RepositoryId, mocker: MockerFixture) -> None:
     """
     must clear package data
     """
@@ -44,12 +45,14 @@ def test_package_clear(database: SQLite, mocker: MockerFixture) -> None:
     logs_mock = mocker.patch("ahriman.core.database.SQLite.logs_remove")
     changes_mock = mocker.patch("ahriman.core.database.SQLite.changes_remove")
     dependencies_mock = mocker.patch("ahriman.core.database.SQLite.dependencies_remove")
+    package_mock = mocker.patch("ahriman.core.database.SQLite.package_remove")
     tree_clear_mock = mocker.patch("ahriman.models.repository_paths.RepositoryPaths.tree_clear")
 
-    database.package_clear("package")
-    build_queue_mock.assert_called_once_with("package")
-    patches_mock.assert_called_once_with("package", [])
-    logs_mock.assert_called_once_with("package", None)
-    changes_mock.assert_called_once_with("package")
-    dependencies_mock.assert_called_once_with("package")
+    database.package_clear("package", repository_id)
+    build_queue_mock.assert_called_once_with("package", repository_id)
+    patches_mock.assert_called_once_with("package", None)
+    logs_mock.assert_called_once_with("package", None, repository_id)
+    changes_mock.assert_called_once_with("package", repository_id)
+    dependencies_mock.assert_called_once_with("package", repository_id)
+    package_mock.assert_called_once_with("package", repository_id)
     tree_clear_mock.assert_called_once_with("package")

tests/ahriman/core/status/test_local_client.py

@@ -158,7 +158,7 @@ def test_package_remove(local_client: LocalClient, package_ahriman: Package, moc
     """
     package_mock = mocker.patch("ahriman.core.database.SQLite.package_clear")
     local_client.package_remove(package_ahriman.base)
-    package_mock.assert_called_once_with(package_ahriman.base)
+    package_mock.assert_called_once_with(package_ahriman.base, local_client.repository_id)
 
 
 def test_package_status_update(local_client: LocalClient, package_ahriman: Package, mocker: MockerFixture) -> None:

tests/ahriman/core/status/test_watcher.py

@@ -101,13 +101,11 @@ def test_package_remove(watcher: Watcher, package_ahriman: Package, mocker: Mock
     must remove package base
     """
     cache_mock = mocker.patch("ahriman.core.status.local_client.LocalClient.package_remove")
-    logs_mock = mocker.patch("ahriman.core.status.watcher.Watcher.package_logs_remove", create=True)
     watcher._known = {package_ahriman.base: (package_ahriman, BuildStatus())}
 
     watcher.package_remove(package_ahriman.base)
     assert not watcher._known
     cache_mock.assert_called_once_with(package_ahriman.base)
-    logs_mock.assert_called_once_with(package_ahriman.base, None)
 
 
 def test_package_remove_unknown(watcher: Watcher, package_ahriman: Package, mocker: MockerFixture) -> None:

tests/ahriman/models/conftest.py

@@ -7,6 +7,7 @@ from pytest_mock import MockerFixture
 from ahriman import __version__
 from ahriman.core.alpm.pacman import Pacman
 from ahriman.core.alpm.remote import AUR
+from ahriman.core.configuration import Configuration
 from ahriman.models.build_status import BuildStatus, BuildStatusEnum
 from ahriman.models.counters import Counters
 from ahriman.models.filesystem_package import FilesystemPackage
@@ -17,6 +18,7 @@ from ahriman.models.package_description import PackageDescription
 from ahriman.models.package_source import PackageSource
 from ahriman.models.remote_source import RemoteSource
 from ahriman.models.repository_paths import RepositoryPaths
+from ahriman.models.scan_paths import ScanPaths
 
 
 @pytest.fixture
@@ -77,7 +79,7 @@ def internal_status(counters: Counters) -> InternalStatus:
 
 @pytest.fixture
 def package_archive_ahriman(package_ahriman: Package, repository_paths: RepositoryPaths, pacman: Pacman,
-                            passwd: Any, mocker: MockerFixture) -> PackageArchive:
+                            scan_paths: ScanPaths, passwd: Any, mocker: MockerFixture) -> PackageArchive:
     """
     package archive fixture
 
@@ -85,6 +87,7 @@ def package_archive_ahriman(package_ahriman: Package, repository_paths: Reposito
         package_ahriman(Package): package test instance
         repository_paths(RepositoryPaths): repository paths test instance
         pacman(Pacman): pacman test instance
+        scan_paths(ScanPaths): scan paths test instance
         passwd(Any): passwd structure test instance
         mocker(MockerFixture): mocker object
 
@@ -92,7 +95,7 @@ def package_archive_ahriman(package_ahriman: Package, repository_paths: Reposito
         PackageArchive: package archive test instance
     """
     mocker.patch("ahriman.models.repository_paths.getpwuid", return_value=passwd)
-    return PackageArchive(repository_paths.build_directory, package_ahriman, pacman)
+    return PackageArchive(repository_paths.build_directory, package_ahriman, pacman, scan_paths)
 
 
 @pytest.fixture
@@ -158,3 +161,20 @@ def pyalpm_package_description_ahriman(package_description_ahriman: PackageDescr
     type(mock).provides = PropertyMock(return_value=package_description_ahriman.provides)
     type(mock).url = PropertyMock(return_value=package_description_ahriman.url)
     return mock
+
+
+@pytest.fixture
+def scan_paths(configuration: Configuration) -> ScanPaths:
+    """
+    scan paths fixture
+
+    Args:
+        configuration(Configuration): configuration test instance
+
+    Returns:
+        ScanPaths: scan paths test instance
+    """
+    return ScanPaths(
+        allowed_paths=configuration.getpathlist("build", "allowed_scan_paths"),
+        blacklisted_paths=configuration.getpathlist("build", "blacklisted_scan_paths"),
+    )

tests/ahriman/models/test_auth_settings.py

@@ -26,6 +26,9 @@ def test_from_option_valid() -> None:
     assert AuthSettings.from_option("mapping") == AuthSettings.Configuration
     assert AuthSettings.from_option("MAPPing") == AuthSettings.Configuration
 
+    assert AuthSettings.from_option("pam") == AuthSettings.PAM
+    assert AuthSettings.from_option("PAM") == AuthSettings.PAM
+
 
 def test_is_enabled() -> None:
     """

tests/ahriman/models/test_package_archive.py

@@ -134,8 +134,10 @@ def test_refine_dependencies(package_archive_ahriman: PackageArchive, mocker: Mo
 
     path1 = Path("usr") / "lib" / "python3.12"
     path2 = path1 / "site-packages"
-    path3 = Path("etc")
-    path4 = Path("var") / "lib" / "whatever"
+    path3 = Path("usr") / "lib" / "path"
+    path4 = Path("usr") / "lib" / "whatever"
+    path5 = Path("usr") / "share" / "applications"
+    path6 = Path("etc")
 
     package1 = FilesystemPackage(package_name="package1", depends={"package5"}, opt_depends={"package2"})
     package2 = FilesystemPackage(package_name="package2", depends={"package1"}, opt_depends=set())
@@ -149,6 +151,8 @@ def test_refine_dependencies(package_archive_ahriman: PackageArchive, mocker: Mo
         path2: [package1, package2, package3, package5],
         path3: [package1, package4],
         path4: [package1],
+        path5: [package1],
+        path6: [package1],
     }) == {
         path1: [package6],
         path2: [package1, package5],

tests/ahriman/models/test_repository_id.py

@@ -7,10 +7,17 @@ def test_id() -> None:
     """
     must correctly generate id
     """
-    assert RepositoryId("", "").id == ""
     assert RepositoryId("arch", "repo").id == "arch-repo"
 
 
+def test_id_empty() -> None:
+    """
+    must raise exception on empty identifier
+    """
+    with pytest.raises(ValueError):
+        assert RepositoryId("", "").id
+
+
 def test_is_empty() -> None:
     """
     must check if repository id is empty or not

tests/ahriman/models/test_scan_paths.py

@@ -0,0 +1,42 @@
+from pathlib import Path
+
+from ahriman.models.scan_paths import ScanPaths
+
+
+def test_post_init(scan_paths: ScanPaths) -> None:
+    """
+    must convert paths to / relative
+    """
+    assert all(not path.is_absolute() for path in scan_paths.allowed_paths)
+    assert all(not path.is_absolute() for path in scan_paths.blacklisted_paths)
+
+
+def test_is_allowed() -> None:
+    """
+    must check if path is subpath of one in allowed list
+    """
+    assert ScanPaths(allowed_paths=[Path("/") / "usr"], blacklisted_paths=[]).is_allowed(Path("usr"))
+    assert ScanPaths(allowed_paths=[Path("/") / "usr"], blacklisted_paths=[]).is_allowed(Path("usr") / "lib")
+    assert not ScanPaths(allowed_paths=[Path("/") / "usr"], blacklisted_paths=[]).is_allowed(Path("var"))
+
+
+def test_is_blacklisted() -> None:
+    """
+    must check if path is not subpath of one in blacklist
+    """
+    assert ScanPaths(
+        allowed_paths=[Path("/") / "usr"],
+        blacklisted_paths=[Path("/") / "usr" / "lib"],
+    ).is_allowed(Path("usr"))
+    assert ScanPaths(
+        allowed_paths=[Path("/") / "usr", Path("/") / "var"],
+        blacklisted_paths=[Path("/") / "usr" / "lib"],
+    ).is_allowed(Path("var"))
+    assert not ScanPaths(
+        allowed_paths=[Path("/") / "usr"],
+        blacklisted_paths=[Path("/") / "usr" / "lib"],
+    ).is_allowed(Path(" usr") / "lib")
+    assert not ScanPaths(
+        allowed_paths=[Path("/") / "usr"],
+        blacklisted_paths=[Path("/") / "usr" / "lib"],
+    ).is_allowed(Path("usr") / "lib" / "qt")

tests/ahriman/web/views/test_view_base.py

@@ -201,7 +201,7 @@ def test_service_not_found(base: BaseView) -> None:
     must raise HTTPNotFound if no repository found
     """
     with pytest.raises(HTTPNotFound):
-        base.service(RepositoryId("", ""))
+        base.service(RepositoryId("repo", "arch"))
 
 
 def test_service_package(base: BaseView, repository_id: RepositoryId, mocker: MockerFixture) -> None:

tests/testresources/core/ahriman.ini

@@ -20,7 +20,9 @@ salt = salt
 allow_read_only = no
 
 [build]
+allowed_scan_paths = /usr/lib
 archbuild_flags =
+blacklisted_scan_paths = /usr/lib/cmake
 build_command = extra-x86_64-build
 ignore_packages =
 makechrootpkg_flags =

tox.ini

@@ -11,6 +11,7 @@ flags = --implicit-reexport --strict --allow-untyped-decorators --allow-subclass
 
 [pytest]
 addopts = --cov=ahriman --cov-report=term-missing:skip-covered --no-cov-on-fail --cov-fail-under=100 --spec
+asyncio_default_fixture_loop_scope = function
 asyncio_mode = auto
 spec_test_format = {result} {docstring_summary}