Haraka 3.1.0 → 3.1.2

package/docs/Tutorial.md

@@ -1,5 +1,4 @@
-Writing Haraka Plugins
-======================
+# Writing Haraka Plugins
 
 Part of the joy of using Haraka as your main mail server is having a strong
 plugin based system which means you control all aspects of how your mail is
@@ -13,11 +12,10 @@ Node.js) and the world is your oyster.
 
 This tutorial will run through a simple plugin which allows you to have
 email addresses that expire in a short period of time. This is handy if you
-want a *disposable email address* to use to sign up for a web site that you
+want a _disposable email address_ to use to sign up for a web site that you
 don't wish to continually receive communication from.
 
-The Design
-----------
+## The Design
 
 In order to make this simple, we are going to simply let you have tagged
 email addresses such as `user-20120515@domain.com` which will expire on the
@@ -26,19 +24,17 @@ reject mails to that address after the expiry date. If the address hasn't
 expired yet it will re-write the address to `user@domain.com` before onward
 delivery.
 
-What You Will Need
-------------------
+## What You Will Need
 
-* Node.js and npm
-* Haraka
-* A text editor
-* [swaks][1]
-* A screwdriver
+- Node.js and npm
+- Haraka
+- A text editor
+- [swaks][1]
+- A screwdriver
 
 [1]: http://jetmore.org/john/code/swaks/
 
-Getting Started
----------------
+## Getting Started
 
 First install Haraka via npm if you haven't already:
 
@@ -57,56 +53,48 @@ Next, let's create a new plugin:
 This should output a bunch of information about files it has created:
 
     Plugin rcpt_to.disposable created
-	Now edit javascript in:    /path/to/new_project/plugins/rcpt_to.disposable.js
-	Add the plugin to config:  /path/to/new_project/config/plugins
-	And edit documentation in: /path/to/new_project/docs/plugins/rcpt_to.disposable.md
+    Now edit javascript in:    /path/to/new_project/plugins/rcpt_to.disposable.js
+    Add the plugin to config:  /path/to/new_project/config/plugins
+    And edit documentation in: /path/to/new_project/docs/plugins/rcpt_to.disposable.md
 
-So let's do the second part now - load up the `config/plugins` file and lets
-set this up to test things. Comment out most of the plugins, except for
+So let's do the second part now - load up the `config/plugins` file and
+set it up to test. Comment out most of the plugins, except for
 `rcpt_to.in_host_list` and add in our new plugin, and change the queue
 plugin to `test_queue`. The final file should look like this:
 
-	# default list of plugins
+    # default list of plugins
 
-	# block mails from known bad hosts (see config/dnsbl.zones for the DNS zones queried)
-	#dnsbl
+    #dns-lists
+    #data.signatures
 
-	# allow bad mail signatures from the config/data.signatures file.
-	#data.signatures
+    # block mail from some known bad HELOs - see config/helo.checks.ini for configuration
+    #helo.checks
 
-	# block mail from some known bad HELOs - see config/helo.checks.ini for configuration
-	#helo.checks
+    # Only accept mail where the MAIL FROM domain is resolvable to an MX record
+    #mail_from.is_resolvable
 
-	# block mail from known bad email addresses you put in config/mail_from.blocklist
-	#mail_from.blocklist
+    # Allow dated tagged addresses
+    rcpt_to.disposable
 
-	# Only accept mail where the MAIL FROM domain is resolvable to an MX record
-	#mail_from.is_resolvable
+    # Only accept mail for your personal list of hosts
+    rcpt_to.in_host_list
 
-	# Allow dated tagged addresses
-	rcpt_to.disposable
+    # Queue mail via qmail-queue
+    #queue/qmail-queue
 
-	# Only accept mail for your personal list of hosts
-	rcpt_to.in_host_list
+    test_queue
 
-	# Queue mail via qmail-queue
-	#queue/qmail-queue
+The ordering here is important - our new plugin has to come before `rcpt_to.in_host_list`.
 
-	test_queue
-
-Remember that the ordering here is important - our new plugin has to come
-before `rcpt_to.in_host_list`.
-
-Now fire up your favourite editor and put the following into
-the `plugins/rcpt_to.disposable.js` file:
+Fire up your favourite editor and put the following into the `plugins/rcpt_to.disposable.js` file:
 
     exports.hook_rcpt = function (next, connection, params) {
-		var rcpt = params[0];
-		this.loginfo("Got recipient: " + rcpt);
-		next();
-	}
+    	const rcpt = params[0];
+    	this.loginfo("Got recipient: " + rcpt);
+    	next();
+    }
 
