summaryrefslogtreecommitdiffabout
path: root/src/varnish-mib.8
authorSergey Poznyakoff <gray@nxc.no>2018-02-05 19:56:59 (GMT)
committer Sergey Poznyakoff <gray@nxc.no>2018-02-05 19:56:59 (GMT)
commitf7677f32b90eea37e54b39a3e26e5437924a2ada (patch) (side-by-side diff)
tree4112eecd0acecd664e613fd1b66dd177b7ab87ba /src/varnish-mib.8
parent027e83b6f5dc6a63ed9c69e534c0b994041df14f (diff)
downloadvarnish-mib-f7677f32b90eea37e54b39a3e26e5437924a2ada.tar.gz
varnish-mib-f7677f32b90eea37e54b39a3e26e5437924a2ada.tar.bz2
Version 2.0
Diffstat (limited to 'src/varnish-mib.8') (more/less context) (ignore whitespace changes)
-rw-r--r--src/varnish-mib.885
1 files changed, 57 insertions, 28 deletions
diff --git a/src/varnish-mib.8 b/src/varnish-mib.8
index 8d86f18..77912af 100644
--- a/src/varnish-mib.8
+++ b/src/varnish-mib.8
@@ -1,8 +1,8 @@
.\" This file is part of Varnish-mib -*- nroff -*-
-.\" Copyright (C) 2014-2016 Sergey Poznyakoff
+.\" Copyright (C) 2014-2018 Sergey Poznyakoff
.\"
.\" Varnish-mib is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 3, or (at your option)
.\" any later version.
.\"
@@ -10,43 +10,69 @@
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with Varnish-mib. If not, see <http://www.gnu.org/licenses/>.
-.TH VARNISH-MIB 8 "February 2, 2018" "varnish-mib"
+.TH VARNISH-MIB 8 "February 5, 2018" "varnish-mib"
.SH NAME
-varnish\-mib \- net-snmp module for obtaining Varnish Cache statistics
+varnish\-mib \- Net-SNMP module for Varnish Cache monitoring
.SH SYNOPSIS
In \fBsnmpd.conf\fR(5):
.PP
.B dlmod varnish_mib /usr/lib/snmp/varnish\-mib.so
.SH DESCRIPTION
Dynamically loadable object module for
.B net-snmp
that provides access to Varnish Cache statistics. The module is
loaded into
.BR snmpd (8)
as shown above (actual path can of course differ, depending on how
-the package was configured). The module is written for Varnish
-version \fB5.\fIX\fR.
+the package was configured). This version is written for Varnish
+\fB5.2.0\fR.
.PP
-The module obtains most of the data using Varnish API, and \fBvarnishd\fR
-administrative interface. You should make sure that \fBsnmpd\fR is
-able to access both data sources.
+The values in the OID branches
+.BR client ,
+.BR total ,
+.BR master ,
+.BR session ,
+.BR threads ", and "
+.B objects
+are obtained from Varnish API.
.PP
-The user \fBsnmpd\fR runs as should be able to read contents of the
-\fB/var/lib/varnish/\fIHOSTNAME\fB/_.vsm_mgt\fR directory and read
-files located in it. It must also have read permission on the varnish
-secret file.
+The OID branches
+.BR backend ,
+.BR bans ", and "
+.B vcl
+are obtained using \fBvarnishd\fR administrative interface (similar
+to
+.BR varnishadm (8)).
+.PP
+To retrieve this information, the module must
+have enough permissions to scan the Varnish management directory and
+read files located in it. This directory is normally named
+\fB/var/lib/varnish/\fIHOSTNAME\fB/_.vsm_mgt\fR, where \fIHOSTNAME\fR
+stands for the server's hostname. Unless
+.BR snmpd (8)
+is run as root, special measures should be undertaken in order to
+grant access rights. For example, if the daemon runs as user
+\fBsnmp\fR, running the following two commands after starting
+\fBvarnishd\fR will do the trick:
+
+.EX
+ setfacl -m u:snmp:rx /var/lib/varnish/$(hostname)/_.vsm_mgt
+ setfacl -m u:snmp:r /var/lib/varnish/$(hostname)/_.vsm_mgt/*
+.EE
+.PP
+
.SH CONFIGURATION OPTIONS
Configuration statements specific to
.B varnish\-mib
must appear in the
.B snmpd.conf
-file below the
+file, after the
.B dlmod
statement that loads the module.
.PP
The following configuration statements are available:
.TP
\fBvarnishBanTableTimeout\fR \fINUMBER\fR
@@ -61,42 +87,44 @@ statement.
Update interval for \fBbackendTable\fR. Default is 5 seconds.
.TP
\fBvarnishCLIPortTimeout\fR \fINUMBER\fR
Sets timeout for I/O operations with Varnish administrative port.
Default is 5 seconds.
.PP
-The following two statements are not normally needed, since
-\fBvarnish-mib\fR obtains this information automatically.
+The following two statements are not normally needed, but are
+provided for completeness sake:
.TP
\fBvarnishCLISocket\fR \fIADDRESS\fR[:\fIPORT\fR]
Sets the address of Varnish administrative interface
socket.
.TP
\fBvarnishCLISecretFile\fR \fIFILE\fR
-Pathname of the Varnish secret file.
+Sets the pathname of the Varnish secret file.
.SH DEBUGGING
The module defines the following debugging tokens:
.TP
.B varnish_mib
-General debugging information.
+Produces general debugging information.
.TP
.B varnish_mib:ban
-Debug ban table loading.
+Outputs verbose report about loading th ban table.
.TP
.B varnish_mib:vcli
-Varnish
+Displays additional information regarding varnish
.B CLI
interaction.
.TP
.B varnish_mib:vcli:transcript
-Enables full transcript of CLI interaction.
+Enables full transcript of varnish CLI session.
.TP
.B varnish_mib:backend
-Debug loading the backend information.
+Outputs verbose information about loading the backend information.
.SH OIDS
-The following OIDs are defined:
+The following OIDs are defined in the
+.B VARNISH-MIB.txt
+file:
.SS Branch \(dqclient\(dq
.TP
.B clientAcceptedConnections
Number of accepted connections.
.TP
.B clientRequestsReceived
@@ -119,15 +147,15 @@ Client requests received, subject to 400 errors.
.TP
.B clientBan
A write-only OID. When set, invalidates the cache using the supplied
value as argument to ban. When read, returns an empty string. E.g.,
to invalidate caches of all \fBpng\fR images:
-.EE
-snmpset \fBhostname\fR VARNISH\-MIB::clientBan.0 s 'req.url ~ \(dq\\.png$\(dq'
.EX
+snmpset \fIhostname\fR VARNISH\-MIB::clientBan.0 s 'req.url ~ \(dq\\.png$\(dq'
+.EE
.SS Branch \(dqbackend\(dq
.TP
.B backendConnSuccess
Number of successful connections to the backend.
.TP
.B backendConnNotAttempted
@@ -255,13 +283,14 @@ Number of times session was queued waiting for a thread.
Number of sessions dropped because session queue was full.
.TP
.B sessClosed
Number of sessions closed.
.TP
.B sessPipeline
-Session pipeline. This variable is available only in Varnish version \fR4.0\fR.
+This OID was used in Varnish \fR4.1\fR, but disappeared from version
+\fB5.0\fR.
.TP
.B sessReadAhead
Session read-ahead.
.TP
.B sessHerd
Session herd.
@@ -270,14 +299,14 @@ Session herd.
Number of sessions dropped for thread.
.TP
.B sessFail
Number of session accept failures.
.TP
.B sessPipeOverflow
-Number of session pipe overflows. This variable is available only in
-Varnish version \fR4.0\fR.
+This OID was used in Varnish \fR4.1\fR, but disappeared in version
+\fB5.0\fR.
.SS Branch \(dqthreads\(dq
.TP
.B threadsPools
Number of thread pools.
.TP
.B threadsTotal
@@ -364,13 +393,13 @@ VCL expression of the ban.
Notice that for performance reasons, the ban table is cached, so the
total number of rows in the \fBbanTable\fR may diverge from the value
of \fBbansTotal\fR variable. The default update interval is 60
seconds. It can be configured in the \fBsnmpd.conf\fR file
(see the \fBvarnishBanTableTimeout\fR statement above).
.SS Branch \(dqagent\(dq
-The \fBagent\fR branch is reserved for OIDs for
+The \fBagent\fR branch is reserved for
implementation-specific management. It is not used currently.
.SH NOTES
The following OIDs were used in Varnish 4. They are no longer
available in Varnish 5:
.TP
.B clientRequests411

Return to:

Send suggestions and report system problems to the System administrator.