lcsync(1)

💖 lcsync(1) — IPv6 multicast file sync tool 💖

okay bestie, sit down, hydrate, because this one is genuinely iconic. this is the manual for lcsync, the IPv6 multicast file sync tool. yes, that one. let's go 🦋

---

✨ NAME ✨

lcsync — IPv6 multicast file sync tool. that's the whole vibe. no notes. 💅

---

✨ SYNOPSIS ✨

okay so there are basically four moods you can be in, and here's all of them, verbatim, no cap:

Serve a a single file:
    lcshare [OPTION...] FILENAME

Serve all files below a directory:
    lcshare [OPTION...] DIRECTORY

Sync remote file(s) with local:
    lcsync [OPTION...] REMOTEFILENAME LOCALFILENAME

Sync two local files (Path required. Can be ./):
    lcsync ./LOCALFILE1 ./LOCALFILE2

---

✨ DESCRIPTION ✨

lcsync is a pair of tools — like, a duo, a duo-tang, main character energy times two 👑 — that sync files over IPv6 multicast or over your plain old local filesystem.

the way it works? it splits the file into blocks, hashes them, and compares them so it can efficiently transfer the absolute minimum amount of data. minimal effort, maximum slay. ✨

🫶 the two icons

• lcshare — the server-side component. it indexes files, listens for MLD multicast group joins, and sends the file and directory block data. it's giving hostess with the mostess. 🎀
• lcsync — the client-side component. it joins multicast groups to receive files and directories. it's the one showing up to the party. 💃

---

🌸 lcshare (server) Options

• --loopback — enable multicast loopback, meaning the sending host will receive the data it sent. it's literally sending itself a message and reading it. self-love, honestly. 💖

---

🌸 lcsync (client) Options

• -a, --archive — set archive options, which is [-g -o -p -r -t]. the whole bundle, one flag, so convenient bestie. 🧚
• -n, --dry-run — don't copy any data. just looking. window shopping. no commitment. 👀
• -g, --group — set group on destination.
• -o, --owner — set owner on destination.
• -p, --perms — set permissions on destination.
• --remote — source path is remote. she's not from around here. 🌈
• -t, --times — set modification times on destination.

---

🌸 General Options

• -b, --batch — Batch mode. No prompting. > ⚠️ NB: if you do not specify a keyfile for encryption, encryption will be disabled. so like, heads up. know that. 😭
• --bwlimit INTEGER — Set send rate limit (bps). an SI prefix of T, G, M or K may be added (eg. --bwlimit 10M). throttle her, gently. 🍓
• --hex — print file hashes in hex.
• -i, --interface INTERFACE — Set network interface to use (default: all). she's everywhere, she's every girl. ✨
• --keyfile keyfile — Read symmetric key from keyfile, which must be the path to a file containing a 128 byte random key. This can be created with a command like:

dd if=/dev/random of=keyfile count=1 bs=128

• --loglevel INTEGER — set loglevel. how much tea do you want spilled in the logs, bestie. 💀
• -r, --recursive — recurse into directories. go deeper. it's giving inception. 🌀
• -q, --quiet — shhh - we're hunting wabbits. 🤫🐰
• -v, --verbose — increase verbosity. tell me everything, i'm obsessed. 🗣️
• -V, --version — display version and exit. quick lil flex and then she's gone. 💅

---

🦋 how the remote sync actually goes down

To sync remote files, each file is split into blocks and a merkle tree is built by hashing the blocks using BLAKE3. 🌳✨

On the sending/server side, this tree is sent on a Librecast Channel (IPv6 multicast group) that is formed from the hash of the filename. the receiver/client joins this channel, and receives the tree. 🔥

If the client already has some data to compare, it builds a merkle tree of the destination file and uses this to quickly compare which blocks differ. It builds a bitmap with this information, and then joins the Channel(s) for the block(s) required, which are sent by the server. so organized. so iconic. 👑

Forward Error Correction (FEC) is enabled by default using RaptorQ (RFC 6330) from the Librecast LCRQ library. free error correction, no effort, we love a gift. 🎁

Symmetric encryption is provided using the XSalsa20 stream cipher from libsodium with Poly1305 MAC authentication tags. A keyfile can be provided, or a key can be derived from a user-supplied password. 🔐💖

---

🫶 the truly unhinged part (affectionate)

There is no unicast communication with the server. There are no requests sent, and the server can sit behind a firewall which is completely closed to inbound TCP and UDP traffic. 🚪🔒

Instead, the server listens on a raw socket for Multicast Listener Discovery (MLD2) reports. It compares any MLD multicast group JOINs against the index it built on startup and finds matches for file (tree) and blocks.

In this way, the server only sends data when at least one client is subscribed. If more clients want to download the data, the server need take no further action. Thus, the load on the server does not change at all, regardless of whether there is one client or a billion. 🌍💫

one client or a billion. and the server does. not. care. that's scale, bestie. that's the dream. 😌

---

✨ ENVIRONMENT ✨

• LCSYNC_PASSWORD — the value of LCSYNC_PASSWORD will be used to derive the symmetric encryption key used for encryption and decryption. set it, and she'll do the math herself. 🧮💜

---

✨ BUGS ✨

If you find one, email bugs@librecast.net. fr fr, they wanna know. 🙈

---

✨ SEE ALSO ✨

rsync(1), ipv6(7), lcrq(7) — the friend group. go say hi. 🫶

---

✨ AUTHOR ✨

lcsync was written by Brett Sheffield <bacs@librecast.net> and released under the terms of the GPL-2 or (at your option) GPL-3. 🎀

https://librecast.net/lcsync.html

---

and that's the page, bestie. 🌸 this one came from the lcsync manual, dated 2025-03-08, and it lives at page lcsync(1). mwah. 💖✨🎀🦋