`blackhole.config`¶

Configuration structure and functionality for testing config validity.

blackhole.config.parse_cmd_args(args)[source]¶

Parse arguments from the command line.

https://kura.gg/blackhole/configuration.html#command-line-options

Parameters: args (list) – Command line arguments.
Returns: Parsed command line arguments.
Return type: argparse.Namespace

blackhole.config.warn_options(config)[source]¶

Warn the user when using certain options.

Parameters: config (Config) – The configuration.

blackhole.config.config_test(args)[source]¶

Test the validity of the configuration file content.

Parameters: args (argparse.Namespace) – Parsed arguments.
Raises: 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.

blackhole.config._compare_uid_and_gid(config)[source]¶

Compare the current user and group and conf settings.

Parameters: config (Config) – The configuration.

class blackhole.config.Config(*args, **kwargs)[source]¶

Configuration module.

Default values are provided as well as self-test functionality to sanity check configuration.

https://kura.gg/blackhole/configuration.html#configuration-options

args = None¶: Arguments parsed from the command line.

config_file = None¶: A file containing configuration values.

load()[source]¶

Load the configuration file and parse.

Raises: ConfigException – When the configuration is invalid.
Returns: Config.

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_option(key)[source]¶

Validate config option is actually… valid…

https://kura.gg/blackhole/configuration.html#configuration-options

Parameters: key (str) – Configuration option.
Raises: ConfigException – When an invalid option is configured.

property workers¶

How many workers to spawn to handle incoming connections.

https://kura.gg/blackhole/configuration.html#workers

Returns: Number of workers. Default: 1
Return type: int

Note

Default value is 1.

A supervisor process will always exist separately from the workers.

property listen¶

Address, port and socket family.

https://kura.gg/blackhole/configuration.html#listen

Returns: Listeners.
Return type: list

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), ]

property tls_listen¶

Address and port and socket family for SSL/TLS connections.

https://kura.gg/blackhole/configuration.html#tls-listen

Returns: TLS listeners. Default: []
Return type: list

property user¶

UNIX user.

https://kura.gg/blackhole/configuration.html#user

Returns: User name.
Return type: str

Note

Defaults to the current user.

property group¶

UNIX group.

https://kura.gg/blackhole/configuration.html#group

Returns: Group name.
Return type: str

Note

Defaults to the current group.

property timeout¶

Timeout in seconds.

https://kura.gg/blackhole/configuration.html#timeout

Returns: Timeout in seconds. Default: 60
Return type: int

Note

Defaults to 60 seconds. Cannot be more 180 seconds for security (denial of service).

property tls_key¶

TLS key file.

https://kura.gg/blackhole/configuration.html#tls-key

Returns: Path to a TLS key file. Default: None
Return type: str

property tls_cert¶

TLS certificate file.

https://kura.gg/blackhole/configuration.html#tls-cert

Returns: Path to a TLS certificate. Default: None
Return type: str

property tls_dhparams¶

Diffie Hellman ephemeral parameters.

https://kura.gg/blackhole/configuration.html#tls-dhparams

Returns: Path to a file containing dhparams. Default: None
Return type: str

property pidfile¶

Path to store the pid.

https://kura.gg/blackhole/configuration.html#pidfile

Returns: Path to a pid file. Default: /tmp/blackhole.pid.
Return type: str

property delay¶

Delay in seconds.

https://kura.gg/blackhole/configuration.html#delay

Returns: Delay in seconds. Default: None
Return type: int or None

Note

Defaults to None. Cannot be higher than 60 seconds for security (denial of service).

property mode¶

Mode with which to respond.

https://kura.gg/blackhole/configuration.html#mode

Returns: A response mode. Default: accept.
Return type: str

Note

Defaults to ‘accept’. Options: ‘accept’, ‘bounce’ and ‘random’.

property max_message_size¶

Maximum size, in bytes, of a message.

https://kura.gg/blackhole/configuration.html#max-message-size

Returns: Maximum message size in bytes. Default: 512000.
Return type: int

Note

Default 512000 bytes (512 KB).

property dynamic_switch¶

Enable or disable dynamic switches.

https://kura.gg/blackhole/configuration.html#dynamic-switch

Returns: Whether dynamic switches are enabled or not. Default: True.
Return type: bool

Note

Allowed values are True and False. Default: True

flags_from_listener(addr, port)[source]¶

Get a list of flags defined for the provided listener.

Scope: listen, tls_listen.

Parameters

addr (str) – The listener host address.
port (int) – The listener port.

Returns

Flags defined for this socket. Default: {}.

Return type

dict

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

create_flags(parts)[source]¶

Create a set of flags from a listener directive.

Parameters: parts (list) – Parts of the listener definition.
Returns: Flags for a listener. Default: {}.
Return type: dict

test()[source]¶

Test configuration validity.

Returns: The configuration object.
Return type: Config

Note

Uses the magic of inspect.getmembers to introspect methods beginning with 'test_' and calling them.

test_workers()[source]¶

Validate the number of workers.

Raises: ConfigException – If an invalid number of workers is provided.

Note

Cannot have more workers than number of processors or cores.

test_ipv6_support()[source]¶

If an IPv6 listener is configured, confirm IPv6 is supported.

Raises: ConfigException – If IPv6 is configured but is not supported by the operating system.

test_tls_ipv6_support()[source]¶

If an IPv6 listener is configured, confirm IPv6 is supported.

Raises: ConfigException – If IPv6 is configured but is not supported by the operating system.

test_same_listeners()[source]¶

Test that multiple listeners are not configured on the same port.

Raises: 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_no_listeners()[source]¶

Test that at least one listener is configured.

Raises: ConfigException – When no listeners are configured.

test_port()[source]¶

Validate port number.

Raises: ConfigException – When a port is configured that we have no permissions for.

test_user()[source]¶

Validate user exists in UNIX password database.

Raises: ConfigException – When the user cannot be accessed on the operating system.

Note

Defaults to getpass.getuser if no user is specified.

test_group()[source]¶

Validate group exists in UNIX group database.

Raises: ConfigException – When the group cannot be accessed on the operating system.

Note

Defaults to grp.getgrgid.gr_name if no group is specified.

test_timeout()[source]¶

Validate timeout - only allow a valid integer value in seconds.

Raises: ConfigException – When the timeout is not a number or is above the maximum allowed value of 180.

test_tls_port()[source]¶

Validate TLS port number.

Raises: ConfigException – When a port is configured that we have no permissions for.

test_tls_settings()[source]¶

Validate TLS configuration.

Raises: ConfigException – When the TLS configuration is invalid.

Note

Verifies if you provide all TLS settings, not just some.

test_tls_dhparams()[source]¶

Validate Diffie Hellman ephemeral parameters.

Raises: ConfigException – When the dhparams file is invalid.

Note

Verifies Diffie Hellman ephemeral parameters are readable.

test_delay()[source]¶

Validate the delay period.

Raises: 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.

test_mode()[source]¶

Validate the response mode.

Raises: ConfigException – When an invalid mode is configured.

Note

Valid options are: ‘accept’, ‘bounce’ and ‘random’.

test_max_message_size()[source]¶

Validate max_message size is an integer.

Raises: ConfigException – When the maximum message size is not a number.

test_pidfile()[source]¶

Validate that the pidfile can be written to.

Raises: ConfigException – When the pidfile is invalid.

test_dynamic_switch()[source]¶

Validate that the dynamic_switch value is correct.

Raises: ConfigException – When the dynamic switch value is invalid.

Table Of Contents

blackhole.config¶

`blackhole.config`¶