1.. Licensed to the Apache Software Foundation (ASF) under one
2   or more contributor license agreements.  See the NOTICE file
3  distributed with this work for additional information
4  regarding copyright ownership.  The ASF licenses this file
5  to you under the Apache License, Version 2.0 (the
6  "License"); you may not use this file except in compliance
7  with the License.  You may obtain a copy of the License at
8
9   http://www.apache.org/licenses/LICENSE-2.0
10
11  Unless required by applicable law or agreed to in writing,
12  software distributed under the License is distributed on an
13  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14  KIND, either express or implied.  See the License for the
15  specific language governing permissions and limitations
16  under the License.
17
18=============
19volume.config
20=============
21
22.. configfile:: volume.config
23
24The :file:`volume.config` file enables you to manage your cache space more
25efficiently and restrict disk usage by creating cache volumes of
26different sizes. By distributing the cache across multiple volumes,
27you can help decrease single-lock pressure when there are not many hard drives
28present. You can further configure these volumes to store data from certain
29origin servers and/or domains in the :file:`hosting.config` file.
30
31Format
32======
33
34For each volume you want to create, enter a line with the following
35format: ::
36
37    volume=volume_number  scheme=protocol_type  size=volume_size
38
39where ``volume_number`` is a number between 1 and 255 (the maximum
40number of volumes is 255) and ``protocol_type`` is ``http``. Traffic
41Server supports ``http`` for HTTP volume types; ``volume_size`` is the
42amount of cache space allocated to the volume. This value can be either
43a percentage of the total cache space or an absolute value. The absolute
44value must be a multiple of 128 MB, where 128 MB is the smallest value.
45If you specify a percentage, then the size is rounded down to the
46closest multiple of 128 MB.
47
48Each volume is striped across several disks to achieve parallel I/O. For
49example: if there are four disks, then a 1-GB volume will have 256 MB on
50each disk (assuming each disk has enough free space available). If you
51do not allocate all the disk space in the cache, then the extra disk
52space is not used. You can use the extra space later to create new
53volumes without deleting and clearing the existing volumes.
54
55.. important::
56
57   Changing this file to add, remove or modify volumes effectively invalidates
58   the cache.
59
60
61Optional ramcache setting
62-------------------------
63
64You can also add an option ``ramcache=true/false`` to the volume configuration
65line.  True is the default setting and so not needed unless you want to explicitly
66set it.  Setting ``ramcache=false`` will disable the ramcache that normally
67sits in front of a volume.  This may be desirable if you are using something like
68ramdisks, to avoid wasting RAM and cpu time on double caching objects.
69
70
71Exclusive spans and volume sizes
72================================
73
74In the following sample configuration 2 spans `/dev/disk1` and `/dev/disk2` are defined
75in :file:`storage.config`, where span `/dev/disk2` is assigned to `volume 3` exclusively
76(`volume 3` is forced to an "exclusive" span `/dev/disk2`).
77In :file:`volume.config` there are 3 volumes defined, where `volume 1` and `volume 2`
78occupy span `/dev/disk1` taking each 50% of its space and `volume 3` takes 100% of span
79`/dev/disk2` exclusively.
80
81storage.config::
82
83      /dev/disk1
84      /dev/disk2 volume=3 # <- exclusive span
85
86volume.config::
87
88      volume=1 scheme=http size=50%
89      volume=2 scheme=http size=50%
90      volume=3 scheme=http size=512 # <- volume forced to a specific exclusive span
91
92It is important to note that when percentages are used to specify volume sizes
93and "exclusive" spans are assigned (forced) to a particular volume (in this case `volume 3`),
94the "exclusive" spans (in this case `/dev/disk2`) are excluded from the total cache
95space when the "non-forced" volumes sizes are calculated (in this case `volume 1` and `volume 2`).
96
97
98Examples
99========
100
101The following example partitions the cache across 5 volumes to decreasing
102single-lock pressure for a machine with few drives. The last volume being
103an example of one that might be composed of purely ramdisks so that the
104ramcache has been disabled.::
105
106    volume=1 scheme=http size=20%
107    volume=2 scheme=http size=20%
108    volume=3 scheme=http size=20%
109    volume=4 scheme=http size=20%
110    volume=5 scheme=http size=20% ramcache=false
111