bionic (5) storage.config.5.gz

Provided by: trafficserver_7.1.2+ds-3_amd64 bug

NAME

       storage.config - Traffic Server cache storage configuration file

       The  storage.config  file  (by  default,  located  in /usr/local/etc/trafficserver/) lists all the files,
       directories, and/or hard disk partitions that make up the Traffic Server  cache.  After  you  modify  the
       storage.config file the new settings will not be effective until Traffic Server is restarted.

FORMAT

       The format of the storage.config file is a series of lines of the form
          pathname size [ volume=number ] [ id=string ]

       where  pathname  is  the name of a partition, directory or file, size is the size of the named partition,
       directory or file (in bytes), and volume is the  volume  number  used  in  the  files  volume.config  and
       hosting.config.  id  is  used  for seeding the Assignment Table. You must specify a size for directories;
       size is optional for files and raw partitions. volume and arg:seed are optional.

       NOTE:
          The volume option is independent of the seed option and either can be used with or without the  other,
          and their ordering on the line is irrelevant.

       NOTE:
          If the id option is used every use must have a unique value for string.

       You can use any partition of any size. For best performance:

       • Use raw disk partitions.

       • For each disk, make all partitions the same size.

       • For each node, use the same number of partitions on all disks.

       • Group  similar  kinds of storage into different volumes. For example split out SSD's or RAM drives into
         their own volume.

       Specify pathnames according to your operating system requirements. See the  following  examples.  In  the
       storage.config file, a formatted or raw disk must be at least 128 MB.

       When  using  raw  disk  or  partitions,  you should make sure the Traffic Server user used by the Traffic
       Server process has read and write privileges on the raw disk device or partition. One good practice is to
       make  sure  the device file is set with 'g+rw' and the Traffic Server user is in the group which owns the
       device file.  However, some operating systems have stronger requirements - see the following examples for
       more information.

       As with standard records.config integers, human readable prefixes are also supported. They include

          • K Kilobytes (1024 bytes)

          • M Megabytes (1024^2 or 1,048,576 bytes)

          • G Gigabytes (1024^3 or 1,073,741,824 bytes)

          • T Terabytes (1024^4 or 1,099,511,627,776 bytes)

   Assignment Table
       Each  storage  element defined in storage.config is divided in to stripes. The assignment table maps from
       an object URL to a specific stripe. The table is initialized based on a pseudo-random  process  which  is
       seeded  by  hashing  a  string  for each stripe. This string is composed of a base string, an offset (the
       start of the stripe on the storage element), and the length of the stripe. By default the  path  for  the
       storage  is used as the base string. This ensures that each stripe has a unique string for the assignment
       hash. This does make the assignment table very sensitive  to  the  path  for  the  storage  elements  and
       changing even one can have a cascading effect which will effectively clear most of the cache. This can be
       problem when drives fail and a system reboot causes the path names to change.

       The id option can be used to create a fixed string that an administrator can use to keep  the  assignment
       table  consistent  by  maintaing  the mapping from physical device to base string even in the presence of
       hardware changes and failures.

EXAMPLES

       The following basic example shows 128 MB of cache storage in the /big_dir directory:

          /big_dir 134217728

       You can use the . symbol for the current directory. Here is an example for 64 MB of cache storage in  the
       current directory:

          . 134217728

       As an alternative, using the human readable prefixes, you can express a 64GB cache file with:

          /really_big_dir 64G

       NOTE:
          When using on-filesystem cache disk storage, you can only have one such directory specified. This will
          be address in a future version.

   Solaris Example
       The following example is for the Solaris operating system:

          /dev/rdsk/c0t0d0s5
          /dev/rdsk/c0t0d1s5

       NOTE:
          Size is optional. If not specified, the entire partition is used.

   Linux Example
       NOTE:
          Rather than refer to disk devices like /dev/sda, /dev/sdb, etc.,  modern  Linux  supports  alternative
          symlinked  names  for  disk  devices in the /dev/disk directory structure. As noted for the Assignment
          Table the path used for the disk can effect the cache if it changes. This can be ameloriated  in  some
          cases by using one of the alternate paths in via /dev/disk. Note that if the by-id or by-path style is
          used, replacing a failed drive will cause that path to change  because  the  new  drive  will  have  a
          different  physical  ID  or  path.  The original hash string can be kept by adding id or path with the
          original path to the storage line.

          If this is not sufficient then the id or path argument should be  used  to  create  a  more  permanent
          assignment table. An example would be:

              /dev/sde id=cache.disk.0
              /dev/sdg id=cache.disk.1

       The following example will use an entire raw disk in the Linux operating system:

          /dev/disk/by-id/[DiskA_ID]    volume=1
          /dev/disk/by-path/[DiskB_Path]   volume=2

       In  order  to  make sure traffic_server will have access to this disk you can use udev(7) to persistently
       set the right permissions. The following  rules  are  targeted  for  an  Ubuntu  system,  and  stored  in
       /etc/udev/rules.d/51-cache-disk.rules:

          # Assign DiskA and DiskB to the tserver group
          # make the assignment final, no later changes allowed to the group!
          SUBSYSTEM=="block", KERNEL=="sd[ef]", GROUP:="tserver"

       In order to apply these settings, trigger a reload with udevadm(8)::

          udevadm trigger --subsystem-match=block

   FreeBSD Example
       Starting  with  5.1  FreeBSD  dropped  support  for  explicit  raw devices. All devices on FreeBSD can be
       accessed raw now.

       The following example will use an entire raw disk in the FreeBSD operating system:

          /dev/ada1
          /dev/ada2

       In order to make sure traffic_server will have access to this disk you can use devfs(8)  to  persistently
       set the right permissions. The following rules are stored in devfs.conf(5):

          # Assign /dev/ada1 and /dev/ada2 to the tserver user
          own    ada[12]  tserver:tserver

       2018, dev@trafficserver.apache.org