1BDSYNC(1)                                                            BDSYNC(1)
2
3
4

NAME

6       bdsync – a fast block device synchronizing tool
7

SYNOPSIS

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

DESCRIPTION

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
19       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
23       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
28       bdsync  was built to do the only thing rsync isn’t able to do: synchro‐
29       nize block devices.
30

OPTIONS

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
36       -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
41       -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
45       -v, –verbose
46              Increase the verbosity of  bdsync.   Can  be  repeated  multiple
47              times.
48
49       -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
53       -b, –blocksize=BLOCKSIZE
54              Set the blocksize in bytes for which hashes  are  calculated  on
55              both LOCDEV and REMDEV.  Default 4096.
56
57       -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
62       -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
68       -r, –remdata
69              Makes bdsync (in client mode) write the remote data to  standard
70              output instead of the local blocks that differs.
71
72       -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
83              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
89              When  the  additional warn option is specified, a warning is is‐
90              sued when sizes differ.
91
92       -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
97       -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
104       -P, –progress
105              This client option makes the client periodically report progress
106              to stderr during operation.  The format is:
107
108              PROGRESS:<pct>%,<diffsize>,<pos>,<size>,<elapsed   s>,<remaining
109              s>
110
111              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
117       -H, –help
118              Display brief help information.
119

USAGE

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
130       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
134       Bdsync can be initiated like this in its most simple form:
135
136              bdsync “bdsync -s” /dev/LOCDEV/dev/REMDEV > DEV.bdsync
137
138       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
142              bdsync “ssh doe@remote bdsync –server” /dev/LOCDEV /dev/REMDEV |
143              gzip > DEV.bdsync.gz
144
145       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
152       On  the  remote machine remote the user doe can apply the patch by exe‐
153       cuting:
154
155              gzip -d < DEV.bdsync.gz | bdsync –patch=/dev/REMDEV
156
157       The reason to use a binary patch file instead of instantly patching the
158       remote block device REMDEV is twofold:
159
160       • 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
164       • Compression  of the patchfile can easily be done, without introducing
165         complexity in bdsync itself.
166

EXIT STATUS

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

AUTHORS

184       Rolf Fokkens.
185
186
187
188                                   July 2017                         BDSYNC(1)
Impressum