route – Manage NGINX Unit route¶

Manage NGINX Unit route configuration.

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

Examples¶

- name: Route with a complex matching rule step and a static fallback step
  steampunk.unit.route:
    name: complex
    steps:
      - match:
          uri: /admin/*
          scheme: https
          arguments:
            mode: strict
            access: "!raw"
          cookies:
            user_role: admin
        action:
          pass: applications/cms
      - action:
          share: /www/static/


- name: Global routes for an imaginary blog site
  steampunk.unit.route:
    global: true
    steps:
      - match:
          host: blog.example.com/admin
          source: "*:8000-9000"
        action:
          pass: applications/blogs/admin
      - match:
          host:
            - blog.example.com
            - blog.*.org
          source: "*:8000-9000"
        action:
          pass: applications/blogs/core

- name: Static file serving with fallbacks
  steampunk.unit.route:
    name: static-site
    steps:
      - action:
          share: /www/static/
          fallback:
            share: /old/static/
            fallback:
              return 404

Parameters¶

global (optional)

Do not create or delete named routes and act on a global route.

type: bool

name (optional)

Name of the route to manage.

Required if global is false. If global is true, this parameter is ignored.

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

steps (optional)

Route steps that are matched sequentially.

Required if state is present.

type: list

action (required)

Action to take if the step’s matches.

See https://unit.nginx.org/configuration/#request-handling for more details about all possible combinations of options.

type: dict

fallback (optional)

A fallback route step that is taken if the file listed in the static parameter is not found or cannot be accessed.

Format of this field is a nested route step. See nested routing example for more information about the format.

type: dict

location (optional)

The location taht request should be redirected to.

type: str

pass (optional)

Route’s destination.

type: str

proxy (optional)

Socket address of an HTTP server where the request is proxied.

type: str

return (optional)

The HTTP response status code to be returned.

Use the location paramter to specfy redirection target if status code implies one.

type: int

share (optional)

A static path from where files are served upon a match.

Use fallback option to specify what happens if the path is not accessible.

type: str

match (optional)

Step’s conditions to be matched.

See https://unit.nginx.org/configuration/#condition-matching for more details about matching, case sensitivity of matches, etc.

type: dict

arguments (optional)

Parameter arguments supplied in the request URI.

See https://unit.nginx.org/configuration/#compound-matching for more information about the format and semantics.

type: list

cookies (optional)

Cookies supplied with the request.

See https://unit.nginx.org/configuration/#compound-matching for more information about the format and semantics.

type: list

destination (optional)

Target IP address and optional port of the request.

See https://unit.nginx.org/configuration/#simple-matching for more information about the format and semantics.

type: list

headers (optional)

Header fields supplied with the request.

See https://unit.nginx.org/configuration/#compound-matching for more information about the format and semantics.

type: list

host (optional)

Host from the Host header field without port number, normalized by removing the trailing period (if any).

See https://unit.nginx.org/configuration/#simple-matching for more information about the format and semantics.

type: list

method (optional)

Method from the request line.

See https://unit.nginx.org/configuration/#simple-matching for more information about the format and semantics.

type: list

scheme (optional)

URI scheme.

See https://unit.nginx.org/configuration/#simple-matching for more information about the format and semantics.

type: str

choices: http, https

source (optional)

Source IP address and optional port of the request.

See https://unit.nginx.org/configuration/#simple-matching for more information about the format and semantics.

type: list

uri (optional)

URI path without arguments.

See https://unit.nginx.org/configuration/#simple-matching for more information about the format and semantics.

type: list

Return Values¶

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

Object representing NGINX Unit route.

name (always), str, my-route)

Route name (can be None for global routes).

steps (always), list, )

List of steps in route

match (if specified), dict, )

Step’s conditions to be matched.

arguments (if specified), list, ): Parameter arguments supplied in the request URI.
cookies (if specified), list, ): Cookies supplied with the request.
destination (if specified), list, ): Target IP address and optional port of the request.
headers (if specified), list, ): Header fields supplied with the request.
host (if specified), list, ): Host from the Host header field without port number.
method (if specified), list, ): Method from the request line.
scheme (if specified), str, ): URI scheme.
source (if specified), list, ): Source IP address and optional port of the request.
uri (if specified), list, ): URI path without arguments.

action (always), dict, )

Action to take if the step’s matches.

pass (if specified), str, ): Route’s destination.
share (if specified), str, ): A static path from where files are served upon a match.
fallback (if specified), dict, ): A fallback route step.
proxy (if specified), str, ): Socket address of an HTTP server where the request is proxied.
return (if specified), int, ): The HTTP response status code to be returned.
location (if specified), str, ): The location taht request should be redirected to.