Local Filesystem

In CloudMount

• Android: a local drive can only reach folders Android lets CloudMount read. Use a sync folder to pair a phone folder with a drive.
• Windows: a local folder can be shown in File Explorer as a synced copy, but not one inside or around %USERPROFILE%\CloudMount, which would sync into itself.

At a glance

Capability	Support
rclone support tier	Tier 1: Core
Checksums	All
Modification times	Kept, to 1 ns
Case-insensitive names	No
Duplicate names allowed	No
Server-side copy	No
Server-side move and rename	Yes
Folder move and rename	Yes, in one step
Free space reporting	Yes
Empty folders	Yes
Change notifications	No
Uploads of unknown size	Yes
Public links	No

From rclone’s documentation

The rest of this page is adapted from rclone’s documentation for this backend (rclone v1.75.2, MIT licence). It is written for rclone’s command line: where it mentions a flag such as --local-example, set the option example in the wizard’s options instead. Commands such as rclone copy aren’t part of CloudMount.

Local paths are specified as normal filesystem paths, e.g. /path/to/wherever, so

rclone sync --interactive /home/source /tmp/destination

Will sync /home/source to /tmp/destination.

Setup notes

In CloudMount you add this drive from the Add drive screen, and the wizard asks for the options listed under Options. The notes below come from rclone’s setup guide.

Modification times

Rclone reads and writes the modification times using an accuracy determined by the OS. Typically this is 1ns on Linux, 10 ns on Windows and 1 Second on OS X.

Filenames

Filenames should be encoded in UTF-8 on disk. This is the normal case for Windows and OS X.

There is a bit more uncertainty in the Linux world, but new distributions will have UTF-8 encoded files names. If you are using an old Linux filesystem with non UTF-8 file names (e.g. latin1) then you can use the convmv tool to convert the filesystem to UTF-8. This tool is available in most distributions’ package managers.

If an invalid (non-UTF8) filename is read, the invalid characters will be replaced with a quoted representation of the invalid bytes. The name gro\xdf will be transferred as gro‛DF. rclone will emit a debug message in this case (use -v to see), e.g.

Local file system at .: Replacing invalid UTF-8 characters in "gro\xdf"

Restricted characters

With the local backend, restrictions on the characters that are usable in file or directory names depend on the operating system. To check what rclone will replace by default on your system, run rclone help flags local-encoding.

On non Windows platforms the following characters are replaced when handling file names.

Character	Value	Replacement
NUL	0x00	␀
/	0x2F	／

When running on Windows the following characters are replaced. This list is based on the Windows file naming conventions.

Character	Value	Replacement
NUL	0x00	␀
SOH	0x01	␁
STX	0x02	␂
ETX	0x03	␃
EOT	0x04	␄
ENQ	0x05	␅
ACK	0x06	␆
BEL	0x07	␇
BS	0x08	␈
HT	0x09	␉
LF	0x0A	␊
VT	0x0B	␋
FF	0x0C	␌
CR	0x0D	␍
SO	0x0E	␎
SI	0x0F	␏
DLE	0x10	␐
DC1	0x11	␑
DC2	0x12	␒
DC3	0x13	␓
DC4	0x14	␔
NAK	0x15	␕
SYN	0x16	␖
ETB	0x17	␗
CAN	0x18	␘
EM	0x19	␙
SUB	0x1A	␚
ESC	0x1B	␛
FS	0x1C	␜
GS	0x1D	␝
RS	0x1E	␞
US	0x1F	␟
/	0x2F	／
“	0x22	＂
*	0x2A	＊
:	0x3A	：
<	0x3C	＜
>	0x3E	＞
?	0x3F	？
\	0x5C	＼
|	0x7C	｜

File names on Windows can also not end with the following characters. These only get replaced if they are the last character in the name:

Character	Value	Replacement
SP	0x20	␠
.	0x2E	．

Invalid UTF-8 bytes will also be replaced, as they can’t be converted to UTF-16.

Paths on Windows

