On Mon, Sep 30, 2019 at 06:49:14AM +0100, Jason McIntyre wrote: > On Mon, Sep 30, 2019 at 10:28:50AM +1000, David Gwynne wrote: > > i got an email recently asking how to configure the tunnel identifier > > on an eoip(4) interface, and initially wanted to point the sender > > at the manpage. unfortunately, the manpage is written for programmers > > who have spent a lot of time in network drivers, ie, me. everyone > > else who just wants to configure an interface with ifconfig(8) or > > netstart(8) loses. > > > > this adds a subsection to the eoip manpage on how to administer the > > interfaces, and very slightly tweaks the example to show how the tunnel > > id lines up between openbsd and whatever mikrotik calls their os. > > > > so ok? > > > > i actually like this change as it makes the documentation more useful > > for what people do with an interface, which is operate it. if this goes > > in i would like to update the other pseudo interface driver manpages so > > they're more like this. > > > > morning. > > i'm not against this addition, but it does seem like we're > setting up issues for the future: we'll be moving from having this info > in one place to many. when it changes, it's easier to get it wrong. > > what's the thinking? i mean, the stuff is already there in ifconfig(8). > is it not clear enough? can we make it clearer? or are people just not > working out where to look?
we (openbsd) try to provide a generic set of ioctls and therefore command line options in ifconfig that end up configuring specific things in a variety of drivers. on top of this, different drivers implement a different subset of these ioctls and ifconfig arguments depending on what the protocol is actually capable of. in this specific situation, the problem is that eoip on a mikrotik (where the eoip protocol was invented) requires the configuration of a 16-bit tunnel identifier, but it is not obvious what you have to type in openbsd to set that. the tunnel-id is kind of equivalent to a vlan tag number, and like the vlan tag number on a vlan interface, it is configured with the vnetid argument in ifconfig. that's not obvious from the manpage. another example is GRE, which as a protocol it has an optional key field in it's header. it's the same problem here same in that it is called one thing in the protocol but you don't type "ifconfig gre0 key 1234". again, you use vnetid to set that. an example of the differening subsets of functionality is also around vnetids. in GRE as a protocol, the Key is optional so you can use ifconfig gre0 -vnetid to disable use of it. in vlan(4) there's a magic value (0) on the wire that means the vlan tag is kind of like a default and you only care about the priority bits, which again you use -vnetid to enable the use of. eoip(4) is different again in that the tunnel-id is mandatory and there are no magic values, so it doesn't support -vnetid. > we kind of farmed all this info into ifconfig(8). i'm not sure whether > we want to move it out again. or if we do, do we try to reduce the > content in ifconfig.8? my opinion is that we should still document what things you can pass to ifconfig, but cut out some references to specific behaviours of various drivers. what functionality a specific driver supports should be in the documentation for that specific driver. alternatively we can come up with a better way to document what a driver does wrt to things like vnetids. > > jmc > > > Index: eoip.4 > > =================================================================== > > RCS file: /cvs/src/share/man/man4/eoip.4,v > > retrieving revision 1.4 > > diff -u -p -r1.4 eoip.4 > > --- eoip.4 29 May 2019 19:37:06 -0000 1.4 > > +++ eoip.4 30 Sep 2019 00:11:55 -0000 > > @@ -83,12 +83,68 @@ route to the tunnel destination than the > > via the tunnel interface. > > Alternatively, the tunnel traffic may be configured in a separate > > routing table to the encapsulated traffic. > > +.Ss Network Interface Administration > > +.Nm > > +interfaces may be configured by > > +.Xr ifconfig 8 > > +or > > +.Xr netstart 8 > > +using the following options: > > +.Bl -tag -width indent > > +.It Cm tunnel Ar src_address dest_address > > +Set the unicast IPv4 or IPv6 addresses for the encapsulating IP packets. > > +The addresses may only be configured while the interface is down. > > +.It Fl Ns Cm tunnel > > +Clear the addresses used for the encapsulating IP packets. > > +The addresses may only be cleared while the interface is down. > > +.It Cm vnetid Ar tunnel-identifier > > +Configure the virtual network identifier to use as the Tunnel Identifier. > > +The virtual network identifier may only be configured while the > > +interface is down. > > +The Tunnel Identifier is a 16-bit value between 0 and 65535 inclusive. > > +.It Cm tunneldomain Ar rdomain > > +Set the routing table the tunnel traffic operates in. > > +The routing table may only be configured while the interface is down. > > +.It Cm tunnelttl Ar ttl > > +Set the Time-To-Live field in IPv4 encapsulation headers, or the > > +Hop Limit field in IPv6 encapsulation headers. > > +.It Cm tunneldf > > +Disable fragmentation of tunnel traffic by the interface. > > +This sets the Don't Fragment (DF) bit on IPv4 packets, > > +and disables fragmentation of IPv6 packets. > > +.It Fl Ns Cm tunneldf > > +Allow fragmentation of tunnel traffic. > > +.\" This clears the Don't Fragment (DF) bit on IPv4 packets, > > +.\" and allows fragmentation of IPv6 packets. > > +.It Cm rxprio Ar prio > > +Configure how the interface sets the priority of incoming packets. > > +.Ar packet > > +maintains the existing priority of the packet. > > +Priority may be hardcoded with a number from 0 to 7. > > +.Ar outer > > +uses the Type of Service field in IPv4 encapsulation headers, or > > +the Traffic Class field in IPv6 encapsulation headers to set the > > +packet priority. > > +.It Cm txprio Ar prio > > +Configure which value is used in the Type of Service field in IPv4 > > +encapsulation headers, or the Traffic Class field in IPv6 encapsulation > > +headers. > > +Values may be hardcoded with a number from 0 to 7, or > > +.Ar packet > > +to specify that the current priority of a packet should be used. > > +.It Cm keepalive Ar period count > > +Enable the transmission of keepalive packets to detect tunnel failure. > > +Keepalives may only be configured while the interface is down. > > +.It Fl Ns Cm keepalive > > +Disable the transmission of keepalive packets to detect tunnel failure. > > +Keepalives may only be disabled while the interface is down. > > +.El > > .Ss Programming Interface > > .Nm > > interfaces support the following > > .Xr ioctl 2 > > calls for configuring tunnel options: > > -.Bl -tag -width indent -offset 3n > > +.Bl -tag -width indent > > .It Dv SIOCSLIFPHYADDR Fa "struct if_laddrreq *" > > Set the unicast IPv4 or IPv6 addresses for the encapsulating IP packets. > > The addresses may only be configured while the interface is down. > > @@ -101,7 +157,7 @@ The addresses may only be cleared while > > Configure a virtual network identifier for use as the Tunnel Identifier. > > The virtual network identifier may only be configured while the > > interface is down. > > -The Tunnel Identifier is a 16-bit value. > > +The Tunnel Identifier is a 16-bit value between 0 and 65535 inclusive. > > .It Dv SIOCGVNETID Fa "struct ifreq *" > > Get the virtual network identifer used in the GRE Key header. > > .It Dv SIOCSLIFPHYRTABLE Fa "struct ifreq *" > > @@ -173,6 +229,7 @@ On Host A > > # route add default B > > # ifconfig eoipN create > > # ifconfig eoipN tunnel A D > > +# ifconfig eoipN vnetid T > > # ifconfig eoipN up > > # route add E D > > .Ed > > @@ -181,7 +238,7 @@ On Host D (MikroTik): > > .Bd -literal -offset indent > > [admin@MikroTik] > interface eoip > > [admin@MikroTik] /interface eoip> add name="eoipN" \e > > -\e... local-address=D remote-address=A > > +\e... tunnel-id=T local-address=D remote-address=A > > [admin@MikroTik] /interface eoip> enable eoipN > > .Ed > > .Sh SEE ALSO > > >