-All we are doing here is logging the fact that we got the recipient.
+Here we log that we got the recipient.
 
 Check this works. You'll need two terminal windows. In window 1:
 
@@ -126,29 +114,28 @@ In the logs you should see:
 Which indicates everything is working. You should also have a file
 `/tmp/mail.eml` containing the email that swaks sent.
 
-Parsing Out The Date
---------------------
+## Parsing Out The Date
 
-Now lets check for emails with an expire date in them and turn them into
+Now check for emails with an expire date in them and turn them into
 `Date` objects. Edit your plugin file as follows:
 
     exports.hook_rcpt = function (next, connection, params) {
-		var rcpt = params[0];
-		this.loginfo("Got recipient: " + rcpt);
-		
-		// Check user matches regex 'user-YYYYMMDD':
-		var match = /^(.*)-(\d{4})(\d{2})(\d{2})$/.exec(rcpt.user);
-		if (!match) {
-			return next();
-		}
-		
-		// get date - note Date constructor takes month-1 (i.e. Dec == 11).
-		var expiry_date = new Date(match[2], match[3]-1, match[4]);
-		
-		this.loginfo("Email expires on: " + expiry_date);
-		
-		next();
-	}
+    	var rcpt = params[0];
+    	this.loginfo("Got recipient: " + rcpt);
+
+    	// Check user matches regex 'user-YYYYMMDD':
+    	var match = /^(.*)-(\d{4})(\d{2})(\d{2})$/.exec(rcpt.user);
+    	if (!match) {
+    		return next();
+    	}
+
+    	// get date - note Date constructor takes month-1 (i.e. Dec == 11).
+    	var expiry_date = new Date(match[2], match[3]-1, match[4]);
+
+    	this.loginfo("Email expires on: " + expiry_date);
+
+    	next();
+    }
 
 Start haraka again and pass it the following email via swaks:
 
@@ -163,61 +150,59 @@ And you should see now in the logs:
 The exact time may vary depending on your timezone, but it should be obvious
 we now have a date object, which we can now compare to the current date.
 
-Rejecting Expired Emails
-------------------------
+## Rejecting Expired Emails
 
 The next edit we have to do is to add in code to compare to the current date
 and reject expired emails. Again, this is very simple:
 
-	exports.hook_rcpt = function (next, connection, params) {
-		var rcpt = params[0];
-		this.loginfo("Got recipient: " + rcpt);
-	
-		// Check user matches regex 'user-YYYYMMDD':
-		var match = /^(.*)-(\d{4})(\d{2})(\d{2})$/.exec(rcpt.user);
-		if (!match) {
-			return next();
-		}
-	
-		// get date - note Date constructor takes month-1 (i.e. Dec == 11).
-		var expiry_date = new Date(match[2], match[3]-1, match[4]);
-	
-		this.loginfo("Email expires on: " + expiry_date);
-		
-		var today = new Date();
-		
-		if (expiry_date < today) {
-			// If we get here, the email address has expired
-			return next(DENY, "Expired email address");
-		}
-		
-		next();
-	}
+    exports.hook_rcpt = function (next, connection, params) {
+    	var rcpt = params[0];
+    	this.loginfo("Got recipient: " + rcpt);
+
+    	// Check user matches regex 'user-YYYYMMDD':
+    	var match = /^(.*)-(\d{4})(\d{2})(\d{2})$/.exec(rcpt.user);
+    	if (!match) {
+    		return next();
+    	}
+
+    	// get date - note Date constructor takes month-1 (i.e. Dec == 11).
+    	var expiry_date = new Date(match[2], match[3]-1, match[4]);
+
+    	this.loginfo("Email expires on: " + expiry_date);
+
+    	var today = new Date();
+
+    	if (expiry_date < today) {
+    		// If we get here, the email address has expired
+    		return next(DENY, "Expired email address");
+    	}
+
+    	next();
+    }
 
 And we can easily check that with swaks (remember to restart Haraka):
 
     $ swaks -h foo.com -t booya-20110101@haraka.local -f somewhere@example.com \
       -s localhost -p 25