On Windows there are many ways of specifying a path to a file system resource. Local paths can be absolute, like C:\path\to\wherever, or relative, like ..\wherever. Network paths in UNC format, \\server\share, are also supported. Path separator can be either \ (as in C:\path\to\wherever) or / (as in C:/path/to/wherever). Length of these paths are limited to 259 characters for files and 247 characters for directories, but there is an alternative extended-length path format increasing the limit to (approximately) 32,767 characters. This format requires absolute paths and the use of prefix \\?\, e.g. \\?\D:\some\very\long\path. For convenience rclone will automatically convert regular paths into the corresponding extended-length paths, so in most cases you do not have to worry about this (read more below). Using the same prefix \\?\ it is also possible to specify path to volumes identified by their GUID, e.g. \\?\Volume{b75e2c83-0000-0000-0000-602f00000000}\some\path.

Long paths

Rclone handles long paths automatically, by converting all paths to extended-length path format, which allows paths up to 32,767 characters.

This conversion will ensure paths are absolute and prefix them with the \\?\. This is why you will see that your paths, for instance .\files is shown as path \\?\C:\files in the output, and \\server\share as \\?\UNC\server\share.

However, in rare cases this may cause problems with buggy file system drivers like EncFS. To disable UNC conversion globally, add this to your .rclone.conf file:

[local]
nounc = true

If you want to selectively disable UNC, you can add it to a separate entry like this:

[nounc]
type = local
nounc = true

And use rclone like this:

rclone copy c:\src nounc:z:\dst

This will use UNC paths on c:\src but not on z:\dst. Of course this will cause problems if the absolute path length of a file exceeds 259 characters on z, so only use this option if you have to.

Symlinks / Junction points

Normally rclone will ignore symlinks or junction points (which behave like symlinks under Windows).

If you supply --copy-links or -L then rclone will follow the symlink and copy the pointed to file or directory. Note that this flag is incompatible with --links / -l.

This flag applies to all commands.

For example, supposing you have a directory structure like this

$ tree /tmp/a
/tmp/a
├── b -> ../b
├── expected -> ../expected
├── one
└── two
    └── three

Then you can see the difference with and without the flag like this

$ rclone ls /tmp/a
        6 one
        6 two/three

and

$ rclone -L ls /tmp/a
     4174 expected
        6 one
        6 two/three
        6 b/two
        6 b/one

--local-links, --links, -l

Normally rclone will ignore symlinks or junction points (which behave like symlinks under Windows).

If you supply this flag then rclone will copy symbolic links from the local storage, and store them as text files, with a .rclonelink suffix in the remote storage.

The text file will contain the target of the symbolic link (see example).

This flag applies to all commands.

For example, supposing you have a directory structure like this

$ tree /tmp/a
/tmp/a
├── file1 -> ./file4
└── file2 -> /home/user/file3

Copying the entire directory with ‘-l’

rclone copy -l /tmp/a/ remote:/tmp/a/

The remote files are created with a .rclonelink suffix

$ rclone ls remote:/tmp/a
       5 file1.rclonelink
      14 file2.rclonelink

The remote files will contain the target of the symbolic links

$ rclone cat remote:/tmp/a/file1.rclonelink
./file4

$ rclone cat remote:/tmp/a/file2.rclonelink
/home/user/file3

Copying them back with ‘-l’

$ rclone copy -l remote:/tmp/a/ /tmp/b/

$ tree /tmp/b
/tmp/b
├── file1 -> ./file4
└── file2 -> /home/user/file3

However, if copied back without ‘-l’

$ rclone copyto remote:/tmp/a/ /tmp/b/

$ tree /tmp/b
/tmp/b
├── file1.rclonelink
└── file2.rclonelink

If you want to copy a single file with -l then you must use the .rclonelink suffix.

$ rclone copy -l remote:/tmp/a/file1.rclonelink /tmp/c

$ tree /tmp/c
/tmp/c
└── file1 -> ./file4

Note that --local-links just enables this feature for the local backend. --links and -l enable the feature for all supported backends and the VFS.

Note that this flag is incompatible with -copy-links / -L.

Symlink targets and the destination

When rclone recreates a .rclonelink file as a symlink on local storage, the symlink can point anywhere - including, with an absolute path or one using ../ - to a location outside the directory you are copying into. This is normal - rclone reproduces whatever target the link had, so backups round-trip faithfully.

