dkimcore.org Documentation

1. Project Overview & Quickstart (haraka/dkimcore.org) Copy Chapter

dkimcore.org

Open-source repository haraka/dkimcore.org

Repository Details Copy Section

• Repository: haraka/dkimcore.org
• Primary Language: Code

Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.

2. Official Technical Reference & Guides (haraka/haraka.github.io) Copy Chapter

File: README.md Copy Chapter

haraka.github.io

Setup Copy Chapter

Install dependencies:

npm install

Development Copy Chapter

npm run dev

Edge Side Rendering Copy Chapter

Can be deployed to Vercel Functions, Netlify Functions, AWS, and most Node-compatible environments.

Look at all the available presets here.

npm run build

Static Generation Copy Chapter

Use the generate command to build your application.

The HTML files will be generated in the .output/public directory and ready to be deployed to any static compatible hosting.

npm run generate

Preview build Copy Chapter

You might want to preview the result of your build locally, to do so, run the following command:

npm run preview

For a detailed explanation of how things work, check out Docus.

File: content/6.core/1.Address.md Copy Chapter

title: Address Object _path: /core/Address Copy Chapter

Address Object

The Address object is an interface to reading email addresses passed in at
SMTP time. As such it parses all the formats in RFC-2821 and 2822, and
supports correctly escaping email addresses.

API Copy Chapter

• new Address (user, host)

Create a new address object for user@host

• new Address (email)

Creates a new address object by parsing the email address. Will throw an
exception if the address cannot be parsed.

• address.user

Access the local part of the email address

• address.host

Access the domain part of the email adress

• address.format()

Provides the email address in the appropriate `` format. And
deals correctly with the null sender and local names.

• address.toString()

Same as format().

• address.address

Provides the email address in 'user@host' format.

Advanced Usage Copy Chapter

It is possible to mess with the regular expressions used to match addresses
for stricter or less strict matching.

To change the behaviour mess with the following variables:

var adr = require('./address');
// Now change one of the following. Note they are RegExp objects NOT strings.
adr.atom_expr;
adr.address_literal_expr;
adr.subdomain_expr;
adr.domain_expr;
adr.qtext_expr;
adr.text_expr;
// Don't forget to recompile:
adr.compile_re();

File: content/6.core/2.Body.md Copy Chapter

title: Body Object _path: /core/Body Copy Chapter

Body Object

This documentation has moved to haraka/email-message.

File: content/6.core/3.Config.md Copy Chapter

title: Config _path: /core/Config Copy Chapter

Config

This documentation has moved to haraka-config.

File: content/6.core/4.Connection.md Copy Chapter

title: Connection Object _path: /core/Connection Copy Chapter

Connection Object

For each connection to Haraka there is one connection object.

API Copy Chapter

• connection.uuid

A unique UUID for this connection.

• connection.remote - info about the host that is connecting to Haraka.

  • ip - remote IP address
  • host - reverse DNS of the remote hosts IP
  • is_private - true if the remote IP is from a private (loopback, RFC 1918, link local, etc.) IP address.
  • is_local - true if the remote IP is localhost (loopback, link local)

• connection.local - info about the host that is running Haraka

  • ip - the IP of the Haraka server, as reported by the OS
  • port - the port number handling the connection.
  • host - the rDNS host name of the local IP

• connection.proxy - proxy properties set when a proxy is used (like haproxy)

  • allowed - if the remote IP has proxy permission
  • ip - when proxied, the proxy servers IP address
  • type - currently null or 'haproxy'

• connection.hello

  • verb - Either 'EHLO' or 'HELO' whichever the remote end used
  • host - The hostname given with HELO or EHLO

• connection.notes

An object which persists during the lifetime of the connection. It is used to store connection-specific properties. See also, connection.results and haraka-notes.

• connection.transaction

The current transaction object, valid after MAIL FROM, and destroyed at queue
time, RSET time, or if MAIL FROM was rejected. See the Transaction Object
documentation file.