-	=== Trying localhost:25...
-	=== Connected to localhost.
-	<-  220 sergeant.org ESMTP Haraka 0.3 ready
-	 -> EHLO foo.com
-	<-  250-Haraka says hi Unknown [127.0.0.1]
-	<-  250-PIPELINING
-	<-  250-8BITMIME
-	<-  250 SIZE 500000
-	 -> MAIL FROM:<somewhere@example.com>
-	<-  250 From address is OK
-	 -> RCPT TO:<booya-20110101@haraka.local>
-	<** 550 Expired email address
-	 -> QUIT
-	<-  221 closing connection. Have a jolly good day.
-	=== Connection closed with remote host.
+    === Trying localhost:25...
+    === Connected to localhost.
+    <-  220 sergeant.org ESMTP Haraka 0.3 ready
+     -> EHLO foo.com
+    <-  250-Haraka says hi Unknown [127.0.0.1]
+    <-  250-PIPELINING
+    <-  250-8BITMIME
+    <-  250 SIZE 500000
+     -> MAIL FROM:<somewhere@example.com>
+    <-  250 From address is OK
+     -> RCPT TO:<booya-20110101@haraka.local>
+    <** 550 Expired email address
+     -> QUIT
+    <-  221 closing connection. Have a jolly good day.
+    === Connection closed with remote host.
 
 Now we need to do one more thing...
 
-Fixing Up Unexpired Emails
---------------------------
+## Fixing Up Unexpired Emails
 
 The last thing we need to do, is if we have an email that isn't expired, we
 need to normalise it back to the real email address, because wherever we
@@ -225,34 +210,34 @@ deliver this to is unlikely to recognise these new email addresses.
 
 Here's how our final plugin will look:
 
-	exports.hook_rcpt = function (next, connection, params) {
-		var rcpt = params[0];
-		this.loginfo("Got recipient: " + rcpt);
-
-		// Check user matches regex 'user-YYYYMMDD':
-		var match = /^(.*)-(\d{4})(\d{2})(\d{2})$/.exec(rcpt.user);
-		if (!match) {
-			return next();
-		}
-
-		// get date - note Date constructor takes month-1 (i.e. Dec == 11).
-		var expiry_date = new Date(match[2], match[3]-1, match[4]);
-
-		this.loginfo("Email expires on: " + expiry_date);
-	
-		var today = new Date();
-	
-		if (expiry_date < today) {
-			// If we get here, the email address has expired
-			return next(DENY, "Expired email address");
-		}
-		
-		// now get rid of the extension:
-		rcpt.user = match[1];
-		this.loginfo("Email address now: " + rcpt);
-		
-		next();
-	}
+    exports.hook_rcpt = function (next, connection, params) {
+    	var rcpt = params[0];
+    	this.loginfo("Got recipient: " + rcpt);
+
+    	// Check user matches regex 'user-YYYYMMDD':
+    	var match = /^(.*)-(\d{4})(\d{2})(\d{2})$/.exec(rcpt.user);
+    	if (!match) {
+    		return next();
+    	}
+
+    	// get date - note Date constructor takes month-1 (i.e. Dec == 11).
+    	var expiry_date = new Date(match[2], match[3]-1, match[4]);
+
+    	this.loginfo("Email expires on: " + expiry_date);
+
+    	var today = new Date();
+
+    	if (expiry_date < today) {
+    		// If we get here, the email address has expired
+    		return next(DENY, "Expired email address");
+    	}
+
+    	// now get rid of the extension:
+    	rcpt.user = match[1];
+    	this.loginfo("Email address now: " + rcpt);
+
+    	next();
+    }
 
 And when we test this with an unexpired address via swaks:
 
@@ -261,14 +246,13 @@ And when we test this with an unexpired address via swaks:
 
 We get in the logs:
 
-	[INFO] [rcpt_to.disposable] Got recipient: <booya-20120101@haraka.local>
-	[INFO] [rcpt_to.disposable] Email expires on: Sun Jan 01 2012 00:00:00 GMT-0500 (EST)
-	[INFO] [rcpt_to.disposable] Email address now: <booya@haraka.local>
+    [INFO] [rcpt_to.disposable] Got recipient: <booya-20120101@haraka.local>
+    [INFO] [rcpt_to.disposable] Email expires on: Sun Jan 01 2012 00:00:00 GMT-0500 (EST)
+    [INFO] [rcpt_to.disposable] Email address now: <booya@haraka.local>
 
 Which indicates that we have successfully modified the email address.
 
