[jay.scot]
[015]


--[ An OpenBSD manpage led me down a rabbit hole


I learned about OpenRsync [0] this week while I continue to dive into
OpenBSD. I use rsync quite often, for backing up my ~/ to an external
disk, which I hadn't quite got around to doing yet since the switch. It
wasn't until late this week that I read a random article that mentioned
OpenRsync, which was a drop-in replacement for rsync. Fantastic, I can
use this instead of rsync.


So off I go and try running the opensync command which, as expected, was
installed and working. Next, I reviewed the man page to see if there
were any new features or slight differences, but this led me to some
confusion. You see, the examples in the man pages give the command to
run as rsync instead of opensync. Here is a section of the man page


	EXAMPLE:
	% rsync -t ../src/bar ../src/baz host:dest


So I ran the rsync command, and it also worked. I thought maybe they
have a symlink from rsync to openrsync or something. I didn't really
think much about it and continued testing my backup script, hoping
I didn't have to change anything with it. Time to test it, it worked
perfectly fine, great! For clarity's sake, I changed the script to use
the openrsync command instead of rsync and then this error happened.


	$ openrsync: -z not supported yet


Wait what? I was super confused for a moment are they different
programs? Time to run a few commands to figure out whats going on:


	$ which rsync
	/usr/local/bin/rsync

	$ which openrsync
	/usr/bin/openrsync

	$ rsync --version
	rsync  version 3.2.5  protocol version 31

	$ openrsync --version
	openrsync: protocol version 27

	$ pkg_info -m | grep rsync
	rsync-3.2.5pl0  mirroring/synchronization over low bandwidth links


Aha! So at some point I must have manually installed GNU rsync via
pkg_add. I removed the rsync package and tried to figure out how the
rsync command the manpage gave was supposed to work. Did I break
something when installing the GNU rsync version? The next step was
downloading the OpenBSD source and looking at the Makefile for opensync.


	$ git clone https://github.com/openbsd/src.git openbsd-src
	$ cd openbsd-src/usr.bin/opensync
	$ /bin/ksh: cd: /home/jay/src/openbsd-src/usr.bin/opensync -
	  No such file or directory


Okay, what is going on? I dig around a bit more and find usr.bin/rsync
and take a look at the Makefile, which makes things clearer. OpenRsync
is built under usr.bin/rsync, but compiled as openrsync. I also noticed
that the manpage is called rsync.1 but then symlinked to openrsync.1,
seems odd.


So the end result is the manpage example is wrong and combined with me
having already installed GNU rsync at somepoint added to the confusion!
I wasn't expecting that, time to figure out how to submit a patch so
that anyone as daft as me doesn't run into the same rabbit hole. I edit
the man page and change the rsync examples to openrsync, confirming it
still builds etc. Then read over the great guide on submitting the patch
[1].


I am surprised that this has not been spotted before, so before I submit
the patch, I search the tech mailing list. Sure enough, there was a diff
posted about a year ago [2] with the updated commands. The reply to the
patch was the following:


	> sorry, i think this one got overlooked! you can check in the
	> archives, but i think the consensus was that when it's ready
	> openrsync will be renamed but, for now, the examples should
	> stay, even if out of kilter.

	> i'm sure another dev can pick this up if i'm way off the mark.

	> jmc


There it is, openrsync will be renamed to rsync at some point which also
explains why the manpage is called rsync and symlinked to openrsync in
the source directory. No need to submit the patch after all.


I had fun with this, I learned about the patch process for OpenBSD, had
a brief look into the OpenBSD source code, and learned about a new tool.
Though my TODO list has a few extra items, I really should look into
AnonCVS and maybe upgrade my system to -current if I intend on
submitting patches.


0. https://man.openbsd.org/openrsync
1. https://www.openbsd.org/faq/faq5.html#Diff
2. gopher://jay.scot/0/files/misc/openrsync-patch.txt


.EOF