blackhole.control

Provides control functionality, including socket wrappers.

blackhole.control._context(use_tls=False)

Create a TLS context using the certificate, key and dhparams file.

Parameters

use_tls (bool) – Whether to create a TLS context or not. Default: False.

Returns

A TLS context or None.

Return type

ssl.SSLContext or None.

Note

Created with:

• ssl.OP_NO_SSLv2

• ssl.OP_NO_SSLv3

• ssl.OP_NO_COMPRESSION

• ssl.OP_CIPHER_SERVER_PREFERENCE

Also responsible for loading Diffie Hellman ephemeral parameters if they’re provided – ssl.SSLContext.load_dh_params

If the -ls or --less-secure option is provided, ssl.OP_SINGLE_DH_USE and ssl.OP_SINGLE_ECDH_USEwill be omitted from the context. – https://kura.gg/blackhole/configuration.html#command-line-options– added in 2.0.13

blackhole.control._socket(addr, port, family)

Create a socket, bind and listen.

Parameters

• addr (str) – The address to use.

• port (int) – The port to use.

• family (socket.AF_INET or socket.AF_INET6.) – The type of socket to use.

Returns

Bound socket.

Return type

socket.socket

Raises

BlackholeRuntimeException – When a socket cannot be bound.

blackhole.control.server(addr, port, family, use_tls=False)

Socket and possibly a TLS context.

Create an instance of socket.socket, bind it and return a dictionary containing the socket object and a TLS context if configured.

Parameters

• addr (str) – The address to use.

• port (int) – The port to use.

• family (socket.AF_INET or socket.AF_INET6.) – The type of socket to use.

• use_tls (bool) – Whether to create a TLS context or not. Default: False.

Returns

Bound socket, a TLS context if configured.

Return type

dict

blackhole.control.pid_permissions()

Change the pid file ownership.

Called before blackhole.control.setgid and blackhole.control.setuid are called to stop blackhole.daemon.Daemon losing permissions to modify the pid file.

Raises

SystemExit – With exit code os.EX_USAGE when a permissions error occurs.

blackhole.control.setgid()

Change group.

Change to a less privileged group. Unless you’re using it incorrectly – in which case, don’t use it.

Raises

SystemExit – Exit code os.EX_USAGE when a configuration error occurs or os.EX_NOPERM when a permission error occurs.

Note

MUST be called BEFORE setuid, not after.

blackhole.control.setuid()

Change user.

Change to a less privileged user.Unless you’re using it incorrectly – inwhich case, don’t use it.

Raises

SystemExit – Exit code os.EX_USAGE when a configuration error occurs or os.EX_NOPERM when a permission error occurs.

Note

MUST be called AFTER setgid, not before.