[master] c09887a Trains are good for writing documentation :-)
Poul-Henning Kamp
phk at varnish-cache.org
Thu Nov 7 16:04:35 CET 2013
commit c09887aef3b4d816eea59a8cce962ec35186e72e
Author: Poul-Henning Kamp <phk at FreeBSD.org>
Date: Thu Nov 7 15:04:03 2013 +0000
Trains are good for writing documentation :-)
diff --git a/doc/sphinx/users-guide/command-line.rst b/doc/sphinx/users-guide/command-line.rst
index 2bf7e2d..d3b5240 100644
--- a/doc/sphinx/users-guide/command-line.rst
+++ b/doc/sphinx/users-guide/command-line.rst
@@ -3,46 +3,94 @@
Typical command line options
----------------------------
-On a modern Linux distro the various options that are used when
-starting up Varnish are stored in /etc/default/varnish (Debian, Ubuntu) or
-/etc/sysconfig/varnish (Red Hat, Centos).
+If you run Varnish out of a package for your operating system,
+you will find the default options here:
-There are quite a few options you can tweak but most of you will only
-need to change a few them.
+* Debian, Ubuntu: /etc/default/varnish
+* Red Hat, Centos: /etc/sysconfig/varnish
+* FreeBSD: /etc/rc.conf (See also: /usr/local/etc/rc.d/varnishd)
-The typical command line options you want to change are:
+There some command line options you will simply have choose values for:
-a *listen_address*
- What address should Varnish listen to. The default is to listen to
- all IP adresses and stick to port 80. ":80" will ask Varnish to
- listen to all adresses, both IPv4 and IPv6 and is probably a
- sensible thing.
+^^^^^^^^^^^^^^^^^^^
+
+What address should Varnish listen to and service HTTP requests on.
+
+You will most likely want to set this to ":80" which is the Well
+Known Port for HTTP.
+
+You can specify multiple addresses separated by a comma, and you
+can use numeric or host/service names as you like, varnish will try
+to open and service as many of them as possible, but if none of them
+can be opened, varnishd will not start.
+
+Here are some examples::
+
+ -a :80
+ -a localhost:80
+ -a 192.168.1.100:8080
+ -a '[fe80::1]:80'
+ -a '0.0.0.0:8080,[::]:8081'
+
+If your webserver runs on the same computer, you will have to move
+it to another port number first.
--f *config file*
- The -f options specifies what VCL file Varnish should use as the default.
-
--s *storage options*
-
- This is probably the most important one. The default is to use
- the memory storage backend and to allocate a small amount of
- memory. On a small site this might suffice. If you have dedicated
- Varnish Cache server you most definitivly want to increase
- the memory allocated or consider another backend.
- Please note that in addition to the memory allocated by the
- storage engine itself Varnish also has internal data structures
- that consume memory. More or less 1kb per object.
- See also :ref:`guide-storage`.
-
--T *listen address*
- Varnish has a built-in text-based administration
- interface. Activating the interface makes Varnish manageble
- without stopping it. You can specify what interface the
- management interface should listen to. Make sure you don't expose
- the management interface to the world as you can easily gain root
- access to a system via the Varnish management interface. I
- recommend tieing it to localhost. If you have users on your
- system that you don't fully trust, use firewall rules to restrict
- access to the interface to root only.
+-f *VCL-file* or -b *backend*
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Varnish needs to know where to find the HTTP server it is caching for.
+You can either specify it with -b and use the default VCL code, or you
+can put it in your own VCL file.
+
+Using -b is a quick way to get started::
+
+ -b localhost:81
+ -b thatotherserver.example.com:80
+ -b 192.168.1.2:80
+
+Notice that if you specify a name, it can at most resolve to one IPv4
+*and* one IPv6 address.
+
+If you go with -f, you can start with a VCL file containing just::
+
+ backend default {
+ .host = "localhost:81";
+ }
+
+which is exactly what -b does.
+
+-s *storage-options*
+^^^^^^^^^^^^^^^^^^^^
+
+This is probably the most important one. The default is to use
+the memory storage backend and to allocate a small amount of
+memory. On a small site this might suffice. If you have dedicated
+Varnish Cache server you most definitivly want to increase
+the memory allocated or consider another backend.
+Please note that in addition to the memory allocated by the
+storage engine itself Varnish also has internal data structures
+that consume memory. More or less 1kb per object.
+See also :ref:`guide-storage`.
+
+-T *CLI-listen-address*
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Varnish has a built-in text-based administration
+interface. Activating the interface makes Varnish manageble
+without stopping it. You can specify what interface the
+management interface should listen to. Make sure you don't expose
+the management interface to the world as you can easily gain root
+access to a system via the Varnish management interface. I
+recommend tieing it to localhost. If you have users on your
+system that you don't fully trust, use firewall rules to restrict
+access to the interface to root only.
+
+-S *CLI-secret-file*
+^^^^^^^^^^^^^^^^^^^^
+
+This file stores a secret you must know, in order to get
+access to the CLI.
For a complete list of the command line parameters please see
:ref:`ref-varnishd-options`.
diff --git a/doc/sphinx/users-guide/run_security.rst b/doc/sphinx/users-guide/run_security.rst
index 4267a93..080bb80 100644
--- a/doc/sphinx/users-guide/run_security.rst
+++ b/doc/sphinx/users-guide/run_security.rst
@@ -80,14 +80,17 @@ and give remote users access via a secure connection to the local
machine (ssh, VPN, etc. etc.)
It is also possible to configure varnishd for "reverse mode", using
-the '-M' argument,
-
-In this case varnishd will attempt to open a TCP connection to the
-specified address, and initiate a CLI connection on it.
+the '-M' argument. In that case varnishd will attempt to open a
+TCP connection to the specified address, and initiate a CLI connection
+to your central varnish management facility.
The connection is also in this case without secrecy, but if configured
the remote end must still satisfy -S/PSK authentication.
+Finally, if you run varnishd with the '-d' option, you get a CLI
+command on stdin/stdout, but since you started the process, it
+would be hard to prevent you getting CLI access, wouldn't it ?
+
Parameters
^^^^^^^^^^
@@ -130,7 +133,7 @@ We do not currently have a way to restrict specific CLI commands
to specific CLI connections. One way to get such an effect is to
"wrap" all CLI access in pre-approved scripts which use varnishadm(1)
to submit the sanitized CLI commands, and restrict a remote user
-to only those scripts in sshd(8)'s configuration.
+to only those scripts, for instance using sshd(8)'s configuration.
VCL programs
------------
@@ -151,7 +154,7 @@ lower the privilege of a child process...
Inline-C is disabled by default starting with Varnish 4, so unless
you enable it, you don't have to worry about it.
-The params mentioned above can restrict VMOD so they can only
+The parameters mentioned above can restrict VMOD, so they can only
be imported from a designated directory, restricting VCL wranglers
to a pre-approved subset of VMODs.
@@ -171,7 +174,7 @@ to do exactly stupid things to them, including opening youself up
to various kinds of attacks and subversive activities.
If you have "administrative" HTTP requests, for instance PURGE
-requests, we recommend that you restrict them to trusted IP
-numbers/nets using VCL's Access Control Lists.
+requests, we strongly recommend that you restrict them to trusted
+IP numbers/nets using VCL's Access Control Lists.
(XXX: missing ref to ACL)
More information about the varnish-commit
mailing list