• connection.relaying

A boolean flag to say whether this connection is allowed to relay mails (i.e.
deliver mails outbound). This is normally set by SMTP AUTH, or sometimes via
an IP address check.

• connection.current_line

For low level use. Contains the current line sent from the remote end,
verbatim as it was sent. Can be useful in certain botnet detection techniques.

• connection.last_response

Contains the last SMTP response sent to the client.

• connection.remote_closed

For low level use. This value is set when the remote host drops the connection.

• connection.results

Store results of processing in a structured format. See docs/Results

File: content/6.core/5.CoreConfig.md Copy Chapter

title: Core Configuration Files _path: /core/CoreConfig Copy Chapter

See Logging.

The Haraka core reads some configuration files to determine a few actions:

• smtp.yaml or smtp.json

If either of these files exist then they are loaded first.
This file is designed to use the JSON/YAML file overrides documented in
Config to optionally provide the entire configuration in a single file.

• plugins

The list of plugins to load

• smtp.ini

  Keys:

  • listen_host, port - the host and port to listen on (default: ::0 and 25)
  • listen - (default: [::0]:25) Comma separated IP:Port addresses to listen on
  • inactivity_time - how long to let clients idle in seconds (default: 300)
  • nodes - specifies how many processes to fork. The string "cpus" will fork as many children as there are CPUs (default: 1, which enables cluster mode with a single process)
  • user - optionally a user to drop privileges to. Can be a string or UID.
  • group - optionally a group to drop privileges to. Can be a string or GID.
  • ignore_bad_plugins - If a plugin fails to compile by default Haraka will stop at load time.
    If, however, you wish to continue on without that plugin's facilities, then
    set this config option
  • daemonize - enable this to cause Haraka to fork into the background on start-up (default: 0)
  • daemon_log_file - (default: /var/log/haraka.log) where to redirect stdout/stderr when daemonized
  • daemon_pid_file - (default: /var/run/haraka.pid) where to write a PID file to
  • spool_dir - (default: none) directory to create temporary spool files in
  • spool_after - (default: -1) if message exceeds this size in bytes, then spool the message to disk
    specify -1 to disable spooling completely or 0 to force all messages to be spooled to disk.
  • graceful_shutdown - (default: false) enable this to wait for sockets on shutdown instead of closing them quickly
  • force_shutdown_timeout - (default: 30) number of seconds to wait for a graceful shutdown

• me

  A name to use for this server. Used in received lines and elsewhere. Setup
  by default to be your hostname.

• connection.ini

  See inline comments in connection.ini for the following settings:

  • haproxy.hosts_ipv4
  • haproxy.hosts_ipv6
  • headers.*
  • max.bytes
  • max.line_length
  • max.data_line_length
  • max.mime_parts
  • message.greeting
  • message.close
  • smtputf8
  • strict_rfc1869
  • uuid.deny_chars
  • uuid.banner_bytes

• plugin_timeout

  Seconds to allow a plugin to run before the next hook is called automatically
  default: 30

  Note also that each plugin can have a config/.timeout
  file specifying a per-plugin timeout. In this file you can set a timeout of 0 to mean that this plugin's hooks never time out. Use this with care.

  If the plugin is in a sub-directory of plugins, then you must create this file
  in the equivalent path e.g. the queue/smtp_forward would need a timeout file in config/queue/smtp_forward.timeout

• outbound.ini

• outbound.bounce_message

  The bounce message if delivery of the message fails. The default is normally fine. Bounce messages contain a number of template replacement values which are best discovered by looking at the source code.

File: content/6.core/6.CustomReturnCodes.md Copy Chapter

title: Custom Return Codes _path: /core/CustomReturnCodes Copy Chapter

Custom Return Codes

This content has moved to haraka-dsn.

File: content/6.core/7.HAProxy.md Copy Chapter

