Configuration options can be passed via the command line as below:
show this help message and exit
show program’s version number and exit
override the default configuration options
perform a configuration test and exit
enable debugging mode
run in the background
Disable ssl.OP_SINGLE_DH_USE and ssl.OP_SINGLE_ECDH_USE. Reduces CPU overhead at the expense of security. Don’t use this option unless you really need to. – added in 2.0.13
Suppress warnings when using -ls/–less-secure, running as root or not using tls_dhparams option.
Here are all available options for the configuration file, their default values and information on what the options actually do.
From 2.1.8 onwards the blackhole_config command will also display this information directly from the command line.
listen = [address]:port [mode=MODE] [delay=DELAY]
127.0.0.1:25, 127.0.0.1:587, :::25, :::587 – 25 is the recognised SMTP port, 587 is the recognised SMTP Submission port. IPv6 listeners are only enabled if IPv6 is supported.
mode= and delay= – allows setting a response mode and delay per listener.
2.0.8 – introduced the new IPv6 aware syntax 2.1.5 – added optional mode and delay flags
:25 is equivalent to listening on port 25 on all IPv4 addresses and :::25is equivalent to listening on port 25 on all IPv6 addresses.
Multiple addresses and ports can be listed on a single line.
listen = 10.0.0.1:25, 10.0.0.2:25, :25, :::25, :587, :::587
The mode= and delay= flags allow specific ports to act in specific ways. i.e. you could accept all mail on 10.0.0.1:25 and bounce it all on 10.0.0.2:25, as below.
listen = 10.0.0.1:25 mode=accept, 10.0.0.2:25 mode=bounce
The mode= and delay= flags may also be specified together, as required.
listen = 10.0.0.1:25 mode=accept delay=5, 10.0.0.2:25 mode=bounce delay=10
The flags accept the same options as Dynamic Switches, including setting a delay range.
tls_listen = [address]:port [mode=MODE] [delay=DELAY]
None – 465 is the recognised SMTPS port *.
mode= and delay= – allows setting a response mode and delay per listener.
2.0.8 – introduced the new IPv6 aware syntax 2.1.5 – added optional mode and delay flags
:465 is equivalent to listening on port 465 on all IPv4 addresses and :::465 is equivalent to listening on port 465 on all IPv6 addresses.
Multiple addresses and ports can be listed on a single line.
tls_listen = 10.0.0.1:465, 10.0.0.2:465, :465, :::465
The mode= and delay= flags allow specific ports to act in specific ways. i.e. you could accept all mail on 10.0.0.1:465 and bounce it all on 10.0.0.2:465, as below.
tls_listen = 10.0.0.1:465 mode=accept, 10.0.0.2:465 mode=bounce
The mode= and delay= flags may also be specified together, as required.
tls_listen = 10.0.0.1:465 mode=accept delay=5, 10.0.0.2:465 mode=bounce delay=10
The flags accept the same options as Dynamic Switches, including setting a delay range.
Port 465 – while originally a recognised port for SMTP over SSL/TLS – is no longer advised for use. It’s listed here because it’s a well known and well used port, but also because Blackhole currently does not support STARTTLS over SMTP or SMTP Submission. – https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.txt
user = user
The current Linux user
Blackhole will set it’s process owner to the value provided with this options. Ports below 1024 require sudo or root privileges, this option is available so that the process can be started, listen on privileged ports and then give up those privileges.
user = blackhole
group = group
The primary group of the current Linux user
Blackhole will set it’s process group to the value provided with this options.
group = blackhole
pidfile = /path/to/file.pid
/tmp/blackhole.pid
Blackhole will write it’s Process ID to this file, allowing you to easily track the process and send signals to it.
pidfile = /var/run/blackhole.pid
timeout = seconds
60 – Maximum value of 180 seconds.
This is the amount of time to wait for a client to send data. Once the timeout value has been reached with no data being sent by the client, the connection will be terminated and a 421 Timeout message will be sent to the client.
Helps mitigate DoS risks.
timeout = 30
tls_cert = /path/to/certificate.pem
None
The certificate file in x509 format for wrapping a connection in SSL/TLS.
tls_cert = /etc/ssl/certs/blackhole.crt
tls_key = /path/to/private.key
None
The private key of the tls_cert.
tls_key = /etc/ssl/private/blackhole.key
tls_dhparams = /path/to/dhparams.pem
None
File containing Diffie Hellman ephemeral parameters for ECDH ciphers.
tls_dhparams = /etc/ssl/dhparams.pem
delay = seconds
None – Maximum value of 60 seconds.
Time to delay before returning a response to a completed DATA command. You can use this to delay testing or simulate lag.
delay = 30
mode = accept | bounce | random
accept – valid options are:- accept, bounce, random.
mode = random
max_message_size = bytes
512000 Bytes (512 KB)
The maximum message size for a message. This includes headers and helps mitigate a DoS risk.
max_message_size = 1024000
dynamic_switch = true | false
true – valid options are:- true, false.
The dynamic switch option allows you to enable or disable parsing of dynamic switches from email headers – Dynamic Switches
dynamic_switch = false
workers = number
1
The workers option allows you to define how many worker processes to spawn to handle incoming mail. The absolute minimum is actually 2. Even by setting the workers value to 1, a supervisor process will always exist meaning that you would have 1 worker and a supervisor.
Currently asyncio does not have the code in place to make STARTTLS possible, the STARTTLS verb returns a 500 Not implemented response until it’s possible to implement. –https://bugs.python.org/review/23749/
Blackhole has builtin support for the following features. While these are not required for the service to run, they do improve it the server in various ways.
uvloop is a fast, drop-in replacement of the built-in asyncio event loop. uvloop is implemented in Cython and uses libuv under the hood.
Using uvloop with Blackhole is as simple as installing libuv and the Blackhole extra package.
On Debian/Ubuntu it’s as simple as installing via APT and Pip respectively.
apt-get install libuv1 libuv1-dev python-dev
pip install blackhole[uvloop]
setproctitle is a simple library that allows Blackhole to set a more ps aux-friendly output for the blackhole processes.
# without setproctitle
python3 /home/kura/.virtualenvs/blackhole/bin/blackhole -c test.conf -d
python3 /home/kura/.virtualenvs/blackhole/bin/blackhole -c test.conf -d
# with setproctitle
blackhole: master
blackhole: worker
You can install setproctitle with the Blackhole extra package.
pip install blackhole[setproctitle]
The init script depends on /etc/blackhole.conf being in place and configured.
Blackhole comes with a script that works with init.d/rc.d, to install it copy it from the init.d/YOUR_DISTRO folder in the root directory of this project to /etc/init.d/.
The init scripts can be found here.
i.e. for Debian/Ubuntu users, mv the file from init.d/debian-ubuntu/ to /etc/init.d/.
Then make sure it’s executable
chmod +x /etc/init.d/blackhole
To make blackhole start on a reboot use the following:
update-rc.d blackhole defaults