view release on metacpan or search on metacpan
- That advice is given only when a directory really is unwritable, so
a full disk or a root that is a file keeps its own error.
[ Documentation ]
- The examples are split by machine - what to run on the
server, on each client, and from cron - and keep the master in a
home directory, so nothing needs sudo.
- What a /srv/filesync root needs instead, the wrapper that
adds --root to filesync-server, and the ssh key the first sync
requires.
- The backup and restore commands follow the example's master
layout, and make the backup directory before cron mirrors into it.
- The synopsis creates the repo first, so it runs as printed.
0.001.1 Sat Oct 24 09:52:47 AM EDT 2026
[ Bug Fixes ]
- Build: test on Windows with Perl 5.42 again. Its B::Hooks::EndOfScope
faults at exit, so the plain-Perl hook is used there.
- filesync, filesync-server and filesync-admin select that hook for
themselves on 5.42 for Windows, so it no longer has to be set to run
them; an implementation already in the environment is left alone.
A test checks the choice in a child process that starts without the
MANIFEST.SKIP view on Meta::CPAN
\bblibdirs\.ts$ # 6.18 through 6.25 generated this
# Avoid Module::Build generated and utility files.
\bBuild$
\b_build/
\bBuild.bat$
\bBuild.COM$
\bBUILD.COM$
\bbuild.com$
# Avoid temp and backup files.
~$
\.old$
\#$
\b\.#
\.bak$
\.tmp$
\.#
\.rej$
schemas\.yml$
\.swp$
sudo mkdir -p /srv/filesync
sudo chown -R foo /srv/filesync
```
`filesync-admin repo create documents` works as it is, and the master is
`/srv/filesync/master/documents`.
### Backup and Restore
The master directory is an ordinary directory tree, so it can be mirrored to a
backup directory from the server account's crontab. Make the backup directory
once - rsync creates the last component only - then let cron keep it in step:
```
# on the server, once
mkdir -p /home/foo/backups/documents
# crontab -e, on the server
* * * * * ionice -c3 rsync -a --delete --exclude '.filesync-tmp-*' \
/home/foo/filesync/master/documents/ /home/foo/backups/documents/
```
Filesync writes each file to a temporary name and renames it into place, so the
mirror never catches a half-written upload; the exclusion keeps the temporary
files themselves out of the backup. `--delete` makes the copy a mirror: a
deletion that reaches the master also removes the backed-up file.
To restore the master from that backup, stop the client jobs (comment out their
cron lines, or disable the scheduled task) and the server's backup job, so the
backup job cannot copy a half-restored tree back into the backup. Let any
running sync finish, then mirror the backup back:
```
rsync -a --delete --checksum \
/home/foo/backups/documents/ /home/foo/filesync/master/documents/
```
`--checksum` compares the contents, so a restored file is not skipped just
because its size and modification time happen to match the newer copy. This is
a rollback rather than a merge: files created after the backup was taken
disappear from the master, and the next sync propagates that to the clients, so
copy anything you need to keep out of the tree first. The server
would rehash the restored files on the next session anyway, but
`filesync-admin reindex` rebuilds the index immediately, before any client
reconnects; clients then pull the restored versions, merging edits they have not
synced as usual.
Before re-enabling the jobs, check that the copy is exact with a read-only
comparison against the backup:
```
rsync -a --delete --checksum --dry-run --itemize-changes \
/home/foo/backups/documents/ /home/foo/filesync/master/documents/
```
No output and exit 0 mean the master matches the backup. Any line beginning
`>f` names a path that still differs, and `*deleting` names one the
rollback should have removed. The index still describes the pre-rollback tree,
so `filesync-admin verify` may report drift at this point; that is expected.
Rebuild it and check it:
```
filesync-admin --root ~/filesync reindex documents
filesync-admin --root ~/filesync verify documents --deep
```
`reindex` hashes every file in the master and replaces the index atomically; it
refuses to run while a sync session holds the repo lock, and it names any paths
it could not index. `clean` and exit 0 from `verify` confirm that the master
and its index agree. Re-enable the jobs once that check passes.
To restore just one file or directory, copy that path back instead of mirroring
the whole tree, with the jobs paused as above so nothing changes the tree while
the copy runs:
```
rsync -a --checksum /home/foo/backups/documents/notes/plan.txt \
/home/foo/filesync/master/documents/notes/
rsync -a --checksum /home/foo/backups/documents/photos/ \
/home/foo/filesync/master/documents/photos/
```
The trailing slash on the second source copies the directory's contents; without
it rsync would put the directory itself inside the destination. Add `--delete`
only when that directory should match the backup exactly, since it removes files
created after the backup was taken. Everything outside the restored paths is
left alone; refresh the index with `reindex` as above, or let the next session
do it, and clients pull the restored versions. Check the restored paths with the
matching `rsync --dry-run --itemize-changes` comparison before re-enabling the
jobs; no output means they match the backup.
Adjust `/usr/local/bin/filesync` to where the script was installed, because
cron's default PATH rarely includes a per-user Perl bin directory.
## Limitations
These are the design weaknesses a reviewer should weigh before relying on the
tool. None of them loses data silently; most cost time or space.
- **One master.** The topology is a star around one server. The replica
lib/App/FileSync.pm view on Meta::CPAN
# on the server, as an administrator
sudo mkdir -p /srv/filesync
sudo chown -R foo /srv/filesync
C<filesync-admin repo create documents> works as it is, and the master is
F</srv/filesync/master/documents>.
=head2 Backup and restore
The master directory is an ordinary directory tree, so it can be mirrored to a
backup directory from the server account's crontab. Make the backup directory
once - rsync creates the last component only - then let cron keep it in step:
# on the server, once
mkdir -p /home/foo/backups/documents
# crontab -e, on the server
* * * * * ionice -c3 rsync -a --delete --exclude '.filesync-tmp-*' \
/home/foo/filesync/master/documents/ /home/foo/backups/documents/
Filesync writes each file to a temporary name and renames it into place, so the
mirror never catches a half-written upload; the exclusion keeps the temporary
files themselves out of the backup. C<--delete> makes the copy a mirror: a
deletion that reaches the master also removes the backed-up file.
To restore the master from that backup, stop the client jobs (comment out their
cron lines, or disable the scheduled task) and the server's backup job, so the
backup job cannot copy a half-restored tree back into the backup. Let any
running sync finish, then mirror the backup back:
rsync -a --delete --checksum \
/home/foo/backups/documents/ /home/foo/filesync/master/documents/
C<--checksum> compares the contents, so a restored file is not skipped just
because its size and modification time happen to match the newer copy. This is
a rollback rather than a merge: files created after the backup was taken
disappear from the master, and the next sync propagates that to the clients, so
copy anything you need to keep out of the tree first. The server
would rehash the restored files on the next session anyway, but
C<filesync-admin reindex> rebuilds the index immediately, before any client
reconnects; clients then pull the restored versions, merging edits they have not
synced as usual.
Before re-enabling the jobs, check that the copy is exact with a read-only
comparison against the backup:
rsync -a --delete --checksum --dry-run --itemize-changes \
/home/foo/backups/documents/ /home/foo/filesync/master/documents/
No output and exit 0 mean the master matches the backup. Any line beginning
C<< >f >> names a path that still differs, and C<*deleting> names one the
rollback should have removed. The index still describes the pre-rollback tree,
so C<filesync-admin verify> may report drift at this point; that is expected.
Rebuild it and check it:
filesync-admin --root ~/filesync reindex documents
filesync-admin --root ~/filesync verify documents --deep
C<reindex> hashes every file in the master and replaces the index atomically; it
refuses to run while a sync session holds the repo lock, and it names any paths
it could not index. C<clean> and exit 0 from C<verify> confirm that the master
and its index agree. Re-enable the jobs once that check passes.
To restore just one file or directory, copy that path back instead of mirroring
the whole tree, with the jobs paused as above so nothing changes the tree while
the copy runs:
rsync -a --checksum /home/foo/backups/documents/notes/plan.txt \
/home/foo/filesync/master/documents/notes/
rsync -a --checksum /home/foo/backups/documents/photos/ \
/home/foo/filesync/master/documents/photos/
The trailing slash on the second source copies the directory's contents; without
it rsync would put the directory itself inside the destination. Add C<--delete>
only when that directory should match the backup exactly, since it removes files
created after the backup was taken. Everything outside the restored paths is
left alone; refresh the index with C<reindex> as above, or let the next session
do it, and clients pull the restored versions. Check the restored paths with the
matching C<rsync --dry-run --itemize-changes> comparison before re-enabling the
jobs; no output means they match the backup.
Adjust F</usr/local/bin/filesync> to where the script was installed, because
cron's default PATH rarely includes a per-user Perl bin directory.
=head1 LIMITATIONS
These are the design weaknesses a reviewer should weigh before relying on the
tool. None of them loses data silently; most cost time or space.
=over 4
lib/App/FileSync/Admin.pm view on Meta::CPAN
Args: C<repo>, C<client> (a client id), optional C<role> (C<client>, the
default, or C<replica>).
Returns: C<{ client, role }>.
Side Effects: rewrites the repo config. Allowing an existing client again
changes its role.
Usage:
$admin->client_allow(repo => 'docs', client => 'backup', role => 'replica');
=head3 EXAMPLE
$admin->client_allow(repo => 'docs', client => 'laptop');
=head3 API SPECIFICATION
=head4 INPUT
{
lib/App/FileSync/Admin.pm view on Meta::CPAN
ok => $report->{ok} ? 1 : 0,
});
return $report;
}
=head2 reindex
Purpose: rebuild F<master.json> from the tree, hashing every file.
Used after a manual repair (a rollback from a backup, say) so the index
describes the restored master without waiting for the next client session.
The old index is deliberately not reused: a restored file can keep its size
and mtime while its content differs, which is exactly the case reindex exists
for.
Args: C<repo>, optional C<dry_run>.
Returns: C<{ repo, master, index, files, dirs, bytes, skipped, dry_run, written }>.
Side Effects: holds the repo lock (the same one the server takes), so it never
lib/App/FileSync/IO.pm view on Meta::CPAN
Side Effects: creates C<$destination>'s parent directories; overwrites
C<$destination>.
Usage:
copy_preserving($from, $to, \@stat);
=head3 EXAMPLE
copy_preserving('/srv/a.txt', '/backup/a.txt');
=head3 API SPECIFICATION
=head4 INPUT
[
{ name => 'source', type => 'string', min => 1 },
{ name => 'destination', type => 'string', min => 1 },
{ name => 'stat', type => 'arrayref', optional => 1 },
]
lib/App/FileSync/Scan.pm view on Meta::CPAN
1;
__END__
=head1 LIMITATIONS
=over 4
=item * The cache trusts size and mtime. A tool that rewrites a file and
restores its mtime (some backup restorers do) goes unnoticed until a
C<verify --deep>.
=item * Every run stats every file; there is no change notification. On a
very large tree the walk, not the transfer, dominates a quiet run.
=item * Directory order is sorted, which costs an O(n log n) per directory
but makes manifests and logs reproducible.
=back
lib/App/FileSync/Transport/SSH.pm view on Meta::CPAN
C<.bat> ssh wrapper is started through C<COMSPEC>, since CreateProcess cannot
start one directly.
Usage:
my $transport = App::FileSync::Transport::SSH->new(%args);
=head3 EXAMPLE
my $t = App::FileSync::Transport::SSH->new(
server => 'backup', repo => 'photos', client => 'nas', role => 'replica', port => 2222,
);
print join(' ', @{ $t->command }), "\n";
=head3 API SPECIFICATION
=head4 INPUT
{
server => { type => 'string', matches => $SERVER },
repo => { type => 'string', min => 1, max => 64 },
lib/App/FileSync/Trash.pm view on Meta::CPAN
1;
__END__
=head1 LIMITATIONS
=over 4
=item * A same-day collision is stored as C<PATH.N>. A real file whose name
already ends in C<.N> (C<backup.1>) deleted the same day as C<backup> is
therefore listed as a version of C<backup> too.
=item * Moving a directory across filesystems is not supported; files are
copied and removed, directories must rename.
=item * Pruning works in whole UTC days, so retention is accurate to a day.
=back
=head1 AUTHOR
lib/App/FileSync/Verify.pm view on Meta::CPAN
__END__
=head1 LIMITATIONS
=over 4
=item * A shallow verify trusts size and mtime, so it cannot see a change that
kept both; use C<deep> or C<sample> for that.
=item * The report says what differs, not which side is right. After a
restore from backup the index, not the tree, is usually the stale one; see
C<filesync-admin reindex>.
=back
=head1 AUTHOR
Nigel Horne, C<< <njh at nigelhorne.com> >>
=head1 LICENCE AND COPYRIGHT
is($stable->{summary}{pulled}, 0, 'nothing is left to pull after the rejoin');
is($stable->{summary}{pushed}, 0, 'nothing is left to push after the rejoin');
is_deeply(files_only($env, $env->{client}), files_only($env, master_dir($env)),
'the rejoined client and master hold the same files');
}
# ------------------------------------- rejoining a forgotten replica
# A replica never pushes and never keeps conflict copies: after a forget it
# must still mirror the master, overwriting local edits and removing extras.
{
my $env = TestSync->new_env(client_id => 'backup-1', role => 'replica');
$env->write_file('server', 'a.txt', "master a\n", $T0);
$env->write_file('server', 'sub/b.txt', "master b\n", $T0 + 1);
make_path($env->server_path('empty'));
my $first = $env->sync();
is($first->{summary}{pulled}, 3, 'the replica first mirrors the files and empty dir');
is($first->{summary}{pushed}, 0, 'and never pushes');
my $base = $env->meta_path('clients', 'backup-1.json');
ok(-e $base, 'the server stored a base for the replica');
# Both sides change before the replica is forgotten: the master edits one
# file, adds one and removes one; the replica edits the same file, adds an
# extra and loses the empty directory.
$env->write_file('server', 'a.txt', "master changed\n", $T0 + 300);
$env->write_file('server', 'master-only.txt', "master only\n", $T0 + 100);
unlink $env->server_path('sub/b.txt');
# The replica's edit is newer than the master's, so a normal client would
# win this path; a replica must still discard its version.
$env->write_file('client', 'a.txt', "replica edit\n", $T0 + 400);
$env->write_file('client', 'rogue.txt', "not on the master\n", $T0 + 200);
rmdir $env->client_path('empty') or die "Cannot remove the replica empty dir: $!";
my $output = `$^X $admin --root $env->{server} client forget backup-1 --repo docs 2>&1`;
is($?, 0, 'the replica can be forgotten');
like($output, qr/Forgot backup-1/, 'the admin command names the replica');
ok(!-e $base, 'the stored base is gone');
my $rejoin = $env->sync();
is($rejoin->{summary}{pulled}, 4,
'the rejoin pulls the changed, added and missing-directory entries');
is($rejoin->{summary}{pushed}, 0, 'the forgotten replica still never pushes');
is($rejoin->{summary}{deleted}, 2, 'it removes its extra and the master-deleted file');
is($rejoin->{summary}{conflicts}, 0, 'a replica has no conflicts to resolve');
is($rejoin->{exit}, 3, 'the removals are reported as warnings');
is($env->read_file('client', 'a.txt'), "master again\n",
'the later master edit is mirrored');
ok(!$env->exists_in('client', 'another-rogue.txt'), 'the later extra is gone');
}
# A forgotten replica must not let an empty master wipe a populated mirror.
# With no base there is no baseline for the percentage limit, so the absolute
# max_deletes guard is the protection that matters here.
{
my $env = TestSync->new_env(
client_id => 'backup-1', role => 'replica', max_deletes => 3,
);
$env->write_file('server', "file$_.txt", "master $_\n", $T0 + $_)
for 1 .. 5;
my $first = $env->sync();
is($first->{summary}{pulled}, 5, 'the replica mirrors the five master files');
my $base = $env->meta_path('clients', 'backup-1.json');
ok(-e $base, 'the replica has a stored base');
# The master is emptied, then the replica is forgotten. Without a base the
# only surviving limit is max_deletes.
unlink $env->server_path("file$_.txt") for 1 .. 5;
my $output = `$^X $admin --root $env->{server} client forget backup-1 --repo docs 2>&1`;
is($?, 0, 'the replica can be forgotten');
ok(!-e $base, 'its base is gone');
my $before = $env->snapshot($env->{client});
my $error;
eval { $env->sync(); 1 } or $error = $@;
ok($error, 'the rejoin is refused without --force');
like($error, qr/refusing to delete 5 files \(limit is 3\)/,
'the refusal names the deletion count and the guard');
{ gone => entry($H1, 100), kept => entry($H1, 100) },
);
is($ordered->[0]{a}, 'delete_remote', 'deletions are ordered first');
is($ordered->[1]{a}, 'push', 'transfers follow');
# Replica: mirror only, never push.
my $replica = App::FileSync::Merge::plan(
base => { a => entry($H1, 100) },
client => { a => entry($H2, 200), extra => entry($H1, 100) },
master => { a => entry($H1, 100), b => entry($H3, 100) },
client_id => 'backup-1',
role => 'replica',
);
my %replica_actions = map { $_->{p} => $_->{a} } @{ $replica->{actions} };
is_deeply(\%replica_actions, { a => 'pull', b => 'pull', extra => 'delete_local' },
'replica pulls what differs and removes extras, never pushes');
is($replica->{conflicts}, 0, 'a replica cannot conflict');
ok((grep { $_ =~ /changed on the replica/ } @{ $replica->{warnings} }),
'local replica edits are reported');
# Delete guard.
t/replica.t view on Meta::CPAN
use File::Path qw(make_path);
use File::Spec;
use lib 't/lib';
use TestSync;
use App::FileSync::Protocol;
use App::FileSync::Transport::Local;
my $T0 = 1_700_000_000;
my $env = TestSync->new_env(client_id => 'backup-1', role => 'replica');
# Populate the master (an administrator can drop files in directly).
$env->write_file('server', 'a.txt', "master a\n", $T0);
$env->write_file('server', 'sub/b.txt', "master b\n", $T0 + 1);
make_path(File::Spec->catdir($env->{server}, 'master', 'docs', 'empty'));
my $first = $env->sync();
is($first->{summary}{pulled}, 3, 'replica pulls the files and the empty directory');
is($env->read_file('client', 'a.txt'), "master a\n", 'content mirrored');
ok($env->exists_in('client', 'sub/b.txt'), 'nested file mirrored');
t/replica.t view on Meta::CPAN
# And the replica never pushes even when the master changes.
$env->write_file('server', 'a.txt', "master changed\n", $T0 + 700);
my $pull = $env->sync();
is($pull->{summary}{pulled}, 1, 'master changes reach the replica');
is($env->read_file('server', 'a.txt'), "master changed\n", 'master content untouched by the replica');
# A hostile or confused replica cannot write, even by talking the protocol
# directly: the plan it is given contains no write actions at all.
{
my $env = TestSync->new_env(client_id => 'backup-2', role => 'replica');
$env->write_file('server', 'a.txt', "master\n", $T0);
my $transport = App::FileSync::Transport::Local->new(
root => $env->{server},
repo => 'docs',
client => 'backup-2',
role => 'replica',
);
my $conn = App::FileSync::Protocol->new(
in => $transport->reader(),
out => $transport->writer(),
);
$conn->send({
cmd => 'hello', proto => 2, client => 'backup-2', host => 'test', os => $^O,
role => 'replica', repo => 'docs', case_insensitive => 0, now => time,
});
ok($conn->recv()->{ok}, 'the replica session opens');
my $content = "evil\n";
my $sha = Digest::SHA->new(256);
$sha->add($content);
my $hash = $sha->hexdigest();
$conn->send({
t/replica.t view on Meta::CPAN
ok(!$env->exists_in('server', 'evil.txt'), 'nothing was written to the master');
$transport->close();
}
# A replica with a surviving base is stopped by the percentage deletion guard.
# The absolute limit is set far above the deletion count, so only the share of
# the base decides; with the base still present, that rule has a baseline.
{
my $env = TestSync->new_env(
client_id => 'backup-3', role => 'replica', max_deletes => 500,
);
$env->write_file('server', "file$_.txt", "master $_\n", $T0 + $_)
for 1 .. 10;
my $first = $env->sync();
is($first->{summary}{pulled}, 10, 'the replica mirrors all ten master files');
my $base = $env->meta_path('clients', 'backup-3.json');
ok(-e $base, 'the replica keeps its base, so the percentage rule applies');
my $base_before = do {
local $/;
open my $fh, '<', $base or die "Cannot read $base: $!";
<$fh>;
};
# The master loses eight of its ten files.
unlink $env->server_path("file$_.txt") for 3 .. 10;
t/replica.t view on Meta::CPAN
my $stable = $env->sync();
is($stable->{summary}{deleted}, 0, 'nothing is left to delete after --force');
is($stable->{summary}{pulled}, 0, 'and nothing is left to pull');
is($stable->{summary}{pushed}, 0, 'and the replica still pushes nothing');
}
# The same guard allows deletions up to the percentage limit. Two of twenty
# files is exactly the 10% allowance, so this mirror converges without --force.
{
my $env = TestSync->new_env(
client_id => 'backup-4', role => 'replica', max_deletes => 500,
);
$env->write_file('server', sprintf('file%02d.txt', $_), "master $_\n", $T0 + $_)
for 1 .. 20;
my $first = $env->sync();
is($first->{summary}{pulled}, 20, 'the replica mirrors twenty master files');
# Deletions at the limit are allowed; only a larger share is refused.
unlink $env->server_path('file19.txt');
t/replica.t view on Meta::CPAN
my $stable = $env->sync();
is($stable->{summary}{deleted}, 0, 'the allowed deletion is not repeated');
is($stable->{summary}{pulled}, 0, 'nothing is left to pull');
is($stable->{summary}{pushed}, 0, 'and nothing is pushed');
}
# One deletion over the allowance is refused: three of twenty is 15%, above
# the 10% limit, so the mirror must stay put until --force says otherwise.
{
my $env = TestSync->new_env(
client_id => 'backup-5', role => 'replica', max_deletes => 500,
);
$env->write_file('server', sprintf('file%02d.txt', $_), "master $_\n", $T0 + $_)
for 1 .. 20;
my $first = $env->sync();
is($first->{summary}{pulled}, 20, 'the replica mirrors twenty master files');
my $base = $env->meta_path('clients', 'backup-5.json');
my $base_before = do {
local $/;
open my $fh, '<', $base or die "Cannot read $base: $!";
<$fh>;
};
unlink $env->server_path('file18.txt');
unlink $env->server_path('file19.txt');
unlink $env->server_path('file20.txt');
t/snapshot.t view on Meta::CPAN
write_file("$root/a.txt", "edited in place\n", $T0 + 600);
is(read_file("$linked->{path}/a.txt"), "edited in place\n",
'in-place edits show through a hardlinked snapshot (documented caveat)');
is(read_file("$copy->{path}/a.txt"), "alpha\n",
'a copy-mode snapshot is unaffected by in-place edits');
}
}
# ------------------------------------------- snapshots and the replica mirror
{
my $env = TestSync->new_env(client_id => 'backup-1', role => 'replica');
$env->write_file('server', 'a.txt', "master a\n", $T0);
$env->write_file('server', 'sub/b.txt', "master b\n", $T0 + 1);
$env->sync();
my $snapshot = $env->snapshot_create();
is($snapshot->{created}, 1, 'the replica takes a snapshot');
is($snapshot->{files}, 2, 'the snapshot holds the mirrored files');
ok(-e File::Spec->catfile($env->{client}, '.filesync-snapshots', $snapshot->{date}, 'a.txt'),
'the snapshot lives inside the replica root');
t/snapshot.t view on Meta::CPAN
is_deeply(
[ map { $_->{date} } @{ $env->snapshot_list()->{snapshots} } ],
[ $snapshot->{date} ],
'the replica lists its snapshot',
);
}
# ------------------------------------------------------------- command line
{
my $env = TestSync->new_env(client_id => 'backup-1', role => 'replica');
$env->write_file('server', 'a.txt', "master\n", $T0);
$env->sync();
App::FileSync::Snapshot::create(root => $env->{client}, date => '2026-01-01');
App::FileSync::Snapshot::create(root => $env->{client}, date => '2026-01-02');
my $output = `$^X $filesync snapshot --repo docs --keep 2 2>&1`;
is($?, 0, 'filesync snapshot exits 0');
like($output, qr/snapshot \d{4}-\d{2}-\d{2} taken \(1 file, 7 B\)/,
website/html/changelog.html view on Meta::CPAN
</ul>
<h3>Documentation</h3>
<ul>
<li>The examples are split by machine — what to run on the server, on
each client, and from cron — and keep the master in a home directory,
so nothing needs sudo.</li>
<li>What a <code>/srv/filesync</code> root needs instead, the wrapper that
adds <code>--root</code> to <code>filesync-server</code>, and the ssh key the
first sync requires.</li>
<li>The backup and restore commands follow the example's master layout, and
make the backup directory before cron mirrors into it.</li>
<li>The synopsis creates the repo first, so it runs as printed.</li>
</ul>
<h2 id="v0-001-1">0.001.1 <span class="muted">— 24 October 2026</span></h2>
<h3>Bug fixes</h3>
<ul>
<li>Build: test on Windows with Perl 5.42 again. Its
<code>B::Hooks::EndOfScope</code> faults at exit, so the plain-Perl hook is
used there.</li>
website/html/commands.html view on Meta::CPAN
<thead>
<tr><th>Command</th><th>What it does</th></tr>
</thead>
<tbody>
<tr><td><code>repo create</code></td><td>Creates the master tree, the metadata directory, the policy and an empty index. <code>--trash-days</code> sets retention, <code>--max-deletes</code> and <code>--max-delete-percent</code> the per-session del...
<tr><td><code>repo list</code></td><td>Lists the repos under the root.</td></tr>
<tr><td><code>repo show</code></td><td>Prints one repo's policy.</td></tr>
<tr><td><code>client allow</code></td><td>Admits a client id to a repo, as <code>client</code> or <code>replica</code>. A repo with no listed clients admits every client.</td></tr>
<tr><td><code>client list</code></td><td>Lists a repo's admitted clients.</td></tr>
<tr><td><code>client forget</code></td><td>Removes a client from the list.</td></tr>
<tr><td><code>reindex</code></td><td>Rebuilds the master index by hashing every file. Holds the repo lock. Used after a manual repair such as a rollback from backup; <code>--dry-run</code> reports without writing.</td></tr>
<tr><td><code>verify</code></td><td>Compares the master with its index. <code>--deep</code> hashes every file; <code>--sample N</code> hashes N of them.</td></tr>
<tr><td><code>restore</code></td><td>Puts a path back from the server trash, into the master by default or into <code>--to</code> as an export. <code>--date</code> picks the newest version from that day; <code>--list</code> lists versions. Restori...
<tr><td><code>log</code></td><td>The server's journal, for one or more repos, with the same time, exit and warning filters as <code>filesync log</code> plus <code>--client</code>.</td></tr>
</tbody>
</table>
</div>
<p>If the server root cannot be written, <code>repo create</code> names the
directory that blocks it and says to chown it to the running account or to use
<code>--root</code> elsewhere. That advice is given only when a directory really
website/html/how-it-works.html view on Meta::CPAN
<p>Pulls are requested in chunks and pushes are sent in chunks; each
256 KiB chunk waits for its acknowledgement, so one request is in
flight at a time. Files of at least 64 KiB are sent as block deltas
when the other side already holds an older copy.</p>
</li>
<li>
<h3>Transfers are verified, then committed</h3>
<p>An upload is checked against its SHA-256 at the end and only then
renamed into the master. A pull is checked against the hash in the plan; a
mismatch fails that pull and the next run retries. Temporary names carry
a <code>.filesync-tmp-</code> prefix, which the backup example excludes.</p>
</li>
<li>
<h3>State is written and the run is logged</h3>
<p>The server rewrites the index and the client's base and appends to the
repo journal. The client updates its cache, prunes its local trash unless
<code>--no-prune</code> was given, and appends to
<code>~/.filesync/logs/REPO.jsonl</code> whatever the outcome. The summary
reports pulled, pushed, deleted and conflicted counts, the payload bytes
in each direction, and how many files moved as a delta.</p>
</li>
website/html/how-it-works.html view on Meta::CPAN
<table>
<thead><tr><th>Path</th><th>Holds</th></tr></thead>
<tbody>
<tr><td><code>ROOT/master/REPO/</code></td><td>The master tree, an ordinary directory.</td></tr>
<tr><td><code>ROOT/.filesync/repos/REPO/config.json</code></td><td>The repo policy and the admitted clients.</td></tr>
<tr><td><code>ROOT/.filesync/repos/REPO/</code></td><td>The index, the per-client bases, the server trash and the journal.</td></tr>
</tbody>
</table>
</div>
<p>The master is a normal tree, so backup is rsync and restore is rsync plus
<code>filesync-admin reindex</code>. The index is a JSON file rewritten whole
at the end of each session.</p>
<h2 id="locking">Locking and concurrency</h2>
<p>Both the client and the server take locks, and a refusal is not an error:
<code>filesync</code> exits <strong>2</strong> so cron can tell "a run was
already in progress" from "a run failed". The plan is computed once, from a
scan taken while the repo lock is held; something else writing into the master
during a session is not seen until the next one.</p>
website/html/index.html view on Meta::CPAN
<p>The client reports its host name as its id; there is nothing else to name.
An id is not a login, and it does not divide the repo: every client of a repo
syncs the whole tree.</p>
<h2>Where to go next</h2>
<ul class="grid">
<li class="card">
<h3><a href="quickstart.html">Quick start</a></h3>
<p>Server and client setup, the first sync, cron, Windows, and a
backup-and-restore drill.</p>
</li>
<li class="card">
<h3><a href="commands.html">Commands</a></h3>
<p>Every option of <code>filesync</code>, <code>filesync-admin</code>
and <code>filesync-server</code>, and what each exit code means.</p>
</li>
<li class="card">
<h3><a href="settings.html">Settings</a></h3>
<p>Process-wide settings, the client's repo list, the server's per-repo
policy, and where each value came from.</p>
website/html/limitations.html view on Meta::CPAN
</ul>
<h2>Consistency</h2>
<ul>
<li><strong>Clock-dependent tie-breaks.</strong> When both sides changed a
file, the newer mtime wins (the master wins ties within two seconds). A
client with a wrong clock picks the wrong winner; the loser is still kept as
a conflict copy.</li>
<li><strong>The cache trusts size and mtime.</strong> A tool that rewrites a
file and restores its mtime — some backup restorers do — goes
unnoticed until a <code>verify --deep</code>.</li>
<li><strong>One scan per session.</strong> The plan is computed once, from a
scan taken while the lock is held. Anything other than filesync writing into
the master during a session is not seen until the next session, and a file
it replaces may be overwritten.</li>
<li><strong>Pulls are verified against the plan.</strong> If the master
changes during the session (only possible if something other than filesync
writes to it), the pull fails with a hash mismatch and the next sync
retries.</li>
<li><strong>Uploads are verified only at the end.</strong> A client that
website/html/limitations.html view on Meta::CPAN
<h2>Recovery and administration</h2>
<ul>
<li><strong>Trash is per repo and per client.</strong> Local trash written by
releases before 0.001.1 sits in one shared directory. It is still searched
by <code>restore</code> and pruned with the default 30 days, but a
<code>restore</code> can then offer another repo's file of the same relative
path.</li>
<li><strong>Same-day trash collisions are numeric.</strong> A real file whose
name already ends in <code>.N</code> (<code>backup.1</code>) deleted the same
day as <code>backup</code> is listed as a version of <code>backup</code>
too. Pruning works in whole UTC days, so retention is accurate to a day.</li>
<li><strong>Trash cannot cross filesystems by rename.</strong> Files are
copied and removed; directories must rename.</li>
<li><strong>Admin methods mostly take no lock.</strong> Only
<code>reindex</code> does; <code>restore</code> into the master rebuilds the
index by walking the tree and does not take the repo lock, so a session
running at the same moment can save an index that omits the restored file
until its next sync.</li>
<li><strong>The server journal is read whole.</strong> <code>filesync-admin
log</code> loads every monthly journal into memory before filtering and
website/html/quickstart.html view on Meta::CPAN
<p>On this page</p>
<ul>
<li><a href="#server">On the server</a></li>
<li><a href="#wrapper">The server-command wrapper</a></li>
<li><a href="#client">On each client</a></li>
<li><a href="#first">The first sync</a></li>
<li><a href="#cron">From cron</a></li>
<li><a href="#checking">Checking what happened</a></li>
<li><a href="#windows">On Windows</a></li>
<li><a href="#srv">A root of /srv/filesync instead</a></li>
<li><a href="#backup">Backup and restore</a></li>
</ul>
</div>
<h2 id="server">On the server</h2>
<p>Create the repo as the account the clients log in to. A session over ssh
carries only the repo, the client id and the role, so the client never tells
the server which root to use: name the same <code>--root</code> on every
server command.</p>
website/html/quickstart.html view on Meta::CPAN
for the account the clients log in to. Then no <code>--root</code> is needed
on the server commands, and no <code>--server-command</code> on the client:</p>
<pre><code># on the server, as an administrator
sudo mkdir -p /srv/filesync
sudo chown -R foo /srv/filesync</code></pre>
<p><code>filesync-admin repo create documents</code> then works as it is, and
the master is <code>/srv/filesync/master/documents</code>.</p>
<h2 id="backup">Backup and restore</h2>
<p>The master directory is an ordinary directory tree, so it can be mirrored
to a backup directory from the server account's crontab. Make the backup
directory once — rsync creates the last component only — then let
cron keep it in step:</p>
<pre><code># on the server, once
mkdir -p /home/foo/backups/documents
# crontab -e, on the server
* * * * * ionice -c3 rsync -a --delete --exclude '.filesync-tmp-*' \
/home/foo/filesync/master/documents/ /home/foo/backups/documents/</code></pre>
<p>Filesync writes each file to a temporary name and renames it into place, so
the mirror never catches a half-written upload; the exclusion keeps the
temporary files themselves out of the backup. <code>--delete</code> makes the
copy a mirror: a deletion that reaches the master also removes the backed-up
file.</p>
<p>To restore the master from that backup, stop the client jobs (comment out
their cron lines, or disable the scheduled task) and the server's backup job,
so the backup job cannot copy a half-restored tree back into the backup. Let
any running sync finish, then mirror the backup back:</p>
<pre><code>rsync -a --delete --checksum \
/home/foo/backups/documents/ /home/foo/filesync/master/documents/</code></pre>
<p><code>--checksum</code> compares the contents, so a restored file is not
skipped just because its size and modification time happen to match the newer
copy. This is a rollback rather than a merge: files created after the backup
was taken disappear from the master, and the next sync propagates that to the
clients, so copy anything you need to keep out of the tree first.</p>
<p>The server would rehash the restored files on the next session anyway, but
<code>filesync-admin reindex</code> rebuilds the index immediately, before any
client reconnects; clients then pull the restored versions, merging edits they
have not synced as usual.</p>
<p>Before re-enabling the jobs, check that the copy is exact with a read-only
comparison against the backup:</p>
<pre><code>rsync -a --delete --checksum --dry-run --itemize-changes \
/home/foo/backups/documents/ /home/foo/filesync/master/documents/</code></pre>
<p>No output and exit 0 mean the master matches the backup. Any line beginning
<code>>f</code> names a path that still differs, and <code>*deleting</code>
names one the rollback should have removed. The index still describes the
pre-rollback tree, so <code>filesync-admin verify</code> may report drift at
this point; that is expected. Rebuild it and check it:</p>
<pre><code>filesync-admin --root ~/filesync reindex documents
filesync-admin --root ~/filesync verify documents --deep</code></pre>
<p><code>reindex</code> hashes every file in the master and replaces the index
atomically; it refuses to run while a sync session holds the repo lock, and it
names any paths it could not index. <code>clean</code> and exit 0 from
<code>verify</code> confirm that the master and its index agree. Re-enable the
jobs once that check passes.</p>
<p>To restore just one file or directory, copy that path back instead of
mirroring the whole tree, with the jobs paused as above so nothing changes the
tree while the copy runs:</p>
<pre><code>rsync -a --checksum /home/foo/backups/documents/notes/plan.txt \
/home/foo/filesync/master/documents/notes/
rsync -a --checksum /home/foo/backups/documents/photos/ \
/home/foo/filesync/master/documents/photos/</code></pre>
<p>The trailing slash on the second source copies the directory's contents;
without it rsync would put the directory itself inside the destination. Add
<code>--delete</code> only when that directory should match the backup
exactly, since it removes files created after the backup was taken. Refresh
the index with <code>reindex</code> as above, or let the next session do it,
and clients pull the restored versions.</p>
</main>
<footer class="site-footer">
<div class="wrap">
<p>App::FileSync 0.002.0 · Copyright 2026 Nigel Horne · GPL-2.0</p>
<p><a href="https://metacpan.org/dist/App-FileSync">CPAN</a> ·
<a href="https://github.com/nigelhorne/App-FileSync">GitHub</a> ·
<a href="https://github.com/nigelhorne/App-FileSync/issues">Issues</a> ·