# haproxy – Enable, disable, and set weights for HAProxy backend servers using socket commands

- Synopsis

- Parameters

- Notes

- Examples

- Status

## Synopsis

- Enable, disable, drain and set weights for HAProxy backend servers using socket commands.

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---
backend string |  | Name of the HAProxy backend pool. If this parameter is unset, it will be auto-detected.

drain
boolean
added in 2.4

Choices:
- no
- yes

Wait until the server has no active connections or until the timeout determined by wait_interval and wait_retries is reached.
Continue only after the status changes to 'MAINT'.
This overrides the shutdown_sessions option.

fail_on_not_found
boolean

Choices:
- no ←
- yes

Fail whenever trying to enable/disable a backend host that does not exist

host string / required |  | Name of the backend host to change.

shutdown_sessions
boolean

Choices:
- no ←
- yes

When disabling a server, immediately terminate all the sessions attached to the specified server.
This can be used to terminate long-running sessions after a server is put into maintenance mode. Overridden by the drain option.

socket path | Default: "/var/run/haproxy.sock" | Path to the HAProxy socket file.

state
string / required

Choices:
- disabled
- drain
- enabled

Desired state of the provided backend host.
Note that `drain` state was added in version 2.4.
It is supported only by HAProxy version 1.5 or later,
When used on versions < 1.5, it will be ignored.

wait
boolean

Choices:
- no ←
- yes

Wait until the server reports a status of 'UP' when `state=enabled`, status of 'MAINT' when `state=disabled` or status of 'DRAIN' when `state=drain`

wait_interval integer | Default: 5 | Number of seconds to wait between retries.
wait_retries integer | Default: 25 | Number of times to check for status after changing the state.
weight string |  | The value passed in argument. If the value ends with the `%` sign, then the new weight will be relative to the initially configured weight. Relative weights are only permitted between 0 and 100% and absolute weights are permitted between 0 and 256.

## Notes

Note

- Enable, disable and drain commands are restricted and can only be issued on sockets configured for level ‘admin’. For example, you can add the line ‘stats socket /var/run/haproxy.sock level admin’ to the general section of haproxy.cfg. See http://haproxy.1wt.eu/download/1.5/doc/configuration.txt.

- Depends on netcat (nc) being available; you need to install the appropriate package for your operating system before this module can be used.

## Examples

    - name: Disable server in 'www' backend pool
      haproxy:
        state: disabled
        host: '{{ inventory_hostname }}'
        backend: www

    - name: Disable server without backend pool name (apply to all available backend pool)
      haproxy:
        state: disabled
        host: '{{ inventory_hostname }}'

    - name: Disable server, provide socket file
      haproxy:
        state: disabled
        host: '{{ inventory_hostname }}'
        socket: /var/run/haproxy.sock
        backend: www

    - name: Disable server, provide socket file, wait until status reports in maintenance
      haproxy:
        state: disabled
        host: '{{ inventory_hostname }}'
        socket: /var/run/haproxy.sock
        backend: www
        wait: yes

    # Place server in drain mode, providing a socket file.  Then check the server's
    # status every minute to see if it changes to maintenance mode, continuing if it
    # does in an hour and failing otherwise.
    - haproxy:
        state: disabled
        host: '{{ inventory_hostname }}'
        socket: /var/run/haproxy.sock
        backend: www
        wait: yes
        drain: yes
        wait_interval: 1
        wait_retries: 60

    - name: Disable backend server in 'www' backend pool and drop open sessions to it
      haproxy:
        state: disabled
        host: '{{ inventory_hostname }}'
        backend: www
        socket: /var/run/haproxy.sock
        shutdown_sessions: yes

    - name: Disable server without backend pool name (apply to all available backend pool) but fail when the backend host is not found
      haproxy:
        state: disabled
        host: '{{ inventory_hostname }}'
        fail_on_not_found: yes

    - name: Enable server in 'www' backend pool
      haproxy:
        state: enabled
        host: '{{ inventory_hostname }}'
        backend: www

    - name: Enable server in 'www' backend pool wait until healthy
      haproxy:
        state: enabled
        host: '{{ inventory_hostname }}'
        backend: www
        wait: yes

    - name: Enable server in 'www' backend pool wait until healthy. Retry 10 times with intervals of 5 seconds to retrieve the health
      haproxy:
        state: enabled
        host: '{{ inventory_hostname }}'
        backend: www
        wait: yes
        wait_retries: 10
        wait_interval: 5

    - name: Enable server in 'www' backend pool with change server(s) weight
      haproxy:
        state: enabled
        host: '{{ inventory_hostname }}'
        socket: /var/run/haproxy.sock
        weight: 10
        backend: www

    - name: Set the server in 'www' backend pool to drain mode
      haproxy:
        state: drain
        host: '{{ inventory_hostname }}'
        socket: /var/run/haproxy.sock
        backend: www

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]

- This module is maintained by the Ansible Community. [community]

### Authors

- Ravi Bhure (@ravibhure)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.