S3QLCP(1)

📦 version 5.2.3, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 S3QLCP — s3qlcp(1) 💖

okay bestie, welcome to the s3qlcp manual page, straight out of the S3QL section of your man pages ✨ this one is short but it's iconic, trust.

✨ NAME ✨

s3qlcp — copy-on-write replication on S3QL file systems 🦋

🎀 SYNOPSIS 🎀

s3qlcp [options] <source-dir> <dest-dir>

🌸 DESCRIPTION 🌸

So, S3QL is a file system for online data storage, and before you start using it, please please please go read the full documentation — not just these man pages, because ngl these only give you the teeny-tiny cliffnotes version of the userspace commands 💅

The s3qlcp command duplicates the directory tree source-dir into dest-dir without physically copying the file contents. and the catch? both source and destination have to live inside the same S3QL file system, no exceptions, fr fr.

The way this replication works: it will not take any additional space for the file contents. Metadata usage will increase proportional to the amount of directory entries and inodes though. And only if one of the directories gets modified later on does the modified data start taking up additional storage space. it's giving ✨efficiency✨

Also important: s3qlcp can only be called by the user that mounted the file system, and (if the file system was mounted with --allow-other or --allow-root) the root user. so if it's not working, check who you are, bestie 🙈

After the replication, both source and target directory are still completely ordinary directories. You can regard <src> as a snapshot of <target> or vice versa. That said, the most common usage of s3qlcp is to regularly duplicate the same source directory — say, documents — to different target directories. For a monthly replication, the target directories would typically be named something like documents_January for the January replication, documents_February for February, etc. And in that case it's clear that the target directories should be regarded as snapshots of the source directory. 👑

Now, technically you could get exactly the same effect by using an ordinary copy program like cp -a. BUT. huge but. That procedure would be orders of magnitude slower, because cp would have to read every single file completely (so S3QL would have to fetch all the data over the network from the backend) before writing them into the destination folder — at which point S3QL would de-duplicate the data. so like… why would you 😭

💫 Snapshotting vs Hardlinking 💫

Snapshot support in S3QL is inspired by the hardlinking feature offered by programs like rsync or storeBackup. Those programs can create a hardlink instead of copying a file if an identical file already exists in the backup. cute concept, but hardlinks have disadvantages:

  • backups and restores always have to be made with a special program that takes care of the hardlinking. The backups must not be touched by any other programs (they may make changes that inadvertently affect other hardlinked files) 💀
  • special care needs to be taken to handle files which are already hardlinked (the restore program needs to know that the hardlink was not introduced by the backup program) 🙈

S3QL snapshots do not have these problems, and they can be used with any backup program. slay. periodt. 💅

⭐ OPTIONS ⭐

The s3qlcp command accepts the following options:

  • --log <target> — where your log messages go, bestie. Specify none for standard output, or syslog for the system logging daemon. Anything else gets interpreted as a file name. Log files get rotated when they reach 1 MiB, and at most 5 old log files are kept. Default: None
  • --debug-modules <modules> — activate debugging output from specific modules (use commas to separate multiple modules, or 'all' for everything). Debug messages get written to whatever target you picked with the --log option. 🐛
  • --debug — activate debugging output from all S3QL modules. Debug messages get written to the target specified by the --log option. 🐛✨
  • --quiet — be really quiet 🤫
  • --version — just print program version and exit. that's it, that's the whole job 🎀

🔥 EXIT CODES 🔥

s3qlcp may terminate with the following exit codes:

  1. 0 — Everything went well. we love to see it 💖
  2. 1 — An unexpected error occurred. This may indicate a bug in the program. 😭
  3. 2 — Invalid command line argument or configuration file key. 🙈

🌈 SEE ALSO 🌈

The S3QL homepage is at https://github.com/s3ql/s3ql/ 🦋

The full S3QL documentation should also be installed somewhere on your system — common locations are /usr/share/doc/s3ql or /usr/local/doc/s3ql 🎀

© 2008 Nikolaus Rath <Nikolaus@rath.org>

and that's the whole page, bestie!! this is version 5.2.3 from Nov 02, 2024, so if your copy says something else, you're reading a different era of the manpage 💅 go forth and snapshot responsibly 🫶

📦 where this page comes from