11 KiB
| title | description | date |
|---|---|---|
| Cache | Rclone docs for cache remote | 2017-09-03 |
Cache (BETA)
The cache remote wraps another existing remote and stores file structure
and its data for long running tasks like rclone mount.
To get started you just need to have an existing remote which can be configured
with cache.
Here is an example of how to make a remote called test-cache. First run:
rclone config
This will guide you through an interactive setup process:
No remotes found - make a new one
n) New remote
r) Rename remote
c) Copy remote
s) Set configuration password
q) Quit config
n/r/c/s/q> n
name> test-cache
Type of storage to configure.
Choose a number from below, or type in your own value
...
5 / Cache a remote
\ "cache"
...
Storage> 5
Remote to cache.
Normally should contain a ':' and a path, eg "myremote:path/to/dir",
"myremote:bucket" or maybe "myremote:" (not recommended).
remote> local:/test
Optional: The URL of the Plex server
plex_url> http://127.0.0.1:32400
Optional: The username of the Plex user
plex_username> dummyusername
Optional: The password of the Plex user
y) Yes type in my own password
g) Generate random password
n) No leave this optional password blank
y/g/n> y
Enter the password:
password:
Confirm the password:
password:
The size of a chunk. Lower value good for slow connections but can affect seamless reading.
Default: 5M
Choose a number from below, or type in your own value
1 / 1MB
\ "1m"
2 / 5 MB
\ "5M"
3 / 10 MB
\ "10M"
chunk_size> 2
How much time should object info (file size, file hashes etc) be stored in cache. Use a very high value if you don't plan on changing the source FS from outside the cache.
Accepted units are: "s", "m", "h".
Default: 5m
Choose a number from below, or type in your own value
1 / 1 hour
\ "1h"
2 / 24 hours
\ "24h"
3 / 24 hours
\ "48h"
info_age> 2
The maximum size of stored chunks. When the storage grows beyond this size, the oldest chunks will be deleted.
Default: 10G
Choose a number from below, or type in your own value
1 / 500 MB
\ "500M"
2 / 1 GB
\ "1G"
3 / 10 GB
\ "10G"
chunk_total_size> 3
Remote config
--------------------
[test-cache]
remote = local:/test
plex_url = http://127.0.0.1:32400
plex_username = dummyusername
plex_password = *** ENCRYPTED ***
chunk_size = 5M
info_age = 48h
chunk_total_size = 10G
You can then use it like this,
List directories in top level of your drive
rclone lsd test-cache:
List all the files in your drive
rclone ls test-cache:
To start a cached mount
rclone mount --allow-other test-cache: /var/tmp/test-cache
Write Features
Offline uploading
In an effort to make writing through cache more reliable, the backend
now supports this feature which can be activated by specifying a
cache-tmp-upload-path.
A files goes through these states when using this feature:
- An upload is started (usually by copying a file on the cache remote)
- When the copy to the temporary location is complete the file is part of the cached remote and looks and behaves like any other file (reading included)
- After
cache-tmp-wait-timepasses and the file is next in line,rclone moveis used to move the file to the cloud provider - Reading the file still works during the upload but most modifications on it will be prohibited
- Once the move is complete the file is unlocked for modifications as it becomes as any other regular file
- If the file is being read through
cachewhen it's actually deleted from the temporary path thencachewill simply swap the source to the cloud provider without interrupting the reading (small blip can happen though)
Files are uploaded in sequence and only one file is uploaded at a time.
Uploads will be stored in a queue and be processed based on the order they were added.
The queue and the temporary storage is persistent across restarts but
can be cleared on startup with the --cache-db-purge flag.
Write Support
Writes are supported through cache.
One caveat is that a mounted cache remote does not add any retry or fallback
mechanism to the upload operation. This will depend on the implementation
of the wrapped remote. Consider using Offline uploading for reliable writes.
One special case is covered with cache-writes which will cache the file
data at the same time as the upload when it is enabled making it available
from the cache store immediately once the upload is finished.
Read Features
Multiple connections
To counter the high latency between a local PC where rclone is running and cloud providers, the cache remote can split multiple requests to the cloud provider for smaller file chunks and combines them together locally where they can be available almost immediately before the reader usually needs them.
This is similar to buffering when media files are played online. Rclone will stay around the current marker but always try its best to stay ahead and prepare the data before.
Plex Integration
There is a direct integration with Plex which allows cache to detect during reading if the file is in playback or not. This helps cache to adapt how it queries the cloud provider depending on what is needed for.
Scans will have a minimum amount of workers (1) while in a confirmed playback cache will deploy the configured number of workers.
This integration opens the doorway to additional performance improvements which will be explored in the near future.
Note: If Plex options are not configured, cache will function with its
configured options without adapting any of its settings.
How to enable? Run rclone config and add all the Plex options (endpoint, username
and password) in your remote and it will be automatically enabled.
Affected settings:
cache-workers: Configured value during confirmed playback or 1 all the other times
Certificate Validation
When the Plex server is configured to only accept secure connections, it is
possible to use .plex.direct URL's to ensure certificate validation succeeds.
These URL's are used by Plex internally to connect to the Plex server securely.
The format for this URL's is the following:
https://ip-with-dots-replaced.server-hash.plex.direct:32400/
The ip-with-dots-replaced part can be any IPv4 address, where the dots
have been replaced with dashes, e.g. 127.0.0.1 becomes 127-0-0-1.
To get the server-hash part, the easiest way is to visit
https://plex.tv/api/resources?includeHttps=1&X-Plex-Token=your-plex-token
This page will list all the available Plex servers for your account
with at least one .plex.direct link for each. Copy one URL and replace
the IP address with the desired address. This can be used as the
plex_url value.
Known issues
Mount and --dir-cache-time
--dir-cache-time controls the first layer of directory caching which works at the mount layer.
Being an independent caching mechanism from the cache backend, it will manage its own entries
based on the configured time.
To avoid getting in a scenario where dir cache has obsolete data and cache would have the correct
one, try to set --dir-cache-time to a lower time than --cache-info-age. Default values are
already configured in this way.
Windows support - Experimental
There are a couple of issues with Windows mount functionality that still require some investigations.
It should be considered as experimental thus far as fixes come in for this OS.
Most of the issues seem to be related to the difference between filesystems on Linux flavors and Windows as cache is heavily dependant on them.
Any reports or feedback on how cache behaves on this OS is greatly appreciated.
- https://github.com/ncw/rclone/issues/1935
- https://github.com/ncw/rclone/issues/1907
- https://github.com/ncw/rclone/issues/1834
Risk of throttling
Future iterations of the cache backend will make use of the pooling functionality of the cloud provider to synchronize and at the same time make writing through it more tolerant to failures.
There are a couple of enhancements in track to add these but in the meantime there is a valid concern that the expiring cache listings can lead to cloud provider throttles or bans due to repeated queries on it for very large mounts.
Some recommendations:
- don't use a very small interval for entry informations (
--cache-info-age) - while writes aren't yet optimised, you can still write through
cachewhich gives you the advantage of adding the file in the cache at the same time if configured to do so.
Future enhancements:
cache and crypt
One common scenario is to keep your data encrypted in the cloud provider
using the crypt remote. crypt uses a similar technique to wrap around
an existing remote and handles this translation in a seamless way.
There is an issue with wrapping the remotes in this order: cloud remote -> crypt -> cache
During testing, I experienced a lot of bans with the remotes in this order. I suspect it might be related to how crypt opens files on the cloud provider which makes it think we're downloading the full file instead of small chunks. Organizing the remotes in this order yelds better results: cloud remote -> cache -> crypt
absolute remote paths
cache can not differentiate between relative and absolute paths for the wrapped remote.
Any path given in the remote config setting and on the command line will be passed to
the wrapped remote as is, but for storing the chunks on disk the path will be made
relative by removing any leading / character.
This behavior is irrelevant for most backend types, but there are backends where a leading /
changes the effective directory, e.g. in the sftp backend paths starting with a / are
relative to the root of the SSH server and paths without are relative to the user home directory.
As a result sftp:bin and sftp:/bin will share the same cache folder, even if they represent
a different directory on the SSH server.
Cache and Remote Control (--rc)
Cache supports the new --rc mode in rclone and can be remote controlled through the following end points:
By default, the listener is disabled if you do not add the flag.
rc cache/expire
Purge a remote from the cache backend. Supports either a directory or a file. It supports both encrypted and unencrypted file names if cache is wrapped by crypt.
Params:
- remote = path to remote (required)
- withData = true/false to delete cached data (chunks) as well (optional, false by default)