From 11d1791c0696559da01fb75f1cff61649a88be37 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20B=C3=BCrgin?= Date: Sun, 23 Feb 2020 07:57:49 +0100 Subject: [PATCH] Wording --- CHANGELOG.md | 4 +- README.md | 39 ++++++++++--------- spamassassin-milter.8 | 8 ++-- src/lib.rs | 4 +- tests/common/mod.rs | 8 ++-- tests/{ham_flow.lua => ham_message.lua} | 0 tests/{ham_flow.rs => ham_message.rs} | 2 +- tests/live.lua | 3 ++ ...p_large_message.lua => skip_oversized.lua} | 0 ...kip_large_message.rs => skip_oversized.rs} | 2 +- tests/{spam_flow.lua => spam_message.lua} | 0 tests/{spam_flow.rs => spam_message.rs} | 2 +- 12 files changed, 37 insertions(+), 35 deletions(-) rename tests/{ham_flow.lua => ham_message.lua} (100%) rename tests/{ham_flow.rs => ham_message.rs} (98%) rename tests/{skip_large_message.lua => skip_oversized.lua} (100%) rename tests/{skip_large_message.rs => skip_oversized.rs} (96%) rename tests/{spam_flow.lua => spam_message.lua} (100%) rename tests/{spam_flow.rs => spam_message.rs} (98%) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9c2a8e1..809bfa6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,7 +1,5 @@ # SpamAssassin Milter changelog -**UNRELEASED** - -## 0.1.0 (2020-??-??) +## 0.1.0 (2020-02-23) Initial release. diff --git a/README.md b/README.md index 7675fa7..4f01ca5 100644 --- a/README.md +++ b/README.md @@ -45,7 +45,7 @@ As a milter, this package requires the libmilter C library to be available. Be sure to install the libmilter shared library and header files. If your distribution does not install a pkg-config metadata file for libmilter, -you can use the provided `milter.pc` file. Put it on the pkg-config path as +try using the provided `milter.pc` file. Put it on the pkg-config path as follows: ``` @@ -67,7 +67,7 @@ Once installed, SpamAssassin Milter can be by invoked as `spamassassin-milter`. `spamassassin-milter` takes one mandatory argument, namely the listening socket of the milter (the socket to which the MTA will connect). The socket spec can be in one of the formats inet:port@host or -inet6:port@host (IPv6), or +inet6:port@host (for IPv6), or unix:path, for a TCP or UNIX domain socket, respectively. For example, the following invocation starts SpamAssassin Milter on port 3000: @@ -93,14 +93,14 @@ service. ## Configuration SpamAssassin Milter is designed as a light-weight ‘glue’ application with just a -few configuration options; this is intentional, as the SpamAssassin components +few configuration switches; this is intentional, as the SpamAssassin components are themselves already highly configurable. SpamAssassin Milter is configured by setting command-line options. All options -have reasonable defaults that work well with a stock installation of -SpamAssassin server (`spamd`) and client (`spamc`). You can get started with -just picking a socket and things should just work. Some integration options are -discussed in subsequent sections. +use sensible defaults that work well with a stock installation of SpamAssassin +server (`spamd`) and client (`spamc`). You can get started with just picking a +socket and things should just work. Some integration options are discussed in +subsequent sections. New users may wish to run SpamAssassin Milter with the `--dry-run` option before going live. Combined with `--verbose`, this gives accurate insight into the @@ -114,8 +114,8 @@ spamassassin-milter --dry-run --verbose inet:3000@localhost SpamAssassin Milter must be integrated with two SpamAssassin components: the SpamAssassin server itself, called `spamd`, which does the actual work, and the -SpamAssassin client `spamc`, which serves as an intermediary between the milter -and the server. +SpamAssassin client `spamc`, which serves as the communication channel between +the milter and the server. ### SpamAssassin configuration @@ -147,9 +147,9 @@ report_safe 0 In addition, body rewriting can also be suppressed on the SpamAssassin Milter side with the `--preserve-body` option. -SpamAssassin may also rewrite the Subject and other headers, for example, adding -a prefix ‘\*\*\*Spam\*\*\*’. This is not done by default, but may be enabled -with a setting like the following: +SpamAssassin may also rewrite the Subject and other headers, for example, by +adding a prefix ‘\*\*\*Spam\*\*\*’. This is not done by default, but may be +enabled with a setting like the following: ``` rewrite_header Subject ***SPAM*** @@ -160,8 +160,8 @@ suppressed on the SpamAssassin Milter side with the `--preserve-headers` option. ### `spamc` configuration -`spamc` can be configured by passing it command-line options, or preferably, by -setting the command-line options in the configuration file +The client program `spamc` can be configured by passing it command-line options, +or preferably, by setting the command-line options in the configuration file `/etc/spamassassin/spamc.conf`. By default, `spamc` will try to reach SpamAssassin server on the dedicated port @@ -175,7 +175,8 @@ instead, set the `--port` or `--socket` option as appropriate in `spamc.conf`: --socket=/run/spamassassin/spamd.sock ``` -When reports are disabled, it is recommended to use the `--headers` option. +When SpamAssassin reports are disabled, it is recommended to use the `--headers` +option: ``` --headers @@ -183,14 +184,14 @@ When reports are disabled, it is recommended to use the `--headers` option. This option is just a shortcut that causes `spamd` not to transmit the message body back to `spamc`. (This option obviously only makes sense and should only be -used when SpamAssassin reports are disabled.) +used when reports are disabled.) Finally, a pitfall of `spamc` deserves highlighting: `spamc` by default tries to resist failure to an extent that it will not indicate failure even if it cannot connect to SpamAssassin server at all (apart from warnings logged to syslog)! If it cannot connect to the server, it simply echoes what it received, and so masks the error condition. This behaviour is labelled ‘safe fallback’ and is perhaps -best disabled once the system is set up. Set the following option: +best disabled once the system is set up. Disable safe fallback as follows: ``` --no-safe-fallback @@ -223,8 +224,8 @@ the `X-Spam-` SpamAssassin headers of the incoming message, and take action based on those. As an example, in case [Dovecot] does mail delivery using [LMTP], enable the -Sieve plugin for the LMTP protocol, then set up a global Sieve script that files -messages flagged as spam into the ‘Junk’ folder: +Sieve plugin for the LMTP protocol, and then set up a global Sieve script that +files messages flagged as spam into the ‘Junk’ folder: ``` require "fileinto"; diff --git a/spamassassin-milter.8 b/spamassassin-milter.8 index fa7ea1e..a9bcba7 100644 --- a/spamassassin-milter.8 +++ b/spamassassin-milter.8 @@ -47,7 +47,7 @@ are gathered as arguments to pass to the .B spamc invocation. .B spamassassin-milter -uses reasonable defaults and if run with no options, will apply modifications +uses sensible defaults and if run with no options, will apply modifications received from SpamAssassin server. .PP .B spamassassin-milter @@ -132,7 +132,7 @@ is, printed to standard error). .BR \-V ", " \-\-version Print version information. .SH SEE ALSO +.BR spamassassin (1), .BR spamc (1), -.BR spamassassin (1p), -.BR Mail::SpamAssassin::Conf (3pm), -.BR spamd (8p) +.BR Mail::SpamAssassin::Conf (3), +.BR spamd (8) diff --git a/src/lib.rs b/src/lib.rs index 446b233..3cebadb 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -25,7 +25,7 @@ mod error; use crate::callbacks::*; pub use crate::config::{Config, ConfigBuilder}; -use milter::Milter; +use milter::{Milter, Result}; /// The name of the SpamAssassin Milter application. pub const MILTER_NAME: &str = "SpamAssassin Milter"; @@ -57,7 +57,7 @@ pub const VERSION: &str = "0.0.3"; /// process::exit(1); /// } /// ``` -pub fn run(socket: &str, config: Config) -> milter::Result<()> { +pub fn run(socket: &str, config: Config) -> Result<()> { milter::set_debug_level(config.milter_debug_level()); config::init(config); diff --git a/tests/common/mod.rs b/tests/common/mod.rs index 38d7faa..f2b839a 100644 --- a/tests/common/mod.rs +++ b/tests/common/mod.rs @@ -12,7 +12,7 @@ pub const SPAMD_PORT: u16 = 3783; // mock port pub type HamOrSpam = Result; -/// A mock `spamd` server that echoes what it is sent after applying +/// Spawns a mock `spamd` server that echoes what it is sent after applying /// transformation `f` to the message content and mock-classifying it as ham or /// spam. pub fn spawn_mock_spamd_server(port: u16, f: F) -> JoinHandle<()> @@ -91,7 +91,7 @@ where } } -const MILTERTEST: &str = "miltertest"; +const MILTERTEST_PROGRAM: &str = "miltertest"; pub fn spawn_miltertest_runner(test_file_name: &str) -> JoinHandle { // This thread is just for safety, in case the miltertest runner thread @@ -107,10 +107,10 @@ pub fn spawn_miltertest_runner(test_file_name: &str) -> JoinHandle { let file_name = to_miltertest_file_name(test_file_name); thread::spawn(move || { - // Wait just a little to give the milter time to start up. + // Wait just a little while to give the milter time to start up. thread::sleep(Duration::from_millis(100)); - let output = Command::new(MILTERTEST) + let output = Command::new(MILTERTEST_PROGRAM) .arg("-s") .arg(&file_name) .output() diff --git a/tests/ham_flow.lua b/tests/ham_message.lua similarity index 100% rename from tests/ham_flow.lua rename to tests/ham_message.lua diff --git a/tests/ham_flow.rs b/tests/ham_message.rs similarity index 98% rename from tests/ham_flow.rs rename to tests/ham_message.rs index a0391b6..713c0ed 100644 --- a/tests/ham_flow.rs +++ b/tests/ham_message.rs @@ -4,7 +4,7 @@ pub use common::*; // `pub` only to silence unused code warnings use spamassassin_milter::*; #[test] -fn ham_flow() { +fn ham_message() { let mut builder = Config::builder(); builder.spamc_args(vec![format!("--port={}", SPAMD_PORT)]); let config = builder.build(); diff --git a/tests/live.lua b/tests/live.lua index 844aaac..ec7a61e 100644 --- a/tests/live.lua +++ b/tests/live.lua @@ -60,6 +60,9 @@ local err = mt.bodystring(conn, "XJS*C4JDBQADN1.NSBN3*2IDNEN*GTUBE-STANDARD-ANTI assert(err == nil, err) assert(mt.getreply(conn) == SMFIR_CONTINUE) +-- TODO `miltertest` bug: Replacing the message body can crash `miltertest`. An +-- internal buffer size (1024) easily overflows when using SpamAssassin reports. + local err = mt.eom(conn) assert(err == nil, err) assert(mt.getreply(conn) == SMFIR_ACCEPT) diff --git a/tests/skip_large_message.lua b/tests/skip_oversized.lua similarity index 100% rename from tests/skip_large_message.lua rename to tests/skip_oversized.lua diff --git a/tests/skip_large_message.rs b/tests/skip_oversized.rs similarity index 96% rename from tests/skip_large_message.rs rename to tests/skip_oversized.rs index c262b01..281298b 100644 --- a/tests/skip_large_message.rs +++ b/tests/skip_oversized.rs @@ -4,7 +4,7 @@ pub use common::*; // `pub` only to silence unused code warnings use spamassassin_milter::*; #[test] -fn skip_large_message() { +fn skip_oversized() { let mut builder = Config::builder(); builder.max_message_size(512); builder.spamc_args(vec![format!("--port={}", SPAMD_PORT)]); diff --git a/tests/spam_flow.lua b/tests/spam_message.lua similarity index 100% rename from tests/spam_flow.lua rename to tests/spam_message.lua diff --git a/tests/spam_flow.rs b/tests/spam_message.rs similarity index 98% rename from tests/spam_flow.rs rename to tests/spam_message.rs index 1f0f5c4..926e1be 100644 --- a/tests/spam_flow.rs +++ b/tests/spam_message.rs @@ -4,7 +4,7 @@ pub use common::*; // `pub` only to silence unused code warnings use spamassassin_milter::*; #[test] -fn spam_flow() { +fn spam_message() { let mut builder = Config::builder(); builder.spamc_args(vec![format!("--port={}", SPAMD_PORT)]); let config = builder.build();