3 ms·
Not a IllumOS/SmartOS user, but can you comment on how good the man pages are? What you state is sometimes a complaint I hear about OpenBSD, but from my experi
by kbenson 7y ago
Not a IllumOS/SmartOS user, but can you comment on how good the man pages are? What you state is sometimes a complaint I hear about OpenBSD, but from my experience using OpenBSD (which was mostly almost a decade ago now) is that's because they actually put a huge amount of effort into making sure the man pages were not just correct, but comprehensive (to the point of requiring code patches to include an accompanying man page patch if it added/changed a feature or changed functionality).
When first using OpenBSD this was jarring, because I just wasn't conditioned to expect that system level features would have useful man pages, as that was almost never the case in Linux.
As a simple example of this, here[1] is the OpenBSD man page for ifconfig. Note that it contains liberal references to other man pages of similar quality and completeness where a protocol or functionality might be better explained. Once I learned this, very little outside help was required to setup OpenBSD firewalls stateful failover of firewall connection state as well as VPN tunnels with automatic IP failover with CARP. All from a handful of man pages.
So, that said, does OpenSolaris have good man pages? If it does, it might be that RTFM is the correct initial response to most questions, as it would be the up to date and definitive information about the what and how of things. A simple comparison of ifconfig[1] makes it look somewhat good, but that doesn't mean it's kept up to date and accurate. Can anyone comment if this is the case?
1: https://man.openbsd.org/netstart.8 https://man.openbsd.org/netstart.8
2: https://illumos.org/man/1M/ifconfig https://illumos.org/man/1M/ifconfig
- rjzzleep 7y agoThese are so different use cases. Good luck trying to find out how to do your network design with the dladm and good luck trying to understand the capabilities and limitations of etherstub from the manpages. But yeah the structure of the OpenBSD man pages looks ok. Where you put proper structured documentation doesn't really matter IMHO. It's conceptually different. You can easily use the OpenBSD manpages, because they map nicely to every other Unix system concept. https://smartos.org/man/1M/dladm https://smartos.org/man/1M/dladm
- kbenson 7y agoHonestly, looking at the dladm man page makes it look pretty good to my eyes. It's technical, and long, but the fact that it seems to go into the capabilities in great detail and how to use it as well as includes twenty separate examples at the bottom is something I see as a good sign. This is exactly the kind of reference, that included with a couple test systems to play with, I could use to figure out how to implement a network design. Whether it accurately explains the capabilities of etherstub I don't know, but it seems to do a good job explaining what it is and is used for. The basic usage is detailed within one of the examples. I'm not sure what you're comparing it to that you think would be a superior way to document it though. I honestly can't imagine it being better in Linux in any way. Windows, it would probably be explained better, but you might have to pay a few hundred dollars for the documentation or training, whether it be from Microsoft or a third party. > It's conceptually different. You can easily use the OpenBSD man pages, because they map nicely to every other Unix system concept. Not any more than SmartOS, I'm sure. IIRC, CARP is an OpenBSD designed protocol to compete with Cisco's proprietary VRRP. pfsync is their tool and protocol to sync PF (their own custom firewall implementation) states across a network link. sasync is their own protocol and implementation to sync IPSEC security associations across the network. These were eventually adopted and ported to FreeBSD, but they are far from "every other Unix system concept". I view OpenBSD and IllumOS/SmartOS to be even more similar in approach now than I did prior to this discussion.
- cbsmith 7y agoIt really is disorienting when you pop open the man page and actually is all the documentation you need.
- kbenson 7y ago“The world is full of magic things, patiently waiting for our senses to grow sharper.”