title: HAProxy PROXY protocol extension support navigation.title: HAProxy _path: /core/HAProxy Copy Chapter

HAProxy

Haraka natively supports the PROXY protocol [1].

This allows an upstream proxy to pass IP address and port of the client which
Haraka will use instead of the socket IP address (which is of the proxy).
This allows DNSBLs and access control lists to operate on the proxied address.

Support is disabled by default and if HAProxy or other attempts to send a
PROXY command then Haraka will return a DENYSOFTDISCONNECT error.
DENYSOFT is used to prevent configuration errors from rejecting valid mail.

To enable support for PROXY you must create a haproxy_hosts configuration
file which should contain a list of IP addresses of the HAProxy hosts
that should be allowed to send the PROXY command. A range of IP
addresses can be specified by it's CIDR network address.

When a host connects to Haraka that matches an IP address present in the
haproxy_hosts file - a banner is not sent, instead Haraka waits for the
PROXY command to be sent before proceeding. The connection will timeout
with 421 PROXY timed out if the command is not sent within 30 seconds.

NOTE: because Haraka does not send a banner when a listed HAProxy host
connects you must set check-send-proxy to ensure that the service checks
send a PROXY command before they run.

[1] http://haproxy.1wt.eu/download/1.5/doc/proxy-protocol.txt

HAProxy supports the PROXY protocol in version 1.5 or later however there
are patches available to add support for 1.4.

Here is an example listener section for haproxy.cfg:

listen smtp :25
        mode tcp
        option tcplog
        option smtpchk
        balance roundrobin
        server smtp1 ip.of.haraka.server1:25 check-send-proxy check inter 10s send-proxy
        server smtp2 ip.of.haraka.server2:25 check-send-proxy check inter 10s send-proxy
        server smtp3 ip.of.haraka.server3:25 check-send-proxy check inter 10s send-proxy
        server smtp4 ip.of.haraka.server4:25 check-send-proxy check inter 10s send-proxy
        server smtp5 ip.of.haraka.server5:25 check-send-proxy check inter 10s send-proxy

The important part is send-proxy which causes HAProxy to send the PROXY
extension on connection.

When using option smtpchk you will see CONNRESET errors reported in the Haraka logs as
smtpchk drops the connection before the HELO response is still being written.
You can use the option tcp-check instead to provide a better service check by having
the check wait for the banner, send QUIT and then check the response:

option tcp-check
    tcp-check expect rstring ^220\ 
    tcp-check send QUIT\r\n
    tcp-check expect rstring ^221\

File: content/6.core/8.Logging_API.md Copy Chapter

title: Logging API _path: /core/Logging_API Copy Chapter

Logging API

Logging conventions within Haraka

See also Copy Chapter

https://github.com/haraka/Haraka/pull/119

logline will always always be in the form:

[level] [connection uuid] [origin] message

where origin is "haraka_core" or the name of the plugin which
triggered the message, and "connection uuid" is the ID of the
connection associated with the message.

when calling a log method on logger, you should provide the
plugin object and the connection object anywhere in the arguments
to the log method.

logger.logdebug("i like turtles", plugin, connection);

will yield, for example,

[DEBUG] [7F1C820F-DC79-4192-9AA6-5307354B20A6] [dnsbl] i like turtles

if you call the log method on the connection object, you can
forego the connection as argument:

connection.logdebug("turtles all the way down", plugin);

and similarly for the log methods on the plugin object:

plugin.logdebug("he just really likes turtles", connection);

failing to provide a connection and/or plugin object will leave
the default values in the log (currently "core" and
"no_connection").

this is implemented by testing for argument type in
the logger.js log* method. objects-as-arguments are then sniffed
to try to determine if they're a connection or plugin instance.

File: content/6.core/9.Header.md Copy Chapter

title: Header Object _path: /core/Header Copy Chapter

Header object

This documentation has moved to haraka/email-message.