-Further Reading
-===============
+# Further Reading
 
 There are many more features of the Haraka API to explore, including access
 to the body of the email and the headers, access to the HELO string, and

package/docs/deprecated/access.md

@@ -1,4 +1,3 @@
 # access - ACLs
 
 Repackaged as [haraka-plugin-access](https://github.com/haraka/haraka-plugin-access).
-

package/docs/deprecated/backscatterer.md

@@ -1,10 +1,9 @@
-backscatterer
-=============
+# backscatterer
 
 This is a very basic pluign that checks the connecting IP against
 ips.backscatterer.org when the envelope-from is null or postmaster@
 as per the instructions at http://www.backscatterer.org/?target=usage
 
 This plugin is used to reject misdirected bounces and autoresponders
-and sender callouts from abusive systems which can happen when a 
+and sender callouts from abusive systems which can happen when a
 local domain is spoofed and used as the envelope-from in a spam run.

package/docs/deprecated/connect.rdns_access.md

@@ -3,60 +3,51 @@
 See [haraka-plugin-access](https://github.com/haraka/haraka-plugin-access)
 for upgrade instructions.
 
-
-connect.rdns\_access
-===================
-
+# connect.rdns_access
 
 This plugin will evaluate the remote IP address and the remote rDNS hostname
-against a set of white and black lists.  The lists are applied in the following
+against a set of white and black lists. The lists are applied in the following
 way:
 
-connect.rdns\_access.whitelist         (pass)
-connect.rdns\_access.whitelist\_regex   (pass)
-connect.rdns\_access.blacklist         (block)
-connect.rdns\_access.blacklist\_regex   (block)
+connect.rdns_access.whitelist (pass)
+connect.rdns_access.whitelist_regex (pass)
+connect.rdns_access.blacklist (block)
+connect.rdns_access.blacklist_regex (block)
 
-Configuration connect.rdns\_access.ini
--------------------------------------
+## Configuration connect.rdns_access.ini
 
 General configuration file for this plugin.
 
-* connect.rdns\_access.general.deny\_msg
+- connect.rdns_access.general.deny_msg
 
   Text to send the user on reject (text).
 
-
-Configuration connect.rdns\_access.whitelist
--------------------------------------------
+## Configuration connect.rdns_access.whitelist
 
 The whitelist is mostly to counter blacklist entries that match more than
-what one would want.  This file should be used for a specific IP address
+what one would want. This file should be used for a specific IP address
 or rDNS hostnames, one per line, that should bypass blacklist checks.
 NOTE: We heavily suggest tailoring blacklist entries to be as accurate as
-possible and never using whitelists.  Nevertheless, if you need whitelists,
+possible and never using whitelists. Nevertheless, if you need whitelists,
 here they are.
 
-Configuration connect.rdns\_access.whitelist\_regex
--------------------------------------------------
+## Configuration connect.rdns_access.whitelist_regex
 
 Does the same thing as the whitelist file, but each line is a regex.
 Each line is also anchored for you, meaning '^' + regex + '$' is added for
-you.  If you need to get around this restriction, you may use a '.*' at
-either the start or the end of your regex.  This should help prevent people
+you. If you need to get around this restriction, you may use a '.\*' at
+either the start or the end of your regex. This should help prevent people
 from writing overly permissive rules on accident.
 
-Configuration connect.rdns\_access.blacklist
--------------------------------------------
+## Configuration connect.rdns_access.blacklist
 
 This file should be used for a specific IP address or rDNS hostnames, one
 per line, that should fail on connect.
 
-Configuration connect.rdns\_access.blacklist\_regex
--------------------------------------------------
+## Configuration connect.rdns_access.blacklist_regex
 
 Does the same thing as the blacklist file, but each line is a regex.
 Each line is also anchored for you, meaning '^' + regex + '$' is added for
-you.  If you need to get around this restriction, you may use a '.*' at
-either the start or the end of your regex.  This should help prevent people
+you. If you need to get around this restriction, you may use a '.\*' at
+either the start or the end of your regex. This should help prevent people
 from writing overly permissive rules on accident.

package/docs/deprecated/data.headers.md

@@ -1,4 +1,3 @@
 # data.headers
 
 Deprecated by [haraka-plugin-headers](https://github.com/haraka/haraka-plugin-headers/)
-

package/docs/deprecated/data.nomsgid.md

@@ -1,5 +1,4 @@
-data.nomsgid
-============
+# data.nomsgid
 
 NOTICE: this plugin is deprecated. Use data.headers instead.
 

package/docs/deprecated/data.noreceived.md

@@ -1,5 +1,4 @@
-data.noreceived
-===============
+# data.noreceived
 
 NOTICE: this plugin is deprecated. Use data.headers instead.
 

package/docs/deprecated/data.rfc5322_header_checks.md

@@ -1,5 +1,4 @@
-data.rfc5322\_header\_checks
-==========================
+# data.rfc5322_header_checks
 
 NOTICE: this plugin is deprecated. Use data.headers instead.
 

package/docs/deprecated/dkim_sign.md

@@ -2,8 +2,7 @@
 
 This plugin implements the [DKIM Core specification](dkimcore.org).
 
-This plugin only *signs* outbound messages. It does not validate DKIM signatures.
-
+This plugin only _signs_ outbound messages. It does not validate DKIM signatures.
 
 ## Getting Started
 
@@ -38,35 +37,32 @@ The values in the address have the following meaning:
     services: s=[email]
     keytypes: [ rsa ]
 
-
 ## Key size
 
 The default key size created by `dkim_key_gen.sh` is 2048. That is considered secure as of mid-2014 but after 2020, you should be using 4096.
 
 # What to sign
 
-The DKIM signing key for messages from example.org *should* be signed with
- a DKIM key for example.org. Failing to do so will result in messages not
-having an *aligned* DKIM signature. For DMARC enabled domains, this will
+The DKIM signing key for messages from example.org _should_ be signed with
+a DKIM key for example.org. Failing to do so will result in messages not
+having an _aligned_ DKIM signature. For DMARC enabled domains, this will
 likely result in deliverability problems.
 
 For correct alignment, Haraka signs each message with that domains DKIM key.
 For an alternative, see the legacy Single Domain Configuration below.
 
-
 # Configuration
 
 This plugin is configured in `dkim_sign.ini`.
 
-- disabled = [ 1 | true | yes ]             (OPTIONAL)
-
-    Set this to disable DKIM signing
+- disabled = [ 1 | true | yes ] (OPTIONAL)
 
-- headers\_to\_sign = list, of; headers       (REQUIRED)
+  Set this to disable DKIM signing
 
-    Set this to the list of headers that should be signed, separated by commas, colons or semi-colons. Signing prevents tampering with the specified headers.
-    The 'From' header is required by the RFC and will be added if missing.
+- headers_to_sign = list, of; headers (REQUIRED)
 
+  Set this to the list of headers that should be signed, separated by commas, colons or semi-colons. Signing prevents tampering with the specified headers.
+  The 'From' header is required by the RFC and will be added if missing.
 
 ## Single Domain Configuration
 
@@ -74,13 +70,13 @@ To sign all messages with a single DKIM key, you must set the selector and domai
 
 - selector = name
 
-    Set this to the selector name published in DNS under the
-    \_domainkey sub-domain of the domain referenced below.
+  Set this to the selector name published in DNS under the
+  \_domainkey sub-domain of the domain referenced below.
 
 - domain = name
 
-    Set this to the domain name that will be used to sign messages
-    which don't match a per-domain DKIM key.  The DNS TXT entry for:
+  Set this to the domain name that will be used to sign messages
+  which don't match a per-domain DKIM key. The DNS TXT entry for:
 
         <selector>._domainkey.<domain>
 

package/docs/deprecated/dkim_verify.md

@@ -1,36 +1,28 @@
-dkim_verify
-===========
+# dkim_verify
 
 This plugin will verify DKIM signatures as defined by RFC 6376 and add
 an Authentication-Results header as appropriate.
 
+## Configuration
 
-Configuration
--------------
+- allowed_time_skew
 
-* allowed_time_skew
-  
   How far can we stretch on time matching, in secs. Useful when clock is skewed.
 
-* sigerror_log_level
+- sigerror_log_level
 
-  
+## Testing
 
-Testing
--------
-
-This plugin also provides a command-line test tool that can be used to 
+This plugin also provides a command-line test tool that can be used to
 debug DKIM issues or to check results.
 
-````
+```
 # dkimverify < message
 identity="@gmail.com" domain="gmail.com" result=pass
-````
+```
 
 You can add `--debug` to the option arguments to see a full trace of the processing.
 
-
-Notes
------
+## Notes
 
 This plugin and underlying library does not currently support DKIM body length limits (l=).