.\" Man page generated from reStructuredText.
.
.TH VMOD_SAINTMODE 3 "" "" ""
.SH NAME
vmod_saintmode \- Saint mode backend director
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.\" 
.
.\" NB:  This file is machine generated, DO NOT EDIT!
.
.\" 
.
.\" Edit vmod.vcc and run make instead
.
.\" 
.
.SH SYNOPSIS
.sp
import saintmode [from "path"] ;
.SH DESCRIPTION
.sp
This VMOD provides saintmode functionality for Varnish Cache 4.1 and
newer. The code is in part based on Poul\-Henning Kamp\(aqs saintmode
implementation in Varnish 3.0.
.sp
Saintmode lets you deal with a backend that is failing in random ways
for specific requests. It maintains a blacklist per backend, marking
the backend as sick for specific objects. When the number of objects
marked as sick for a backend reaches a set threshold, the backend is
considered sick for all requests. Each blacklisted object carries a
TTL, which denotes the time it will stay blacklisted.
.sp
Saintmode in Varnish 4.1 is implemented as a director VMOD. We instantiate a
saintmode object and give it a backend as an argument. The resulting object can
then be used in place of the backend, with the effect that it also has added
saintmode capabilities.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
vcl 4.0;

import saintmode;
import directors;

backend tile1 { .host = "192.0.2.11"; .port = "80"; }
backend tile2 { .host = "192.0.2.12"; .port = "80"; }

sub vcl_init {
        # Instantiate sm1, sm2 for backends tile1, tile2
        new sm1 = saintmode.saintmode(tile1, 10);
        new sm2 = saintmode.saintmode(tile2, 10);

        # Add both to a director. Use sm0, sm1 in place of tile1, tile2.
        new imagedirector = directors.random();
        imagedirector.add_backend(sm1.backend(), 1);
        imagedirector.add_backend(sm2.backend(), 1);
}

sub vcl_backend_fetch {
        set bereq.backend = imagedirector.backend();
}

sub vcl_backend_response {
        if (beresp.status >= 500) {
                # This marks the backend as sick for this specific
                # object for the next 20s.
                saintmode.blacklist(20s);
                return (retry);
        }
}
.ft P
.fi
.UNINDENT
.UNINDENT
.SH CONTENTS
.INDENT 0.0
.IP \(bu 2
\fIfunc_blacklist\fP
.IP \(bu 2
\fIobj_saintmode\fP
.IP \(bu 2
\fIfunc_saintmode.backend\fP
.UNINDENT
.SS blacklist
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
VOID blacklist(PRIV_VCL, DURATION expires)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Marks the backend as sick for a specific object. Used in vcl_backend_response.
Corresponds to the use of \fBberesp.saintmode\fP in Varnish 3.0. Only available
in vcl_backend_response.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sub vcl_backend_response {
    if (beresp.http.broken\-app) {
        saintmode.blacklist(20s);
        return (retry);
    }
}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS saintmode
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
new OBJ = saintmode(PRIV_VCL, BACKEND backend, INT threshold)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Constructs a saintmode director object. The \fBthreshold\fP argument sets
the saintmode threshold, which is the maximum number of items that can be
blacklisted before the whole backend is regarded as sick. Corresponds with the
\fBsaintmode_threshold\fP parameter of Varnish 3.0.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sub vcl_init {
    new sm = saintmode.saintmode(b, 10);
}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS saintmode.backend
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
BACKEND saintmode.backend()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Used for assigning the backend from the saintmode object.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sub vcl_backend_fetch {
    set bereq.backend = sm.backend();
}
.ft P
.fi
.UNINDENT
.UNINDENT
.\" Generated by docutils manpage writer.
.