SPF evaluates the connecting IP against the envelope MAIL FROM or HELO domain; it does not authenticate the visible From header. This lesson treats SPF policy delegation as one decision point in a longer message path. The configuration is useful only when an operator can show which message entered it, which identity and rule matched, what the next daemon returned, and how a failure is retried or contained.
Prerequisites and inherited lab checkpoint
Lesson 11 must preserve Authentication-Results ownership and a working milter path.
For the SPF policy delegation lab, use reserved domain example.test, documentation addresses and disposable messages. Preserve postconf -n, postconf -M, package versions, DNS answers and a queue baseline before changing the lab. Keep console access and do not copy credentials, private keys or customer messages into the evidence record.
Install and prepare the required components
sudo dnf info pypolicyd-spf
sudo dnf install -y pypolicyd-spf
sudo cp -a /etc/python-policyd-spf/policyd-spf.conf /etc/python-policyd-spf/policyd-spf.conf.before-nitwings
rpm -q pypolicyd-spf
Confirm package availability and ownership in the enabled RHEL repositories before adding a third-party source. Record the repository, signing key fingerprint, version and support lifecycle.
A package install creates files and service identities; it does not establish safe relay, authentication, delivery or filtering behavior.
Back up only the files this lesson changes and record modes, owners and SELinux labels so rollback restores more than text.
Use systemctl cat, package file lists and local manual pages to identify paths on the installed build instead of assuming a path from another distribution.
Build the SPF policy delegation configuration and understand every boundary
The following lab configuration keeps ownership and failure behavior visible. Replace reserved identities only after the matching DNS, database, socket or filesystem object has been created.
Validate the effective configuration before reload, trace one accepted message and one rejected message, and retain the queue ID. A syntactically valid file can still express the wrong trust boundary.
Run the syntax or lookup test before reload. A reload must never be the first parser of a production configuration.
The positive test proves the intended path. The negative test proves an unauthorized sender, recipient or client is not accidentally accepted.
Stop the named dependency in the disposable lab and verify temporary failure or controlled bypass matches the documented policy.
Repeat the accepted path after restart and reboot, then compare effective configuration rather than only source files.
Production decisions before continuing
Decision
Choose deliberately
Evidence to retain
Failure policy
DNS timeout or policy-service failure must defer or follow a deliberately reviewed policy; it must not permanently reject from missing evidence.
SMTP transcript, queue state and dependency alert
Trust boundary
Trust only the explicitly named local daemon, authenticated identity, internal host or validated result required at this stage. Never infer trust merely because traffic originates on localhost.
Matching client, sender, recipient or daemon identity
Secrets and data
Restrict credentials, message samples and keys to the minimum service identity.
Owner, mode, label and secret rotation record
Activation
Validate, reload, run positive and negative tests, then watch one complete message.
Syntax output, queue ID and linked log events
Rollback
Restore the exact files and map/database state changed by this lesson.
Rollback command and repeated acceptance result
Place SPF policy delegation in the message path
SPF evaluates the connecting IP against the envelope MAIL FROM or HELO domain; it does not authenticate the visible From header. The policy service receives client IP, HELO and envelope sender at the SMTP restriction stage and returns a bounded action.
Understand the component before configuring it
Layer
Question to answer
Evidence
Input
Connection, envelope, content or stored-message evidence entering this stage
SMTP transcript, lookup input or message header
Decision
The policy service receives client IP, HELO and envelope sender at the SMTP restriction stage and returns a bounded action.
Effective configuration and exact matched rule
Output
An explicit accept, reject, defer, annotate, route or delivery result
Queue state, delivery status or downstream response
Dependency
The named daemon, lookup, socket, DNS record and storage required for the decision
Socket, timeout, journal and controlled outage test
Recovery
Can processing resume without duplicate, loss or unauthorized delivery?
Retained queue ID, backup and repeated acceptance
Build it step by step
Draw the path. Mark the connection, envelope, content and authenticated identities available at this stage.
Inventory the effective state. Capture package version, active service, sockets, Postfix parameters, master services and lookup results.
Prepare one coherent configuration. Substitute documented lab values and verify ownership, mode and SELinux context.
Validate before activation. Run component syntax checks, map queries and a non-delivering test where supported.
Exercise three outcomes. Send an intended message, an intended denial and a message while the named dependency is unavailable.
Trace one queue ID. Join ingress, policy, filtering, routing and final delivery events without relying on subject text.
Close the change. Restart or reboot where relevant, repeat tests, check queue age and document rollback.
Replace sample hostnames, addresses and queue IDs only after resolving them from the lab. Do not paste production identities into a public command transcript.
postconf -n shows non-default global parameters; postconf -M and postconf -P expose master service and field overrides.
A successful lookup proves only that input. Test present, absent, disabled and dependency-unavailable results separately.
Use the queue ID as the correlation key. Message subjects and recipient addresses are not unique and may contain sensitive information.
Evidence and acceptance criteria
Evidence
Healthy result
Failure meaning
Syntax
All component validators succeed before activation
The running service would parse an unreviewed or invalid state
Positive path
A reserved valid message follows the intended path and produces the expected evidence.
The intended message cannot complete this decision point
Negative path
A deliberately invalid identity, recipient or content sample is denied or classified at the designed stage.
The configuration may relay, authenticate, route or deliver too broadly
Dependency failure
Stopping the dependency produces the documented temporary failure or reviewed bypass and raises an observable signal.
Messages may be lost, permanently rejected or silently bypass controls
Persistence
Effective state and tests agree after restart and reboot
Only transient state was changed
Worked incident: SPF policy delegation behaves differently from the design
A forwarder changes the connecting IP but keeps the original envelope domain. A strict receiver rejects SPF even though DKIM survives. The operator records SPF as one authentication input and lets DMARC alignment evaluate surviving aligned identifiers.
Troubleshooting by symptom
Symptom
Inspect first
Defensible next action
Service active but no decision
Socket, effective configuration and queue-linked logs
Find the first layer where the message bypasses the component
Every message fails
Syntax, permissions, label, dependency and timeout
Restore the last valid state and retest one fixture
Invalid sample passes
Rule order, trusted-source exception and actual input identity
Correct the narrow matching rule and rerun negative tests
Intermittent deferral
Dependency latency, process limits, queue age and resource pressure
Fix capacity or failure policy without discarding queued mail
Unsafe operations and recovery boundaries
Unsafe: changing several mail-flow stages in one reload makes causality and rollback ambiguous.
Unsafe: logging full credentials, private keys or customer messages expands the incident boundary.
Unsafe: deleting or requeueing the whole queue to hide a failure destroys mail or creates duplicates.
Rewritten knowledge checks
What is the input to this decision?
Identify the exact connection, envelope, content, DNS or stored-message field named in the lesson.
What proves the component ran?
A queue-linked log, header, lookup result or delivery status produced by that component.
What should dependency outage do?
DNS timeout or policy-service failure must defer or follow a deliberately reviewed policy; it must not permanently reject from missing evidence.
Why run a negative test?
It proves trust or matching has not become broader than the intended path.
What completes the change?
Persistence, monitoring, rollback and one end-to-end message after restart.
What must be captured before this change?
The effective configuration, package versions, owned sockets, a UTC test result and the exact files or database rows that rollback will restore.
Why is a service restart not an acceptance test?
A running process does not prove the intended message path, denial path, dependency failure behavior or persistence.
What makes a placeholder safe to replace?
Its source, format, owner and scope are explained and the substituted value is verified before activation.
When should rollout stop?
Stop when identity is ambiguous, syntax fails, the negative test becomes permissive, a dependency failure produces permanent loss or rollback cannot be executed.
What evidence belongs in handover?
The reviewed configuration, syntax output, positive and negative transcripts, logs, monitoring threshold, backup location and tested rollback result.
Cumulative lab checkpoint
Capture the inherited checkpoint and state the exact sender, recipient, client address and expected SMTP result.
Install the required package from a recorded source and save the package/file/service inventory.
Apply the complete lab configuration, including permissions, socket paths, map generation and service ownership.
Run syntax and lookup validation, then activate without closing the recovery session.
Complete positive, negative and dependency-outage tests while retaining queue IDs and UTC logs.
Restart the participating services, repeat the accepted path and confirm no unexplained deferred mail remains.
Execute rollback once, prove the previous behavior, then reapply the reviewed state as the checkpoint for the next lesson.
