1BDSYNC(1) BDSYNC(1)
2
6 bdsync – a fast block device synchronizing tool
7
9 Client: bdsync [–verbose] [–digest=DIGEST] REMSHCMD LOCDEV REMDEV
10 Server: bdsync –server [–verbose]
11 Patch: bdsync –patch[=DSTDEV] [–verbose]
12
14 Bdsync can be used to synchronize block devices over a network. It
15 generates a “binary patchfile” in an efficient way by comparing check‐
16 sums of blocks of the local block device LOCDEV and the remote block
17 device REMDEV.
18 This binary patchfile can be sent to the remote machine and applied to
20 its block device REMDEV, after which the local blockdev LOCDEV and the
21 remote block device REMDEV are synchronized.
22 Both LOCDEV, REMDEV and DSTDEV can be true block devices, but may be
24 (image) files as well. When using an image file for DSTDEV (the –patch
25 mode), the –diffsize may be used to resize the image file when appro‐
26 priate.
27 bdsync was built to do the only thing rsync isn’t able to do: synchro‐
29 nize block devices.
30
32 -s, –server
33 Start bdsync as a server. No further arguments are accepted,
34 all controll is done by standard input and standard output
35 -p, –patch[=DEVICE]
37 Make bdsync “patch” a device by applying a bdsync file read from
38 standard input. The device will be determined from the bdsync
39 data unless an (optional) device name DEVICE is specified
40 -w, –warndev
42 Makes bdsync (in patch mode) warn if the specified device with
43 the –patch option differs from the device in the patch data
44 -v, –verbose
46 Increase the verbosity of bdsync. Can be repeated multiple
47 times.
48 -h, –hash=DIGEST
50 Choose any of openssl’s digests as a hash for matching blocks on
51 LOCDEV en REMDEV. Default is md5.
52 -b, –blocksize=BLOCKSIZE
54 Set the blocksize in bytes for which hashes are calculated on
55 both LOCDEV and REMDEV. Default 4096.
56 -c, –checksum=DIGEST
58 Choose any of openssl’s digests as a checksum for all LOCDEV da‐
59 ta. The checksum will be written to the binary patchfile. De‐
60 fault is none.
61 -t, –twopass
63 Makes bdsync first match checksums using large blocks (64 *
64 BLOCKSIZE) and then match checksums using small blocks (BLOCK‐
65 SIZE). This may reduce systemcall overhead and networktraffic
66 when the “binary patchfile” has limited size.
67 -r, –remdata
69 Makes bdsync (in client mode) write the remote data to standard
70 output instead of the local blocks that differs.
71 -d, –diffsize[=OPTION[,warn]]
73 Specifies how bdsync (in client mode and patch mode) should han‐
74 dle different sizes of devices. Possible values for OPTION are
75 strict, resize and minsize. When strict is specified, different
76 sizes for LOCDEV and REMDEV are not allowed. When resize is
77 specified, different sizes are accepted and the LOCDEV size is
78 applied to REMDEV in patch mode which is only supported for (im‐
79 age) files (not devices). When minsize is specified, the small‐
80 est size of both LOCDEV and REMDEV is considered (excess data is
81 ignored).
82 When the –diffsize command line option is not specified at all,
84 it defaults to –diffsize=strict. When the –diffsize is speci‐
85 fied without any of the additional options, it defaults to
86 –diffsize=resize which is consistent with earlier versions of
87 bdsync.
88 When the additional warn option is specified, a warning is is‐
90 sued when sizes differ.
91 -z, –zeroblocks
93 Makes bdsync (in client mode and server mode) identify zero-
94 filled blocks and optimize hashes for these blocks. This may be
95 usefull for sparse files with lots of zero filled blocks.
96 -F, –flushcache
98 This client option makes both bdsync client and server actively
99 inform the OS the data is no longer needed after reading it
100 hence reducing OS buffer cache polution by bdsync. This works
101 especially well when deltas are small, because in that case
102 bdsync itself won’t be reading blocks twice.
103 -P, –progress
105 This client option makes the client periodically report progress
106 to stderr during operation. The format is:
107 PROGRESS:<pct>%,<diffsize>,<pos>,<size>,<elapsed s>,<remaining
109 s>
110 Where: <pct> is progress in %, <diffsize> is the current size of
112 the generated diff, <pos> is the current position reading
113 LOCDEV, <size> is the total size of LOCDEV, <elapsed s> is the
114 elapsed time in seconds and <remaining s> is an estimate of the
115 remaining time left in seconds.
116 -H, –help
118 Display brief help information.
119
121 Bdsync assumes a client is connecting to a server. The connection
122 isn’t established by the client itself, but by a remote-shell-command
123 REMSHCMD. This REMSHCMD can be any kind of command to make a connec‐
124 tion: rsh, ssh, netcat.. If using rsh or ssh REMSHCMD should be the
125 full command to make the connection including the remote bdsync command
126 te be executed in server mode. If using netcat to make the connection,
127 the remote server mode bdsync command should be executed by inetd,
128 xinetd etc.
129 The –verbose option results in verbose output. In Server mode the out‐
131 put will be sent to syslog. The –verbose option can be repeated rais‐
132 ing the verbosity level.
133 Bdsync can be initiated like this in its most simple form:
135 bdsync “bdsync -s” /dev/LOCDEV/dev/REMDEV > DEV.bdsync
137 This generates a patchfile DEV.rsync containing the blocks in the
139 /dev/LOCDEV device that differ from the blocks in the /dev/REMDEV de‐
140 vice which both are local. A more realistic example is this:
141 bdsync “ssh doe@remote bdsync –server” /dev/LOCDEV /dev/REMDEV |
143 gzip > DEV.bdsync.gz
144 When run as john at local the bdsync client makes an ssh connection to
146 remote as user doe and executes a bdsync server by passing it the
147 –server option. The generated patchfile output is passed on to gzip
148 which creates a compressed patchfile DEV.bdsync.gz on local. The
149 patchfile contains all blocks in /dev/LOCDEV at local that differ from
150 /dev/REMDEV at remote.
151 On the remote machine remote the user doe can apply the patch by exe‐
153 cuting:
154 gzip -d < DEV.bdsync.gz | bdsync –patch=/dev/REMDEV
156 The reason to use a binary patch file instead of instantly patching the
158 remote block device REMDEV is twofold:
159 • Sending over a complete patchfile allows to synchronize in a consis‐
161 tent way in case of an interruption (powerloss, network malfunction)
162 since you can choose to apply the (complete) patchfile or not.
163 • Compression of the patchfile can easily be done, without introducing
165 complexity in bdsync itself.
166
168 0 completed successfully
169 1 invalid or conflicting parameters supplied
170 2 invalid patch format
171 3 size mismatch of source and destination blockdevice
172 4 protocol error
173 5 checksum error
174 6 read error
175 7 failed to collect randomness
176 8 process management error
177 9 write error
178 10 digest error
179 11 transmission error
180 12 IO error
181 13 connection error
182
184 Rolf Fokkens.
185 July 2017 BDSYNC(1)