Re: demystify vport(4) in vport(4) and ifconfig(8)
On Fri, Oct 29, 2021 at 08:18:43AM -0600, Theo de Raadt wrote:
> Please don't do this.
Agreed. Please don't add such quirks to bend over backwards for pagers
that misbehave.
> Ingo Schwarze wrote:
>
> > Hi Stuart,
> >
> > Stuart Henderson wrote on Fri, Oct 29, 2021 at 01:59:38PM +0100:
> > > On 2021/10/29 14:08, Ingo Schwarze wrote:
> > >> Stuart Henderson wrote on Fri, Oct 29, 2021 at 10:53:41AM +0100:
> > >>> On 2021/10/28 23:19, Klemens Nanni wrote:
> > On Fri, Oct 29, 2021 at 12:57:54AM +0200, Ingo Schwarze wrote:
> >
> > > MANPAGER=firefox man -T html $(ifconfig -C)
> >
> > This doesn't work if firefox is already running as the MANPAGER firefox
> > process exits immediately after sending the file/link to the running
> > process, which causes mandoc to exit after removing the temporary file,
> > by which time firefox fails to open the no longer exiting file.
> >
> > >>> I use mutt_bgrun for things like this
> >
> > >> I don't see how that can possibly help.
> >
> > > Oh, of course you're right - I was confused between my helper
> > > scripts. The one I actually use for html in mutt looks like this,
> > > so it's not any user for MANPAGER..
> > >
> > > tmp=`mktemp -d /tmp/mutthtml.X` || exit 1
> > > mhonarc -rcfile ~/.m2h_rcfile -single > $tmp/mail.html
> > > (chrome $tmp/mail.html 2>/dev/null; sleep 30; rm -r $tmp) &
> >
> > Indeed, if i added sleep(30) to the place in question
> > in usr.bin/mandoc/main.c, i would expect quite an outrage...
> > A protest rally on my front lawn or something like that...
> >
> > Then again, the man(1) process that is about to exit could maybe fork
> > a child before exiting. The parent exiting right away makes sure that
> > the user gets back their shell prompt instantly after exiting the pager.
> > The child process, now being in the background, could sleep a few seconds
> > before deleting the temporary output files, then exit, too.
> >
> > This does appear to successfully work around the firefox bug.
> > With the patch below, "MANPAGER=firefox man -T html ..."
> > now works reliably for me.
> >
> > It does seem somewhat ugly, though, so i'm not sure whether i should
> > commit it. In particular, fork(2)ing merely to go to the background
> > seems both cumbersome and expensive - admittedly, your script cited
> > above does the same, but that doesn't imply i have to like that, right?
> >
> > Is there a cleaner way to let man(1) go into the background and
> > let the shell offer a fresh prompt while man(1) still sleeps,
> > without needing to fork(2)?
> >
> > Yours,
> > Ingo
> >
> >
> > Index: main.c
> > ===
> > RCS file: /cvs/src/usr.bin/mandoc/main.c,v
> > retrieving revision 1.262
> > diff -u -p -r1.262 main.c
> > --- main.c 4 Oct 2021 21:28:50 - 1.262
> > +++ main.c 29 Oct 2021 14:12:08 -
> > @@ -1203,6 +1203,7 @@ woptions(char *arg, enum mandoc_os *os_e
> > static void
> > run_pager(struct outstate *outst, char *tag_target)
> > {
> > + const struct timespec delay = { 5, 0 };
> > int signum, status;
> > pid_tman_pgid, tc_pgid;
> > pid_tpager_pid, wait_pid;
> > @@ -1245,13 +1246,16 @@ run_pager(struct outstate *outst, char *
> > if (wait_pid == -1) {
> > mandoc_msg(MANDOCERR_WAIT, 0, 0,
> > "%s", strerror(errno));
> > - break;
> > + return;
> > }
> > if (!WIFSTOPPED(status))
> > break;
> >
> > signum = WSTOPSIG(status);
> > }
> > + if (fork() > 0)
> > + _exit(mandoc_msg_getrc());
> > + nanosleep(, NULL);
> > }
> >
> > static pid_t
> >
>
Re: demystify vport(4) in vport(4) and ifconfig(8)
Please don't do this.
Ingo Schwarze wrote:
> Hi Stuart,
>
> Stuart Henderson wrote on Fri, Oct 29, 2021 at 01:59:38PM +0100:
> > On 2021/10/29 14:08, Ingo Schwarze wrote:
> >> Stuart Henderson wrote on Fri, Oct 29, 2021 at 10:53:41AM +0100:
> >>> On 2021/10/28 23:19, Klemens Nanni wrote:
> On Fri, Oct 29, 2021 at 12:57:54AM +0200, Ingo Schwarze wrote:
>
> > MANPAGER=firefox man -T html $(ifconfig -C)
>
> This doesn't work if firefox is already running as the MANPAGER firefox
> process exits immediately after sending the file/link to the running
> process, which causes mandoc to exit after removing the temporary file,
> by which time firefox fails to open the no longer exiting file.
>
> >>> I use mutt_bgrun for things like this
>
> >> I don't see how that can possibly help.
>
> > Oh, of course you're right - I was confused between my helper
> > scripts. The one I actually use for html in mutt looks like this,
> > so it's not any user for MANPAGER..
> >
> > tmp=`mktemp -d /tmp/mutthtml.X` || exit 1
> > mhonarc -rcfile ~/.m2h_rcfile -single > $tmp/mail.html
> > (chrome $tmp/mail.html 2>/dev/null; sleep 30; rm -r $tmp) &
>
> Indeed, if i added sleep(30) to the place in question
> in usr.bin/mandoc/main.c, i would expect quite an outrage...
> A protest rally on my front lawn or something like that...
>
> Then again, the man(1) process that is about to exit could maybe fork
> a child before exiting. The parent exiting right away makes sure that
> the user gets back their shell prompt instantly after exiting the pager.
> The child process, now being in the background, could sleep a few seconds
> before deleting the temporary output files, then exit, too.
>
> This does appear to successfully work around the firefox bug.
> With the patch below, "MANPAGER=firefox man -T html ..."
> now works reliably for me.
>
> It does seem somewhat ugly, though, so i'm not sure whether i should
> commit it. In particular, fork(2)ing merely to go to the background
> seems both cumbersome and expensive - admittedly, your script cited
> above does the same, but that doesn't imply i have to like that, right?
>
> Is there a cleaner way to let man(1) go into the background and
> let the shell offer a fresh prompt while man(1) still sleeps,
> without needing to fork(2)?
>
> Yours,
> Ingo
>
>
> Index: main.c
> ===
> RCS file: /cvs/src/usr.bin/mandoc/main.c,v
> retrieving revision 1.262
> diff -u -p -r1.262 main.c
> --- main.c4 Oct 2021 21:28:50 - 1.262
> +++ main.c29 Oct 2021 14:12:08 -
> @@ -1203,6 +1203,7 @@ woptions(char *arg, enum mandoc_os *os_e
> static void
> run_pager(struct outstate *outst, char *tag_target)
> {
> + const struct timespec delay = { 5, 0 };
> int signum, status;
> pid_tman_pgid, tc_pgid;
> pid_tpager_pid, wait_pid;
> @@ -1245,13 +1246,16 @@ run_pager(struct outstate *outst, char *
> if (wait_pid == -1) {
> mandoc_msg(MANDOCERR_WAIT, 0, 0,
> "%s", strerror(errno));
> - break;
> + return;
> }
> if (!WIFSTOPPED(status))
> break;
>
> signum = WSTOPSIG(status);
> }
> + if (fork() > 0)
> + _exit(mandoc_msg_getrc());
> + nanosleep(, NULL);
> }
>
> static pid_t
>
Re: demystify vport(4) in vport(4) and ifconfig(8)
Hi Stuart,
Stuart Henderson wrote on Fri, Oct 29, 2021 at 01:59:38PM +0100:
> On 2021/10/29 14:08, Ingo Schwarze wrote:
>> Stuart Henderson wrote on Fri, Oct 29, 2021 at 10:53:41AM +0100:
>>> On 2021/10/28 23:19, Klemens Nanni wrote:
On Fri, Oct 29, 2021 at 12:57:54AM +0200, Ingo Schwarze wrote:
> MANPAGER=firefox man -T html $(ifconfig -C)
This doesn't work if firefox is already running as the MANPAGER firefox
process exits immediately after sending the file/link to the running
process, which causes mandoc to exit after removing the temporary file,
by which time firefox fails to open the no longer exiting file.
>>> I use mutt_bgrun for things like this
>> I don't see how that can possibly help.
> Oh, of course you're right - I was confused between my helper
> scripts. The one I actually use for html in mutt looks like this,
> so it's not any user for MANPAGER..
>
> tmp=`mktemp -d /tmp/mutthtml.X` || exit 1
> mhonarc -rcfile ~/.m2h_rcfile -single > $tmp/mail.html
> (chrome $tmp/mail.html 2>/dev/null; sleep 30; rm -r $tmp) &
Indeed, if i added sleep(30) to the place in question
in usr.bin/mandoc/main.c, i would expect quite an outrage...
A protest rally on my front lawn or something like that...
Then again, the man(1) process that is about to exit could maybe fork
a child before exiting. The parent exiting right away makes sure that
the user gets back their shell prompt instantly after exiting the pager.
The child process, now being in the background, could sleep a few seconds
before deleting the temporary output files, then exit, too.
This does appear to successfully work around the firefox bug.
With the patch below, "MANPAGER=firefox man -T html ..."
now works reliably for me.
It does seem somewhat ugly, though, so i'm not sure whether i should
commit it. In particular, fork(2)ing merely to go to the background
seems both cumbersome and expensive - admittedly, your script cited
above does the same, but that doesn't imply i have to like that, right?
Is there a cleaner way to let man(1) go into the background and
let the shell offer a fresh prompt while man(1) still sleeps,
without needing to fork(2)?
Yours,
Ingo
Index: main.c
===
RCS file: /cvs/src/usr.bin/mandoc/main.c,v
retrieving revision 1.262
diff -u -p -r1.262 main.c
--- main.c 4 Oct 2021 21:28:50 - 1.262
+++ main.c 29 Oct 2021 14:12:08 -
@@ -1203,6 +1203,7 @@ woptions(char *arg, enum mandoc_os *os_e
static void
run_pager(struct outstate *outst, char *tag_target)
{
+ const struct timespec delay = { 5, 0 };
int signum, status;
pid_tman_pgid, tc_pgid;
pid_tpager_pid, wait_pid;
@@ -1245,13 +1246,16 @@ run_pager(struct outstate *outst, char *
if (wait_pid == -1) {
mandoc_msg(MANDOCERR_WAIT, 0, 0,
"%s", strerror(errno));
- break;
+ return;
}
if (!WIFSTOPPED(status))
break;
signum = WSTOPSIG(status);
}
+ if (fork() > 0)
+ _exit(mandoc_msg_getrc());
+ nanosleep(, NULL);
}
static pid_t
Re: demystify vport(4) in vport(4) and ifconfig(8)
On 2021/10/29 14:08, Ingo Schwarze wrote: > Hi Stuart, > > Stuart Henderson wrote on Fri, Oct 29, 2021 at 10:53:41AM +0100: > > On 2021/10/28 23:19, Klemens Nanni wrote: > >> On Fri, Oct 29, 2021 at 12:57:54AM +0200, Ingo Schwarze wrote: > > >>> MANPAGER=firefox man -T html $(ifconfig -C) > > >> This doesn't work if firefox is already running as the MANPAGER firefox > >> process exits immediately after sending the file/link to the running > >> process, which causes mandoc to exit after removing the temporary file, > >> by which time firefox fails to open the no longer exiting file. > >> > > > I use mutt_bgrun for things like this > > I don't see how that can possibly help. Oh, of course you're right - I was confused between my helper scripts. The one I actually use for html in mutt looks like this, so it's not any user for MANPAGER.. tmp=`mktemp -d /tmp/mutthtml.X` || exit 1 mhonarc -rcfile ~/.m2h_rcfile -single > $tmp/mail.html (chrome $tmp/mail.html 2>/dev/null; sleep 30; rm -r $tmp) &
Re: demystify vport(4) in vport(4) and ifconfig(8)
On Fri, Oct 29, 2021 at 02:08:32PM +0200, Ingo Schwarze wrote: > Then, much later, because firefox is a monster and a slug: > > 12. firefox attempts to open "$tmpfile", > which was already deleted long before Set the user immutable flag on the temporary file ;-)
Re: demystify vport(4) in vport(4) and ifconfig(8)
Hi Stuart, Stuart Henderson wrote on Fri, Oct 29, 2021 at 10:53:41AM +0100: > On 2021/10/28 23:19, Klemens Nanni wrote: >> On Fri, Oct 29, 2021 at 12:57:54AM +0200, Ingo Schwarze wrote: >>> MANPAGER=firefox man -T html $(ifconfig -C) >> This doesn't work if firefox is already running as the MANPAGER firefox >> process exits immediately after sending the file/link to the running >> process, which causes mandoc to exit after removing the temporary file, >> by which time firefox fails to open the no longer exiting file. >> > I use mutt_bgrun for things like this I don't see how that can possibly help. Accoring to https://gist.github.com/tabletick/4129818 , the mutt_bgrun program essentially does this: cp "$file" "$tmpfile" ( "$viewer" $options "$tmpfile" rm -f "$tmpfile" rmdir "$tmpdir" ) & Assume that $file is the temporary HTML file written by man(1), $tmpfile is the temporary filename (very poorly) generated by mutt_bgrun, $viewer is firefox and $options is empty. Then mutt_bgrun is defeated by the firefox bug that i described in exactly the same way as that bug defeats man(1) itself. The following sequence of events will sometimes occur: 1. man(1) writes $file 2. man(1) calls mutt_bgrun 3. mutt_bgrun copies $file to $tmpfile 4. mutt_bgrun spawns a subshell in the background 5. mutt_bgrun exits 6. man(1) deletes $file, which is harmless at this point because $tmpfile still exists 7. man(1) exits 8. the mutt_bgrun subshell calls firefox 9. That temporary firefox process hands the $tmpfile name to the main running firefox application via IPC. 10. the mutt_bgrun subshell deletes "$tmpfile" 11. the mutt_bgrun subshell exits Then, much later, because firefox is a monster and a slug: 12. firefox attempts to open "$tmpfile", which was already deleted long before If i understand correctly, mutt_bgrun is designed to solve exactly the opposite problem we are having here: When a viewer (like, for example, xpdf(1)) blocks the formatter (like, for example, mutt(1) or man(1)) until the user exits the viewer, then mutt_bgrun does the job of putting the viewer into the background such that the formatter can proceed before the user exits the viewer. But the problem here is that firefox is already doing too much in the background (specifically, opening the $file, which it really ought to do in the foreground before returning), not that it does too little in the background. Yours, Ingo
Re: demystify vport(4) in vport(4) and ifconfig(8)
On 2021/10/28 23:19, Klemens Nanni wrote: > On Fri, Oct 29, 2021 at 12:57:54AM +0200, Ingo Schwarze wrote: > > MANPAGER=firefox man -T html $(ifconfig -C) > > This doesn't work if firefox is already running as the MANPAGER firefox > process exits immediately after sending the file/link to the running > process, which causes mandoc to exit after removing the temporary file, > by which time firefox fails to open the no longer exiting file. > I use mutt_bgrun for things like this
Re: demystify vport(4) in vport(4) and ifconfig(8)
Hi Klemens,
Klemens Nanni wrote on Thu, Oct 28, 2021 at 11:19:30PM +:
> On Fri, Oct 29, 2021 at 12:57:54AM +0200, Ingo Schwarze wrote:
>> MANPAGER=firefox man -T html $(ifconfig -C)
> This doesn't work if firefox is already running
It is true that it sometimes works and sometimes fails due to a race
condition caused by firefox, but that is kind of orthogonal to benno@'s
question.
> as the MANPAGER firefox process exits immediately after sending the
> file/link to the running process,
I consider that a bug in firefox. If a program is instructed to open a
file, and in particular a file in /tmp/, it must not exit before actually
opening the file.
> which causes mandoc to exit after removing the temporary file,
> by which time firefox fails to open the no longer exiting file.
Is there a way how man(1) could work around that braindead behaviour
of firefox? I don't want to commit the following patch - which delays
program exit of man(1) after the pager exits - because the delay is
annoying when using a reasonable pager like less(1).
If someone can come up with an acceptable idea for a workaround,
or if someone can fix firefox, that will be welcome...
Yours,
Ingo
Index: main.c
===
RCS file: /cvs/src/usr.bin/mandoc/main.c,v
retrieving revision 1.262
diff -u -p -r1.262 main.c
--- main.c 4 Oct 2021 21:28:50 - 1.262
+++ main.c 29 Oct 2021 00:06:24 -
@@ -1203,6 +1203,7 @@ woptions(char *arg, enum mandoc_os *os_e
static void
run_pager(struct outstate *outst, char *tag_target)
{
+ const struct timespec delay = { 1, 0 };
int signum, status;
pid_tman_pgid, tc_pgid;
pid_tpager_pid, wait_pid;
@@ -1252,6 +1253,7 @@ run_pager(struct outstate *outst, char *
signum = WSTOPSIG(status);
}
+ nanosleep(, NULL);
}
static pid_t
Re: demystify vport(4) in vport(4) and ifconfig(8)
On Fri, Oct 29, 2021 at 12:57:54AM +0200, Ingo Schwarze wrote: > MANPAGER=firefox man -T html $(ifconfig -C) This doesn't work if firefox is already running as the MANPAGER firefox process exits immediately after sending the file/link to the running process, which causes mandoc to exit after removing the temporary file, by which time firefox fails to open the no longer exiting file.
Re: demystify vport(4) in vport(4) and ifconfig(8)
Hi, Sebastian Benoit wrote on Thu, Oct 28, 2021 at 11:05:54PM +0200: > We tend to forget that there are other output formats for manpages > as well. right now, i can got to https://man.openbsd.org/ifconfig and > jump from there to all of these manpages. With them removed, i can no > longer do that. > > Not sure if thats a valid consideration though. I don't think that's a good reason to keep a long, static list in a manual page *if* that list keeps creating maintenance headaches and keeps getting outdated. If information is naturally available from a command line program but painful to maintain in manual pages, then i don't think it is reasonable to expect it to be available from https://man.openbsd.org/, and i think it is good enough if the manual page explains how to get the information at the command line. Besides, choose from: for name in $(ifconfig -C); do firefox https://man.openbsd.org/$name.4; done and MANPAGER=firefox man -T html $(ifconfig -C) All that said, don't forget the web equivalent of semantic apropos(1): https://man.openbsd.org/?query=Cd~pseudo-device=1 I admit that the URI syntax of web apropos is exceedingly ugly for historical reasons. I really ought to implement something like https://man.openbsd.org/apropos/Cd~pseudo-device https://man.openbsd.org/a/Cd~pseudo-device https://apropos.openbsd.org/Cd~pseudo-device Another day, another task... Too many pending tasks already... Yours, Ingo
Re: demystify vport(4) in vport(4) and ifconfig(8)
David Gwynne(da...@gwynne.id.au) on 2021.10.29 07:02:14 +1000: > On Thu, Oct 28, 2021 at 03:43:11PM +0100, Jason McIntyre wrote: > > On Thu, Oct 28, 2021 at 04:53:39PM +1000, David Gwynne wrote: > > > > > > > > > > On 28 Oct 2021, at 15:35, Jason McIntyre wrote: > > > > > > > > On Thu, Oct 28, 2021 at 01:27:17PM +1000, David Gwynne wrote: > > > >> > > > >>> that strategy does rely on individual driver docs saying upfront that > > > >>> they can be created though, even if using create is not common. i > > > >>> wonder if > > > >>> ifconfig already knows what it can create, and could maybe be more > > > >>> helpful if "create" without an ifname gave a hint. > > > >> > > > >> dlg@rpi3b trees$ ifconfig -C > > > >> aggr bpe bridge carp egre enc eoip etherip gif gre lo mgre mpe mpip > > > >> mpw nvgre pair pflog pflow pfsync ppp pppoe svlan switch tap tpmr > > > >> trunk tun veb vether vlan vport vxlan wg > > > >> > > > >> the "interface can be created paragraph" is in most of the manpages for > > > >> these drivers, except for pair, pfsync, pppoe, and vether (and > > > >> veb/vport). some of them could be improved, eg, bpe and switch. > > > >> > > > > > > > > oops, missed that flag! > > > > > > maybe the doco for "create" in ifconfig.8 should refer back to it too. > > > > > > > good idea - this fits in nicely with stuart's proposal to not list every > > device. > > > > > > > > > i had thought maybe if there was such an option, we wouldn;t need the > > > > "if can be created" blurb in every page. but i suppose we do need to say > > > > it somewhere. > > > > > > the driver manpages are in a weird place because they're supposed to be > > > for programmers, and the ifconfig manpage is for "operators". however, > > > the driver pages have the "theory of operation" for their interfaces. so > > > you have the high level theory in the driver manpage, the way 99% of use > > > actually interact with interfaces in ifconfig.8, and then you go back to > > > the driver doco for the low level programming detail. it's not the best > > > sandwich. > > > > > > > yep. > > > > > > another issue is that the text is inconsistent across pages. > > > > > > yeah, but that can be fixed easily. > > > > > > > hopefully! > > > > anyway, here' my proposal following your and sthen's advice. > > ok? > > > > jmc > > > > Index: ifconfig.8 > > === > > RCS file: /cvs/src/sbin/ifconfig/ifconfig.8,v > > retrieving revision 1.377 > > diff -u -p -r1.377 ifconfig.8 > > --- ifconfig.8 27 Oct 2021 06:36:51 - 1.377 > > +++ ifconfig.8 28 Oct 2021 14:41:06 - > > @@ -177,42 +177,9 @@ network. > > The default broadcast address is the address with a host part of all 1's. > > .It Cm create > > Create the specified network pseudo-device. > > -At least the following devices can be created on demand: > > -.Pp > > -.Xr aggr 4 , > > -.Xr bpe 4 , > > -.Xr bridge 4 , > > -.Xr carp 4 , > > -.Xr egre 4 , > > -.Xr enc 4 , > > -.Xr eoip 4 , > > -.Xr etherip 4 , > > -.Xr gif 4 , > > -.Xr gre 4 , > > -.Xr lo 4 , > > -.Xr mgre 4 , > > -.Xr mpe 4 , > > -.Xr mpip 4 , > > -.Xr mpw 4 , > > -.Xr nvgre 4 , > > -.Xr pair 4 , > > -.Xr pflog 4 , > > -.Xr pflow 4 , > > -.Xr pfsync 4 , > > -.Xr ppp 4 , > > -.Xr pppoe 4 , > > -.Xr svlan 4 , > > -.Xr switch 4 , > > -.Xr tap 4 , > > -.Xr tpmr 4 , > > -.Xr trunk 4 , > > -.Xr tun 4 , > > -.Xr veb 4 , > > -.Xr vether 4 , > > -.Xr vlan 4 , > > -.Xr vport 4 , > > -.Xr vxlan 4 , > > -.Xr wg 4 > > +A list of devices which can be dynamically created may be shown with the > > +.Fl C > > +option. > > .It Cm debug > > Enable driver-dependent debugging code; usually, this turns on > > extra console error logging. > > if solene@ doesnt think it hurts then i'm ok with it. We tend to forget that there are other output formats for manpages as well. right now, i can got to https://man.openbsd.org/ifconfig and jump from there to all of these manpages. With them removed, i can no longer do that. Not sure if thats a valid consideration though.
Re: demystify vport(4) in vport(4) and ifconfig(8)
On Thu, Oct 28, 2021 at 03:43:11PM +0100, Jason McIntyre wrote: > On Thu, Oct 28, 2021 at 04:53:39PM +1000, David Gwynne wrote: > > > > > > > On 28 Oct 2021, at 15:35, Jason McIntyre wrote: > > > > > > On Thu, Oct 28, 2021 at 01:27:17PM +1000, David Gwynne wrote: > > >> > > >>> that strategy does rely on individual driver docs saying upfront that > > >>> they can be created though, even if using create is not common. i > > >>> wonder if > > >>> ifconfig already knows what it can create, and could maybe be more > > >>> helpful if "create" without an ifname gave a hint. > > >> > > >> dlg@rpi3b trees$ ifconfig -C > > >> aggr bpe bridge carp egre enc eoip etherip gif gre lo mgre mpe mpip mpw > > >> nvgre pair pflog pflow pfsync ppp pppoe svlan switch tap tpmr trunk tun > > >> veb vether vlan vport vxlan wg > > >> > > >> the "interface can be created paragraph" is in most of the manpages for > > >> these drivers, except for pair, pfsync, pppoe, and vether (and > > >> veb/vport). some of them could be improved, eg, bpe and switch. > > >> > > > > > > oops, missed that flag! > > > > maybe the doco for "create" in ifconfig.8 should refer back to it too. > > > > good idea - this fits in nicely with stuart's proposal to not list every > device. > > > > > > i had thought maybe if there was such an option, we wouldn;t need the > > > "if can be created" blurb in every page. but i suppose we do need to say > > > it somewhere. > > > > the driver manpages are in a weird place because they're supposed to be for > > programmers, and the ifconfig manpage is for "operators". however, the > > driver pages have the "theory of operation" for their interfaces. so you > > have the high level theory in the driver manpage, the way 99% of use > > actually interact with interfaces in ifconfig.8, and then you go back to > > the driver doco for the low level programming detail. it's not the best > > sandwich. > > > > yep. > > > > another issue is that the text is inconsistent across pages. > > > > yeah, but that can be fixed easily. > > > > hopefully! > > anyway, here' my proposal following your and sthen's advice. > ok? > > jmc > > Index: ifconfig.8 > === > RCS file: /cvs/src/sbin/ifconfig/ifconfig.8,v > retrieving revision 1.377 > diff -u -p -r1.377 ifconfig.8 > --- ifconfig.827 Oct 2021 06:36:51 - 1.377 > +++ ifconfig.828 Oct 2021 14:41:06 - > @@ -177,42 +177,9 @@ network. > The default broadcast address is the address with a host part of all 1's. > .It Cm create > Create the specified network pseudo-device. > -At least the following devices can be created on demand: > -.Pp > -.Xr aggr 4 , > -.Xr bpe 4 , > -.Xr bridge 4 , > -.Xr carp 4 , > -.Xr egre 4 , > -.Xr enc 4 , > -.Xr eoip 4 , > -.Xr etherip 4 , > -.Xr gif 4 , > -.Xr gre 4 , > -.Xr lo 4 , > -.Xr mgre 4 , > -.Xr mpe 4 , > -.Xr mpip 4 , > -.Xr mpw 4 , > -.Xr nvgre 4 , > -.Xr pair 4 , > -.Xr pflog 4 , > -.Xr pflow 4 , > -.Xr pfsync 4 , > -.Xr ppp 4 , > -.Xr pppoe 4 , > -.Xr svlan 4 , > -.Xr switch 4 , > -.Xr tap 4 , > -.Xr tpmr 4 , > -.Xr trunk 4 , > -.Xr tun 4 , > -.Xr veb 4 , > -.Xr vether 4 , > -.Xr vlan 4 , > -.Xr vport 4 , > -.Xr vxlan 4 , > -.Xr wg 4 > +A list of devices which can be dynamically created may be shown with the > +.Fl C > +option. > .It Cm debug > Enable driver-dependent debugging code; usually, this turns on > extra console error logging. if solene@ doesnt think it hurts then i'm ok with it. dlg
Re: demystify vport(4) in vport(4) and ifconfig(8)
On Thu, Oct 28, 2021 at 04:06:39PM +0100, Stuart Henderson wrote: > On 2021/10/28 13:11, David Gwynne wrote: > > On Wed, Oct 27, 2021 at 10:12:35AM +0100, Stuart Henderson wrote: > > > On 2021/10/27 17:44, David Gwynne wrote: > > > > > > > > > benno@ suggested I look at vether(4) to adapt the text related to > > > > > bridge(4) but I'm not sure how to rewrite it properly for veb(4). > > > > > > > > i get that, but for a different reason. im too close to veb/vport, so i > > > > think it's all very obvious. > > > > > > > > maybe we could split the first paragraph into separate ones for veb > > > > and vport, and flesh them out a bit. what is it about vport that > > > > needs to be said? > > > > > > I'm not so close to veb/vport (and haven't run into a situation to use > > > it yet, though maybe I'll give it a try converting an etherip/ipsec > > > bridge that I have). I think it's pretty obvious too, though I think > > > people aren't grasping what "the network stack can be connected" means, > > > would the diff below help? it feels a bit more like spelling things out > > > than is usual for a manual page but maybe that's needed here. > > > > I think it is needed here. My only issue is that the layer 3 stack is > > more than just IP, it also includes mpls and pppoe and bpe(4). Listing > > all that is heading into "list all the things" territory again though. > > I'll commit it with this tweaked a bit > > +They are then independent of the host network stack: the individual > +Ethernet ports no longer function as independent devices and cannot > +be configured with > +.Xr inet 4 > +or > +.Xr inet6 4 > +addresses or other layer-3 features themselves. > > happy to tweak further, but I think it's an improvement already that's better than all the attempts i came up with myself. ok by me. > > > > for ifconfig I would be in favour of _not_ listing all the possible > > > cloneable interface types that can be used with create, it's just another > > > thing to get out of sync - maybe just a few of the common ones and tell > > > the reader about ifconfig -C at that point.. "ifconfig create" barely > > > seems necessary except possibly for tun/tap - for most interface types > > > you are going to run another ifconfig command (like "ifconfig veb0 add > > > em0") which creates the interface automatically anyway. > > > > Having clonable interfaces be implicitly created is something that > > annoys me. If I ifconfig bridge0 add gre0, it should actually fail > > without side effects such as bringing an unwanted child^Winterface > > into the world. This and other implicit behaviours like bringing > > an interface up when an address on it is configured are also painful > > from a locking point of view, even after trying to figure out what's > > reasonable to clean up when a later step fails. > > > > I seem to lose this argument every time though. > > The "auto up when configuring an address" is very convenient but > it can result in actual problems too (pppoe needs to know > which protocols to negotiate so it's racy) as well as making > locking painful mmm.
Re: demystify vport(4) in vport(4) and ifconfig(8)
On 2021/10/28 13:11, David Gwynne wrote: > On Wed, Oct 27, 2021 at 10:12:35AM +0100, Stuart Henderson wrote: > > On 2021/10/27 17:44, David Gwynne wrote: > > > > > > > benno@ suggested I look at vether(4) to adapt the text related to > > > > bridge(4) but I'm not sure how to rewrite it properly for veb(4). > > > > > > i get that, but for a different reason. im too close to veb/vport, so i > > > think it's all very obvious. > > > > > > maybe we could split the first paragraph into separate ones for veb > > > and vport, and flesh them out a bit. what is it about vport that > > > needs to be said? > > > > I'm not so close to veb/vport (and haven't run into a situation to use > > it yet, though maybe I'll give it a try converting an etherip/ipsec > > bridge that I have). I think it's pretty obvious too, though I think > > people aren't grasping what "the network stack can be connected" means, > > would the diff below help? it feels a bit more like spelling things out > > than is usual for a manual page but maybe that's needed here. > > I think it is needed here. My only issue is that the layer 3 stack is > more than just IP, it also includes mpls and pppoe and bpe(4). Listing > all that is heading into "list all the things" territory again though. I'll commit it with this tweaked a bit +They are then independent of the host network stack: the individual +Ethernet ports no longer function as independent devices and cannot +be configured with +.Xr inet 4 +or +.Xr inet6 4 +addresses or other layer-3 features themselves. happy to tweak further, but I think it's an improvement already > > for ifconfig I would be in favour of _not_ listing all the possible > > cloneable interface types that can be used with create, it's just another > > thing to get out of sync - maybe just a few of the common ones and tell > > the reader about ifconfig -C at that point.. "ifconfig create" barely > > seems necessary except possibly for tun/tap - for most interface types > > you are going to run another ifconfig command (like "ifconfig veb0 add > > em0") which creates the interface automatically anyway. > > Having clonable interfaces be implicitly created is something that > annoys me. If I ifconfig bridge0 add gre0, it should actually fail > without side effects such as bringing an unwanted child^Winterface > into the world. This and other implicit behaviours like bringing > an interface up when an address on it is configured are also painful > from a locking point of view, even after trying to figure out what's > reasonable to clean up when a later step fails. > > I seem to lose this argument every time though. The "auto up when configuring an address" is very convenient but it can result in actual problems too (pppoe needs to know which protocols to negotiate so it's racy) as well as making locking painful
Re: demystify vport(4) in vport(4) and ifconfig(8)
On Thu, Oct 28, 2021 at 04:53:39PM +1000, David Gwynne wrote: > > > > On 28 Oct 2021, at 15:35, Jason McIntyre wrote: > > > > On Thu, Oct 28, 2021 at 01:27:17PM +1000, David Gwynne wrote: > >> > >>> that strategy does rely on individual driver docs saying upfront that > >>> they can be created though, even if using create is not common. i wonder > >>> if > >>> ifconfig already knows what it can create, and could maybe be more > >>> helpful if "create" without an ifname gave a hint. > >> > >> dlg@rpi3b trees$ ifconfig -C > >> aggr bpe bridge carp egre enc eoip etherip gif gre lo mgre mpe mpip mpw > >> nvgre pair pflog pflow pfsync ppp pppoe svlan switch tap tpmr trunk tun > >> veb vether vlan vport vxlan wg > >> > >> the "interface can be created paragraph" is in most of the manpages for > >> these drivers, except for pair, pfsync, pppoe, and vether (and > >> veb/vport). some of them could be improved, eg, bpe and switch. > >> > > > > oops, missed that flag! > > maybe the doco for "create" in ifconfig.8 should refer back to it too. > good idea - this fits in nicely with stuart's proposal to not list every device. > > > i had thought maybe if there was such an option, we wouldn;t need the > > "if can be created" blurb in every page. but i suppose we do need to say > > it somewhere. > > the driver manpages are in a weird place because they're supposed to be for > programmers, and the ifconfig manpage is for "operators". however, the driver > pages have the "theory of operation" for their interfaces. so you have the > high level theory in the driver manpage, the way 99% of use actually interact > with interfaces in ifconfig.8, and then you go back to the driver doco for > the low level programming detail. it's not the best sandwich. > yep. > > another issue is that the text is inconsistent across pages. > > yeah, but that can be fixed easily. > hopefully! anyway, here' my proposal following your and sthen's advice. ok? jmc Index: ifconfig.8 === RCS file: /cvs/src/sbin/ifconfig/ifconfig.8,v retrieving revision 1.377 diff -u -p -r1.377 ifconfig.8 --- ifconfig.8 27 Oct 2021 06:36:51 - 1.377 +++ ifconfig.8 28 Oct 2021 14:41:06 - @@ -177,42 +177,9 @@ network. The default broadcast address is the address with a host part of all 1's. .It Cm create Create the specified network pseudo-device. -At least the following devices can be created on demand: -.Pp -.Xr aggr 4 , -.Xr bpe 4 , -.Xr bridge 4 , -.Xr carp 4 , -.Xr egre 4 , -.Xr enc 4 , -.Xr eoip 4 , -.Xr etherip 4 , -.Xr gif 4 , -.Xr gre 4 , -.Xr lo 4 , -.Xr mgre 4 , -.Xr mpe 4 , -.Xr mpip 4 , -.Xr mpw 4 , -.Xr nvgre 4 , -.Xr pair 4 , -.Xr pflog 4 , -.Xr pflow 4 , -.Xr pfsync 4 , -.Xr ppp 4 , -.Xr pppoe 4 , -.Xr svlan 4 , -.Xr switch 4 , -.Xr tap 4 , -.Xr tpmr 4 , -.Xr trunk 4 , -.Xr tun 4 , -.Xr veb 4 , -.Xr vether 4 , -.Xr vlan 4 , -.Xr vport 4 , -.Xr vxlan 4 , -.Xr wg 4 +A list of devices which can be dynamically created may be shown with the +.Fl C +option. .It Cm debug Enable driver-dependent debugging code; usually, this turns on extra console error logging.
Re: demystify vport(4) in vport(4) and ifconfig(8)
> On 28 Oct 2021, at 15:35, Jason McIntyre wrote: > > On Thu, Oct 28, 2021 at 01:27:17PM +1000, David Gwynne wrote: >> >>> that strategy does rely on individual driver docs saying upfront that >>> they can be created though, even if using create is not common. i wonder if >>> ifconfig already knows what it can create, and could maybe be more >>> helpful if "create" without an ifname gave a hint. >> >> dlg@rpi3b trees$ ifconfig -C >> aggr bpe bridge carp egre enc eoip etherip gif gre lo mgre mpe mpip mpw >> nvgre pair pflog pflow pfsync ppp pppoe svlan switch tap tpmr trunk tun veb >> vether vlan vport vxlan wg >> >> the "interface can be created paragraph" is in most of the manpages for >> these drivers, except for pair, pfsync, pppoe, and vether (and >> veb/vport). some of them could be improved, eg, bpe and switch. >> > > oops, missed that flag! maybe the doco for "create" in ifconfig.8 should refer back to it too. > i had thought maybe if there was such an option, we wouldn;t need the > "if can be created" blurb in every page. but i suppose we do need to say > it somewhere. the driver manpages are in a weird place because they're supposed to be for programmers, and the ifconfig manpage is for "operators". however, the driver pages have the "theory of operation" for their interfaces. so you have the high level theory in the driver manpage, the way 99% of use actually interact with interfaces in ifconfig.8, and then you go back to the driver doco for the low level programming detail. it's not the best sandwich. > another issue is that the text is inconsistent across pages. yeah, but that can be fixed easily. dlg
Re: demystify vport(4) in vport(4) and ifconfig(8)
On Thu, Oct 28, 2021 at 01:27:17PM +1000, David Gwynne wrote: > > > that strategy does rely on individual driver docs saying upfront that > > they can be created though, even if using create is not common. i wonder if > > ifconfig already knows what it can create, and could maybe be more > > helpful if "create" without an ifname gave a hint. > > dlg@rpi3b trees$ ifconfig -C > aggr bpe bridge carp egre enc eoip etherip gif gre lo mgre mpe mpip mpw nvgre > pair pflog pflow pfsync ppp pppoe svlan switch tap tpmr trunk tun veb vether > vlan vport vxlan wg > > the "interface can be created paragraph" is in most of the manpages for > these drivers, except for pair, pfsync, pppoe, and vether (and > veb/vport). some of them could be improved, eg, bpe and switch. > oops, missed that flag! i had thought maybe if there was such an option, we wouldn;t need the "if can be created" blurb in every page. but i suppose we do need to say it somewhere. another issue is that the text is inconsistent across pages. jmc
Re: demystify vport(4) in vport(4) and ifconfig(8)
On Wed, Oct 27, 2021 at 02:32:31PM +0100, Jason McIntyre wrote: > On Wed, Oct 27, 2021 at 10:12:35AM +0100, Stuart Henderson wrote: > > On 2021/10/27 17:44, David Gwynne wrote: > > > > > > > benno@ suggested I look at vether(4) to adapt the text related to > > > > bridge(4) but I'm not sure how to rewrite it properly for veb(4). > > > > > > i get that, but for a different reason. im too close to veb/vport, so i > > > think it's all very obvious. > > > > > > maybe we could split the first paragraph into separate ones for veb > > > and vport, and flesh them out a bit. what is it about vport that > > > needs to be said? > > > > I'm not so close to veb/vport (and haven't run into a situation to use > > it yet, though maybe I'll give it a try converting an etherip/ipsec > > bridge that I have). I think it's pretty obvious too, though I think > > people aren't grasping what "the network stack can be connected" means, > > would the diff below help? it feels a bit more like spelling things out > > than is usual for a manual page but maybe that's needed here. > > > > for ifconfig I would be in favour of _not_ listing all the possible > > cloneable interface types that can be used with create, it's just another > > thing to get out of sync - maybe just a few of the common ones and tell > > the reader about ifconfig -C at that point.. "ifconfig create" barely > > seems necessary except possibly for tun/tap - for most interface types > > you are going to run another ifconfig command (like "ifconfig veb0 add > > em0") which creates the interface automatically anyway. > > > > hi. > > i agree with staurt about "create": this list was once short and made > sense. now it just keeps going out of date, without providing any help > to the reader. i don;t want to stack diff on diff, but maybe once the > veb stuff is sorted i will zap the create list. makes sense to me. > that strategy does rely on individual driver docs saying upfront that > they can be created though, even if using create is not common. i wonder if > ifconfig already knows what it can create, and could maybe be more > helpful if "create" without an ifname gave a hint. dlg@rpi3b trees$ ifconfig -C aggr bpe bridge carp egre enc eoip etherip gif gre lo mgre mpe mpip mpw nvgre pair pflog pflow pfsync ppp pppoe svlan switch tap tpmr trunk tun veb vether vlan vport vxlan wg the "interface can be created paragraph" is in most of the manpages for these drivers, except for pair, pfsync, pppoe, and vether (and veb/vport). some of them could be improved, eg, bpe and switch. > anyway, to that end i'm ok with solene's diff. > > i'm also ok with your diff, with one tweak: > > > Index: veb.4 > > === > > RCS file: /cvs/src/share/man/man4/veb.4,v > > retrieving revision 1.2 > > diff -u -p -r1.2 veb.4 > > --- veb.4 23 Feb 2021 11:43:41 - 1.2 > > +++ veb.4 27 Oct 2021 09:03:49 - > > @@ -28,20 +28,30 @@ The > > .Nm veb > > pseudo-device supports the creation of a single layer 2 Ethernet > > network between multiple ports. > > -Ethernet interfaces are added to the bridge to be used as ports. > > +Ethernet interfaces are added to the > > .Nm veb > > -takes over the operation of the interfaces that are added as ports > > -and uses them independently of the host network stack. > > -The network stack can be connected to the Ethernet network managed > > -by > > +bridge to be used as ports. > > +Unlike > > +.Xr bridge 4 , > > .Nm veb > > -by creating a > > +takes over the operation of the interfaces that are added as ports. > > +They are then independent of the host network stack; the individual > > i think a colon would work better than a semi-colon here, since i think > the info after it is essentially an explainer of what independent means. > > jmc > > > +Ethernet ports no longer function as independent layer 3 devices > > +and cannot be configured with > > +.Xr inet 4 > > +or > > +.Xr inet6 4 > > +addresses themselves. > > +.Pp > > +The Ethernet network managed by > > +.Nm veb > > +can be connected to the network stack as a whole by creating a > > .Nm vport > > interface and attaching it as a port to the bridge. > > From the perspective of the host network stack, a > > .Nm vport > > interface acts as a normal interface connected to an Ethernet > > -network. > > +network and can be configured with addresses. > > .Pp > > .Nm veb > > is a learning bridge that maintains a table of Ethernet addresses > >
Re: demystify vport(4) in vport(4) and ifconfig(8)
On Wed, Oct 27, 2021 at 10:12:35AM +0100, Stuart Henderson wrote: > On 2021/10/27 17:44, David Gwynne wrote: > > > > > benno@ suggested I look at vether(4) to adapt the text related to > > > bridge(4) but I'm not sure how to rewrite it properly for veb(4). > > > > i get that, but for a different reason. im too close to veb/vport, so i > > think it's all very obvious. > > > > maybe we could split the first paragraph into separate ones for veb > > and vport, and flesh them out a bit. what is it about vport that > > needs to be said? > > I'm not so close to veb/vport (and haven't run into a situation to use > it yet, though maybe I'll give it a try converting an etherip/ipsec > bridge that I have). I think it's pretty obvious too, though I think > people aren't grasping what "the network stack can be connected" means, > would the diff below help? it feels a bit more like spelling things out > than is usual for a manual page but maybe that's needed here. I think it is needed here. My only issue is that the layer 3 stack is more than just IP, it also includes mpls and pppoe and bpe(4). Listing all that is heading into "list all the things" territory again though. > for ifconfig I would be in favour of _not_ listing all the possible > cloneable interface types that can be used with create, it's just another > thing to get out of sync - maybe just a few of the common ones and tell > the reader about ifconfig -C at that point.. "ifconfig create" barely > seems necessary except possibly for tun/tap - for most interface types > you are going to run another ifconfig command (like "ifconfig veb0 add > em0") which creates the interface automatically anyway. Having clonable interfaces be implicitly created is something that annoys me. If I ifconfig bridge0 add gre0, it should actually fail without side effects such as bringing an unwanted child^Winterface into the world. This and other implicit behaviours like bringing an interface up when an address on it is configured are also painful from a locking point of view, even after trying to figure out what's reasonable to clean up when a later step fails. I seem to lose this argument every time though. > > Index: veb.4 > === > RCS file: /cvs/src/share/man/man4/veb.4,v > retrieving revision 1.2 > diff -u -p -r1.2 veb.4 > --- veb.4 23 Feb 2021 11:43:41 - 1.2 > +++ veb.4 27 Oct 2021 09:03:49 - > @@ -28,20 +28,30 @@ The > .Nm veb > pseudo-device supports the creation of a single layer 2 Ethernet > network between multiple ports. > -Ethernet interfaces are added to the bridge to be used as ports. > +Ethernet interfaces are added to the > .Nm veb > -takes over the operation of the interfaces that are added as ports > -and uses them independently of the host network stack. > -The network stack can be connected to the Ethernet network managed > -by > +bridge to be used as ports. > +Unlike > +.Xr bridge 4 , > .Nm veb > -by creating a > +takes over the operation of the interfaces that are added as ports. > +They are then independent of the host network stack; the individual > +Ethernet ports no longer function as independent layer 3 devices > +and cannot be configured with > +.Xr inet 4 > +or > +.Xr inet6 4 > +addresses themselves. > +.Pp > +The Ethernet network managed by > +.Nm veb > +can be connected to the network stack as a whole by creating a > .Nm vport > interface and attaching it as a port to the bridge. > From the perspective of the host network stack, a > .Nm vport > interface acts as a normal interface connected to an Ethernet > -network. > +network and can be configured with addresses. > .Pp > .Nm veb > is a learning bridge that maintains a table of Ethernet addresses >
Re: demystify vport(4) in vport(4) and ifconfig(8)
On Wed, 27 Oct 2021 14:32:31 +0100 Jason McIntyre : > On Wed, Oct 27, 2021 at 10:12:35AM +0100, Stuart Henderson wrote: > > On 2021/10/27 17:44, David Gwynne wrote: > > > > > > > benno@ suggested I look at vether(4) to adapt the text related to > > > > bridge(4) but I'm not sure how to rewrite it properly for veb(4). > > > > > > i get that, but for a different reason. im too close to veb/vport, so i > > > think it's all very obvious. > > > > > > maybe we could split the first paragraph into separate ones for veb > > > and vport, and flesh them out a bit. what is it about vport that > > > needs to be said? > > > > I'm not so close to veb/vport (and haven't run into a situation to use > > it yet, though maybe I'll give it a try converting an etherip/ipsec > > bridge that I have). I think it's pretty obvious too, though I think > > people aren't grasping what "the network stack can be connected" means, > > would the diff below help? it feels a bit more like spelling things out > > than is usual for a manual page but maybe that's needed here. > > > > for ifconfig I would be in favour of _not_ listing all the possible > > cloneable interface types that can be used with create, it's just another > > thing to get out of sync - maybe just a few of the common ones and tell > > the reader about ifconfig -C at that point.. "ifconfig create" barely > > seems necessary except possibly for tun/tap - for most interface types > > you are going to run another ifconfig command (like "ifconfig veb0 add > > em0") which creates the interface automatically anyway. > > > > hi. > > i agree with staurt about "create": this list was once short and made > sense. now it just keeps going out of date, without providing any help > to the reader. i don;t want to stack diff on diff, but maybe once the > veb stuff is sorted i will zap the create list. > > that strategy does rely on individual driver docs saying upfront that > they can be created though, even if using create is not common. i wonder if > ifconfig already knows what it can create, and could maybe be more > helpful if "create" without an ifname gave a hint. > > anyway, to that end i'm ok with solene's diff. > I agree about ifconfig(8), if it's incomplete this is more misleading than helping, and hints in the devices man pages about using ifconfig/hostname.if are a very helpful and won't rot.
Re: demystify vport(4) in vport(4) and ifconfig(8)
On Wed, Oct 27, 2021 at 10:12:35AM +0100, Stuart Henderson wrote: > On 2021/10/27 17:44, David Gwynne wrote: > > > > > benno@ suggested I look at vether(4) to adapt the text related to > > > bridge(4) but I'm not sure how to rewrite it properly for veb(4). > > > > i get that, but for a different reason. im too close to veb/vport, so i > > think it's all very obvious. > > > > maybe we could split the first paragraph into separate ones for veb > > and vport, and flesh them out a bit. what is it about vport that > > needs to be said? > > I'm not so close to veb/vport (and haven't run into a situation to use > it yet, though maybe I'll give it a try converting an etherip/ipsec > bridge that I have). I think it's pretty obvious too, though I think > people aren't grasping what "the network stack can be connected" means, > would the diff below help? it feels a bit more like spelling things out > than is usual for a manual page but maybe that's needed here. > > for ifconfig I would be in favour of _not_ listing all the possible > cloneable interface types that can be used with create, it's just another > thing to get out of sync - maybe just a few of the common ones and tell > the reader about ifconfig -C at that point.. "ifconfig create" barely > seems necessary except possibly for tun/tap - for most interface types > you are going to run another ifconfig command (like "ifconfig veb0 add > em0") which creates the interface automatically anyway. > hi. i agree with staurt about "create": this list was once short and made sense. now it just keeps going out of date, without providing any help to the reader. i don;t want to stack diff on diff, but maybe once the veb stuff is sorted i will zap the create list. that strategy does rely on individual driver docs saying upfront that they can be created though, even if using create is not common. i wonder if ifconfig already knows what it can create, and could maybe be more helpful if "create" without an ifname gave a hint. anyway, to that end i'm ok with solene's diff. i'm also ok with your diff, with one tweak: > Index: veb.4 > === > RCS file: /cvs/src/share/man/man4/veb.4,v > retrieving revision 1.2 > diff -u -p -r1.2 veb.4 > --- veb.4 23 Feb 2021 11:43:41 - 1.2 > +++ veb.4 27 Oct 2021 09:03:49 - > @@ -28,20 +28,30 @@ The > .Nm veb > pseudo-device supports the creation of a single layer 2 Ethernet > network between multiple ports. > -Ethernet interfaces are added to the bridge to be used as ports. > +Ethernet interfaces are added to the > .Nm veb > -takes over the operation of the interfaces that are added as ports > -and uses them independently of the host network stack. > -The network stack can be connected to the Ethernet network managed > -by > +bridge to be used as ports. > +Unlike > +.Xr bridge 4 , > .Nm veb > -by creating a > +takes over the operation of the interfaces that are added as ports. > +They are then independent of the host network stack; the individual i think a colon would work better than a semi-colon here, since i think the info after it is essentially an explainer of what independent means. jmc > +Ethernet ports no longer function as independent layer 3 devices > +and cannot be configured with > +.Xr inet 4 > +or > +.Xr inet6 4 > +addresses themselves. > +.Pp > +The Ethernet network managed by > +.Nm veb > +can be connected to the network stack as a whole by creating a > .Nm vport > interface and attaching it as a port to the bridge. > From the perspective of the host network stack, a > .Nm vport > interface acts as a normal interface connected to an Ethernet > -network. > +network and can be configured with addresses. > .Pp > .Nm veb > is a learning bridge that maintains a table of Ethernet addresses >
Re: demystify vport(4) in vport(4) and ifconfig(8)
On Wed, 27 Oct 2021 07:28:32 +1000 David Gwynne : > On Tue, Oct 26, 2021 at 09:18:30PM +0200, Solene Rapenne wrote: > > I tried to figure out how to use veb interfaces but the man page > > wasn't obvious in regards to the "vport" thing. It turns out it's > > a kind of interface that can be created with ifconfig. > > > > I think we should make this clearer. > > agreed. the man page for veb/vport is definitely not... rigorous. > > > Because ifconfig(8) mentions many type of interfaces I've searched > > for "vport" without success while "most" types are referenced in > > the man page. Like I added veb(4) recently, the diff adds vport(4) > > and missing mpip(4) so a search would give a clue it's related to > > ifconfig. > > I'm ok with the ifconfig chunk. > > > in veb(4), I think we should add vport in the synposis because the > > man page is shared for veb and vport interfaces but at first look > > it seems only veb is a type of interface. > > The synopsis shows what you put into a kernel config file (eg > src/sys/conf/GENERIC) to enable the driver, but "pseudo-device > vport" is not valid kernel config. You enable the veb driver and that > one driver provides both veb and vport interfaces. Another example of > this is the gre driver which provides gre, egre, mgre, nvgre, and eoip > interfaces. > > > And finally, I added a mention that vport can be created with > > ifconfig(8) so it's really obvious. Maybe it's too much and can be > > removed. > > It should definitely be said. The other man pages for clonable > interfaces generally have a paragraph like this: > > .Nm gre , > .Nm mgre , > .Nm egre , > and > .Nm nvgre > interfaces can be created at runtime using the > .Ic ifconfig iface Ns Ar N Ic create > command or by setting up a > .Xr hostname.if 5 > configuration file for > .Xr netstart 8 . > > I just noticed vether.4 is also missing a paragraph like that too :( > > > comments? ok? > > Apart from it not being obvious where vport interfaces come from, is > there anything else not obvious about veb? > veb is fine to me, here is a diff that adds the ifconfig paragraph to veb(4) and vether(4), I removed my first change from veb. benno@ suggested I look at vether(4) to adapt the text related to bridge(4) but I'm not sure how to rewrite it properly for veb(4). Index: share/man/man4//veb.4 === RCS file: /home/reposync/src/share/man/man4/veb.4,v retrieving revision 1.2 diff -u -p -r1.2 veb.4 --- share/man/man4//veb.4 23 Feb 2021 11:43:41 - 1.2 +++ share/man/man4//veb.4 27 Oct 2021 06:28:45 - @@ -43,6 +43,17 @@ From the perspective of the host network interface acts as a normal interface connected to an Ethernet network. .Pp +A +.Nm veb +or +.Nm vport +interface can be created at runtime using the +.Ic ifconfig iface Ns Ar N Ic create +command or by setting up a +.Xr hostname.if 5 +configuration file for +.Xr netstart 8 . +.Pp .Nm veb is a learning bridge that maintains a table of Ethernet addresses and the port that each address is reachable with. Index: share/man/man4//vether.4 === RCS file: /home/reposync/src/share/man/man4/vether.4,v retrieving revision 1.5 diff -u -p -r1.5 vether.4 --- share/man/man4//vether.417 Oct 2017 22:47:58 - 1.5 +++ share/man/man4//vether.427 Oct 2021 06:29:54 - @@ -30,6 +30,15 @@ standard network frames with an Ethernet for use as a member in a .Xr bridge 4 . .Pp +A +.Nm +interface can be created at runtime using the +.Ic ifconfig vether Ns Ar N Ic create +command or by setting up a +.Xr hostname.if 5 +configuration file for +.Xr netstart 8 . +.Pp To use .Nm the administrator needs to configure an address onto the interface
Re: demystify vport(4) in vport(4) and ifconfig(8)
On 2021/10/27 17:44, David Gwynne wrote: > > > benno@ suggested I look at vether(4) to adapt the text related to > > bridge(4) but I'm not sure how to rewrite it properly for veb(4). > > i get that, but for a different reason. im too close to veb/vport, so i > think it's all very obvious. > > maybe we could split the first paragraph into separate ones for veb > and vport, and flesh them out a bit. what is it about vport that > needs to be said? I'm not so close to veb/vport (and haven't run into a situation to use it yet, though maybe I'll give it a try converting an etherip/ipsec bridge that I have). I think it's pretty obvious too, though I think people aren't grasping what "the network stack can be connected" means, would the diff below help? it feels a bit more like spelling things out than is usual for a manual page but maybe that's needed here. for ifconfig I would be in favour of _not_ listing all the possible cloneable interface types that can be used with create, it's just another thing to get out of sync - maybe just a few of the common ones and tell the reader about ifconfig -C at that point.. "ifconfig create" barely seems necessary except possibly for tun/tap - for most interface types you are going to run another ifconfig command (like "ifconfig veb0 add em0") which creates the interface automatically anyway. Index: veb.4 === RCS file: /cvs/src/share/man/man4/veb.4,v retrieving revision 1.2 diff -u -p -r1.2 veb.4 --- veb.4 23 Feb 2021 11:43:41 - 1.2 +++ veb.4 27 Oct 2021 09:03:49 - @@ -28,20 +28,30 @@ The .Nm veb pseudo-device supports the creation of a single layer 2 Ethernet network between multiple ports. -Ethernet interfaces are added to the bridge to be used as ports. +Ethernet interfaces are added to the .Nm veb -takes over the operation of the interfaces that are added as ports -and uses them independently of the host network stack. -The network stack can be connected to the Ethernet network managed -by +bridge to be used as ports. +Unlike +.Xr bridge 4 , .Nm veb -by creating a +takes over the operation of the interfaces that are added as ports. +They are then independent of the host network stack; the individual +Ethernet ports no longer function as independent layer 3 devices +and cannot be configured with +.Xr inet 4 +or +.Xr inet6 4 +addresses themselves. +.Pp +The Ethernet network managed by +.Nm veb +can be connected to the network stack as a whole by creating a .Nm vport interface and attaching it as a port to the bridge. From the perspective of the host network stack, a .Nm vport interface acts as a normal interface connected to an Ethernet -network. +network and can be configured with addresses. .Pp .Nm veb is a learning bridge that maintains a table of Ethernet addresses
Re: demystify vport(4) in vport(4) and ifconfig(8)
On Wed, Oct 27, 2021 at 08:34:48AM +0200, Solene Rapenne wrote: > On Wed, 27 Oct 2021 07:28:32 +1000 > David Gwynne : > > > On Tue, Oct 26, 2021 at 09:18:30PM +0200, Solene Rapenne wrote: > > > I tried to figure out how to use veb interfaces but the man page > > > wasn't obvious in regards to the "vport" thing. It turns out it's > > > a kind of interface that can be created with ifconfig. > > > > > > I think we should make this clearer. > > > > agreed. the man page for veb/vport is definitely not... rigorous. > > > > > Because ifconfig(8) mentions many type of interfaces I've searched > > > for "vport" without success while "most" types are referenced in > > > the man page. Like I added veb(4) recently, the diff adds vport(4) > > > and missing mpip(4) so a search would give a clue it's related to > > > ifconfig. > > > > I'm ok with the ifconfig chunk. > > > > > in veb(4), I think we should add vport in the synposis because the > > > man page is shared for veb and vport interfaces but at first look > > > it seems only veb is a type of interface. > > > > The synopsis shows what you put into a kernel config file (eg > > src/sys/conf/GENERIC) to enable the driver, but "pseudo-device > > vport" is not valid kernel config. You enable the veb driver and that > > one driver provides both veb and vport interfaces. Another example of > > this is the gre driver which provides gre, egre, mgre, nvgre, and eoip > > interfaces. > > > > > And finally, I added a mention that vport can be created with > > > ifconfig(8) so it's really obvious. Maybe it's too much and can be > > > removed. > > > > It should definitely be said. The other man pages for clonable > > interfaces generally have a paragraph like this: > > > > .Nm gre , > > .Nm mgre , > > .Nm egre , > > and > > .Nm nvgre > > interfaces can be created at runtime using the > > .Ic ifconfig iface Ns Ar N Ic create > > command or by setting up a > > .Xr hostname.if 5 > > configuration file for > > .Xr netstart 8 . > > > > I just noticed vether.4 is also missing a paragraph like that too :( > > > > > comments? ok? > > > > Apart from it not being obvious where vport interfaces come from, is > > there anything else not obvious about veb? > > > > veb is fine to me, here is a diff that adds the ifconfig paragraph > to veb(4) and vether(4), I removed my first change from veb. ok by me. > benno@ suggested I look at vether(4) to adapt the text related to > bridge(4) but I'm not sure how to rewrite it properly for veb(4). i get that, but for a different reason. im too close to veb/vport, so i think it's all very obvious. maybe we could split the first paragraph into separate ones for veb and vport, and flesh them out a bit. what is it about vport that needs to be said? > Index: share/man/man4//veb.4 > === > RCS file: /home/reposync/src/share/man/man4/veb.4,v > retrieving revision 1.2 > diff -u -p -r1.2 veb.4 > --- share/man/man4//veb.4 23 Feb 2021 11:43:41 - 1.2 > +++ share/man/man4//veb.4 27 Oct 2021 06:28:45 - > @@ -43,6 +43,17 @@ From the perspective of the host network > interface acts as a normal interface connected to an Ethernet > network. > .Pp > +A > +.Nm veb > +or > +.Nm vport > +interface can be created at runtime using the > +.Ic ifconfig iface Ns Ar N Ic create > +command or by setting up a > +.Xr hostname.if 5 > +configuration file for > +.Xr netstart 8 . > +.Pp > .Nm veb > is a learning bridge that maintains a table of Ethernet addresses > and the port that each address is reachable with. > Index: share/man/man4//vether.4 > === > RCS file: /home/reposync/src/share/man/man4/vether.4,v > retrieving revision 1.5 > diff -u -p -r1.5 vether.4 > --- share/man/man4//vether.4 17 Oct 2017 22:47:58 - 1.5 > +++ share/man/man4//vether.4 27 Oct 2021 06:29:54 - > @@ -30,6 +30,15 @@ standard network frames with an Ethernet > for use as a member in a > .Xr bridge 4 . > .Pp > +A > +.Nm > +interface can be created at runtime using the > +.Ic ifconfig vether Ns Ar N Ic create > +command or by setting up a > +.Xr hostname.if 5 > +configuration file for > +.Xr netstart 8 . > +.Pp > To use > .Nm > the administrator needs to configure an address onto the interface