What rclone will not do is write through such a link. If a remote you are copying from contains both a symlink and a file or directory that would be placed inside it - for example a dir.rclonelink pointing somewhere outside the destination, alongside a dir/file.txt - rclone refuses to follow the symlink when writing dir/file.txt. The offending file is skipped with an error, the rest of the transfer continues, and the skipped file is counted in the error summary printed at the end of the run.

This protects you from a malicious or compromised remote using -l / --links to plant a symlink and then write through it to somewhere outside your destination. Ordinary symlink round-trips, and symlinks that stay inside the destination, are unaffected.

If you have intentionally pre-created a symlinked directory inside your destination and want rclone to write into the directory it points at, do not use -l / --links for that copy, or remove the symlink first.

Restricting filesystems with --one-file-system

Normally rclone will recurse through filesystems as mounted.

However if you set --one-file-system or -x this tells rclone to stay in the filesystem specified by the root and not to recurse into different file systems.

For example if you have a directory hierarchy like this

root
├── disk1     - disk1 mounted on the root
│   └── file3 - stored on disk1
├── disk2     - disk2 mounted on the root
│   └── file4 - stored on disk12
├── file1     - stored on the root disk
└── file2     - stored on the root disk

Using rclone --one-file-system copy root remote: will only copy file1 and file2. E.g.

$ rclone -q --one-file-system ls root
        0 file1
        0 file2

$ rclone -q ls root
        0 disk1/file3
        0 disk2/file4
        0 file1
        0 file2

NB Rclone (like most unix tools such as du, rsync and tar) treats a bind mount to the same device as being on the same filesystem.

NB This flag is only available on Unix based systems. On systems where it isn’t supported (e.g. Windows) it will be ignored.

Options

Advanced options

The wizard shows these under Advanced options. Most drives work without changing any of them.

nounc

Disable UNC (long path names) conversion on Windows.

Type: bool · Default: false

Choices:

• true: Disables long file names.

copy_links

Follow symlinks and copy the pointed to item.

Type: bool · Default: false

links

Translate symlinks to/from regular files with a ‘.rclonelink’ extension for the local backend.

Type: bool · Default: false

skip_links

Don’t warn about skipped symlinks.

This flag disables warning messages on skipped symlinks or junction points, as you explicitly acknowledge that they should be skipped.

Type: bool · Default: false

skip_specials

Don’t warn about skipped pipes, sockets and device objects.

This flag disables warning messages on skipped pipes, sockets and device objects, as you explicitly acknowledge that they should be skipped.

Type: bool · Default: false

zero_size_links

Assume the Stat size of links is zero (and read them instead) (deprecated).

Rclone used to use the Stat size of links as the link size, but this fails in quite a few places:

• Windows
• On some virtual filesystems (such ash LucidLink)
• Android

So rclone now always reads the link.

Type: bool · Default: false

unicode_normalization

Apply unicode NFC normalization to paths and filenames.

This flag can be used to normalize file names into unicode NFC form that are read from the local filesystem.

Rclone does not normally touch the encoding of file names it reads from the file system.

This can be useful when using macOS as it normally provides decomposed (NFD) unicode which in some language (eg Korean) doesn’t display properly on some OSes.

Note that rclone compares filenames with unicode normalization in the sync routine so this flag shouldn’t normally be used.

Type: bool · Default: false

no_check_updated

Don’t check to see if the files change during upload.

Normally rclone checks the size and modification time of files as they are being uploaded and aborts with a message which starts “can’t copy - source file is being updated” if the file changes during upload.

