.. This file is part of PEPSI. Copyright (C) 2026 GNUnet e.V. PEPSI is free software; you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version. ================ pepsi-reputation ================ *Keep the IP blocklists that inbound mail is checked against, and check whether this host is on one.* Role ==== ``pepsi-reputation`` downloads whole IP blocklists into the database, where :doc:`pepsi-ingress` looks up the client of every unauthenticated session. Each list is a ``[pepsi-reputation-list-NAME]`` section; the ones that Pepsi knows about ship in ``${DATADIR}/config.d/reputation.conf`` (Spamhaus DROP and blocklist.de's mail list enabled, UCEPROTECT level 1 by rsync disabled), all marking rather than rejecting. ``pepsi-reputation-iplists.timer`` runs ``iplists update`` hourly. When started as ``root``, it continues as the ``pepsi`` service account. Reference: :manpage:`pepsi-reputation(1)`. Why download instead of asking ============================== Most MTAs query DNS blocklists per connection. Pepsi does not, for two reasons that follow from its :ref:`principles `: * a query tells the list operator which server is talking to this host, for every connection (principle 4, collect and keep the minimum); * a query makes every session wait on a third party, and its failure must not decide whether mail is accepted (principle 1, external services are consulted without becoming dependencies). A downloaded list has neither problem. The cost is coverage: Spamhaus ZEN, SpamCop and Barracuda are free only as DNS queries. Features ======== * **iplists update** — download each enabled list that is due (``MIN_INTERVAL``, 45 minutes by default, because list operators lock out hosts that download too often), conditionally over HTTPS (``ETag``/``Last-Modified``) or by rsync into ``CACHE_DIR``; when the file changed, replace the list's entries in ``pepsi.ip_blocklist`` in one transaction. ``--force`` ignores the interval and the validators. * **iplists status** — per list: ``current``, ``stale``, ``never-loaded``, ``disabled`` or ``no-rsync``, its entries, its last check and last error. * Formats: rbldnsd ``ip4set``/``ip6trie`` and plain address lists (``FORMAT = ip-list``), Spamhaus DROP's JSON (``FORMAT = spamhaus-drop``). * **check** — ask the DNS blocklists (``CHECK_IP_ZONES``, ``CHECK_DOMAIN_ZONES``) about this host's own sending and MX addresses and domains, daily from ``pepsi-reputation-check.timer``. A list's answers count only if it passes its RFC 5782 test entries for the address family, and a refused query (Spamhaus's ``127.255.255.254`` for a public resolver) is *unchecked*, never clean. Listings are logged, stored for :doc:`pepsi-status`, and reported by :doc:`pepsi-setup` ``check`` beside the large mailbox providers' sender requirements and sign-ups (Gmail Postmaster Tools, whose ``google-site-verification`` record ``pepsi-setup`` publishes from ``GOOGLE_SITE_VERIFICATION``; Microsoft SNDS/JMRP; Yahoo Sender Hub). Pepsi never signs up anywhere itself: that would mean holding credentials for those providers' accounts on the mail server. What ingress does with it ========================= For an unauthenticated session from the network, ingress looks the client address up once, in one query, in every enabled list that was confirmed current within its ``MAX_AGE``, and records ``state.origin.ip_blocklist``: ``{"listed": true|false, "lists": {"NAME": true, …}}``. When no list could be consulted (none loaded yet, all stale, a database error) the key is absent, so a stage cannot mistake "unknown" for "clean". A list with ``ACTION = reject`` makes ingress refuse the session's recipients with ``554 5.7.1``, except ``postmaster``. :doc:`pepsi-stage-if` routes on the mark (``STATE_PATH = origin.ip_blocklist.listed``, or ``origin.ip_blocklist.lists.NAME`` for one list). Security ======== * The lists are trusted to say who is a spam source, and to nothing more: a forged list can make mail from some addresses be marked or, with ``ACTION = reject``, refused. HTTPS downloads verify the server against the system roots; entries wider than a /8 (IPv4) or /16 (IPv6) are dropped, so no list can mark the whole internet; a file that is mostly not entries is refused. * ``pepsi.ip_blocklist`` and ``pepsi.ip_blocklist_source`` are written by the ``pepsi`` role and read by ``pepsi-ingress``; ``pepsi-httpd`` and ``pepsi-telemetry`` have no access. * The self-check asks about this host's own addresses and domains only; ``pepsi.reputation_check`` holds nothing about a correspondent. * rsync is an optional dependency, run with an empty environment and the URL after ``--``; an ``rsync://`` URL must name one file. A host without rsync does not use rsync lists, and :doc:`pepsi-setup` warns about them.