wiki:WebGui

Page Outdated

New VAC Page

This page is outdated. For the latest information on the Varnish Administration Console visit the  Varnish Software website and its  VAC product page.

Varnish Administration Console (only for customers with service agrement)

TOC?

Old Description

The Varnish Administration Console is tool that can be used to administer and monitor your Varnish servers. It lets you

  • create groups of Varnish servers so that they share the VCL configuration and parameters,
  • show graphs and statistics for groups and nodes (servers)
  • change parameters and edit VCLs
  • stop, start and monitor the health of the nodes and backends
  • access the management console manually

The power of the Administration Console is enabled by using the management port of Varnish, a feature seldom used by users new to Varnish. Hopefully VAC will make tweaking and running Varnish somewhat easier.

The concepts of groups (or clusters) is an important feature, and needs some attention. By creating a group, all nodes added to that group will share the same VCLs and parameters, so a node added to that group will have its VCLs discarded and parameters changed.

Requirements

Varnish Administration Console is written in Perl and requires the following modules (package names in parenthesis):

  • HTTP::Daemon (deb: libwww-perl, rpm: perl-libwww-perl)
  • HTML::Template (deb: libhtml-template-perl, rpm: perl-HTML-Template)
  • GD::Graph (deb: libgd-graph-perl, rpm: perl-GD-Graph)
  • LWP::UserAgent? (deb: libwww-perl, rpm: perl-LWP-UserAgent?)
  • Algorithm::Diff (deb: libalgorithm-diff-perl, rpm: perl-Algorithm-Diff)
  • DBD::Sqlite3 (deb: libdbd-sqlite3-perl, rpm: perl-DBD-Sqlite)

It uses HTTP::Daemon to create its own web server, so no external web server is needed.

Configuration

Web server

The configuration of the Varnish Administration Console is done from the startup file, start.pl. It should be fairly well documented, but the configurable items are

address This is the address to bind to. Omit it if you want it to bind to all interfaces.
port The port to listen for incoming HTTP requests.
poll_interval This is the intervall between each statistics collection from the varnish nodes.
restricted Setting this to 1 will disable destructive operations in the web GUI, making the GUI 'read only'.
graph_width, graph_height The width and height of the graphs in 'View stats'.
large_graph_width, large_graph_width The width and height of the enlarged graphs in 'View stats'.
log_filename The name of the log file.
db_filename The name of the Sqlite3 database file

When your configuration looks OK, you must create the Sqlite3 database. The SQL needed for the database is found in the varnish_webgui.sql, so the database can be created like this

sqlite3 varnish.db < varnish_webgui.sql

with 'varnish.db' being the file specified in db_filename.

With the start.pl configured correctly, and the database file created, you should be able to start by running start.pl:

./start.pl

Varnish

All the Varnish servers that are intended to be managed by the Varnish Administration Console must have the management port enabled, since it is used to do all the magic. To enable the management port you must add the -T option to varnishd, e.g.

/opt/varnishd/sbin/varnishd -f config.vcl -a :80 -T 192.168.0,3:9001

Exposing the management port to the world is a big security issue, so make sure you either bind to a local network interface or have a firewall or something similar in front.

The Varnish Administration Console views

View stats

'View stats' shows graphs and statistics for the groups and nodes registered in the Administration Console.

Starting from the top, you see the time for when the data was last collected. The summary section shows graphs and some more or less usefull statistics without giving you all the statistics from Varnish (which is a lot). Each column either a group or a standalone node. To view the group and its nodes you click '(show group)'. The colored dot beside the name of the group or node gives you the running status when the page was loaded. A green dot means everything runs OK, a yellow dot means that one of the nodes in the group did not respond OK, a red dot means that the node, or all the nodes of a group, has stopped. Clicking the dot till take you to the 'Node management' view.

Below each graph you can set the timespan to the last minute, hour, day and week. At the bottom you can turn on raw statistics, which gives you alle the statistics counters. Turning on auto refresh will refresh the page at the rate of the statistics polling of the Varnish nodes, enabling you to follow the data "real time". Clicking the 'Raw data as CSV' vill give you the raw statistics as comma separated values, useful if you want to import it into other systems.

A feature when enabling raw statistics is the possibility to graph the value of the counter in the same way as in the summary section. This is done by clicking the counter for the given node or group. As for the other graphs, it lets you view the last minute, hour, day and week. Since most counters are just increasing values, graphing the value does not give you that much. To view the delta between each poll, averaged to change per. second, the bottom row of time resolutions is used.

Configure parameters

