doc/remote-cache.1.xml

   1 <?xml version="1.0" encoding="iso-8859-1"?>
   2 <!DOCTYPE refentry PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
   3 <refentry id="onnode.1">
   4
   5 <refmeta>
   6         <refentrytitle>remote-cache</refentrytitle>
   7         <manvolnum>1</manvolnum>
   8 </refmeta>
   9
  10
  11 <refnamediv>
  12         <refname>remote-cache</refname>
  13         <refpurpose>Read-Mostly caching daemon for re-exporting remote NFS shares</refpurpose>
  14 </refnamediv>
  15
  16 <refsynopsisdiv>
  17         <cmdsynopsis>
  18                 <command>remote-cache --export=DIR --cache=DIR --remote=DIR [--max-dir-cache=TIMEOUT] [--dir-min-inodes=INTEGER] [--dir-min-blocks=INTEGER] [--file-min-inodes=INTEGER] [--file-min-blocks=INTEGER] [--file-max-size=MB] [--file-check-parent-mtime] [--file-min-mtime-age=SECONDS] [--read-write]
  19                 </command>
  20                 <command>remote-cache --unexport=DIR
  21                 </command>
  22         </cmdsynopsis>
  23 </refsynopsisdiv>
  24
  25   <refsect1><title>DESCRIPTION</title>
  26     <para>
  27     Remote-cache is a fuse module that is used to create a local read-mostly
  28     cached copy of a remote NFS share. The purpose of this is to provide a
  29     local cache of a remote NFS share in order to provide access to the data.
  30     NFS is VERY painful and slow to use across >100ms links.
  31     </para>
  32     <para>
  33       The default is to provide a read-only cached copy of the filesystem but
  34       read-write can be provided using the --read-write option.
  35       In read-write mode any writes or metadata changes will be passed-through
  36       to the remote site as well as the local cache for the file and or
  37       directory will be flushed. Write performance is thus slow.
  38     </para>
  39     <para>
  40       Eventhough read-write is supported, write is veryu slow so remote-cache should only be used in read-mostly environments.
  41     </para>
  42
  43     <refsect2><title>--remote</title>
  44     <para>
  45     This specifies the mountpoint where the remote NFS server is mounted.
  46     This is the remote share we will "wan-accelerate" using remote-cache.
  47     </para>
  48     <para>
  49     This share should be mounted using soft and intr.
  50     </para>
  51     <para>
  52     A good choice of options to mount the remote share with are :
  53       <screen format="linespecific">
  54       mount -o soft,intr,actimeo=600 REMOTE-SERVER:/share /mnt/remote-share
  55       </screen>
  56     </para>
  57     </refsect2>
  58
  59     <refsect2><title>--cache</title>
  60     <para>
  61     This controls which local directory to store the cached copies of the
  62     files/data from the share.
  63     </para>
  64     <para>
  65     Mtime of the objects are used to track whether an object in the cache
  66     is up to data or needs to be remigrated.
  67     </para>
  68     </refsect2>
  69
  70     <refsect2><title>--export</title>
  71     <para>
  72     This specifies the mountpoint where this fuse module will attach.
  73     When accessing data through this mountpoint, the fuse module will either
  74     return data from the local cache, or if the local cache does not contain
  75     an up to date copy of that object, it will instead pass through the request
  76     to the remote site.
  77     </para>
  78     <para>
  79     This directory can be re-exported read-only or read-write by the local NFS server to
  80     clients on the local site.
  81     </para>
  82     </refsect2>
  83
  84     <refsect2><title>--unexport</title>
  85     <para>
  86       This command will unexport a remote-cache exported filesystem and shut
  87       down all associated background daemons.
  88     </para>
  89     </refsect2>
  90
  91     <refsect2><title>--max-dir-cache</title>
  92     <para>
  93     Directory content is cached for each directory containing the list of
  94     object names that are stored in the directory and also the full stat()
  95     information for the objects.
  96     </para>
  97     <para>
  98     This parameter controls how long a directory will be cached before it
  99     is flushed and re-read from the remote site.
 100     </para>
 101     <para>
 102     This parameter defaults to 0, meaning that once a directory has been
 103     cached, it will remain cached forever, or until the mtime of the
 104     directory on the remote site changes.
 105     </para>
 106     <para>
 107     This means that a directory once cached will remain cached forever until
 108     its mtime has changed. I.e. when entries have been added/deleted to the
 109     directory.
 110     But since we also cache all the attributes for the child objects in this
 111     cache it also means that we will not detect changes to actual child files.
 112     I.e. we will not detect if a file has been written to/modified since
 113     this does not cause the mtime of the parent directory to change
 114     which in turn means we will not flush our cache. This is by design.
 115     </para>
 116
 117     </refsect2>
 118
 119     <refsect2><title>--dir-min-inodes</title>
 120     <para>
 121     This parameter defaults to 100.
 122     </para>
 123     <para>
 124     When there are less than this number of free inodes in the cache file system
 125     remote-cache will no longer add new directories to the directory structure
 126     cache. When this happens, clients will still be able to access/list these
 127     directories but it will be slow since the directories will not be cached
 128     and all access will be passed through to the remote site.
 129     </para>
 130     <para>
 131     This will be logged with an entry similar to
 132     <screen format="linespecific">
 133     2008/06/10 12:24:41.582921 [ 1605]: Cache is full. Only 74 inodes left in /gpfs/cache. Can not build local cache of directory /mnt/nfs/export
 134     </screen>
 135     </para>
 136     </refsect2>
 137
 138
 139     <refsect2><title>--dir-min-blocks</title>
 140     <para>
 141     This parameter defaults to 1000.
 142     </para>
 143     <para>
 144     When there are less than this number of free blocks in the cache file system
 145     remote-cache will no longer add new directories to the directory structure
 146     cache. When this happens, clients will still be able to access/list these
 147     directories but it will be slow since the directories will not be cached
 148     and all access will be passed through to the remote site.
 149     </para>
 150     <para>
 151     This will be logged with an entry similar to
 152     <screen format="linespecific">
 153     2008/06/10 12:24:41.582921 [ 1605]: Cache is full. Only 237 blocks left in /gpfs/cache. Can not build local cache of directory /mnt/nfs/export
 154     </screen>
 155     </para>
 156     </refsect2>
 157
 158     <refsect2><title>--file-min-inodes</title>
 159     <para>
 160     This parameter defaults to 100.
 161     </para>
 162     <para>
 163     When there are less than this number of free inodes in the cache file system
 164     remote-cache will no longer add more files to the cache.
 165     When this happens, clients will still be able to access/read these
 166     files but it will be slow since all reads will be passed through to
 167     the remote site.
 168     </para>
 169     <para>
 170     This will be logged with an entry similar to
 171     <screen format="linespecific">
 172     2008/06/10 12:24:41.582921 [ 1605]: Cache is full. Only 74 inodes left in /gpfs/cache. Can not build add file /mnt/nfs/export/foo to the cache
 173     </screen>
 174     </para>
 175     </refsect2>
 176
 177
 178     <refsect2><title>--file-min-blocks</title>
 179     <para>
 180     This parameter defaults to 10000.
 181     </para>
 182     <para>
 183     When there are less than this number of free blocks in the cache file system
 184     remote-cache will no longer add more files to the cache.
 185     When this happens, clients will still be able to access/read these
 186     files but it will be slow since all i/o will be passed through to the
 187     remote site.
 188     </para>
 189     <para>
 190     This will be logged with an entry similar to
 191     <screen format="linespecific">
 192     2008/06/10 12:24:41.582921 [ 1605]: Cache is full. Only 237 blocks left in /gpfs/cache. Can not build add file /mnt/nfs/export/foo to the cache
 193     </screen>
 194     </para>
 195     </refsect2>
 196
 197     <refsect2><title>--file-max-size</title>
 198     <para>
 199     This parameter defaults to 0.
 200     </para>
 201     <para>
 202     Maximum size in MB of files to cache. Files larger than this will not be
 203     copied to the local cache.
 204     </para>
 205     <para>
 206     When set to 0 there will be no size limitation of files to cache.
 207     </para>
 208     </refsect2>
 209
 210
 211     <refsect2><title>--file-migrate-max-concurrent</title>
 212     <para>
 213     This parameter defaults to 1000.
 214     </para>
 215     <para>
 216     Maximum number of concurrent migrations of files we allow before we start
 217     failing the migration.
 218
 219     Note that failing a migration is not a severe issue, it just means that the
 220     file will be migrate a little while later instead next time it is accessed.
 221     </para>
 222     </refsect2>
 223
 224
 225
 226     <refsect2><title>--file-check-parent-mtime</title>
 227     <para>
 228     This paranter can only be used in environments where files are
 229     created/deleted but where files are never modified after being created.
 230     Never use this option unless this is true for the i/o patterns of the
 231     environment.
 232     </para>
 233     <para>
 234     If the environment is an archive server or similar where files, once they
 235     have been created are never changed. Then it is possible to use a more
 236     aggressive caching strategy for attributes and instead look at the
 237     mtime of the parent directory and the cached directory entries to determine
 238     whether the cached file is up to date. This greatly reduces the amount
 239     of GETATTR calls that are issued to the remote site and also greatly
 240     reduses the stress on the local nfs clients attribute cache since we only
 241     cache the attributes for the directories and never for the leaf
 242     objects/files.
 243     </para>
 244     <para>
 245     The process works as follows : First get the attributes for the parent
 246     directory on the remote site (which most of the time will come out of
 247     the nfs clients attribute cache), then compare the mtime with the mtime
 248     of the parent directory in the cache directory. If the directory mtime's
 249     are the same, then we read the attributes for the file from the local
 250     cached copy and return to the client instead of the attributes off the
 251     remote server.
 252     </para>
 253     </refsect2>
 254
 255     <refsect2><title>--file-min-mtime-age=SECONDS</title>
 256     <para>
 257     Do not migrate the file to the cache if it was changed (based on mtime)
 258     less than this many seconds ago.
 259     </para>
 260
 261     <para>
 262     This parameter defaults to 120 seconds.
 263     </para>
 264     </refsect2>
 265
 266     <refsect2><title>--read-write</title>
 267     <para>
 268     EXPERIMENTAL.
 269     </para>
 270
 271     <para>
 272     This allows the filesystem to be exported read-write. All data or metadata
 273     changing operations are passed through to the master server and the local
 274     cache is invalidated. Do NOT use this option together with --file-check-parent-mtime.
 275     </para>
 276
 277     <para>
 278     Since in this mode all writes are pass-through, writes will be slow.
 279     </para>
 280     </refsect2>
 281   </refsect1>
 282
 283
 284   <refsect1><title>EXAMPLES</title>
 285     <para>
 286     Mount the remote server/share on a local mountpoint.
 287     <screen format="linespecific">
 288     mount -o ro,soft,intr,actimeo=600 REMOTE-SERVER:/remote-share /mnt/remote-share
 289     </screen>
 290     </para>
 291
 292     <para>
 293     Create a local export and cache directory
 294     <screen format="linespecific">
 295     mkdir /export/data
 296     mkdir /export/cache
 297     </screen>
 298     </para>
 299
 300     <para>
 301     Startup remote-cache
 302     <screen format="linespecific">
 303     remote-cache --export=/export/data --cache=/export/cache --remote=/mnt/remote-share
 304     </screen>
 305     </para>
 306
 307     <para>
 308     You can now access the share through /export/data which should be much much
 309     faster than accessing it through /mnt/remote-share if the remote server is more than 10ms away.
 310     Also look in the /export/cache directory to see when/which files are currently cached locally.
 311     </para>
 312   </refsect1>
 313
 314   <refsect1><title>CACHE CLEANUP</title>
 315   <para>
 316   Removing data from the cache to reclaim space is easy.
 317   </para>
 318   <para>
 319   For files you can just delete them with "rm".
 320   </para>
 321   <para>
 322   If you want to remove an entire directory tree from the cache it is more
 323   complex. For this you must first rename (mv) the directory to something else
 324   and then you can "rm -rf" that renamed directory tree.
 325   </para>
 326   </refsect1>
 327
 328   <refsect1><title>LOGGING</title>
 329     <para>
 330     All debug and error messages are logged to /var/log/log.remote-cache.
 331     </para>
 332     <para>
 333     The log level can be controlled by the --debug=X command line parameter.
 334     The default is 0 : ERROR.
 335     </para>
 336     <para>
 337     Possible debuglevels are :
 338       <screen format="linespecific">
 339         0: ERROR
 340         1: WARNING
 341         2: NOTICE
 342         3: INFO
 343         4: DEBUG
 344     </screen>
 345     </para>
 346   </refsect1>
 347
 348   <refsect1><title>SEE ALSO</title>
 349     <para>
 350       ctdbd(1), ctdb(1), <ulink url="http://ctdb.samba.org/"/>
 351     </para>
 352   </refsect1>
 353   <refsect1><title>COPYRIGHT/LICENSE</title>
 354 <literallayout>
 355 Copyright (C) Ronnie Sahlberg 2008
 356
 357 This program is free software; you can redistribute it and/or modify
 358 it under the terms of the GNU General Public License as published by
 359 the Free Software Foundation; either version 3 of the License, or (at
 360 your option) any later version.
 361
 362 This program is distributed in the hope that it will be useful, but
 363 WITHOUT ANY WARRANTY; without even the implied warranty of
 364 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 365 General Public License for more details.
 366
 367 You should have received a copy of the GNU General Public License
 368 along with this program; if not, see http://www.gnu.org/licenses/.
 369 </literallayout>
 370   </refsect1>
 371 </refentry>