[master] ff64843 Varnishncsa updated documentation
Martin Blix Grydeland
martin at varnish-cache.org
Tue Nov 19 17:37:57 CET 2013
commit ff6484327ec12e45bff8c0caa7738de2c4a647b5
Author: Martin Blix Grydeland <martin at varnish-software.com>
Date: Tue Nov 19 16:57:05 2013 +0100
Varnishncsa updated documentation
diff --git a/bin/varnishncsa/Makefile.am b/bin/varnishncsa/Makefile.am
index 9912d4c..6f3a7f9 100644
--- a/bin/varnishncsa/Makefile.am
+++ b/bin/varnishncsa/Makefile.am
@@ -25,9 +25,31 @@ varnishncsa_LDADD = \
$(top_builddir)/lib/libvarnishapi/libvarnishapi.la \
${RT_LIBS} ${LIBM}
-varnishncsa.1: $(top_srcdir)/doc/sphinx/reference/varnishncsa.rst
+noinst_PROGRAMS = varnishncsa_opt2rst
+varnishncsa_opt2rst_SOURCES = \
+ varnishncsa_options.h \
+ varnishncsa_options.c \
+ $(top_srcdir)/lib/libvarnishtools/opt2rst.c
+
+BUILT_SOURCES = varnishncsa_options.rst varnishncsa_synopsis.rst
+EXTRA_DIST = $(BUILT_SOURCES)
+MAINTAINERCLEANFILES = $(EXTRA_DIST)
+
+varnishncsa_options.rst:
+ ./varnishncsa_opt2rst options > $@
+varnishncsa_synopsis.rst:
+ ./varnishncsa_opt2rst synopsis > $@
+
+if HAVE_RST2MAN
+varnishncsa_options.rst varnishncsa_synopsis.rst: varnishncsa_opt2rst
+endif
+
+varnishncsa.1: \
+ $(top_srcdir)/doc/sphinx/reference/varnishncsa.rst \
+ varnishncsa_options.rst \
+ varnishncsa_synopsis.rst
if HAVE_RST2MAN
- ${RST2MAN} $? $@
+ ${RST2MAN} $(top_srcdir)/doc/sphinx/reference/varnishncsa.rst $@
else
@echo "========================================"
@echo "You need rst2man installed to make dist"
diff --git a/doc/sphinx/reference/varnishncsa.rst b/doc/sphinx/reference/varnishncsa.rst
index 3acac45..13b9c10 100644
--- a/doc/sphinx/reference/varnishncsa.rst
+++ b/doc/sphinx/reference/varnishncsa.rst
@@ -7,6 +7,7 @@ Display Varnish logs in Apache / NCSA combined log format
---------------------------------------------------------
:Author: Dag-Erling Smørgrav
+:Author: Martin Blix Grydeland
:Date: 2010-05-31
:Version: 1.0
:Manual section: 1
@@ -15,10 +16,8 @@ Display Varnish logs in Apache / NCSA combined log format
SYNOPSIS
========
-varnishncsa [-a] [-C] [-D] [-d] [-f] [-F format] [-I regex]
-[-i tag] [-n varnish_name] [-m tag:regex ...] [-P file] [-r file] [-V] [-w file]
-[-X regex] [-x tag]
-
+.. include:: ../../../bin/varnishncsa/varnishncsa_synopsis.rst
+varnishncsa |synopsis|
DESCRIPTION
===========
@@ -28,142 +27,107 @@ presents them in the Apache / NCSA "combined" log format.
The following options are available:
--a When writing to a file, append to it rather than overwrite it.
-
--C Ignore case when matching regular expressions.
-
--D Daemonize.
+.. include:: ../../../bin/varnishncsa/varnishncsa_options.rst
--d Process old log entries on startup. Normally, varnishncsa
- will only process entries which are written to the log
- after it starts.
+FORMAT
+======
--f Prefer the X-Forwarded-For HTTP header over client.ip in
- the log output.
+Specify the log format used. If no format is specified the default log
+format is used.
--F format Specify the log format used. If no format is specified the
- default log format is used. Currently it is:
+The default log format is::
- %h %l %u %t "%r" %s %b "%{Referer}i" "%{User-agent}i"
+ %h %l %u %t "%r" %s %b "%{Referer}i" "%{User-agent}i"
- Escape sequences \\n and \\t are supported.
+Escape sequences \\n and \\t are supported.
- Supported formatters are:
+Supported formatters are:
- %b
- Size of response in bytes, excluding HTTP headers.
- In CLF format, i.e. a '-' rather than a 0 when no
- bytes are sent.
+%b
+ Size of response in bytes, excluding HTTP headers. In CLF format,
+ i.e. a '-' rather than a 0 when no bytes are sent.
- %D
- Time taken to serve the request, in microseconds.
+%D
+ Time taken to serve the request, in microseconds.
- %H
- The request protocol. Defaults to HTTP/1.0 if not
- known.
+%H
+ The request protocol. Defaults to HTTP/1.0 if not known.
- %h
- Remote host. Defaults to '-' if not known.
- Defaults to 127.0.0.1 for backend requests.
+%h
+ Remote host. Defaults to '-' if not known.
- %{X}i
- The contents of request header X.
+%{X}i
+ The contents of request header X.
- %l
- Remote logname (always '-')
+%l
+ Remote logname (always '-')
- %m
- Request method. Defaults to '-' if not known.
+%m
+ Request method. Defaults to '-' if not known.
- %q
- The query string, if no query string exists, an
- empty string.
+%q
+ The query string, if no query string exists, an empty string.
- %{X}o
- The contents of response header X.
+%{X}o
+ The contents of response header X.
- %r
- The first line of the request. Synthesized from other
- fields, so it may not be the request verbatim.
+%r
+ The first line of the request. Synthesized from other fields, so it
+ may not be the request verbatim.
- %s
- Status sent to the client
+%s
+ Status sent to the client
- %t
- Time when the request was received, in HTTP date/time
- format.
+%t
+ Time when the request was received, in HTTP date/time format.
- %{X}t
- Time when the request was received, in the format
- specified by X. The time specification format is the
- same as for strftime(3).
+%{X}t
+ Time when the request was received, in the format specified
+ by X. The time specification format is the same as for strftime(3).
- %T
- Time taken to serve the request, in seconds.
+%T
+ Time taken to serve the request, in seconds.
- %U
- The request URL without any query string. Defaults to
- '-' if not known.
+%U
+ The request URL without any query string. Defaults to '-' if not
+ known.
- %u
- Remote user from auth
+%u
+ Remote user from auth
- %{X}x
- Extended variables. Supported variables are:
+%{X}x
+ Extended variables. Supported variables are:
- Varnish:time_firstbyte
- Time from when the request processing starts
- until the first byte is sent to the client.
+ Varnish:time_firstbyte
+ Time from when the request processing starts until the first byte
+ is sent to the client.
- Varnish:hitmiss
- Whether the request was a cache hit or miss. Pipe
- and pass are considered misses.
+ Varnish:hitmiss
+ Whether the request was a cache hit or miss. Pipe and pass are
+ considered misses.
- Varnish:handling
- How the request was handled, whether it was a
- cache hit, miss, pass, pipe or error.
+ Varnish:handling
+ How the request was handled, whether it was a cache hit, miss,
+ pass, pipe or error.
- VCL_Log:key
- Output value set by std.log("key:value") in VCL.
-
-
--m tag:regex only list records where tag matches regex. Multiple
- -m options are AND-ed together.
-
--n Specifies the name of the varnishd instance to get logs
- from. If -n is not specified, the host name is used.
-
--P file Write the process's PID to the specified file.
+ VCL_Log:key
+ Output value set by std.log("key:value") in VCL.
--r file Read log entries from file instead of shared memory.
-
--V Display the version number and exit.
-
--w file Write log entries to file instead of displaying them.
- The file will be overwritten unless the -a
- option was specified.
-
- If varnishncsa receives a SIGHUP while writing to a file,
- it will reopen the file, allowing the old one to be
- rotated away.
-
--X regex Exclude log entries which match the specified
- regular expression.
+SIGNALS
+=======
--x tag Exclude log entries with the specified tag.
+SIGHUP
+ Rotate the log file (see -w option)
-If the -o option was specified, a tag and a regex argument must be given.
-varnishncsa will then only log for request groups which include that tag
-and the regular expression matches on that tag.
+SIGUSR1
+ Flush any outstanding transactions
SEE ALSO
========
-* varnishd(1)
-* varnishhist(1)
-* varnishlog(1)
-* varnishstat(1)
-* varnishtop(1)
+varnishd(1)
+varnishlog(1)
+varnishstat(1)
HISTORY
=======
@@ -172,7 +136,6 @@ The varnishncsa utility was developed by Poul-Henning Kamp in
cooperation with Verdens Gang AS and Varnish Software AS. This manual page was
written by Dag-Erling Smørgrav ⟨des at des.no⟩.
-
COPYRIGHT
=========
@@ -180,4 +143,4 @@ This document is licensed under the same licence as Varnish
itself. See LICENCE for details.
* Copyright (c) 2006 Verdens Gang AS
-* Copyright (c) 2006-2011 Varnish Software AS
+* Copyright (c) 2006-2013 Varnish Software AS
More information about the varnish-commit
mailing list