haraka 0.0.33 → 3.3.0

package/docs/deprecated/mail_from.blocklist.md

@@ -0,0 +1,18 @@
+# mail_from.blocklist
+
+## DEPRECATED
+
+This plugin is deprecated. Use instead the mail_from.access plugin, which
+does everything this one does and much more. (whitelists, blacklists, regex)
+
+This plugin blocks MAIL_FROM addresses in a list.
+
+NOTE: If all you need is to deny mail based on the exact address, this plugin
+will work just fine. If you want to customize the deny message, add blocks
+based on a regex, or add whitelists, please use the mail_from.access plugin.
+
+## Configuration
+
+- mail_from.blocklist
+
+  Contains a list of email addresses to block.

package/docs/deprecated/mail_from.nobounces.md

@@ -0,0 +1,8 @@
+# mail_from.nobounces
+
+This mail blocks all bounce messages using the simple rule of checking
+for `MAIL FROM:<>`.
+
+This is useful to enable if you have a mail server that gets spoofed too
+much but very few legitimate users. It is potentially bad to block all
+bounce messages, but unfortunately for some hosts, sometimes necessary.

package/docs/deprecated/rcpt_to.access.md

@@ -0,0 +1,53 @@
+## DEPRECATION NOTICE
+
+See [haraka-plugin-access](https://github.com/haraka/haraka-plugin-access)
+for upgrade instructions.
+
+# rcpt_to.access
+
+This plugin blocks RCPT_TO addresses in a list or regex.
+This plugin will evaluate the RCPT_TO address against a set of white and black
+lists. The lists are applied in the following way:
+
+rcpt_to.access.whitelist (pass)
+rcpt_to.access.whitelist_regex (pass)
+rcpt_to.access.blacklist (block)
+rcpt_to.access.blacklist_regex (block)
+
+## Configuration rcpt_to.access.ini
+
+General configuration file for this plugin.
+
+- rcpt_to.access.general.deny_msg
+
+  Text to send the user on reject (text).
+
+## Configuration rcpt_to.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 address
+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,
+here they are.
+
+## Configuration rcpt_to.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
+from writing overly permissive rules on accident.
+
+## Configuration rcpt_to.access.blacklist
+
+This file should be used for a specific address, one per line, that should
+fail on connect.
+
+## Configuration rcpt_to.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
+from writing overly permissive rules on accident.

package/docs/deprecated/rcpt_to.blocklist.md

@@ -0,0 +1,18 @@
+# rcpt_to.blocklist
+
+## DEPRECATED
+
+This plugin is deprecated. Use instead the rcpt_to.access plugin, which
+does everything this one does and much more. (whitelists, blacklists, regex)
+
+This plugin blocks RCPT_TO addresses in a list.
+
+NOTE: If all you need is to deny mail based on the exact address, this plugin
+will work just fine. If you want to customize the deny message, add blocks
+based on a regex, or add whitelists, please use the rcpt_to.access plugin.
+
+## Configuration
+
+- rcpt_to.blocklist
+
+  Contains a list of email addresses to block.

package/docs/deprecated/rcpt_to.routes.md

@@ -0,0 +1,3 @@
+# rcpt_to.routes
+
+Moved to [https://github.com/haraka/haraka-plugin-recipient-routes](https://github.com/haraka/haraka-plugin-recipient-routes)

package/docs/deprecated/rdns.regexp.md

@@ -0,0 +1,30 @@
+# rdns.regexp
+
+WARNING: The services offered by this plugin, and much more, are now provided
+more efficiently with the connect.rdns_access plugin. Please transition over
+to using the new connect.rdns_access plugin, as this plugin is now deprecated
+and may be removed in a future version of Haraka.
+
+This plugin checks the reverse-DNS against a list of regular expressions. Any
+matches will result in a rejection, unless there is an allow rule to
+balance off broad regexes.
+
+To give an example. Assume we add a rule to deny all hosts with dynamic
+in the rDNS hostname (._dynamic._). Now we find a mail server,
+generaldynamics.com that is clearly a false positive. We could try
+to correct the original regex (clearly it is a poorly written regex), or
+we could add an allow rule for generaldynamics.com (.\*generaldynamics\.com$).
+This means that even though the dynamic block rule matches, it will be
+superseded by the allow rule for generaldynamics.com.
+
+## Configuration
+
+- rdns.deny_regexps
+
+  The list of regular expressions to deny. Over broad regexes in this list
+  can be corrected by using the allow list.
+
+- rdns.allow_regexps
+
+  The list of regular expressions to allow. This list is always processed
+  in favor of rules in the deny file.

package/docs/plugins/aliases.md

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

package/docs/plugins/auth/auth_bridge.md

@@ -0,0 +1,34 @@
+# auth/auth_bridge
+
+This plugin allows you to authenticate users to remote SMTP servers
+bridging the original user and password to the remote server,
+and proxy the result back to authenticate the client.
+
+This plugin is meant to be used with the plugin `queue/smtp_bridge`.
+
+It is different than `auth/auth_proxy` because it doesn't require
+the AUTH user in user@domain.com format, and it doesn't check that
+the domain is the configuration file. This plugins simply takes
+the original user and password and tries to authenticate it in the
+remote SMTP server.
+
+## Configuration
+
+Configuration is stored in `config/smtp_bridge.ini` and uses the INI
+style formatting.
+
+The configuration of this plugin is simple:
+
+    host=localhost
+    #port=
+    #auth_type=
+    #priority=10
+
+- host: the host where you will be authenticating and posting,
+  for example `smtp.host.tld`. This is the only setting required.
+
+If needed you can also set
+
+- port: default to empty and Haraka will use 25.
+
+The options `auth_type` and `priority` will be used by `queue/smtp_bridge`

package/docs/plugins/auth/auth_ldap.md

@@ -0,0 +1,4 @@
+# auth/auth_ldap
+
+Repackaged as [haraka-plugin-auth-ldap](https://github.com/haraka/haraka-plugin-auth-ldap).
+Loading `auth/auth_ldap` in `config/plugins` is auto-redirected to `auth-ldap`.

package/docs/plugins/auth/auth_proxy.md

@@ -0,0 +1,36 @@
+# auth/auth_proxy
+
+This plugin allows you to authenticate users by domain to remote SMTP servers
+and proxy the result back to authenticate the client.
+
+For this to work - the AUTH username _must_ be in user@domain.com format
+regardless as to whether the remote SMTP server requires it in this format.
+The domain part of the username is used to look-up which SMTP servers should
+be used to authenticate users for that domain.
+When sending the AUTH credentials to the remote server, this plugin will try
+and send the full username e.g. user@domain.com first and if this fails it
+will then strip the @domain.com part and just send the unqualified username.
+
+Due to the way this plugin works - it can only support PLAIN and LOGIN
+authentication methods and for this reason it requires that STARTTLS be
+used via the tls plugin before it will advertise AUTH capabilities by the
+EHLO command. When connecting to the remote SMTP systems it will always
+attempt STARTTLS if it is offered, but it does _not_ require it, so caution
+should be exercised.
+
+## Configuration
+
+Configuration is stored in `config/auth_proxy.ini` and uses the INI
+style formatting.
+
+The configuration of this plugin is simple:
+
+    [domains]
+    domain.com = server1.domain.com:587 server2.domain.com
+
+Where domain.com is the domain-part of the username equals a list of hosts
+that should be consulted in host:port format. The :port is optional and will
+default to 25. The list of hosts can be space, semi-colon or comma separated.
+
+If more than host is specified, then subsequent hosts will only be tested if
+there is some sort of error e.g. timeout, connection or protocol error.

package/docs/plugins/auth/auth_vpopmaild.md

@@ -0,0 +1,33 @@
+# auth/auth_vpopmaild
+
+The `auth/vpopmaild` plugin allows SMTP users to authenticate against a vpopmaild daemon.
+
+## Configuration
+
+The configuration file is stored in `config/auth_vpopmaild.ini`.
+
+### settings
+
+- host: The host/IP that vpopmaild is listening on (default: localhost).
+
+- port: The TCP port that vpopmaild is listening on (default: 89).
+
+- sysadmin: A colon separated username:password of a vpopmail user with SYSADMIN privileges (see vpopmail/bin/vmoduser -S). This is **only** necessary to support CRAM-MD5 which requires access to the clear text password. On new installs, it's best not to use CRAM-MD5, as it requires storing clear text passwords. Legacy clients with MUAs configured to authenticate with CRAM-MD5 will need this enabled.
+
+- constrain_sender: (default: true). For outbound messages (due to successful AUTH), constrain the envelope sender (MAIL FROM) to the same domain as the authenticated user. This setting, combined with `rate_rcpt_sender` in the [limit](https://github.com/haraka/haraka-plugin-limit) plugin can dramatically reduce the amount of backscatter and spam sent when an email account is compromised.
+
+### Per-domain Configuration
+
+Additionally, domains can each have their own configuration for connecting
+to vpopmaild. The defaults are the same, so only the differences needs to
+be declared. Example:
+
+```ini
+[example.com]
+host=192.168.0.1
+port=999
+
+[example2.com]
+host=192.168.0.2
+sysadmin=postmaster@example2.com:sekret
+```

package/docs/plugins/auth/flat_file.md

@@ -0,0 +1,40 @@
+# auth/flat_file
+
+The `auth/flat_file` plugin allows you to create a file containing username and password combinations, and have relaying users authenticate from that file.
+
+Note that passwords are stored in clear-text, so this may not be a great idea for large scale systems. However the plugin would be a good start for someone looking to implement authentication using some other form of auth.
+
+**Security** - it is recommended to switch to [auth-encfile][url-authencflat] to protect your user credentials.
+
+**IMPORANT NOTE** - this plugin requires that STARTTLS be used via the tls plugin before it will advertise AUTH capabilities by the EHLO command. Localhost and IPs in RFC1918 ranges
+are exempt from this rule.
+
+## Configuration
+
+Configuration is stored in `config/auth_flat_file.ini`.
+
+- [core]methods
+
+Authentication methods are listed in the `[core]methods` parameter. Authentification methods are comma separated. Currently supported methods are: `CRAM-MD5`, `PLAIN` and `LOGIN`. The `PLAIN` and `LOGIN` methods are insecure and require TLS to be enabled.
+
+- [core]constrain_sender: (default: true). For outbound messages (due to successful AUTH), constrain the envelope sender (MAIL FROM) to the same domain as the authenticated user. This setting, combined with `rate_rcpt_sender` in the [limit](https://github.com/haraka/haraka-plugin-limit) plugin can dramatically reduce the amount of backscatter and spam sent when an email account is compromised.
+
+Example:
+
+```ini
+[core]
+methods=PLAIN,LOGIN,CRAM-MD5
+constrain_sender=true
+```
+
+Users are stored in the `[users]` section.
+
+Example:
+
+```ini
+[users]
+user1=password1
+user@domain.com=password2
+```
+
+[url-authencflat]: https://github.com/AuspeXeu/haraka-plugin-auth-enc-file

package/docs/plugins/block_me.md

@@ -0,0 +1,18 @@
+# block_me
+
+This plugin allows you to configure an address which mail sent to will be
+parsed for a From: address in the body of the message, and will add that
+from address to the `mail_from.blocklist` config file.
+
+Effectively this allows your users to forward spams that got through to a
+particular mailbox to block them in the future.
+
+Note that this is a system-wide block, and not per-user. Be careful with this.
+
+## Configuration
+
+- `config/block_me.recipient` - a file containing the address to email to
+  get something blocked. For example: **spam@domain.com**.
+
+- `config/block_me.senders` - a file containing a list of email addresses
+  that are allowed to email the dropbox.

package/docs/plugins/data.signatures.md

@@ -0,0 +1,11 @@
+# data.signatures
+
+This plugin allows you to add string signatures to a configuration file and
+have this plugin scan the body text of an email for those strings. Mails
+matching these signatures will be blocked.
+
+## Configuration
+
+- data.signatures
+
+  This file contains a list of strings (one per line) that will be matched.

package/docs/plugins/delay_deny.md

@@ -0,0 +1,23 @@
+# delay_deny
+
+Delays all pre-DATA 'deny' results until the recipients are sent
+and all post-DATA commands until all hook_data_post plugins have run.
+This allows relays and authenticated users to bypass pre-DATA rejections.
+
+## Configuration
+
+Configuration options are in config/delay_deny.ini.
+
+This plugin operates in one of two modes: included and excluded.
+
+### included plugins
+
+A comma or semicolon separated list of denials that are to be included.
+In this mode, _only_ plugins in the list are bypassed. All other plugins
+can immediately reject connections.
+
+### excluded plugins
+
+A comma or semicolon separated list of denials that are to be excluded.
+Excluded plugins that are not bypassed and can still immediately reject
+connections.

package/docs/plugins/max_unrecognized_commands.md

@@ -0,0 +1,6 @@
+# max_unrecognized_commands
+
+The functionality of this plugin was folded into
+[haraka-plugin-limit](https://github.com/haraka/haraka-plugin-limit).
+Loading `max_unrecognized_commands` in `config/plugins` is auto-redirected
+to `limit`.

package/docs/plugins/prevent_credential_leaks.md

@@ -0,0 +1,22 @@
+# prevent_credential_leaks
+
+This plugin prevents an authenticated user (via SMTP AUTH) from sending
+their username and password out in a message (e.g. like replying to a
+phish).
+
+If their username and password are detected inside the message body, then
+the message is rejected with the message:
+
+```
+Credential leak detected: never give out your username/password to anyone!
+```
+
+Note that if the username is qualified e.g. user@domain.com - then the
+plugin will search for both `user` and `user@domain.com` for maximum
+effectiveness.
+
+## Configuration
+
+No configuration is required. Simply add the plugin to your `config/plugins`
+file. It should be added before any other plugins that run on hook_data_post
+for maximum efficiency.

package/docs/plugins/process_title.md

@@ -0,0 +1,42 @@
+# process_title
+
+This plugin causes the process title seen by the UNIX 'ps' command to
+be modified from this:
+
+```
+node haraka.js -c /etc/haraka
+```
+
+to this:
+
+```
+Haraka (master) cn=11148 cc=1082 cps=21/25.24/79 rcpts=144950/1.84 rps=518/328.18/586 msgs=78815/7.07 mps=302/178.44/329 out=0/0/0 respawn=0
+ \_ Haraka (worker) cn=1646 cc=140 cps=5/3.73/17 rcpts=20310/1.86 rps=75/46.04/102 msgs=10938/6.65 mps=42/24.8/56 out=0/0/0
+ \_ Haraka (worker) cn=1563 cc=168 cps=3/3.54/18 rcpts=19844/1.87 rps=78/45/96 msgs=10627/6.8 mps=49/24.1/53 out=0/0/0
+ \_ Haraka (worker) cn=1852 cc=172 cps=3/4.2/16 rcpts=26278/2.03 rps=93/59.56/114 msgs=12938/6.99 mps=40/29.33/65 out=0/0/0
+ \_ Haraka (worker) cn=1704 cc=187 cps=5/3.86/14 rcpts=23688/1.84 rps=93/53.7/125 msgs=12886/7.56 mps=64/29.21/66 out=0/0/0
+ \_ Haraka (worker) cn=2296 cc=218 cps=2/5.2/20 rcpts=29300/1.78 rps=117/66.4/125 msgs=16489/7.18 mps=40/37.37/66 out=0/0/0
+ \_ Haraka (worker) cn=2091 cc=195 cps=4/4.74/16 rcpts=25646/1.71 rps=84/58.12/117 msgs=14982/7.16 mps=52/33.95/66 out=0/0/0
+```
+
+where:
+
+- cn = Total number of connections
+- cc = Total number of concurrent connections
+- cps = Number of connections in the last second / average / maximum
+- rcpts = Total number of recipients / Average number of recipients per message
+- rps = Number of recipients in the last second / average / maximum
+- msgs = Total number of messages / Average number messages per connection
+- mps = Number of messages in the last second / average / maximum
+- out = Mails being processed / Mails waiting to be processed / Mails in temp fail state
+- respawn = Number of worker processes respawned (only under cluster)
+
+If 'cluster' is used then the master process will show the total
+across all workers, with the exception of outbound stats.
+
+All of the counts shown are since the process started, so if a
+worker has been re-started then the counts may not add up.
+
+Note: this plugin should be added at the top of `config/plugins` so
+that its `connect_init`, `rcpt`, `data`, and `disconnect` hooks run
+before any plugin that might short-circuit those hooks.

package/docs/plugins/queue/deliver.md

@@ -0,0 +1,3 @@
+# queue/deliver
+
+This plugin is now redundant. Outbound delivery is now built into Haraka.

package/docs/plugins/queue/discard.md

@@ -0,0 +1,32 @@
+# discard
+
+This plugin will discard a message by pretending that the message was queued.
+
+It is designed to be used by other plugins which request the message be
+discard by setting a connection or transaction note that this plugin
+checks.
+
+It uses the 'queue' hook, so it runs after all the plugins that hook on `data_post`.
+
+If you use the 'quarantine' plug-in then this plugin should run _after_ it.
+
+USE THIS PLUGIN WITH CARE!
+
+# Enable
+
+Enable by adding a `queue/discard` entry in `config/plugins` **before** your
+other queue plugins that perform actual deliveries.
+
+# Usage
+
+Set
+
+```javascript
+connection.notes.discard = [1 | true]
+```
+
+or
+
+```javascript
+connection.transaction.notes.discard = [1 | true]
+```

package/docs/plugins/queue/lmtp.md

@@ -0,0 +1,24 @@
+# queue/lmtp
+
+This plugin delivers inbound mail via LMTP.
+
+## Configuration
+
+LMTP is enabled by adding `queue/lmtp` to config/plugins. LMTP delivery is configured in `config/lmtp.ini` . By default, all inbound messages are forwarded to the host specified in the `[main]` section. Domain specific routes can be specified by creating additional sections with the same host/port or path options.
+
+### lmtp.ini
+
+```ini
+; defaults
+host=localhost
+port=24
+
+[example1.com]
+; Goes elsewhere
+host=10.1.1.1
+port=2400
+
+[example2.com]
+; Using unix domain sockets
+path = /tmp/blah_com_socket
+```

package/docs/plugins/queue/qmail-queue.md

@@ -0,0 +1,16 @@
+# queue/qmail-queue
+
+This plugin delivers the mail to the `qmail-queue` program, which can be used
+for both inbound and outbound delivery.
+
+## Configuration
+
+- qmail-queue.path
+
+  The path to the `qmail-queue` binary. Default: `/var/qmail/bin/qmail-queue`
+
+- qmail-queue.ini
+  - enable_outbound=true
+
+    Deliver outbound email to qmail. Set to false to use Haraka's
+    separate Outbound mail routing (MX based delivery)).

package/docs/plugins/queue/quarantine.md

@@ -0,0 +1,87 @@
+# quarantine
+
+This plugin will save a message (in message/rfc822 format) to a specified
+directory, which will be created automatically if it does not already exist,
+a dated sub-folder is also added to the end of the path specified in YYYYMMDD
+format.
+
+It is designed to be used by other plugins which request the message be
+quarantined by setting a connection or transaction note that this plugin
+checks.
+
+NOTE: this plugin simply saves a copy of the message. It does not reject or
+discard the message and relies on another plugin to perform this function.
+
+It uses the 'queue' hook, so that it runs after all the 'data_post' plugins
+and should be listed in 'config/plugins' to run before your queue hooks that
+perform actual deliveries.
+
+To ensure that only completely written files are present in the quarantine,
+the files are written to a temporary directory first and then hardlinked to
+the final destination before the temporary file is deleted.
+
+The temporary directory is 'quarantine_path/tmp' which defaults to:
+/var/spool/haraka/quarantine/tmp.
+
+Upon start-up, any files present in the temporary directory are deleted
+syncronously prior to any messages being accepted.
+
+## Configuration
+
+This plugin looks for 'quarantine.ini' in the config directory.
+
+- quarantine_path (default: /var/spool/haraka/quarantine)
+
+  The default base path to save the quarantine files to. It will be created
+  if it does not already exist.
+
+## Usage
+
+If you wish to keep a copy of the message in your plugin, simply either:
+
+```javascript
+connection.notes.quarantine = [1 | true | 'sub/directory/path']
+```
+
+or
+
+```javascript
+connection.transaction.notes.quarantine = [1 | true | 'sub/directory/path']
+```
+
+e.g.
+
+```javascript
+connection.notes.quarantine = 1
+```
+
+would save the message to '/var/spool/quarantine/haraka/YYYYMMDD/UUID' where
+YYYMMDD and UUID are expanded to current date and transaction UUID.
+
+and
+
+```javascript
+connection.notes.quarantine = 'corpus'
+```
+
+would save the message to '/var/spool/quarantine/haraka/corpus/YYYYMMDD/UUID'.
+
+Note: you can specify 'corpus/foo' or 'corpus/foo/bar' and the directories will
+be automatically created. Do not add any leading or trailing slashes.
+
+By default - after the message is quarantined, the plugin will tell Haraka to
+continue to the next plugin. You can specify a different action like DENY or
+OK and supply an optional message using the following notes:
+
+```javascript
+connection.notes.quarantine_action = [OK, 'Message quarantined']
+connection.transaction.notes.quarantine_action = [DENY, 'Message rejected']
+```
+
+If you don't want to supply a specific message back to the client you can
+also just specify a return code:
+
+```javascript
+connection.notes.quarantine_action = OK
+connection.transaction.notes.quarantine_action = DENY
+```

package/docs/plugins/queue/smtp_bridge.md

@@ -0,0 +1,32 @@
+# queue/smtp_bridge
+
+This plugin delivers to another SMTP server, bridging the authentication
+details and post data from the initial connection.
+
+This plugin is meant to be used with the plugin `auth/auth_bridge`.
+
+It is different than `queue/smtp_proxy` or `queue/smpt_forward` because
+it doesn't use the AUTH details from a configuration file. This plugins
+simply post the data from the original connection to the remote SMTP server
+using the original AUTH details.
+
+## Configuration
+
+Configuration is stored in `config/smtp_bridge.ini` and uses the INI
+style formatting.
+
+The configuration of this plugin is simple:
+
+    host=localhost
+    #port=
+    #auth_type=
+    #priority=10
+
+- host: the host where you will be authenticating and posting,
+  for example `smtp.host.tld`. This is the only setting required.
+
+If needed you can also set
+
+- port: default to empty and Haraka will use 25.
+- auth_type: default to empty and Haraka will try to pick an appropriate method.
+- priority: default to 10.