[master] d6aca56 Separate out the text describing the storage backends so it can be resued in both the man page and users guide
Per Buer
perbu at varnish-cache.org
Sat Sep 8 19:53:11 CEST 2012
commit d6aca56d15aa7ba737bb088bd12e622e19ab087b
Author: Per Buer <per.buer at gmail.com>
Date: Sat Sep 8 19:50:53 2012 +0200
Separate out the text describing the storage backends so it can be resued in both the man page and users guide
diff --git a/doc/sphinx/include/storage_backends.rst b/doc/sphinx/include/storage_backends.rst
new file mode 100644
index 0000000..ec80601
--- /dev/null
+++ b/doc/sphinx/include/storage_backends.rst
@@ -0,0 +1,113 @@
+
+malloc
+~~~~~~
+
+syntax: malloc[,size]
+
+Malloc is a memory based backend. Each object will be allocated from
+memory. If your system runs low on memory swap will be used. Be aware
+that the size limitation only limits the actual storage and that
+approximately 1k of memory per object will be used for various
+internal structures.
+
+The size parameter specifies the maximum amount of memory varnishd
+will allocate. The size is assumed to be in bytes, unless followed by
+one of the following suffixes:
+
+ K, k The size is expressed in kibibytes.
+
+ M, m The size is expressed in mebibytes.
+
+ G, g The size is expressed in gibibytes.
+
+ T, t The size is expressed in tebibytes.
+
+The default size is unlimited.
+
+Mallocs performance is bound by memory speed so it is very fast.
+
+file
+~~~~
+
+syntax: file[,path[,size[,granularity]]]
+
+The file backend stores objects in memory backed by a file on disk
+with mmap. This is the default storage backend and unless you specify
+another storage this one will used along with Transient storage.
+
+The path parameter specifies either the path to the backing file or
+the path to a directory in which varnishd will create the backing
+file. The default is /tmp.
+
+The size parameter specifies the size of the backing file. The size
+is assumed to be in bytes, unless fol‐ lowed by one of the following
+suffixes:
+
+ K, k The size is expressed in kibibytes.
+
+ M, m The size is expressed in mebibytes.
+
+ G, g The size is expressed in gibibytes.
+
+ T, t The size is expressed in tebibytes.
+
+ % The size is expressed as a percentage of the free space on the
+ file system where it resides.
+
+The default size is 50%.
+
+If the backing file already exists, it will be truncated or expanded
+to the specified size.
+
+Note that if varnishd has to create or expand the file, it will not
+pre-allocate the added space, leading to fragmentation, which may
+adversely impact performance. Pre-creating the storage file using
+dd(1) will reduce fragmentation to a minimum.
+
+The granularity parameter specifies the granularity of
+allocation. All allocations are rounded up to this size. The
+is assumed to be in bytes, unless followed by one of the
+suffixes described for size except for %.
+
+The default size is the VM page size. The size should be reduced if
+you have many small objects.
+
+File performance is typically limited by the write speed of the
+device, and depending on use, the seek time.
+
+persistent (experimental)
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+syntax: persistent,path,size {experimental}
+
+Persistent storage. Varnish will store objects in a file in a manner
+that will secure the survival of *most* of the objects in the event of
+a planned or unplanned shutdown of Varnish.
+
+The path parameter specifies the path to the backing file. If
+the file doesn't exist Varnish will create it.
+
+The size parameter specifies the size of the backing file. The
+size is assumed to be in bytes, unless followed by one of the
+following suffixes:
+
+ K, k The size is expressed in kibibytes.
+
+ M, m The size is expressed in mebibytes.
+
+ G, g The size is expressed in gibibytes.
+
+ T, t The size is expressed in tebibytes.
+
+Varnish will split the file into logical *silos* and write to the
+silos in the manner of a circular buffer. Only one silo will be kept
+open at any given point in time. Full silos are *sealed*. When Varnish
+starts after a shutdown it will discard the content of any silo that
+isn't sealed.
+
+Transient Storage
+-----------------
+
+If you name any of your storage backend "Transient" it will be
+used for transient (short lived) objects. By default Varnish
+would use an unlimited malloc backend for this.
diff --git a/doc/sphinx/reference/varnishd.rst b/doc/sphinx/reference/varnishd.rst
index 87141bf..95b0097 100644
--- a/doc/sphinx/reference/varnishd.rst
+++ b/doc/sphinx/reference/varnishd.rst
@@ -157,110 +157,7 @@ Storage Types
The following storage types are available:
-malloc[,size]
-
- Malloc is a memory based backend. Each object will be allocated
- from memory. If your system runs low on memory swap will be
- used. Be aware that the size limitation only limits the actual
- storage and that approximately 1k of memory per object will be
- used for various internal structures.
-
- The size parameter specifies the maximum amount of memory
- varnishd will allocate. The size is assumed to be in bytes,
- unless followed by one of the following suffixes:
-
- K, k The size is expressed in kibibytes.
-
- M, m The size is expressed in mebibytes.
-
- G, g The size is expressed in gibibytes.
-
- T, t The size is expressed in tebibytes.
-
- The default size is unlimited.
-
- Mallocs performance is bound by memory speed so it is very fast.
-
-file[,path[,size[,granularity]]]
-
- The file backend stores objects in memory backed by a file on
- disk with mmap. This is the default storage backend and unless
- you specify another storage this one will used along with
- Transient storage.
-
- The path parameter specifies either the path to the backing file
- or the path to a directory in which varnishd will create the
- backing file. The default is /tmp.
-
- The size parameter specifies the size of the backing file. The
- size is assumed to be in bytes, unless fol‐ lowed by one of the
- following suffixes:
-
- K, k The size is expressed in kibibytes.
-
- M, m The size is expressed in mebibytes.
-
- G, g The size is expressed in gibibytes.
-
- T, t The size is expressed in tebibytes.
-
- % The size is expressed as a percentage of the free space on the
- file system where it resides.
-
- The default size is 50%.
-
- If the backing file already exists, it will be truncated or
- expanded to the specified size.
-
- Note that if varnishd has to create or expand the file, it will
- not pre-allocate the added space, leading to fragmentation,
- which may adversely impact performance. Pre-creating the
- storage file using dd(1) will reduce fragmentation to a minimum.
-
- The granularity parameter specifies the granularity of
- allocation. All allocations are rounded up to this size. The
- size is assumed to be in bytes, unless followed by one of the
- suffixes described for size except for %.
-
- The default size is the VM page size. The size should be
- reduced if you have many small objects.
-
- File performance is typically limited by the write speed of the
- device, and depending on use, the seek time.
-
-persistent,path,size {experimental}
-
- Persistent storage. Varnish will store objects in a file in a
- manner that will secure the survival of *most* of the objects in
- the event of a planned or unplanned shutdown of Varnish.
-
- The path parameter specifies the path to the backing file. If
- the file doesn't exist Varnish will create it.
-
- The size parameter specifies the size of the backing file. The
- size is assumed to be in bytes, unless followed by one of the
- following suffixes:
-
- K, k The size is expressed in kibibytes.
-
- M, m The size is expressed in mebibytes.
-
- G, g The size is expressed in gibibytes.
-
- T, t The size is expressed in tebibytes.
-
- Varnish will split the file into logical *silos* and write to
- the silos in the manner of a circular buffer. Only one silo will
- be kept open at any given point in time. Full silos are
- *sealed*. When Varnish starts after a shutdown it will discard
- the content of any silo that isn't sealed.
-
-Transient Storage
------------------
-
- If you name any of your storage backend "Transient" it will be
- used for transient (short lived) objects. By default Varnish
- would use an unlimited malloc backend for this.
+.. include:: ../include/storage_backends.rst
Management Interface
--------------------
diff --git a/doc/sphinx/users-guide/storage-backends.rst b/doc/sphinx/users-guide/storage-backends.rst
index 5d576cf..7436837 100644
--- a/doc/sphinx/users-guide/storage-backends.rst
+++ b/doc/sphinx/users-guide/storage-backends.rst
@@ -6,16 +6,8 @@ Storage backends
Intro
~~~~~
-Malloc
-~~~~~~
-
-File
-~~~~
-
-Persistent
-~~~~~~~~~~
-
-Transient
-~~~~~~~~~
+Varnish has pluggable storage backends. It can store data in various
+backends which have different performance characteristics.
+.. include:: ../include/storage_backends.rst
More information about the varnish-commit
mailing list