However on some file systems this modification time check may fail (e.g. Glusterfs #2206) so this check can be disabled with this flag.

If this flag is set, rclone will use its best efforts to transfer a file which is being updated. If the file is only having things appended to it (e.g. a log) then rclone will transfer the log file with the size it had the first time rclone saw it.

If the file is being modified throughout (not just appended to) then the transfer may fail with a hash check failure.

In detail, once the file has had stat() called on it for the first time we:

• Only transfer the size that stat gave
• Only checksum the size that stat gave
• Don’t update the stat info for the file

NB do not use this flag on a Windows Volume Shadow (VSS). For some unknown reason, files in a VSS sometimes show different sizes from the directory listing (where the initial stat value comes from on Windows) and when stat is called on them directly. Other copy tools always use the direct stat value and setting this flag will disable that.

Type: bool · Default: false

one_file_system

Don’t cross filesystem boundaries (unix/macOS only).

Type: bool · Default: false

case_sensitive

Force the filesystem to report itself as case sensitive.

Normally the local backend declares itself as case insensitive on Windows/macOS and case sensitive for everything else. Use this flag to override the default choice.

Type: bool · Default: false

case_insensitive

Force the filesystem to report itself as case insensitive.

Normally the local backend declares itself as case insensitive on Windows/macOS and case sensitive for everything else. Use this flag to override the default choice.

Type: bool · Default: false

no_clone

Disable reflink cloning for server-side copies.

Normally, for local-to-local transfers, rclone will “clone” the file when possible, and fall back to “copying” only when cloning is not supported.

Cloning creates a shallow copy (or “reflink”) which initially shares blocks with the original file. Unlike a “hardlink”, the two files are independent and neither will affect the other if subsequently modified.

Cloning is usually preferable to copying, as it is much faster and is deduplicated by default (i.e. having two identical files does not consume more storage than having just one.) However, for use cases where data redundancy is preferable, –local-no-clone can be used to disable cloning and force “deep” copies.

Currently, cloning is only supported when using APFS on macOS (support for other platforms may be added in the future.)

Type: bool · Default: false

no_preallocate

Disable preallocation of disk space for transferred files.

Preallocation of disk space helps prevent filesystem fragmentation. However, some virtual filesystem layers (such as Google Drive File Stream) may incorrectly set the actual file size equal to the preallocated space, causing checksum and file size checks to fail. Use this flag to disable preallocation.

Type: bool · Default: false

no_sparse

Disable sparse files for multi-thread downloads.

On Windows platforms rclone will make sparse files when doing multi-thread downloads. This avoids long pauses on large files where the OS zeros the file. However sparse files may be undesirable as they cause disk fragmentation and can be slow to work with.

Type: bool · Default: false

no_set_modtime

Disable setting modtime.

Normally rclone updates modification time of files after they are done uploading. This can cause permissions issues on Linux platforms when the user rclone is running as does not own the file uploaded, such as when copying to a CIFS mount owned by another user. If this option is enabled, rclone will no longer update the modtime after copying a file.

Type: bool · Default: false

metadata_restore_special_bits

Restore the setuid, setgid and sticky bits from metadata.

When restoring metadata with –metadata rclone applies the “mode” from the source. By default rclone applies only the permission bits and strips the setuid, setgid and sticky bits.

The “mode” comes from the source remote which may not be trusted. Restoring a setuid or setgid bit onto freshly written, source-controlled content can plant a setuid binary, which is dangerous in particular when restoring from an untrusted source while running as root. For this reason these bits are not restored by default.

If you trust the source and want the setuid, setgid and sticky bits restored - for example when restoring a system backup made by rclone - set this flag.

Type: bool · Default: false

fatal_if_no_space

Make out-of-space errors fatal during transfers.

When enabled, an ENOSPC error during a write returns a fatal error so that rclone aborts rather than retrying the operation. Useful for backup scripts that should halt loudly on a full disk rather than spin retrying.

Type: bool · Default: false

time_type

Set what kind of time is returned.

Normally rclone does all operations on the mtime or Modification time.

If you set this flag then rclone will return the Modified time as whatever you set here. So if you use “rclone lsl –local-time-type ctime” then you will see ctimes in the listing.

If the OS doesn’t support returning the time_type specified then rclone will silently replace it with the modification time which all OSes support.

• mtime is supported by all OSes
• atime is supported on all OSes except: plan9, js
• btime is only supported on: Windows, macOS, freebsd, netbsd
• ctime is supported on all Oses except: Windows, plan9, js

Note that setting the time will still set the modified time so this is only useful for reading.

Type: mtime|atime|btime|ctime · Default: mtime

Choices:

• mtime: The last modification time.
• atime: The last access time.
• btime: The creation time.
• ctime: The last status change time.

hashes

Comma separated list of supported checksum types.

Type: CommaSepList

encoding

The encoding for the backend.

See the encoding section in the overview for more info.

Type: Encoding · Default: Slash,Dot

description

Description of the remote.

Type: string