'Configure parameters' lets you configure the Varnish parameters for the groups and nodes. And changes on a group parameter will also change all the nodes of that group. If you need a parameter to be different on one of the nodes in a group you can set that specific parameter for the node after setting it for the group. Clicking the question mark behind each parameter will show a description of that parameter along with its default value.

Edit VCL

From 'Edit VCL' you can edit the VCL of a group or a standalone node. In the same was a changes to the parameters of a group is applied to its nodes, changes to the VCL of a group is also done on the node of the group. As any typical editor, you can create new VCLs, load existing VCLS, save VCLS and discard VCLs. In addition you can make a VCL active if you have more than one VCLs. Note that you can not discard the VCL if there is only one VCL available.

When saving the VCL, any VCL errors are displayed, with the possibility to jump straight to the error by clicking 'Line X Pos Y' in the error output. If the group does not contain any nodes, no error messages are displayed, as it must have a node to verify the VCL against.

Node management

'Node management' lets you control your groups and nodes, e.g. starting, stopping and removing nodes to groups. The 'All nodes' section shows all the registered nodes, regardless of group, along with the backend healths, if the backend declaration of the VCl contains a probe.

The colored dot in the 'V' column shows the status of the Varnish node_

  • green dot: Varnish is responding with a 200 OK to a GET on  http://<server>/
  • yellow dot: Varnish is responding with a non-200 status to a GET on  http://<server>/
  • red dot: Varnish does not respond, typically if the node has been stopped

The colored dot in the 'M' signals if the management port can be reached on the Varnish server. As Varnish Administration Console uses the management port to control the Varnish node and collect information, this must be a green dot (not red).

For easy access, clicking the server name will open a new browser with the Varnish server as URL and clicking the management port will open the 'Mangement console' view for that node.

Adding a node to a group is done by filling in the input row with the required information, then click 'Add'. The check box 'Group inherit settings' (default checked for the first node) determines if the group should inherit the VCLs and parameters of the node. Otherwise the node will inherit the VCLs and parameters of the group. This check box is only visible for non-Standalone groups, as Standalone nodes are standalone and will not have their VCLs and parameters magically altered.

Editing a node is done by clicking 'Edit' on the row of node. This will let you change the values of the node, including change the group. As for when adding nodes, moving a node will have the node inherit the VCLs and parameters of the group.

Management console

'Management console' gives you direct access to the management console of the nodes from the Varnish Administration Console. It is more or less as a telnet session to the management port, with the added feature of having TAB completion for the CLI commands. The color scheme and size can be adjusted for each session.

NOTE: The management console uses javascript to send the CLI commands to the web server in the background, and some browsers (like firefox) will silently fail such requests if the hostname of the URL you are using does not match the hostname used by the javascript. Therefore, make sure you are using the hostname of the web server when using the Varnish Administration Console.

Other tings

Logging

The Varnish Administration Console logs (some) information, especially changes performed by the user. The log lines look like

[2009-02-19 08:35:21] [INFO] [public-1] [Updated node] [name=public-1] [address=localhost] [port=80] [group=public-web] [management_port=9001]
[2009-02-19 08:35:38] [INFO] [public-2] [Added node] [name=public-2] [address=localhost] [port=8181] [group=public-web] [management_port=9002]
[2009-02-19 13:21:00] [INFO] [private-1] [Saved VCL] [boot] [1%2C7c1%2C7%0A%3C%20backend%20default%20%7B%3C%20%20%20%20%20.host%20%3D%20%22localhost%22%3B%3C%20%20%20%20%20.port%20%3D%20%228080%22%3B%3C%20%20%20%20%20.probe%20%3D%20%7B%3C%20%20%20%20%20%20%20%20%20.url%20%3D%20%22%2Fbaba%22%3B%3C%20%20%20%20%20%7D%3C%20%7D---%0A%3E%20backend%20default%20%7B%0D%3E%20%20%20%20%20.host%20%3D%20%22localhost%22%3B%0D%3E%20%20%20%20%20.port%20%3D%20%228080%22%3B%0D%3E%20%20%20%20%20.probe%20%3D%20%7B%0D%3E%20%20%20%20%20%20%20%20%20.url%20%3D%20%22%2F%22%3B%0D%3E%20%20%20%20%20%7D%0D%3E%20%7D%0D]
[2009-02-19 15:04:03] [INFO] [public-web] [Parameter change] [cli_timeout] [5 => 7]

and follows the pattern

[timestamp in local time] [Severity] [Name of node/group] [Operation performed] [Additional info] .... [Additional info N]

When saving VCL, an URL encoded diff is logged. Other log lines should be fairly self explainable.

Attachments