--- /dev/null
+.\" Title: remote-cache
+.\" Author:
+.\" Generator: DocBook XSL Stylesheets v1.73.2 <http://docbook.sf.net/>
+.\" Date: 03/09/2009
+.\" Manual:
+.\" Source:
+.\"
+.TH "REMOTE\-CACHE" "1" "03/09/2009" "" ""
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.SH "NAME"
+remote-cache - Read-Only caching daemon for re-exporting remote NFS shares
+.SH "SYNOPSIS"
+.HP 282
+\fBremote\-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]
+ \fR
+.SH "DESCRIPTION"
+.PP
+Remote\-cache is a fuse module that is used to create a local read\-only cached copy of a remote NFS share\. The purpose of this is to provide a local cache of a remote NFS share in order to provide access to the data\. NFS is VERY painful and slow to use across >100ms links\.
+.SS "\-\-remote"
+.PP
+This specifies the mountpoint where the remote NFS server is mounted\. This is the remote share we will "wan\-accelerate" using remote\-cache\.
+.PP
+This share MUST be mounted as read\-only\. It should also be mounted using soft and intr\.
+.PP
+A good choice of options to mount the remote share with are :
+.sp
+.RS 4
+.nf
+ mount \-o ro,soft,intr,actimeo=600 REMOTE\-SERVER:/share /mnt/remote\-share
+
+.fi
+.RE
+.sp
+.SS "\-\-cache"
+.PP
+This controls which local directory to store the cached copies of the files/data from the share\.
+.PP
+Mtime of the objects are used to track whether an object in the cache is up to data or needs to be remigrated\.
+.SS "\-\-export"
+.PP
+This specifies the mountpoint where this fuse module will attach\. When accessing data through this mountpoint, the fuse module will either return data from the local cache, or if the local cache does not contain an up to date copy of that object, it will instead pass through the request to the remote site\.
+.PP
+This directory can be re\-exported read\-only by the local NFS server to clients on the local site\.
+.SS "\-\-max\-dir\-cache"
+.PP
+Directory content is cached for each directory containing the list of object names that are stored in the directory and also the full stat() information for the objects\.
+.PP
+This parameter controls how long a directory will be cached before it is flushed and re\-read from the remote site\.
+.PP
+This parameter defaults to 0, meaning that once a directory has been cached, it will remain cached forever, or until the mtime of the directory on the remote site changes\.
+.PP
+This means that a directory once cached will remain cached forever until its mtime has changed\. I\.e\. when entries have been added/deleted to the directory\. But since we also cache all the attributes for the child objects in this cache it also means that we will not detect changes to actual child files\. I\.e\. we will not detect if a file has been written to/modified since this does not cause the mtime of the parent directory to change which in turn means we will not flush our cache\. This is by design\.
+.SS "\-\-dir\-min\-inodes"
+.PP
+This parameter defaults to 100\.
+.PP
+When there are less than this number of free inodes in the cache file system remote\-cache will no longer add new directories to the directory structure cache\. When this happens, clients will still be able to access/list these directories but it will be slow since the directories will not be cached and all access will be passed through to the remote site\.
+.PP
+This will be logged with an entry similar to
+.sp
+.RS 4
+.nf
+ 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
+
+.fi
+.RE
+.sp
+.SS "\-\-dir\-min\-blocks"
+.PP
+This parameter defaults to 1000\.
+.PP
+When there are less than this number of free blocks in the cache file system remote\-cache will no longer add new directories to the directory structure cache\. When this happens, clients will still be able to access/list these directories but it will be slow since the directories will not be cached and all access will be passed through to the remote site\.
+.PP
+This will be logged with an entry similar to
+.sp
+.RS 4
+.nf
+ 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
+
+.fi
+.RE
+.sp
+.SS "\-\-file\-min\-inodes"
+.PP
+This parameter defaults to 100\.
+.PP
+When there are less than this number of free inodes in the cache file system remote\-cache will no longer add more files to the cache\. When this happens, clients will still be able to access/read these files but it will be slow since all reads will be passed through to the remote site\.
+.PP
+This will be logged with an entry similar to
+.sp
+.RS 4
+.nf
+ 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
+
+.fi
+.RE
+.sp
+.SS "\-\-file\-min\-blocks"
+.PP
+This parameter defaults to 10000\.
+.PP
+When there are less than this number of free blocks in the cache file system remote\-cache will no longer add more files to the cache\. When this happens, clients will still be able to access/read these files but it will be slow since all i/o will be passed through to the remote site\.
+.PP
+This will be logged with an entry similar to
+.sp
+.RS 4
+.nf
+ 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
+
+.fi
+.RE
+.sp
+.SS "\-\-file\-max\-size"
+.PP
+This parameter defaults to 0\.
+.PP
+Maximum size in MB of files to cache\. Files larger than this will not be copied to the local cache\.
+.PP
+When set to 0 there will be no size limitation of files to cache\.
+.SS "\-\-file\-migrate\-max\-concurrent"
+.PP
+This parameter defaults to 1000\.
+.PP
+Maximum number of concurrent migrations of files we allow before we start failing the migration\. Note that failing a migration is not a severe issue, it just means that the file will be migrate a little while later instead next time it is accessed\.
+.SS "\-\-file\-check\-parent\-mtime"
+.PP
+This paranter can only be used in environments where files are created/deleted but where files are never modified after being created\. Never use this option unless this is true for the i/o patterns of the environment\.
+.PP
+If the environment is an archive server or similar where files, once they have been created are never changed\. Then it is possible to use a more aggressive caching strategy for attributes and instead look at the mtime of the parent directory and the cached directory entries to determine whether the cached file is up to date\. This greatly reduces the amount of GETATTR calls that are issued to the remote site and also greatly reduses the stress on the local nfs clients attribute cache since we only cache the attributes for the directories and never for the leaf objects/files\.
+.PP
+The process works as follows : First get the attributes for the parent directory on the remote site (which most of the time will come out of the nfs clients attribute cache), then compare the mtime with the mtime of the parent directory in the cache directory\. If the directory mtime\'s are the same, then we read the attributes for the file from the local cached copy and return to the client instead of the attributes off the remote server\.
+.SS "\-\-file\-min\-mtime\-age=SECONDS"
+.PP
+Do not migrate the file to the cache if it was changed (based on mtime) less than this many seconds ago\.
+.PP
+This parameter defaults to 120 seconds\.
+.SS "\-\-read\-write"
+.PP
+EXPERIMENTAL\.
+.PP
+This allows the filesystem to be exported read\-write\. All data or metadata changing operations are passed through to the master server and the local cache is invalidated\. Do NOT use this option together with \-\-file\-check\-parent\-mtime\.
+.PP
+Since in this mode all writes are pass\-through, writes will be slow\.
+.SH "EXAMPLES"
+.PP
+Mount the remote server/share on a local mountpoint\.
+.sp
+.RS 4
+.nf
+ mount \-o ro,soft,intr,actimeo=600 REMOTE\-SERVER:/remote\-share /mnt/remote\-share
+
+.fi
+.RE
+.PP
+Create a local export and cache directory
+.sp
+.RS 4
+.nf
+ mkdir /export/data
+ mkdir /export/cache
+
+.fi
+.RE
+.PP
+Startup remote\-cache
+.sp
+.RS 4
+.nf
+ remote\-cache \-\-export=/export/data \-\-cache=/export/cache \-\-remote=/mnt/remote\-share
+
+.fi
+.RE
+.PP
+You can now access the share through /export/data which should be much much faster than accessing it through /mnt/remote\-share if the remote server is more than 10ms away\. Also look in the /export/cache directory to see when/which files are currently cached locally\.
+.SH "CACHE CLEANUP"
+.PP
+Removing data from the cache to reclaim space is easy\.
+.PP
+For files you can just delete them with "rm"\.
+.PP
+If you want to remove an entire directory tree from the cache it is more complex\. For this you must first rename (mv) the directory to something else and then you can "rm \-rf" that renamed directory tree\.
+.SH "LOGGING"
+.PP
+All debug and error messages are logged to /var/log/log\.remote\-cache\.
+.PP
+The log level can be controlled by the \-\-debug=X command line parameter\. The default is 0 : ERROR\.
+.PP
+Possible debuglevels are :
+.sp
+.RS 4
+.nf
+ 0: ERROR
+ 1: WARNING
+ 2: NOTICE
+ 3: INFO
+ 4: DEBUG
+
+.fi
+.RE
+.sp
+.SH "SEE ALSO"
+.PP
+ctdbd(1), ctdb(1),
+\fI\%http://ctdb.samba.org/\fR
+.SH "COPYRIGHT/LICENSE"
+.sp
+.RS 4
+.nf
+Copyright (C) Ronnie Sahlberg 2008
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 3 of the License, or (at
+your option) any later version\.
+
+This program is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE\. See the GNU
+General Public License for more details\.
+
+You should have received a copy of the GNU General Public License
+along with this program; if not, see http://www\.gnu\.org/licenses/\.
+.fi
+.RE
--- /dev/null
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>remote-cache</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en"><a name="onnode.1"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>remote-cache — Read-Only caching daemon for re-exporting remote NFS shares</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="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]
+ </code> </p></div></div><div class="refsect1" lang="en"><a name="id2514489"></a><h2>DESCRIPTION</h2><p>
+ Remote-cache is a fuse module that is used to create a local read-only
+ cached copy of a remote NFS share. The purpose of this is to provide a
+ local cache of a remote NFS share in order to provide access to the data.
+ NFS is VERY painful and slow to use across >100ms links.
+ </p><div class="refsect2" lang="en"><a name="id2478349"></a><h3>--remote</h3><p>
+ This specifies the mountpoint where the remote NFS server is mounted.
+ This is the remote share we will "wan-accelerate" using remote-cache.
+ </p><p>
+ This share MUST be mounted as read-only. It should also be mounted using soft and intr.
+ </p><p>
+ A good choice of options to mount the remote share with are :
+ </p><pre class="screen">
+ mount -o ro,soft,intr,actimeo=600 REMOTE-SERVER:/share /mnt/remote-share
+ </pre><p>
+ </p></div><div class="refsect2" lang="en"><a name="id2478373"></a><h3>--cache</h3><p>
+ This controls which local directory to store the cached copies of the
+ files/data from the share.
+ </p><p>
+ Mtime of the objects are used to track whether an object in the cache
+ is up to data or needs to be remigrated.
+ </p></div><div class="refsect2" lang="en"><a name="id2478389"></a><h3>--export</h3><p>
+ This specifies the mountpoint where this fuse module will attach.
+ When accessing data through this mountpoint, the fuse module will either
+ return data from the local cache, or if the local cache does not contain
+ an up to date copy of that object, it will instead pass through the request
+ to the remote site.
+ </p><p>
+ This directory can be re-exported read-only by the local NFS server to
+ clients on the local site.
+ </p></div><div class="refsect2" lang="en"><a name="id2478408"></a><h3>--max-dir-cache</h3><p>
+ Directory content is cached for each directory containing the list of
+ object names that are stored in the directory and also the full stat()
+ information for the objects.
+ </p><p>
+ This parameter controls how long a directory will be cached before it
+ is flushed and re-read from the remote site.
+ </p><p>
+ This parameter defaults to 0, meaning that once a directory has been
+ cached, it will remain cached forever, or until the mtime of the
+ directory on the remote site changes.
+ </p><p>
+ This means that a directory once cached will remain cached forever until
+ its mtime has changed. I.e. when entries have been added/deleted to the
+ directory.
+ But since we also cache all the attributes for the child objects in this
+ cache it also means that we will not detect changes to actual child files.
+ I.e. we will not detect if a file has been written to/modified since
+ this does not cause the mtime of the parent directory to change
+ which in turn means we will not flush our cache. This is by design.
+ </p></div><div class="refsect2" lang="en"><a name="id2479576"></a><h3>--dir-min-inodes</h3><p>
+ This parameter defaults to 100.
+ </p><p>
+ When there are less than this number of free inodes in the cache file system
+ remote-cache will no longer add new directories to the directory structure
+ cache. When this happens, clients will still be able to access/list these
+ directories but it will be slow since the directories will not be cached
+ and all access will be passed through to the remote site.
+ </p><p>
+ This will be logged with an entry similar to
+ </p><pre class="screen">
+ 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
+ </pre><p>
+ </p></div><div class="refsect2" lang="en"><a name="id2479607"></a><h3>--dir-min-blocks</h3><p>
+ This parameter defaults to 1000.
+ </p><p>
+ When there are less than this number of free blocks in the cache file system
+ remote-cache will no longer add new directories to the directory structure
+ cache. When this happens, clients will still be able to access/list these
+ directories but it will be slow since the directories will not be cached
+ and all access will be passed through to the remote site.
+ </p><p>
+ This will be logged with an entry similar to
+ </p><pre class="screen">
+ 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
+ </pre><p>
+ </p></div><div class="refsect2" lang="en"><a name="id2479638"></a><h3>--file-min-inodes</h3><p>
+ This parameter defaults to 100.
+ </p><p>
+ When there are less than this number of free inodes in the cache file system
+ remote-cache will no longer add more files to the cache.
+ When this happens, clients will still be able to access/read these
+ files but it will be slow since all reads will be passed through to
+ the remote site.
+ </p><p>
+ This will be logged with an entry similar to
+ </p><pre class="screen">
+ 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
+ </pre><p>
+ </p></div><div class="refsect2" lang="en"><a name="id2479669"></a><h3>--file-min-blocks</h3><p>
+ This parameter defaults to 10000.
+ </p><p>
+ When there are less than this number of free blocks in the cache file system
+ remote-cache will no longer add more files to the cache.
+ When this happens, clients will still be able to access/read these
+ files but it will be slow since all i/o will be passed through to the
+ remote site.
+ </p><p>
+ This will be logged with an entry similar to
+ </p><pre class="screen">
+ 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
+ </pre><p>
+ </p></div><div class="refsect2" lang="en"><a name="id2479700"></a><h3>--file-max-size</h3><p>
+ This parameter defaults to 0.
+ </p><p>
+ Maximum size in MB of files to cache. Files larger than this will not be
+ copied to the local cache.
+ </p><p>
+ When set to 0 there will be no size limitation of files to cache.
+ </p></div><div class="refsect2" lang="en"><a name="id2479719"></a><h3>--file-migrate-max-concurrent</h3><p>
+ This parameter defaults to 1000.
+ </p><p>
+ Maximum number of concurrent migrations of files we allow before we start
+ failing the migration.
+
+ Note that failing a migration is not a severe issue, it just means that the
+ file will be migrate a little while later instead next time it is accessed.
+ </p></div><div class="refsect2" lang="en"><a name="id2479736"></a><h3>--file-check-parent-mtime</h3><p>
+ This paranter can only be used in environments where files are
+ created/deleted but where files are never modified after being created.
+ Never use this option unless this is true for the i/o patterns of the
+ environment.
+ </p><p>
+ If the environment is an archive server or similar where files, once they
+ have been created are never changed. Then it is possible to use a more
+ aggressive caching strategy for attributes and instead look at the
+ mtime of the parent directory and the cached directory entries to determine
+ whether the cached file is up to date. This greatly reduces the amount
+ of GETATTR calls that are issued to the remote site and also greatly
+ reduses the stress on the local nfs clients attribute cache since we only
+ cache the attributes for the directories and never for the leaf
+ objects/files.
+ </p><p>
+ The process works as follows : First get the attributes for the parent
+ directory on the remote site (which most of the time will come out of
+ the nfs clients attribute cache), then compare the mtime with the mtime
+ of the parent directory in the cache directory. If the directory mtime's
+ are the same, then we read the attributes for the file from the local
+ cached copy and return to the client instead of the attributes off the
+ remote server.
+ </p></div><div class="refsect2" lang="en"><a name="id2479774"></a><h3>--file-min-mtime-age=SECONDS</h3><p>
+ Do not migrate the file to the cache if it was changed (based on mtime)
+ less than this many seconds ago.
+ </p><p>
+ This parameter defaults to 120 seconds.
+ </p></div><div class="refsect2" lang="en"><a name="id2479789"></a><h3>--read-write</h3><p>
+ EXPERIMENTAL.
+ </p><p>
+ This allows the filesystem to be exported read-write. All data or metadata
+ changing operations are passed through to the master server and the local
+ cache is invalidated. Do NOT use this option together with --file-check-parent-mtime.
+ </p><p>
+ Since in this mode all writes are pass-through, writes will be slow.
+ </p></div></div><div class="refsect1" lang="en"><a name="id2479811"></a><h2>EXAMPLES</h2><p>
+ Mount the remote server/share on a local mountpoint.
+ </p><pre class="screen">
+ mount -o ro,soft,intr,actimeo=600 REMOTE-SERVER:/remote-share /mnt/remote-share
+ </pre><p>
+ </p><p>
+ Create a local export and cache directory
+ </p><pre class="screen">
+ mkdir /export/data
+ mkdir /export/cache
+ </pre><p>
+ </p><p>
+ Startup remote-cache
+ </p><pre class="screen">
+ remote-cache --export=/export/data --cache=/export/cache --remote=/mnt/remote-share
+ </pre><p>
+ </p><p>
+ You can now access the share through /export/data which should be much much
+ faster than accessing it through /mnt/remote-share if the remote server is more than 10ms away.
+ Also look in the /export/cache directory to see when/which files are currently cached locally.
+ </p></div><div class="refsect1" lang="en"><a name="id2528504"></a><h2>CACHE CLEANUP</h2><p>
+ Removing data from the cache to reclaim space is easy.
+ </p><p>
+ For files you can just delete them with "rm".
+ </p><p>
+ If you want to remove an entire directory tree from the cache it is more
+ complex. For this you must first rename (mv) the directory to something else
+ and then you can "rm -rf" that renamed directory tree.
+ </p></div><div class="refsect1" lang="en"><a name="id2528526"></a><h2>LOGGING</h2><p>
+ All debug and error messages are logged to /var/log/log.remote-cache.
+ </p><p>
+ The log level can be controlled by the --debug=X command line parameter.
+ The default is 0 : ERROR.
+ </p><p>
+ Possible debuglevels are :
+ </p><pre class="screen">
+ 0: ERROR
+ 1: WARNING
+ 2: NOTICE
+ 3: INFO
+ 4: DEBUG
+ </pre><p>
+ </p></div><div class="refsect1" lang="en"><a name="id2528552"></a><h2>SEE ALSO</h2><p>
+ ctdbd(1), ctdb(1), <a class="ulink" href="http://ctdb.samba.org/" target="_top">http://ctdb.samba.org/</a>
+ </p></div><div class="refsect1" lang="en"><a name="id2528565"></a><h2>COPYRIGHT/LICENSE</h2><div class="literallayout"><p><br>
+Copyright (C) Ronnie Sahlberg 2008<br>
+<br>
+This program is free software; you can redistribute it and/or modify<br>
+it under the terms of the GNU General Public License as published by<br>
+the Free Software Foundation; either version 3 of the License, or (at<br>
+your option) any later version.<br>
+<br>
+This program is distributed in the hope that it will be useful, but<br>
+WITHOUT ANY WARRANTY; without even the implied warranty of<br>
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU<br>
+General Public License for more details.<br>
+<br>
+You should have received a copy of the GNU General Public License<br>
+along with this program; if not, see http://www.gnu.org/licenses/.<br>
+</p></div></div></div></body></html>
git.samba.org / sahlberg / remote-cache.git / commitdiff