015.txt - gopherhole - My gopherhole source code.
(HTM) git clone git://jay.scot/gopherhole
(DIR) Log
(DIR) Files
(DIR) Refs
---
015.txt (4200B)
---
1 [jay.scot]
2 [015]
3
4
5 --[ An OpenBSD manpage led me down a rabbit hole
6
7
8 I learned about OpenRsync [0] this week while I continue to dive into
9 OpenBSD. I use rsync quite often, for backing up my ~/ to an external
10 disk, which I hadn't quite got around to doing yet since the switch. It
11 wasn't until late this week that I read a random article that mentioned
12 OpenRsync, which was a drop-in replacement for rsync. Fantastic, I can
13 use this instead of rsync.
14
15
16 So off I go and try running the opensync command which, as expected, was
17 installed and working. Next, I reviewed the man page to see if there
18 were any new features or slight differences, but this led me to some
19 confusion. You see, the examples in the man pages give the command to
20 run as rsync instead of opensync. Here is a section of the man page
21
22
23 EXAMPLE:
24 % rsync -t ../src/bar ../src/baz host:dest
25
26
27 So I ran the rsync command, and it also worked. I thought maybe they
28 have a symlink from rsync to openrsync or something. I didn't really
29 think much about it and continued testing my backup script, hoping
30 I didn't have to change anything with it. Time to test it, it worked
31 perfectly fine, great! For clarity's sake, I changed the script to use
32 the openrsync command instead of rsync and then this error happened.
33
34
35 $ openrsync: -z not supported yet
36
37
38 Wait what? I was super confused for a moment are they different
39 programs? Time to run a few commands to figure out whats going on:
40
41
42 $ which rsync
43 /usr/local/bin/rsync
44
45 $ which openrsync
46 /usr/bin/openrsync
47
48 $ rsync --version
49 rsync version 3.2.5 protocol version 31
50
51 $ openrsync --version
52 openrsync: protocol version 27
53
54 $ pkg_info -m | grep rsync
55 rsync-3.2.5pl0 mirroring/synchronization over low bandwidth links
56
57
58 Aha! So at some point I must have manually installed GNU rsync via
59 pkg_add. I removed the rsync package and tried to figure out how the
60 rsync command the manpage gave was supposed to work. Did I break
61 something when installing the GNU rsync version? The next step was
62 downloading the OpenBSD source and looking at the Makefile for opensync.
63
64
65 $ git clone https://github.com/openbsd/src.git openbsd-src
66 $ cd openbsd-src/usr.bin/opensync
67 $ /bin/ksh: cd: /home/jay/src/openbsd-src/usr.bin/opensync -
68 No such file or directory
69
70
71 Okay, what is going on? I dig around a bit more and find usr.bin/rsync
72 and take a look at the Makefile, which makes things clearer. OpenRsync
73 is built under usr.bin/rsync, but compiled as openrsync. I also noticed
74 that the manpage is called rsync.1 but then symlinked to openrsync.1,
75 seems odd.
76
77
78 So the end result is the manpage example is wrong and combined with me
79 having already installed GNU rsync at somepoint added to the confusion!
80 I wasn't expecting that, time to figure out how to submit a patch so
81 that anyone as daft as me doesn't run into the same rabbit hole. I edit
82 the man page and change the rsync examples to openrsync, confirming it
83 still builds etc. Then read over the great guide on submitting the patch
84 [1].
85
86
87 I am surprised that this has not been spotted before, so before I submit
88 the patch, I search the tech mailing list. Sure enough, there was a diff
89 posted about a year ago [2] with the updated commands. The reply to the
90 patch was the following:
91
92
93 > sorry, i think this one got overlooked! you can check in the
94 > archives, but i think the consensus was that when it's ready
95 > openrsync will be renamed but, for now, the examples should
96 > stay, even if out of kilter.
97
98 > i'm sure another dev can pick this up if i'm way off the mark.
99
100 > jmc
101
102
103 There it is, openrsync will be renamed to rsync at some point which also
104 explains why the manpage is called rsync and symlinked to openrsync in
105 the source directory. No need to submit the patch after all.
106
107
108 I had fun with this, I learned about the patch process for OpenBSD, had
109 a brief look into the OpenBSD source code, and learned about a new tool.
110 Though my TODO list has a few extra items, I really should look into
111 AnonCVS and maybe upgrade my system to -current if I intend on
112 submitting patches.
113
114
115 0. https://man.openbsd.org/openrsync
116 1. https://www.openbsd.org/faq/faq5.html#Diff
117 2. gopher://jay.scot/0/files/misc/openrsync-patch.txt
118
119
120 .EOF