Start with a short summary and cover the options in a standard list style.
Organize sections by common focus and prioritize more useful information
closer to the top.
Flesh out authors, history, caveats, and security considerations sections.
Details
Details
- Reviewers
def markj eadler - Group Reviewers
Doc Committers manpages - Commits
- rS339785: dumpon.8: Significantly revamp page
Diff Detail
Diff Detail
- Repository
- rS FreeBSD src repository - subversion
- Lint
Lint Not Applicable - Unit
Tests Not Applicable
Event Timeline
Comment Actions
I did a quick review and it seems fine.
| sbin/dumpon/dumpon.8 | ||
|---|---|---|
| 31 ↗ | (On Diff #49539) | don't forget to bump. |
| sbin/dumpon/dumpon.8 | ||
|---|---|---|
| 117 ↗ | (On Diff #49539) | It should probably be mentioned that this comes from ports. |
| 119 ↗ | (On Diff #49539) | .Xr netdump 4 here and elsewhere? |
| 127 ↗ | (On Diff #49539) | e.g. |
| 127 ↗ | (On Diff #49539) | I'd suggest avoiding "NIC" and just write "network interface". |
| 139 ↗ | (On Diff #49539) | "same link" would be more correct. |
| 299 ↗ | (On Diff #49539) | "Support for encrypted kernel core dumps and ..." sounds more natural to me. |
| 304 ↗ | (On Diff #49539) | What does "reference" mean here? Man page? |
| 321 ↗ | (On Diff #49539) | "cannot" is used elsewhere. "full dump" means something else in this page. |
| 337 ↗ | (On Diff #49539) | Trivial to someone who understands the implications of adding padding bytes to a crypto scheme? It's trivial to implement, I agree, but I'm not sure if it's trivial to implement correctly. I'm not sure that this sentence is adding much. :) |
| sbin/dumpon/dumpon.8 | ||
|---|---|---|
| 119 ↗ | (On Diff #49539) | Didn't realize there was a netdump(4) page. Will fix. |
| 127 ↗ | (On Diff #49539) | I should not write docs at night, will fix. Thanks. |
| 139 ↗ | (On Diff #49539) | For my edification, what's the distinction? I will go ahead and change it assuming you know what you're talking about — I'm not exactly a networking expert. |
| 299 ↗ | (On Diff #49539) | Agreed, will fix. |
| 304 ↗ | (On Diff #49539) | Yeah. The exact language was borrowed from mdoc.7. I'm not attached to it and obviously it isn't clear, so I'll fix it. |
| 321 ↗ | (On Diff #49539) | Hm. As far as 'full dump', I think that is intentional. The only case where we can know the dump size in advance is for full dumps (under the assumption that RAM does not grow online), right? Minidumps are variable sized and compressed dumps are variable sized. It just happens that check_size() is skipped outside of the function for netdump or gzip, and inside the function for debug.minidump==1. Go figure. Maybe that should be cleaned up. I can send a patch ;-). I've clarified the language around what kinds of dumps have predictable size (just uncompressed full dumps) and predictable storage (local disk). I'm not totally convinced 'cannot' and 'can not' are identical. In my dialect they are subtly different — separate words are used for emphasis. But I am happy to change it. |
| 337 ↗ | (On Diff #49539) | Putting the most important bit first: I'm happy to drop the sentence and agree it's utterly unhelpful for documentation. :-) I'm not sure the implications re: padding are really significant. One of the weaknesses of the EKCD design we have now is that we *don't* MAC either the kerneldumpheader or the encrypted contents, so both are subject to arbitrary tampering. It's purely a privacy scheme. So what I'm saying is, naively padding the plaintext with zeros rather than PKCS#7 likely doesn't increase our attack surface at all. OTOH, I'd suggest just abandoning block ciphers altogether instead of worrying about correct PKCS padding. None AES-CTR, AES-GCM, nor Chacha20 care about plaintexts being multiple of block sized. I will probably end up doing it eventually. |
Comment Actions
Thanks for doing this cleanup.
| sbin/dumpon/dumpon.8 | ||
|---|---|---|
| 139 ↗ | (On Diff #49539) | In general, there's nothing preventing two hosts on the same link but on different subnets from communicating. All that's required for netdump is that the client can ARP the server to learn its MAC address. For that to work, we just need to be able to reach the server using the link layer (Ethernet)'s broadcast delivery mechanism. The hosts that can be reached this way are said to belong to the same network segment, link or L2 broadcast domain as the originating host. So, if a netdump client can ARP the server directly (i.e., they're on the same link), it'll just use the configured client and server IPs without caring whether they belong to the same subnet. |
| 321 ↗ | (On Diff #49539) | Oops, sorry, I was thinking of the size checks performed in the kernel at panic time (where we do know the minidump size), not the ones done in dumpon(8). You're right. Regarding "can not," I did try to infer a meaningful difference between the two but couldn't come up with anything. I don't care too much either way, it's just a sort of inconsistency I notice very readily, for better or worse. |
| 337 ↗ | (On Diff #49539) | Fair enough, please feel free to keep the sentence you added. I just thought it was kind of funny: I know it's trivial to implement because I did it, but I didn't commit it because I wasn't sure it was safe. Thanks for the explanation. |
Comment Actions
Just scratching my own itch :-). I really prefer manual pages that make finding option documentation easy, and the '-foo Do bar baz...' style table is probably the prevailing pattern. And I refer to dumpon.8 often enough to remember how annoying it is (was).
| sbin/dumpon/dumpon.8 | ||
|---|---|---|
| 139 ↗ | (On Diff #49539) | Ah, I guess the distinction is you could theoretically have multiple distinct IP (layer 3) subnets on the same layer 2 fabric. It seems like a weird way to configure a network, but I'm sure inevitably someone has done it. Thanks. |
| 337 ↗ | (On Diff #49539) | Heh, no worries. Re: not committing it, that was a very reasonable choice. With crypto it's always better to err on the side of caution. |
| sbin/dumpon/dumpon.8 | ||
|---|---|---|
| 139 ↗ | (On Diff #49539) | Oh yes. IIRC, OneFS clusters in the various test labs all live in a big broadcast domain (at least on the management side, not sure about frontend data). Ideally you'd use VLANs to logically partition such a network. |