vmod_directors (3) - Linux Manuals

vmod_directors: Backend traffic directors

Command to display vmod_directors manual in Linux: $ man 3 vmod_directors

NAME

vmod_directors - Backend traffic directors

SYNOPSIS

import directors [from "path"] ;

DESCRIPTION

vmod_directors enables backend load balancing in Varnish.

The module implements a set of basic load balancing techniques, and also serves as an example on how one could extend the load balancing capabilities of Varnish.

To enable load balancing you must import this vmod (directors) in your VCL::

import directors;

Then you define your backends. Once you have the backends declared you can add them to a director. This happens in executed VCL code. If you want to emulate the previous behavior of Varnish 3.0 you can just initialize the directors in vcl_init, like this::

sub vcl_init {
    new vdir = directors.round_robin();
    vdir.add_backend(backend1);
    vdir.add_backend(backend2);
}

As you can see there is nothing keeping you from manipulating the directors elsewhere in VCL. So, you could have VCL code that would add more backends to a director when a certain URL is called.

Note that directors can use other directors as backends.

•: Object fallback
•: VOID fallback.add_backend(BACKEND)
•: BACKEND fallback.backend()
•: Object hash
•: VOID hash.add_backend(BACKEND, REAL)
•: BACKEND hash.backend(STRING_LIST)
•: Object random
•: VOID random.add_backend(BACKEND, REAL)
•: BACKEND random.backend()
•: Object round_robin
•: VOID round_robin.add_backend(BACKEND)
•: BACKEND round_robin.backend()

OBJECT ROUND_ROBIN

Description: Create a round robin director.
This director will pick backends in a round robin fashion.
Example: new vdir = directors.round_robin();

VOID round_robin.add_backend(BACKEND)

Prototype: VOID round_robin.add_backend(BACKEND)
Description: Add a backend to the round-robin director.
Example: vdir.add_backend(backend1); vdir.add_backend(backend2);

BACKEND round_robin.backend()

Prototype: BACKEND round_robin.backend()
Description: Pick a backend from the director.
Example: set req.backend_hint = vdir.backend();

OBJECT FALLBACK

Description: Create a fallback director.
A fallback director will try each of the added backends in turn, and return the first one that is healthy.
Example: new vdir = directors.fallback();

VOID fallback.add_backend(BACKEND)

Prototype: VOID fallback.add_backend(BACKEND)
Description: Add a backend to the director.
Note that the order in which this is done matters for the fallback director.
Example: vdir.add_backend(backend1); vdir.add_backend(backend2);

BACKEND fallback.backend()

Prototype: BACKEND fallback.backend()
Description: Pick a backend from the director.
Example: set req.backend_hint = vdir.backend();

OBJECT RANDOM

Description: Create a random backend director.
The random director distributes load over the backends using a weighted random probability distribution.
Example: new vdir = directors.random();

VOID random.add_backend(BACKEND, REAL)

Prototype: VOID random.add_backend(BACKEND, REAL)
Description: Add a backend to the director with a given weight.
Each backend backend will receive approximately 100 * (weight / (sum(all_added_weights))) per cent of the traffic sent to this director.
Example: vdir.add_backend(backend1, 10); vdir.add_backend(backend2, 5); # 2/3 to backend1, 1/3 to backend2.

BACKEND random.backend()

Prototype: BACKEND random.backend()
Description: Pick a backend from the director.
Example: set req.backend_hint = vdir.backend();

OBJECT HASH

Description

Create a hashing backend director.

The director chooses the backend server by computing a hash/digest of the string given to .backend().

Commonly used with client.identity or a session cookie to get sticky sessions.

Example

new vdir = directors.hash();

VOID hash.add_backend(BACKEND, REAL)

Prototype: VOID hash.add_backend(BACKEND, REAL)
Description: Add a backend to the director with a certain weight.
Weight is used as in the random director. Recommended value is 1.0 unless you have special needs.
Example: vdir.add_backend(backend1, 1.0); vdir.add_backend(backend2, 1.0);

BACKEND hash.backend(STRING_LIST)

Prototype: BACKEND hash.backend(STRING_LIST)
Description: Pick a backend from the backend director.
Use the string or list of strings provided to pick the backend.
Example: set req.backend_hint = vdir.backend(req.http.cookie); # pick a backend based on the cookie header from the client