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 id are optional.

       NOTE:
          The volume option is independent of the id 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.

       NOTE:
          Any  change to this files can (and almost always will) invalidate the existing cache in
          its entirety.

       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 maintaining 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 addressed 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 ameliorated 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

   Advanced
       Because relative paths in storage.config are relative  to  the  base  prefix,  when  using
       customized  runroot  it  may be necessary to adjust such paths in storage.config or adjust
       runroot.yaml itself.  Despite the name, the cachedir value is not used for this file.

COPYRIGHT

       2024, dev@trafficserver.apache.org