listener – Manage NGINX Unit listener

Manage NGINX Unit listener configuration.

Upstream docs are at https://unit.nginx.org/configuration/#listeners.

Examples

- name: Create new listener (applications/test must exist)
  steampunk.unit.listener:
    pattern: "127.0.0.1:80"
    pass: applications/test

- name: Create new listener (certificate bundle must exist)
  steampunk.unit.listener:
    pattern: "127.0.0.1:80"
    pass: applications/test
    tls:
      certificate: bundle

- name: Delete listener
  steampunk.unit.listener:
    pattern: "*:3000"
    state: absent

Parameters

pass (optional)

Destination that should receive the incomming requests.

If the destination is not defined at the time of module’s execution, module will abort the operation.

Required if state is present.

type: str
pattern (required)

A pattern that listener will listen to. Pattern also serves as an id that module uses to enforce state.

type: str
provider (optional)

Connection parameters.

type: dict
ca_path (optional)

Path to the CA bundle that should be used to validate the backend certificate.

If this parameter is not set, module will use the CA bundle that python is using.

Can also be set using the UNIT_CA_PATH environment variable.

type: path
endpoint (optional)

HTTP or UNIX uri that should be used to communicate with the Unit.

The uri MUST be prefixed by either http://, https://, or unix://.

By default, modules will try to connect to unix:///var/run/unit/control.sock, and if this socket does not exist, fallback to unix:///var/run/control.unit.sock.

Can also be set using the UNIT_ENDPOINT environment variable.

type: str
password (optional)

Password that is used when the endpoint is protected using the basic authentication.

This parameter is ignored when the enpoint parameter points to an unix socket.

Value is masked in the logs.

Can also be set using the UNIT_ENDPOINT environment variable.

type: str
username (optional)

Username that is used when the enpoint is protected using the basic authentication.

This parameter is ignored when the enpoint parameter points to an unix socket.

Can also be set using the UNIT_ENDPOINT environment variable.

type: str
verify (optional)

Flag that controls the certificate validation.

If you are using self-signed certificates, you can set this parameter to false.

ONLY USE THIS PARAMETER IN DEVELOPMENT SCENARIOS! In you use self-signed certificates in production, see the auth.ca_path parameter.

Can also be set using the UNIT_VERIFY environment variable.

type: bool
default: True
state (optional)

State of the manager resource.

type: str
default: present
choices: present, absent
tls (optional)

SSL/TLS configuration.

type: dict
certificate (optional)

Name of the certificate chain.

If the certificate chain is not already defined, module will report an error.

type: str

Return Values

object (On success and if I(state) == C(present)), complex, )

Object representing NGINX Unit listener.

pattern (always), str, 127.0.0.1:3000)

Listener pattern.

pass (always), str, applications/test)

Destination for incomming requests.

tls (if set), complex, )

SSL/TLS configuration

certificate (always), str, certificates/my-bundle)

Certificate bundle