Should simnet functionality be documented?

Should simnet functionality be documented?

[william]

Hello all,

I've been working on adding a flag to the dladm create-simnet. While 
completing that work, it's been noted that the simnet functionality 
isn't really documented anywhere you'd expect to find it. I've found 
simnets useful on a few occasions and think more people might as well, 
if it were more easily discoverable.

I'm not familiar with any background that may explain the omission, 
perhaps a desire to not make an ongoing commitment to the feature, or a 
feeling that it's only useful to a very niche audience? There are few 
references to simnet outside the code that implements them, the most 
definitive being the feature proposal:

https://www.mail-archive.com/opensolaris-arc@mail.opensolaris.org/msg09920.html

Is there a particular reason the feature is well hidden, and would there 
be opposition to adding information to the dladm man page and command 
help text? I am willing to do the legwork to get the information added.

For reference, the ticket I created may be found at:

https://www.illumos.org/issues/16763

Best,

Bill
william@welliver.org

Re: [discuss] Should simnet functionality be documented?

[Joshua M. Clulow]

On Mon, 9 Sept 2024 at 10:51, <william@welliver.org> wrote:
> I've been working on adding a flag to the dladm create-simnet. While
> completing that work, it's been noted that the simnet functionality
> isn't really documented anywhere you'd expect to find it. I've found
> simnets useful on a few occasions and think more people might as well,
> if it were more easily discoverable.

Agreed!

> I'm not familiar with any background that may explain the omission,
> perhaps a desire to not make an ongoing commitment to the feature, or a
> feeling that it's only useful to a very niche audience? There are few
> references to simnet outside the code that implements them, the most
> definitive being the feature proposal:
>
> https://www.mail-archive.com/opensolaris-arc@mail.opensolaris.org/msg09920.html
>
> Is there a particular reason the feature is well hidden, and would there
> be opposition to adding information to the dladm man page and command
> help text? I am willing to do the legwork to get the information added.

I think, in general, at Sun, lots of things like simnet that were
engineering tools without strong promises around them were kept from
the immediate notice of customers by omission from the manual and so
on.

I don't think there's any reason for them not to be documented at this
point, though!  I believe we make somewhat heavy use of simnet links
at Oxide as part of Falcon, a network topology virtualisation testing
tool:

    https://github.com/oxidecomputer/falcon

Thanks for working on it!  Let us know if you hit any bumps or need
additional guidance, etc.


Cheers.

-- 
Joshua M. Clulow
http://blog.sysmgr.org