milter

The milter library provides Rust bindings to libmilter, the sendmail mail filter API.

This library serves the creation of milters: mail filtering applications that can be integrated with MTAs (mail servers) such as Postfix.

Requirements

This crate requires the milter C library (libmilter) to be available.

☞ On Debian and Ubuntu, install the package libmilter-dev.

If your distribution does not provide pkg-config metadata for libmilter, try using the provided milter.pc file when executing the build:

PKG_CONFIG_PATH=. cargo build

The integration tests of this crate require the third-party miltertest utility in order to exercise the test milters. This program can be found among the OpenDKIM command-line tools.

☞ On Debian and Ubuntu, install either the miltertest or the opendkim-tools package (only required when working on the milter crate itself).

The minimum supported Rust version is 1.42.0.

Usage

The main use case of this library is creating milter applications, that is, executable programs with a main function.

Include libc in addition to milter in Cargo.toml:

[dependencies]
milter = "0.2"
libc = "0.2"

Here’s a simple but complete milter application that logs client IP addresses:

use milter::{on_connect, Context, Milter, Status};
use std::net::SocketAddr;

fn main() {
    Milter::new("unix:/run/ipmilter.sock")
        .name("IPMilter")
        .on_connect(connect_callback)
        .run()
        .expect("milter execution failed");
}

#[on_connect(connect_callback)]
fn handle_connect(
    _: Context<()>,
    _: &str,
    socket_addr: Option<SocketAddr>,
) -> Status {
    if let Some(socket_addr) = socket_addr {
        println!("connect from {}", socket_addr.ip());
    }

    Status::Continue
}

Refer to the API documentation for complete usage instructions.

Examples

This package includes an example milter inspect, which prints all arguments and macros for each stage, and so is immediately useful as a view into how milters operate, and what shape the received data has.

Start the inspect example by passing a socket spec with an unused port (again, if your distribution does not provide the requisite pkg-config metadata, you may need to adjust PKG_CONFIG_PATH, see above):

cargo run --example inspect inet:3000@localhost

After the milter has started, configure the MTA – Postfix – to connect to it. Add the following parameters to /etc/postfix/main.cf, and reload the Postfix configuration:

smtpd_milters = inet:localhost:3000
non_smtpd_milters = $smtpd_milters

The inspect milter will then print everything it receives from Postfix.

Licence

Copyright © 2019–2021 David Bürgin

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.