Bug 281541
| Summary: | rpcinfo: format of argument to -a flag is undocumented | ||
|---|---|---|---|
| Product: | Documentation | Reporter: | Garrett Wollman <wollman> |
| Component: | Manual Pages | Assignee: | freebsd-bugs (Nobody) <bugs> |
| Status: | New --- | ||
| Severity: | Affects Only Me | CC: | doc, gperciva, jpb |
| Priority: | --- | ||
| Version: | Latest | ||
| Hardware: | Any | ||
| OS: | Any | ||
| Attachments: | |||
Your understanding looks correct.
I found the definition of "universal address format" in RFC 5665. In particular, for IPv4, it's:
h1.h2.h3.h4.p1.p2
where hX is the normal IPv4, and .p1.p2 is the port. Interestingly, the RFC says
> Assuming big-endian ordering, p1 and p2 are, respectively,
> the first and second octets each converted to ASCII-decimal.
> https://www.rfc-editor.org/rfc//rfc5665#section-5.2.3.3
Shouldn't the RFC *specify* whether it's big-endian or little-endian?
Anyway, in terms of the actual code, when we do `rpcinfo -a address ...`, we end up in usr.bin/rpcinfo/rpcinfo.c line 1236, where `address` is passed to uaddr2taddr().
In turn, uaddr2taddr() is defined in both sys/rpc/rpc_generic.c and lib/libc/rpc/rpc_generic.c. Those files are similar, but not identical... but they don't seem to differ significantly in their implementations of uaddr2taddr(). And yes, it looks big-endian; p2 ends up being `portlo` and p1 is `porthi` in the code.
Created attachment 254317 [details]
Proposed change incorporating text from RFC 5665
I took a stab at incorporating the text from RFC5665 into the man page for rpcinfo(8). Check the attachment.
If acceptable, I'll generate a diff and push to Phabricator.
Comment on attachment 254317 [details]
Proposed change incorporating text from RFC 5665
Well, that at least makes it clear what the weird format is. I suspect a .Bd/.Ed block should be used instead of quotation marks here to clearly call out the quotation, as it's longer than a single sentence. Similarly .Rs/Re with the appropriate macros for the source citation. The bit about `-T` should be moved to the second paragraph.
Thanks for your interest! At first glance, it looks as though you included more than a whole paragraph verbatim from RFC 5665. Is that common practice in FreeBSD? RFC 5665 states that code components are under the Simplified BSD License (which is 2-clause); however, the the latest legal provisions [1] say that the previous version erroneously referred to "simplified BSD license" instead of "revised BSD license" (which is 3-clause). [1] https://trustee.ietf.org/documents/trust-legal-provisions/tlp-5/ Also, those are for "code components". I haven't yet found a definitive statement about the copyright and licensing for text itself; given that they carefully define "code components", I suspect that the text is not under so permissive a license. ... Also, I don't think this needs such a verbose answer. My guess is that 2 or 3 sentences, along with a reminder that it's defined in RFC 5665 (with a link in the SEE ALSO section), would be sufficient. Created attachment 254321 [details]
Revised description of address format (reply to comments 3 and 4)
Update to the address format in response to comments 3 and 4.
Created attachment 254322 [details]
Update to SEE ALSO section to reference RFC 5665.
Update to SEE ALSO to include reference to RFC 5665. My mandoc/groff is a bit rusty so please let me know if this is how it should look.
Thanks,
Jim B.
Thanks! SEE ALSO looks good. For the -a part, I'd be tempted to leave the first paragraph unchanged -- that is, keep the mention of -T in there. In the proposed version, the -T is way at the bottom and thus easier to overlook. I think we can omit the "assuming big-endian ordering" -- as per comment 1, the implementation of rpcinfo in FreeBSD already assumes big-endian. Also, I'd be tempted to remove the mention of the hex address. I think that everybody is familiar with the form 192.168.1.125. As a more general note, I think this is ready for Phabricator. (That said, I'm not a FreeBSD committer or maintainer, so take my opinions with a grain of salt!) Created attachment 254337 [details]
git diff for rpcinfo.8
Here is a git diff usr.bin/rpcinfo/rpcinfo.8
I decided to leave the text about the hexadecimal address in because without it, it is not at all obvious how the discussion of host 192.168.1.125 port 5665 gets turned into uaddr 192.168.1.125.22.33.
I'll get this up to Phabricator for everyone else to review.
Jim B.
|
It says: If versnum is not specified, rpcinfo tries to ping all available version numbers for that program number. This option avoids calls to remote rpcbind to find the address of the service. The serv_address is specified in universal address format of the given transport. However, "universal address format" is not defined anywhere. It's not even easily googlable. I ended up reading an implementation (in the Linux kernel, oddly enough) to find out what it actually is: it appends the port number to the numeric form of the address, *as big-endian octets separated by dots*. Thus, for example, port 2049 is represented as ".8.1". I think this is a consequence of the incomplete assimilation of TI-RPC from 20 years ago, but it's long past time to at least document what this syntax is.