[REVIEW] 16763: dladm simnet functionality should be documented

[REVIEW] 16763: dladm simnet functionality should be documented

[william]

Hello all,

I have an initial contribution for basic simnet documentation that I'd 
like to have reviewed.

Gerrit Review: https://code.illumos.org/c/illumos-gate/+/3683

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

For ease of review, I attached an HTML rendition of the proposed man 
page changes. Unfortunately, redmine helpfully renders the markup to 
text. I've temporarily made the page available at:

http://bill.welliver.org/dist/dladm.8.html

Any feedback would be welcome!

Best,

Bill

Re: [developer] [REVIEW] 16763: dladm simnet functionality should be documented

[Olaf Bohlen]

Dear William,

maybe the create-simnet subcommand should include a very brief explanation what “simnet” actually is. So that end users understand that it is mostly a debugging facility.

Regards,

Olaf Bohlen
olbohlen@eenfach.de

> Am 11.09.2024 um 07:24 schrieb william@welliver.org:
> 
> Hello all,
> 
> I have an initial contribution for basic simnet documentation that I'd like to have reviewed.
> 
> Gerrit Review: https://code.illumos.org/c/illumos-gate/+/3683
> 
> Bug Ticket: https://www.illumos.org/issues/16763
> 
> For ease of review, I attached an HTML rendition of the proposed man page changes. Unfortunately, redmine helpfully renders the markup to text. I've temporarily made the page available at:
> 
> http://bill.welliver.org/dist/dladm.8.html
> 
> Any feedback would be welcome!
> 
> Best,
> 
> Bill
> 
> ------------------------------------------
> illumos: illumos-developer
> Permalink: https://illumos.topicbox.com/groups/developer/Ta3283bbd32ecf85f-M32dbe25c3985f34d45a63077
> Delivery options: https://illumos.topicbox.com/groups/developer/subscription

Re: [developer] [REVIEW] 16763: dladm simnet functionality should be documented

[H. William Welliver]

Hi!

I did add a brief description of what simnets are in the “Description” section, as that is where other types of objects (vnics, etherstubs, etc) are introduced. I’ll also willingly admit that I don’t normally read that section and jump right to the command details but I was trying to remain consistent with the existing document.

As a side-note: I didn’t specifically describe simnets as a debugging facility because I think they can be handy for other things, as well. I first (mis)used them by adding one to a bridge created from the physical nics on the device. I then configured the other end as the host’s primary interface. This enabled the host to be accessible without a particular port needing to be physically “up”. Strange and very niche, but pretty handy for making network appliances.

Bill

> On Sep 11, 2024, at 2:48 PM, Olaf Bohlen <olbohlen@eenfach.de> wrote:
> 
> Dear William,
> 
> maybe the create-simnet subcommand should include a very brief explanation what “simnet” actually is. So that end users understand that it is mostly a debugging facility.
> 
> Regards,
> 
> Olaf Bohlen
> olbohlen@eenfach.de

Re: [developer] [REVIEW] 16763: dladm simnet functionality should be documented

[Olaf Bohlen]

"H. William Welliver" <william@welliver.org> writes:

Hi,

> I did add a brief description of what simnets are in the “Description”
> section, as that is where other types of objects (vnics, etherstubs,
> etc) are introduced. I’ll also willingly admit that I don’t normally
> read that section and jump right to the command details but I was
> trying to remain consistent with the existing document.

Yes, I meant something like "the dladm create-simnet creates an
instance of a simulated network device mostly used for debugging
purposes" or similar...so an indirect formulation - because a lot
of people just skip the descriptions ;)

Regards,

Olaf

-- 
      ~       Olaf Bohlen - olbohlen@eenfach.de
      |~~     Het
     /|  \    Bruine
 ___/_|___\   Leven
   \__n____/# DGCN2

Re: [developer] [REVIEW] 16763: dladm simnet functionality should be documented

[Joshua M. Clulow]

On Thu, 12 Sept 2024 at 01:33, Olaf Bohlen <olbohlen@eenfach.de> wrote:
> "H. William Welliver" <william@welliver.org> writes:
> > I did add a brief description of what simnets are in the “Description”
> > section, as that is where other types of objects (vnics, etherstubs,
> > etc) are introduced. I’ll also willingly admit that I don’t normally
> > read that section and jump right to the command details but I was
> > trying to remain consistent with the existing document.
>
> Yes, I meant something like "the dladm create-simnet creates an
> instance of a simulated network device mostly used for debugging
> purposes" or similar...so an indirect formulation - because a lot
> of people just skip the descriptions ;)

I think "debugging purposes" is a bit too editorial, to be honest.
You can use them for really any purpose, including tinkering and
simulating different network topologies between zones or VMs.  At
Oxide, we have a framework called Falcon for driving networking and
virtualisation test topologies that makes pretty heavy use of simnets
for certain things:

    https://github.com/oxidecomputer/falcon


Cheers.

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