%%%%%%%%%%%%%%
Reporting bugs
%%%%%%%%%%%%%%

Varnish can be a tricky beast to debug, having potentially thousands
of threads crowding into a few data structures makes for *interesting*
core dumps.

Actually, let me rephrase that without irony:  You tire of the "no,
not thread 438 either, lets look at 439 then..." routine really fast.

So if you run into a bug, it is important that you spend a little bit
of time collecting the right information, to help us fix the bug.

The most valuable information you can give us, is **always** how
to trigger and reproduce the problem.  If you can tell us that, we
rarely need anything else to solve it.  The caveat being, that we
do not have a way to simulate high levels of real-life web-traffic,
so telling us to "have 10.000 clients hit at once" does not really
allow us to reproduce.

Roughly we have three clases of bugs with Varnish, and the information
we need to debug them depends on the kind of bug.

Varnish crashes
===============

Plain and simple: **boom**

Varnish is split over two processes, the manager and the child.  The child
does all the work, and the manager hangs around to resurect it, if it
crashes.

Therefore, the first thing to do if you see a varnish crash, is to examine
your syslogs, to see if it has happened before.  (One site is rumoured
to have had varnish restarting every 10 minutes and *still* provide better
service than their CMS system.)

When it crashes, if at all possible, Varnish will spew out a crash dump
that looks something like::

	Child (32619) died signal=6 (core dumped)
	Child (32619) Panic message: Assert error in ccf_panic(), cache_cli.c line 153:
	  Condition(!strcmp("", "You asked for it")) not true.
	errno = 9 (Bad file descriptor)
	thread = (cache-main)
	ident = FreeBSD,9.0-CURRENT,amd64,-sfile,-hcritbit,kqueue
	Backtrace:
	  0x42bce1: pan_ic+171
	  0x4196af: ccf_panic+4f
	  0x8006b3ef2: _end+80013339a
	  0x8006b4307: _end+8001337af
	  0x8006b8b76: _end+80013801e
	  0x8006b8d84: _end+80013822c
	  0x8006b51c1: _end+800134669
	  0x4193f6: CLI_Run+86
	  0x429f8b: child_main+14b
	  0x43ef68: start_child+3f8
	[...]

If you can get that information to us, we are usually able to
see exactly where things went haywire, and that speeds up bugfixing
a lot.

There will be a lot more information than this, and before sending
it all to us, you should obscure any sensitive/secret
data/cookies/passwords/ip# etc.  Please make sure to keep context
when you do so, ie: do not change all the IP# to "X.X.X.X", but
change each IP# to something unique, otherwise we are likely to be
more confused than informed.

The most important line is the "Panic Message", which comes in two
general forms:

"Missing errorhandling code in ..."
	This is a place where we can conceive ending up, and have not
	(yet) written the padded-box error handling code for.

	The most likely cause here, is that you need a larger workspace
	for HTTP headers and Cookies.
rip out all the autocrap stuff
and replace it with a 5 line shellscript that calls ``uname -s``.

Poul-Henning, 2010-04-20
    ./usr/share/doc/varnish-doc/html/_sources/phk/thoughts.txt                                          0000644 0000000 0000000 00000002663 11652771702 022603  0                                                                                                    ustar   root                            root                                                                                                                                                                                                                   .. _phk_thoughts:

=========================
What were they thinking ?
=========================

The reason I try to write these notes is the chinese wall.

Ever since I first saw it on a school-book map, I have been wondering
what the decision making process were like.

We would like to think that the emperor asked for ideas, and that
advisors came up with analyses, budgets, cost/benefit calculations
and project plans for various proposals, and that the emperor applied
his wisdom to choose the better idea.

But it could also be, that The Assistant to The Deputy Viceminister of
Northern Affairs, edged in sideways, at a carefully chosen time where
the emperor looked relaxed and friendly, and sort of happend to mention
that 50 villages had been sort of raided by the barbarians, hoping
for the reply, which would not be a career opportunity
for The Assistant to The Assistant to The Deputy Viceminister of
Northern Affairs.

And likely as not, the emperor absentmindedly grunted "Why don't
you just build a wall to keep them out or something ?"  probably
wondering about the competence of an administration, which could
not figure out to build palisades around border villages without
bothering him and causing a monument to the Peter Principle and
Parkinssons Law to be built, which can be seen from orbit, and
possibly from the moon, if you bring your binoculars.

If somebody had written some notes, we might have known.

Poul-Henning, 2010-05-28
                                                                             ./usr/share/doc/varnish-doc/html/_sources/installation/                                             0000755 0000000 0000000 00000000000 12705674615 022112  5                                                                                                    ustar   root                            root                                                                                                                                                                                  