BDSYNC(1)

📦
version 0.11.2 · 2 versions
, in fedora 43, fedora 44

💖 NAME 💖

hiii bestie, welcome to the bdsync page from the General Commands Manual — bdsync is a fast block device synchronizing tool. that's it, that's the whole vibe. 💅

✨ SYNOPSIS ✨

like, here's the shape of it, no cap:

Client: bdsync [–verbose] [–digest=DIGEST] REMSHCMD LOCDEV REMDEV
Server: bdsync –server [–verbose]
Patch: bdsync –patch[=DSTDEV] [–verbose]

🦋 DESCRIPTION 🦋

okay so picture this: you wanna sync block devices across a network. bdsync does that. it builds a “binary patchfile” the efficient way — by comparing checksums of blocks of the local block device LOCDEV against the remote block device REMDEV. 🧚

then that binary patchfile gets shipped over to the remote machine and applied to its block device REMDEV, and boom 💥 — LOCDEV (local) and REMDEV (remote) are synchronized. matched. iconic.

LOCDEV, REMDEV and DSTDEV can all be true block devices, but lowkey they can also be (image) files. and when you're using an image file as DSTDEV (that's –patch mode, iykyk), you can use –diffsize to resize that image file when appropriate.

bdsync was built to do the one thing rsync literally cannot do: synchronize block devices. periodt. 👑

🌸 OPTIONS 🌸

  • -s, –server — start bdsync as a server. no further arguments are accepted, everything is controlled through standard input and standard output. 🫶
  • -p, –patch[=DEVICE] — make bdsync “patch” a device by applying a bdsync file read from standard input. the device gets figured out from the bdsync data itself, unless you specify the (optional) device name DEVICE.
  • -w, –warndev — makes bdsync (in patch mode) warn you if the device you specified with the –patch option differs from the device that's in the patch data. 👀
  • -v, –verbose — cranks up the verbosity of bdsync. yes bestie, you can repeat it multiple times. spam it. 💬
  • -h, –hash=DIGEST — pick any of openssl's digests as the hash for matching blocks on LOCDEV en REMDEV. default is md5.
  • -b, –blocksize=BLOCKSIZE — sets the blocksize in bytes that hashes get calculated over, on both LOCDEV and REMDEV. default 4096.
  • -c, –checksum=DIGEST — pick any of openssl's digests as a checksum for all LOCDEV data. that checksum gets written into the binary patchfile. default is none.
  • -t, –twopass — makes bdsync first match checksums using big blocks (64 * BLOCKSIZE) and then match checksums using small blocks (BLOCKSIZE). this may reduce systemcall overhead and networktraffic when the “binary patchfile” has limited size. ✨
  • -r, –remdata — makes bdsync (in client mode) write the remote data to standard output instead of the local blocks that differ.
  • -d, –diffsize[=OPTION[,warn]] — specifies how bdsync (in client mode and patch mode) should handle different sizes of devices. possible values for OPTION are strict, resize and minsize. when strict is specified, different sizes for LOCDEV and REMDEV are not allowed. when resize is specified, different sizes are accepted and the LOCDEV size is applied to REMDEV in patch mode — which is only supported for (image) files, not devices. when minsize is specified, the smallest size of both LOCDEV and REMDEV is considered (excess data is ignored).
    • when the –diffsize command line option isn't specified at all, it defaults to –diffsize=strict.
    • when –diffsize is specified without any of the additional options, it defaults to –diffsize=resize, which is consistent with earlier versions of bdsync.
    • when the additional warn option is specified, a warning is issued when sizes differ. ⚠️
  • -z, –zeroblocks — makes bdsync (in client mode and server mode) identify zero-filled blocks and optimize hashes for those blocks. this may be usefull for sparse files with lots of zero filled blocks. 🍓
  • -F, –flushcache — this client option makes both the bdsync client and server actively inform the OS that the data is no longer needed after reading it, hence reducing OS buffer cache polution by bdsync. this works especially well when deltas are small, because in that case bdsync itself won't be reading blocks twice. 🧼
  • -P, –progress — this client option makes the client periodically report progress to stderr during operation. the format is:
PROGRESS:<pct>%,<diffsize>,<pos>,<size>,<elapsed s>,<remaining s>

where: <pct> is progress in %, <diffsize> is the current size of the generated diff, <pos> is the current position reading LOCDEV, <size> is the total size of LOCDEV, <elapsed s> is the elapsed time in seconds and <remaining s> is an estimate of the remaining time left in seconds. 📊

  • -H, –help — display brief help information. 🫶

🌈 USAGE 🌈

bdsync assumes a client is connecting to a server. but the connection isn't established by the client itself — it's established by a remote-shell-command REMSHCMD. and REMSHCMD can be literally any kind of command that makes a connection: rsh, ssh, netcat.. you name it. 🦋

if you're using rsh or ssh, REMSHCMD should be the full command to make the connection, including the remote bdsync command to be executed in server mode. if you're using netcat to make the connection, the remote server mode bdsync command should be executed by inetd, xinetd etc.

the –verbose option results in verbose output. in Server mode the output will be sent to syslog. and the –verbose option can be repeated, raising the verbosity level. 💬

bdsync can be initiated like this in its most simple form:

bdsync “bdsync -s” /dev/LOCDEV/dev/REMDEV > DEV.bdsync

this generates a patchfile DEV.rsync containing the blocks in the /dev/LOCDEV device that differ from the blocks in the /dev/REMDEV device — which both are local. a more realistic example is this:

bdsync “ssh doe@remote bdsync –server” /dev/LOCDEV /dev/REMDEV |
gzip > DEV.bdsync.gz

when run as john at local, the bdsync client makes an ssh connection to remote as user doe and executes a bdsync server by passing it the –server option. the generated patchfile output is passed on to gzip, which creates a compressed patchfile DEV.bdsync.gz on local. the patchfile contains all blocks in /dev/LOCDEV at local that differ from /dev/REMDEV at remote. ✨

on the remote machine remote, the user doe can apply the patch by executing:

gzip -d < DEV.bdsync.gz | bdsync –patch=/dev/REMDEV

and the reason to use a binary patch file instead of instantly patching the remote block device REMDEV is twofold, bestie:

  • sending over a complete patchfile allows you to synchronize in a consistent way in case of an interruption (powerloss, network malfunction), since you can choose to apply the (complete) patchfile or not. 🛡️
  • compression of the patchfile can easily be done, without introducing complexity in bdsync itself. 🎀

💜 EXIT STATUS 💜

here's the tea, the codes it'll hand you:

  • 0 — completed successfully ✅
  • 1 — invalid or conflicting parameters supplied
  • 2 — invalid patch format
  • 3 — size mismatch of source and destination blockdevice
  • 4 — protocol error
  • 5 — checksum error
  • 6 — read error
  • 7 — failed to collect randomness
  • 8 — process management error
  • 9 — write error
  • 10 — digest error
  • 11 — transmission error
  • 12 — IO error
  • 13 — connection error

👑 AUTHORS 👑

Rolf Fokkens.

okay that's the whole page bestie, you're so welcome 💖 and for the sign-off: this whole thing is the bdsync(1) page from the General Commands Manual, dated July 2017. go sync something, slay 🦋✨

📦 where this page comes from