blackhole.config
¶Configuration structure and functionality for testing config validity.
Parse arguments from the command line.
https://kura.gg/blackhole/configuration.html#command-line-options
args (list) – Command line arguments.
Parsed command line arguments.
Warn the user when using certain options.
config (Config) – The configuration.
Test the validity of the configuration file content.
args (argparse.Namespace) – Parsed arguments.
SystemExit – Exit code os.EX_OK
when config is valid or os.EX_USAGE
when config is invalid.
Note
Problems with the configuration will be written to the console using the logging
module.
Compare the current user and group and conf settings.
config (Config) – The configuration.
Configuration module.
Default values are provided as well as self-test functionality to sanity check configuration.
https://kura.gg/blackhole/configuration.html#configuration-options
Arguments parsed from the command line.
A file containing configuration values.
Load the configuration file and parse.
ConfigException – When the configuration is invalid.
Note
Spaces, single and double quotes will be stripped. Lines beginning # will be ignored. # comments in-line will be stripped out and ignored.
i.e.
# listen = :1025, :::1025 -> listen = :25, :::25 # IPv4 & IPv6 -> listen = :25, :::25
Validate config option is actually… valid…
https://kura.gg/blackhole/configuration.html#configuration-options
key (str) – Configuration option.
ConfigException – When an invalid option is configured.
How many workers to spawn to handle incoming connections.
https://kura.gg/blackhole/configuration.html#workers
Number of workers. Default: 1
Note
Default value is 1.
A supervisor process will always exist separately from the workers.
Address, port and socket family.
https://kura.gg/blackhole/configuration.html#listen
Listeners.
Note
Default IPv4:
- [(‘127.0.0.1’, 25, socket.AF_INET,
(‘127.0.0.1’, 587, socket.AF_INET), ]
Default IPv6:
- [(‘127.0.0.1’, 25, socket.AF_INET),
(‘127.0.0.1’, 587, socket.AF_INET), ]
Address and port and socket family for SSL/TLS connections.
https://kura.gg/blackhole/configuration.html#tls-listen
TLS listeners. Default: []
UNIX user.
https://kura.gg/blackhole/configuration.html#user
User name.
Note
Defaults to the current user.
UNIX group.
https://kura.gg/blackhole/configuration.html#group
Group name.
Note
Defaults to the current group.
Timeout in seconds.
https://kura.gg/blackhole/configuration.html#timeout
Timeout in seconds. Default: 60
Note
Defaults to 60 seconds. Cannot be more 180 seconds for security (denial of service).
TLS key file.
https://kura.gg/blackhole/configuration.html#tls-key
Path to a TLS key file. Default: None
TLS certificate file.
https://kura.gg/blackhole/configuration.html#tls-cert
Path to a TLS certificate. Default: None
Diffie Hellman ephemeral parameters.
https://kura.gg/blackhole/configuration.html#tls-dhparams
Path to a file containing dhparams. Default: None
Path to store the pid.
https://kura.gg/blackhole/configuration.html#pidfile
Path to a pid file. Default: /tmp/blackhole.pid
.
Delay in seconds.
https://kura.gg/blackhole/configuration.html#delay
Note
Defaults to None
. Cannot be higher than 60 seconds for security (denial of service).
Mode with which to respond.
https://kura.gg/blackhole/configuration.html#mode
A response mode. Default: accept
.
Note
Defaults to ‘accept’. Options: ‘accept’, ‘bounce’ and ‘random’.
Maximum size, in bytes, of a message.
https://kura.gg/blackhole/configuration.html#max-message-size
Maximum message size in bytes. Default: 512000
.
Note
Default 512000 bytes (512 KB).
Enable or disable dynamic switches.
https://kura.gg/blackhole/configuration.html#dynamic-switch
Whether dynamic switches are enabled or not. Default: True
.
Get a list of flags defined for the provided listener.
Scope: listen
, tls_listen
.
Flags defined for this socket. Default: {}
.
Note
If multiple modes or delays are listed in a single listener, the last definition will be used:
listen = :25 mode=bounce mode=random
-> mode=random
A mode and delay can be used in tandum:
listen = :25 mode=bounce delay=10
The delay can also be specified as a range:
listen = :25 delay=5-10
Using a delay range will cause the server to choose a random value within that range per connection.
Mode and delay can be defined for each address/port in a listen directive:
listen = :25 mode=bounce, :::25 delay=10, :587 mode=random
Test configuration validity.
The configuration object.
Note
Uses the magic of inspect.getmembers
to introspect methods beginning with 'test_' and calling them.
Validate the number of workers.
ConfigException – If an invalid number of workers is provided.
Note
Cannot have more workers than number of processors or cores.
If an IPv6 listener is configured, confirm IPv6 is supported.
ConfigException – If IPv6 is configured but is not supported by the operating system.
If an IPv6 listener is configured, confirm IPv6 is supported.
ConfigException – If IPv6 is configured but is not supported by the operating system.
Test that multiple listeners are not configured on the same port.
ConfigException – When multiple listeners are configured on the same port.
Note
IPv4 and IPv6 addresses are different sockets so they can listen on the same port because they have different addresses.
Test that at least one listener is configured.
ConfigException – When no listeners are configured.
Validate port number.
ConfigException – When a port is configured that we have no permissions for.
Validate user exists in UNIX password database.
ConfigException – When the user cannot be accessed on the operating system.
Note
Defaults to getpass.getuser
if no user is specified.
Validate group exists in UNIX group database.
ConfigException – When the group cannot be accessed on the operating system.
Note
Defaults to grp.getgrgid.gr_name
if no group is specified.
Validate timeout - only allow a valid integer value in seconds.
ConfigException – When the timeout is not a number or is above the maximum allowed value of 180.
Validate TLS port number.
ConfigException – When a port is configured that we have no permissions for.
Validate TLS configuration.
ConfigException – When the TLS configuration is invalid.
Note
Verifies if you provide all TLS settings, not just some.
Validate Diffie Hellman ephemeral parameters.
ConfigException – When the dhparams file is invalid.
Note
Verifies Diffie Hellman ephemeral parameters are readable.
Validate the delay period.
ConfigException – When the delay is not a number or is above the maximum allowed value of 60.
Note
Delay must be lower than the timeout.
Validate the response mode.
ConfigException – When an invalid mode is configured.
Note
Valid options are: ‘accept’, ‘bounce’ and ‘random’.
Validate max_message size is an integer.
ConfigException – When the maximum message size is not a number.
Validate that the pidfile can be written to.
ConfigException – When the pidfile is invalid.
Validate that the dynamic_switch value is correct.
ConfigException – When the dynamic switch value is invalid.