veth.4

veth.4

[Tomas Pospisek]

[-- Attachment #1: Type: TEXT/PLAIN, Size: 2851 bytes --]

Hello linux-man ML and Michael,

below you'll find a manpage about the veth virtual ethernet device. The 
manpage is a summarisation of the sparse information about veth I found on 
the net.

I'd be glad if veth(4) could find a place in the manpages because 
allthough I was using veth's a lot lately, I had no idea about how they 
work and so didn't my peers. So I suspect a manpage might be useful.

In my ignorance I've chosen section 4 for the manpage, maybe there's a 
better one.

You can find the manpage below

Thanks,
*t

***************************************************************
.\" Copyright (c) 2012 Tomáš Pospíšek (tpo_deb-UQchlGytWBLoPl2ZpcX+cw@public.gmane.org),
.\"     Fri, 02 Nov 2012 13:37:33 +0100
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, write to the Free
.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
.\" USA.
.\"
.\"
.TH veth 4 2012-11-02 "Linux" "Linux Programmer's Manual"
.SH NAME
veth \- Virtual Ethernet Device
.SH DESCRIPTION
The \fBveth*\fP devices are virtual ethernet devices.

They can act as tunnels between network namespaces to create
a bridge to a physical network device in another namespace, but
can also be used as standalone network devices.

Because of their original purpose for tunneling \fBveth\fP devices
are allways created in pairs, that are interconnected with
each other.  When one \fBveth\fP end receives a packet it
appears on its pair and vice versa.

\fBVeth\fP devices can be manipulated with the
.BR ip (8)
tool. See \fB ip link help\fP for more information.

.SH "SEE ALSO"
.BR ip (8) ,
.BR clone (2)

.SH COLOPHON
This page is based on Pavel Emelianov's veth driver submission to
the LKML and on the 
.BR clone (8)
manpage.

It is part of release 3.44 of the Linux
.I man-pages
project.
A description of the project,
and information about reporting bugs,
can be found at
http://man7.org/linux/man-pages/.
***************************************************************

Re: veth.4

[Michael Kerrisk (man-pages)]

Hi Tomáš!

On Fri, Nov 2, 2012 at 2:25 PM, Tomas Pospisek <tpo-UQchlGytWBLoPl2ZpcX+cw@public.gmane.org> wrote:
> Hello linux-man ML and Michael,
>
> below you'll find a manpage about the veth virtual ethernet device. The
> manpage is a summarisation of the sparse information about veth I found on
> the net.

Thanks for this!

> I'd be glad if veth(4) could find a place in the manpages because allthough
> I was using veth's a lot lately, I had no idea about how they work and so
> didn't my peers. So I suspect a manpage might be useful.

Yes, it seems reasonable to me.

> In my ignorance I've chosen section 4 for the manpage, maybe there's a
> better one.

Section 4 seems about right to me,

> You can find the manpage below

See comments. After revising, could you resubmit, and and Eric
Biederman and Pavel Emelianov to CC, asking them for comment. Maybe
also CC linux-kernel.

Also, do you have a pointer to "Pavel Emelianov's veth driver
submission to the LKML"? I couldn't find it. It would be at least
handy to have a URL for archived mail in the changelog for this man
page.

[...]

> .TH veth 4 2012-11-02 "Linux" "Linux Programmer's Manual"
> .SH NAME
> veth \- Virtual Ethernet Device
> .SH DESCRIPTION
> The \fBveth*\fP devices are virtual ethernet devices.

Ethernet

> They can act as tunnels between network namespaces to create
> a bridge to a physical network device in another namespace, but
> can also be used as standalone network devices.
>
> Because of their original purpose for tunneling \fBveth\fP devices

I somewhat prefer the use of the line formatting directives, thus

.B veth

> are allways created in pairs, that are interconnected with

always

> each other.  When one \fBveth\fP end receives a packet it

I prefer new sentences to start on new source lines (See man-pages(7).)

> appears on its pair and vice versa.
>
> \fBVeth\fP devices can be manipulated with the
> .BR ip (8)
> tool. See \fB ip link help\fP for more information.

See
.I "ip link help"
for more information.

>
> .SH "SEE ALSO"
> .BR ip (8) ,
> .BR clone (2)

Reverse the order of those two lines.

> .SH COLOPHON

The COLOPHON is autogenerated by scripts. No need to add it, and we
don't really need the next sentence in the man-page itself, thought it
will be useful for the changelog.

> This page is based on Pavel Emelianov's veth driver submission to
> the LKML and on the .BR clone (8)
> manpage.
>
> It is part of release 3.44 of the Linux
> .I man-pages
> project.
> A description of the project,
> and information about reporting bugs,
> can be found at
> http://man7.org/linux/man-pages/.
> ***************************************************************

Best,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: veth.4

[Tomas Pospisek]

[-- Attachment #1: Type: TEXT/PLAIN, Size: 5194 bytes --]

Hi again Michael, Pavel, Eric and mailing list

(Cc: to Eric, Pavel and Linux Netdev List on behalf of Michael asking for 
comment)

Here's the revised veth(4) man page (the inline replies to Michael's 
critique are following the man page):

********************************************************************
.\" Copyright (c) 2012 Tomáš Pospíšek (tpo_deb@sourcepole.ch),
.\"     Fri, 03 Nov 2012 22:35:33 +0100
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, write to the Free
.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
.\" USA.
.\"
.\"
.TH veth 4 2012-11-02 "Linux" "Linux Programmer's Manual"
.SH NAME
veth \- Virtual Ethernet Device
.SH DESCRIPTION
The
.B veth
devices are virtual Ethernet devices.

They can act as tunnels between network namespaces to create
a bridge to a physical network device in another namespace, but
can also be used as standalone network devices.

Because of their original purpose for tunneling
.B veth
devices are always created in pairs, that are
interconnected with each other.
When one
.B veth
end receives a packet it appears on its pair and vice versa.

.B Veth
devices can be manipulated with the
.BR ip (8)
tool.
See
.I "ip link help"
for more information.

.SH NOTES
This page is based on Pavel Emelianov's veth driver submission to
the LKML and on the 
.BR clone (8)
manpage.

.SH "SEE ALSO"
.BR clone (2),
.BR ip (8)
********************************************************************

On Sat, 3 Nov 2012, Michael Kerrisk (man-pages) wrote:

> On Fri, Nov 2, 2012 at 2:25 PM, Tomas Pospisek <tpo-UQchlGytWBLoPl2ZpcX+cw@public.gmane.org> wrote:
[...]
>> You can find the manpage below
>
> See comments. After revising, could you resubmit, and and Eric
> Biederman and Pavel Emelianov to CC, asking them for comment. Maybe
> also CC linux-kernel.
>
> Also, do you have a pointer to "Pavel Emelianov's veth driver
> submission to the LKML"? I couldn't find it. It would be at least
> handy to have a URL for archived mail in the changelog for this man
> page.

Apparently that was to the Linux Netdev List. So I've Cc'ed it instead of 
LKML.

http://lwn.net/Articles/237688/
http://lwn.net/Articles/241883/

>> .TH veth 4 2012-11-02 "Linux" "Linux Programmer's Manual"
>> .SH NAME
>> veth \- Virtual Ethernet Device
>> .SH DESCRIPTION
>> The \fBveth*\fP devices are virtual ethernet devices.
>
> Ethernet
>
>> They can act as tunnels between network namespaces to create
>> a bridge to a physical network device in another namespace, but
>> can also be used as standalone network devices.
>>
>> Because of their original purpose for tunneling \fBveth\fP devices
>
> I somewhat prefer the use of the line formatting directives, thus
>
> .B veth
>
>> are allways created in pairs, that are interconnected with
>
> always
>
>> each other.  When one \fBveth\fP end receives a packet it
>
> I prefer new sentences to start on new source lines (See man-pages(7).)
>
>> appears on its pair and vice versa.
>>
>> \fBVeth\fP devices can be manipulated with the
>> .BR ip (8)
>> tool. See \fB ip link help\fP for more information.
>
> See
> .I "ip link help"
> for more information.
>
>> .SH "SEE ALSO"
>> .BR ip (8) ,
>> .BR clone (2)
>
> Reverse the order of those two lines.
>
>> .SH COLOPHON
>
> The COLOPHON is autogenerated by scripts. No need to add it, [...]

The above manpage should have incorporated all your critique to this 
point.

> [...] and we
> don't really need the next sentence in the man-page itself, thought it
> will be useful for the changelog.
>
>> This page is based on Pavel Emelianov's veth driver submission to
>> the LKML and on the .BR clone (8)
>> manpage.

The reason I've included this - and I've moved it to the "NOTES" section 
above - is that I feel extremely uncomfortable evoking the impression the 
man page would be my work. I don't want to deny responsability for what 
I've submitted to the mailing list - the faults are of course mine. But 
99% of the sentences from the veth(4) manpage are copy/paste from Pavel's 
email or the clone man page.

Certainly I won't insist on the NOTES section and rip it out or move it 
to the comments on your request.

Thanks a lot for your consideration of the manpage submission,
*t

Re: veth.4

[Eric W. Biederman]

Tomas Pospisek <tpo-UQchlGytWBLoPl2ZpcX+cw@public.gmane.org> writes:

> Hi again Michael, Pavel, Eric and mailing list
>
> (Cc: to Eric, Pavel and Linux Netdev List on behalf of Michael asking
> for comment)
>
> Here's the revised veth(4) man page (the inline replies to Michael's
> critique are following the man page):
>
> ********************************************************************
> .\" Copyright (c) 2012 Tomáš Pospíšek (tpo_deb@sourcepole.ch),
> .\"     Fri, 03 Nov 2012 22:35:33 +0100
> .\"
> .\" This is free documentation; you can redistribute it and/or
> .\" modify it under the terms of the GNU General Public License as
> .\" published by the Free Software Foundation; either version 2 of
> .\" the License, or (at your option) any later version.
> .\"
> .\" The GNU General Public License's references to "object code"
> .\" and "executables" are to be interpreted as the output of any
> .\" document formatting or typesetting system, including
> .\" intermediate and printed output.
> .\"
> .\" This manual is distributed in the hope that it will be useful,
> .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
> .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
> .\" GNU General Public License for more details.
> .\"
> .\" You should have received a copy of the GNU General Public
> .\" License along with this manual; if not, write to the Free
> .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
> .\" USA.
> .\"
> .\"
> .TH veth 4 2012-11-02 "Linux" "Linux Programmer's Manual"
> .SH NAME
> veth \- Virtual Ethernet Device
> .SH DESCRIPTION
> The
> .B veth
> devices are virtual Ethernet devices.
>
> They can act as tunnels between network namespaces to create
> a bridge to a physical network device in another namespace, but
> can also be used as standalone network devices.

As far as understanding and using them I think this text is a bit weak.
Perhaps something like:

ip link add type veth creates a pair of directly connected ethernet
devices.   What is transmited on one device is immediately received on
the other device.  When either devices is down the link state of the
pair is down.  veth device pairs are useful for combining the network
facilities of the kernel together in interesting ways.  A particularly
interesting use case is to place one end of a veth pair in one network
namespace and another end of the veth pair in another network namespace
allowing communication between network namespaces.

ethtool can be used to test if a networking device is a veth device,
and to find the peer network interface.

Eric

>
> Because of their original purpose for tunneling
> .B veth
> devices are always created in pairs, that are
> interconnected with each other.
> When one
> .B veth
> end receives a packet it appears on its pair and vice versa.
>
> .B Veth
> devices can be manipulated with the
> .BR ip (8)
> tool.
> See
> .I "ip link help"
> for more information.
>
> .SH NOTES
> This page is based on Pavel Emelianov's veth driver submission to
> the LKML and on the .BR clone (8)
> manpage.
>
> .SH "SEE ALSO"
> .BR clone (2),
> .BR ip (8)
> ********************************************************************
>
> On Sat, 3 Nov 2012, Michael Kerrisk (man-pages) wrote:
>
>> On Fri, Nov 2, 2012 at 2:25 PM, Tomas Pospisek <tpo-UQchlGytWBLoPl2ZpcX+cw@public.gmane.org> wrote:
> [...]
>>> You can find the manpage below
>>
>> See comments. After revising, could you resubmit, and and Eric
>> Biederman and Pavel Emelianov to CC, asking them for comment. Maybe
>> also CC linux-kernel.
>>
>> Also, do you have a pointer to "Pavel Emelianov's veth driver
>> submission to the LKML"? I couldn't find it. It would be at least
>> handy to have a URL for archived mail in the changelog for this man
>> page.
>
> Apparently that was to the Linux Netdev List. So I've Cc'ed it instead
> of LKML.
>
> http://lwn.net/Articles/237688/
> http://lwn.net/Articles/241883/
>
>>> .TH veth 4 2012-11-02 "Linux" "Linux Programmer's Manual"
>>> .SH NAME
>>> veth \- Virtual Ethernet Device
>>> .SH DESCRIPTION
>>> The \fBveth*\fP devices are virtual ethernet devices.
>>
>> Ethernet
>>
>>> They can act as tunnels between network namespaces to create
>>> a bridge to a physical network device in another namespace, but
>>> can also be used as standalone network devices.
>>>
>>> Because of their original purpose for tunneling \fBveth\fP devices
>>
>> I somewhat prefer the use of the line formatting directives, thus
>>
>> .B veth
>>
>>> are allways created in pairs, that are interconnected with
>>
>> always
>>
>>> each other.  When one \fBveth\fP end receives a packet it
>>
>> I prefer new sentences to start on new source lines (See man-pages(7).)
>>
>>> appears on its pair and vice versa.
>>>
>>> \fBVeth\fP devices can be manipulated with the
>>> .BR ip (8)
>>> tool. See \fB ip link help\fP for more information.
>>
>> See
>> .I "ip link help"
>> for more information.
>>
>>> .SH "SEE ALSO"
>>> .BR ip (8) ,
>>> .BR clone (2)
>>
>> Reverse the order of those two lines.
>>
>>> .SH COLOPHON
>>
>> The COLOPHON is autogenerated by scripts. No need to add it, [...]
>
> The above manpage should have incorporated all your critique to this
> point.
>
>> [...] and we
>> don't really need the next sentence in the man-page itself, thought it
>> will be useful for the changelog.
>>
>>> This page is based on Pavel Emelianov's veth driver submission to
>>> the LKML and on the .BR clone (8)
>>> manpage.
>
> The reason I've included this - and I've moved it to the "NOTES"
> section above - is that I feel extremely uncomfortable evoking the
> impression the man page would be my work. I don't want to deny
> responsability for what I've submitted to the mailing list - the
> faults are of course mine. But 99% of the sentences from the veth(4)
> manpage are copy/paste from Pavel's email or the clone man page.
>
> Certainly I won't insist on the NOTES section and rip it out or move
> it to the comments on your request.
>
> Thanks a lot for your consideration of the manpage submission,
> *t
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: veth.4

[Pavel Emelyanov]

On 11/04/2012 04:35 AM, Eric W. Biederman wrote:
> Tomas Pospisek <tpo-UQchlGytWBLoPl2ZpcX+cw@public.gmane.org> writes:
> 
>> Hi again Michael, Pavel, Eric and mailing list
>>
>> (Cc: to Eric, Pavel and Linux Netdev List on behalf of Michael asking
>> for comment)
>>
>> Here's the revised veth(4) man page (the inline replies to Michael's
>> critique are following the man page):
>>
>> ********************************************************************
>> .\" Copyright (c) 2012 Tomáš Pospíšek (tpo_deb@sourcepole.ch),
>> .\"     Fri, 03 Nov 2012 22:35:33 +0100
>> .\"
>> .\" This is free documentation; you can redistribute it and/or
>> .\" modify it under the terms of the GNU General Public License as
>> .\" published by the Free Software Foundation; either version 2 of
>> .\" the License, or (at your option) any later version.
>> .\"
>> .\" The GNU General Public License's references to "object code"
>> .\" and "executables" are to be interpreted as the output of any
>> .\" document formatting or typesetting system, including
>> .\" intermediate and printed output.
>> .\"
>> .\" This manual is distributed in the hope that it will be useful,
>> .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
>> .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
>> .\" GNU General Public License for more details.
>> .\"
>> .\" You should have received a copy of the GNU General Public
>> .\" License along with this manual; if not, write to the Free
>> .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
>> .\" USA.
>> .\"
>> .\"
>> .TH veth 4 2012-11-02 "Linux" "Linux Programmer's Manual"
>> .SH NAME
>> veth \- Virtual Ethernet Device
>> .SH DESCRIPTION
>> The
>> .B veth
>> devices are virtual Ethernet devices.
>>
>> They can act as tunnels between network namespaces to create
>> a bridge to a physical network device in another namespace, but
>> can also be used as standalone network devices.
> 
> As far as understanding and using them I think this text is a bit weak.
> Perhaps something like:
> 
> ip link add type veth creates a pair of directly connected ethernet
> devices.   What is transmited on one device is immediately received on
> the other device.  When either devices is down the link state of the
> pair is down.  veth device pairs are useful for combining the network
> facilities of the kernel together in interesting ways.  A particularly
> interesting use case is to place one end of a veth pair in one network
> namespace and another end of the veth pair in another network namespace
> allowing communication between network namespaces.

Ack

> ethtool can be used to test if a networking device is a veth device,
> and to find the peer network interface.

This one requires clarification, I think. The ethtool will report you 
just and ifindex of the peer, and the caller can do something useful 
with it if the peer is still in the same net namespace as the original 
device. But how would you find the peer device in case it already sits 
in some other network namespace?

> Eric

Thanks,
Pavel
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: veth.4

[Eric W. Biederman]

Pavel Emelyanov <xemul-bzQdu9zFT3WakBO8gow8eQ@public.gmane.org> writes:

> On 11/04/2012 04:35 AM, Eric W. Biederman wrote:
>> Tomas Pospisek <tpo-UQchlGytWBLoPl2ZpcX+cw@public.gmane.org> writes:
>> 
>>> Hi again Michael, Pavel, Eric and mailing list
>>>
>>> (Cc: to Eric, Pavel and Linux Netdev List on behalf of Michael asking
>>> for comment)
>>>
>>> Here's the revised veth(4) man page (the inline replies to Michael's
>>> critique are following the man page):
>>>
>>> ********************************************************************
>>> .\" Copyright (c) 2012 Tomáš Pospíšek (tpo_deb@sourcepole.ch),
>>> .\"     Fri, 03 Nov 2012 22:35:33 +0100
>>> .\"
>>> .\" This is free documentation; you can redistribute it and/or
>>> .\" modify it under the terms of the GNU General Public License as
>>> .\" published by the Free Software Foundation; either version 2 of
>>> .\" the License, or (at your option) any later version.
>>> .\"
>>> .\" The GNU General Public License's references to "object code"
>>> .\" and "executables" are to be interpreted as the output of any
>>> .\" document formatting or typesetting system, including
>>> .\" intermediate and printed output.
>>> .\"
>>> .\" This manual is distributed in the hope that it will be useful,
>>> .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
>>> .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
>>> .\" GNU General Public License for more details.
>>> .\"
>>> .\" You should have received a copy of the GNU General Public
>>> .\" License along with this manual; if not, write to the Free
>>> .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
>>> .\" USA.
>>> .\"
>>> .\"
>>> .TH veth 4 2012-11-02 "Linux" "Linux Programmer's Manual"
>>> .SH NAME
>>> veth \- Virtual Ethernet Device
>>> .SH DESCRIPTION
>>> The
>>> .B veth
>>> devices are virtual Ethernet devices.
>>>
>>> They can act as tunnels between network namespaces to create
>>> a bridge to a physical network device in another namespace, but
>>> can also be used as standalone network devices.
>> 
>> As far as understanding and using them I think this text is a bit weak.
>> Perhaps something like:
>> 
>> ip link add type veth creates a pair of directly connected ethernet
>> devices.   What is transmited on one device is immediately received on
>> the other device.  When either devices is down the link state of the
>> pair is down.  veth device pairs are useful for combining the network
>> facilities of the kernel together in interesting ways.  A particularly
>> interesting use case is to place one end of a veth pair in one network
>> namespace and another end of the veth pair in another network namespace
>> allowing communication between network namespaces.
>
> Ack
>
>> ethtool can be used to test if a networking device is a veth device,
>> and to find the peer network interface.
>
> This one requires clarification, I think. The ethtool will report you 
> just and ifindex of the peer, and the caller can do something useful 
> with it if the peer is still in the same net namespace as the original 
> device. But how would you find the peer device in case it already sits 
> in some other network namespace?

Until just recently the ifindex of networking devices was universally
unique so finding the other end of the device could be done with a brute
force search through network namespaces.  Even without a guarantee of
global uniqueness in the ifindex performing a bidirectional comparison
of the return ifindicies of veth devices can give a strong hint that you
have found both ends of the tunnel.

For checkpoint/restart we may need to implement something better at some point.


Eric

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: veth.4

[Michael Kerrisk (man-pages)]

Hoi Tomas,

Do you have a revised version of this page taking into account the
comments of Eric and Pavel?

Thanks,

Michael



On Mon, Nov 5, 2012 at 5:11 AM, Eric W. Biederman <ebiederm-aS9lmoZGLiXQFizaE/u3fw@public.gmane.orgm> wrote:
> Pavel Emelyanov <xemul-bzQdu9zFT3WakBO8gow8eQ@public.gmane.org> writes:
>
>> On 11/04/2012 04:35 AM, Eric W. Biederman wrote:
>>> Tomas Pospisek <tpo-UQchlGytWBLoPl2ZpcX+cw@public.gmane.org> writes:
>>>
>>>> Hi again Michael, Pavel, Eric and mailing list
>>>>
>>>> (Cc: to Eric, Pavel and Linux Netdev List on behalf of Michael asking
>>>> for comment)
>>>>
>>>> Here's the revised veth(4) man page (the inline replies to Michael's
>>>> critique are following the man page):
>>>>
>>>> ********************************************************************
>>>> .\" Copyright (c) 2012 Tomáš Pospíšek (tpo_deb@sourcepole.ch),
>>>> .\"     Fri, 03 Nov 2012 22:35:33 +0100
>>>> .\"
>>>> .\" This is free documentation; you can redistribute it and/or
>>>> .\" modify it under the terms of the GNU General Public License as
>>>> .\" published by the Free Software Foundation; either version 2 of
>>>> .\" the License, or (at your option) any later version.
>>>> .\"
>>>> .\" The GNU General Public License's references to "object code"
>>>> .\" and "executables" are to be interpreted as the output of any
>>>> .\" document formatting or typesetting system, including
>>>> .\" intermediate and printed output.
>>>> .\"
>>>> .\" This manual is distributed in the hope that it will be useful,
>>>> .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
>>>> .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
>>>> .\" GNU General Public License for more details.
>>>> .\"
>>>> .\" You should have received a copy of the GNU General Public
>>>> .\" License along with this manual; if not, write to the Free
>>>> .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
>>>> .\" USA.
>>>> .\"
>>>> .\"
>>>> .TH veth 4 2012-11-02 "Linux" "Linux Programmer's Manual"
>>>> .SH NAME
>>>> veth \- Virtual Ethernet Device
>>>> .SH DESCRIPTION
>>>> The
>>>> .B veth
>>>> devices are virtual Ethernet devices.
>>>>
>>>> They can act as tunnels between network namespaces to create
>>>> a bridge to a physical network device in another namespace, but
>>>> can also be used as standalone network devices.
>>>
>>> As far as understanding and using them I think this text is a bit weak.
>>> Perhaps something like:
>>>
>>> ip link add type veth creates a pair of directly connected ethernet
>>> devices.   What is transmited on one device is immediately received on
>>> the other device.  When either devices is down the link state of the
>>> pair is down.  veth device pairs are useful for combining the network
>>> facilities of the kernel together in interesting ways.  A particularly
>>> interesting use case is to place one end of a veth pair in one network
>>> namespace and another end of the veth pair in another network namespace
>>> allowing communication between network namespaces.
>>
>> Ack
>>
>>> ethtool can be used to test if a networking device is a veth device,
>>> and to find the peer network interface.
>>
>> This one requires clarification, I think. The ethtool will report you
>> just and ifindex of the peer, and the caller can do something useful
>> with it if the peer is still in the same net namespace as the original
>> device. But how would you find the peer device in case it already sits
>> in some other network namespace?
>
> Until just recently the ifindex of networking devices was universally
> unique so finding the other end of the device could be done with a brute
> force search through network namespaces.  Even without a guarantee of
> global uniqueness in the ifindex performing a bidirectional comparison
> of the return ifindicies of veth devices can give a strong hint that you
> have found both ends of the tunnel.
>
> For checkpoint/restart we may need to implement something better at some point.
>
>
> Eric
>



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: veth.4

[Tomas Pospisek]

[-- Attachment #1: Type: TEXT/PLAIN, Size: 4685 bytes --]

On Thu, 13 Dec 2012, Michael Kerrisk (man-pages) wrote:

> Do you have a revised version of this page taking into account the
> comments of Eric and Pavel?

No I don't. I got trampled down by a horde of rabid real life tasks and am 
slowly recovering from it. I'll make a new effort at some point, Eric's 
and Pavel's emails still have their cosy place in my INBOX and are waiting 
to be groomed.

Thanks for pinging me!
*t

> On Mon, Nov 5, 2012 at 5:11 AM, Eric W. Biederman <ebiederm-aS9lmoZGLiVWk0Htik3J/w@public.gmane.org> wrote:
>> Pavel Emelyanov <xemul-bzQdu9zFT3WakBO8gow8eQ@public.gmane.org> writes:
>>
>>> On 11/04/2012 04:35 AM, Eric W. Biederman wrote:
>>>> Tomas Pospisek <tpo-UQchlGytWBLoPl2ZpcX+cw@public.gmane.org> writes:
>>>>
>>>>> Hi again Michael, Pavel, Eric and mailing list
>>>>>
>>>>> (Cc: to Eric, Pavel and Linux Netdev List on behalf of Michael asking
>>>>> for comment)
>>>>>
>>>>> Here's the revised veth(4) man page (the inline replies to Michael's
>>>>> critique are following the man page):
>>>>>
>>>>> ********************************************************************
>>>>> .\" Copyright (c) 2012 Tomáš Pospíšek (tpo_deb@sourcepole.ch),
>>>>> .\"     Fri, 03 Nov 2012 22:35:33 +0100
>>>>> .\"
>>>>> .\" This is free documentation; you can redistribute it and/or
>>>>> .\" modify it under the terms of the GNU General Public License as
>>>>> .\" published by the Free Software Foundation; either version 2 of
>>>>> .\" the License, or (at your option) any later version.
>>>>> .\"
>>>>> .\" The GNU General Public License's references to "object code"
>>>>> .\" and "executables" are to be interpreted as the output of any
>>>>> .\" document formatting or typesetting system, including
>>>>> .\" intermediate and printed output.
>>>>> .\"
>>>>> .\" This manual is distributed in the hope that it will be useful,
>>>>> .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
>>>>> .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
>>>>> .\" GNU General Public License for more details.
>>>>> .\"
>>>>> .\" You should have received a copy of the GNU General Public
>>>>> .\" License along with this manual; if not, write to the Free
>>>>> .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
>>>>> .\" USA.
>>>>> .\"
>>>>> .\"
>>>>> .TH veth 4 2012-11-02 "Linux" "Linux Programmer's Manual"
>>>>> .SH NAME
>>>>> veth \- Virtual Ethernet Device
>>>>> .SH DESCRIPTION
>>>>> The
>>>>> .B veth
>>>>> devices are virtual Ethernet devices.
>>>>>
>>>>> They can act as tunnels between network namespaces to create
>>>>> a bridge to a physical network device in another namespace, but
>>>>> can also be used as standalone network devices.
>>>>
>>>> As far as understanding and using them I think this text is a bit weak.
>>>> Perhaps something like:
>>>>
>>>> ip link add type veth creates a pair of directly connected ethernet
>>>> devices.   What is transmited on one device is immediately received on
>>>> the other device.  When either devices is down the link state of the
>>>> pair is down.  veth device pairs are useful for combining the network
>>>> facilities of the kernel together in interesting ways.  A particularly
>>>> interesting use case is to place one end of a veth pair in one network
>>>> namespace and another end of the veth pair in another network namespace
>>>> allowing communication between network namespaces.
>>>
>>> Ack
>>>
>>>> ethtool can be used to test if a networking device is a veth device,
>>>> and to find the peer network interface.
>>>
>>> This one requires clarification, I think. The ethtool will report you
>>> just and ifindex of the peer, and the caller can do something useful
>>> with it if the peer is still in the same net namespace as the original
>>> device. But how would you find the peer device in case it already sits
>>> in some other network namespace?
>>
>> Until just recently the ifindex of networking devices was universally
>> unique so finding the other end of the device could be done with a brute
>> force search through network namespaces.  Even without a guarantee of
>> global uniqueness in the ifindex performing a bidirectional comparison
>> of the return ifindicies of veth devices can give a strong hint that you
>> have found both ends of the tunnel.
>>
>> For checkpoint/restart we may need to implement something better at some point.
>>
>>
>> Eric
>>
>
>
>
> -- 
> Michael Kerrisk
> Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
> Author of "The Linux Programming Interface"; http://man7.org/tlpi/
>
>

Re: veth.4

[Michael Kerrisk (man-pages)]

On Thu, Dec 13, 2012 at 11:05 AM, Tomas Pospisek <tpo-UQchlGytWBLoPl2ZpcX+cw@public.gmane.org> wrote:
> On Thu, 13 Dec 2012, Michael Kerrisk (man-pages) wrote:
>
>> Do you have a revised version of this page taking into account the
>> comments of Eric and Pavel?
>
>
> No I don't. I got trampled down by a horde of rabid real life tasks and am
> slowly recovering from it. I'll make a new effort at some point, Eric's and
> Pavel's emails still have their cosy place in my INBOX and are waiting to be
> groomed.

Good, because I would be happy to add that page to the set.

MfG,

Michael


>> On Mon, Nov 5, 2012 at 5:11 AM, Eric W. Biederman <ebiederm@xmission.com>
>> wrote:
>>>
>>> Pavel Emelyanov <xemul-bzQdu9zFT3WakBO8gow8eQ@public.gmane.org> writes:
>>>
>>>> On 11/04/2012 04:35 AM, Eric W. Biederman wrote:
>>>>>
>>>>> Tomas Pospisek <tpo-UQchlGytWBLoPl2ZpcX+cw@public.gmane.org> writes:
>>>>>
>>>>>> Hi again Michael, Pavel, Eric and mailing list
>>>>>>
>>>>>> (Cc: to Eric, Pavel and Linux Netdev List on behalf of Michael asking
>>>>>> for comment)
>>>>>>
>>>>>> Here's the revised veth(4) man page (the inline replies to Michael's
>>>>>> critique are following the man page):
>>>>>>
>>>>>> ********************************************************************
>>>>>> .\" Copyright (c) 2012 Tomáš Pospíšek (tpo_deb-UQchlGytWBLoPl2ZpcX+cw@public.gmane.org),
>>>>>> .\"     Fri, 03 Nov 2012 22:35:33 +0100
>>>>>> .\"
>>>>>> .\" This is free documentation; you can redistribute it and/or
>>>>>> .\" modify it under the terms of the GNU General Public License as
>>>>>> .\" published by the Free Software Foundation; either version 2 of
>>>>>> .\" the License, or (at your option) any later version.
>>>>>> .\"
>>>>>> .\" The GNU General Public License's references to "object code"
>>>>>> .\" and "executables" are to be interpreted as the output of any
>>>>>> .\" document formatting or typesetting system, including
>>>>>> .\" intermediate and printed output.
>>>>>> .\"
>>>>>> .\" This manual is distributed in the hope that it will be useful,
>>>>>> .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
>>>>>> .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
>>>>>> .\" GNU General Public License for more details.
>>>>>> .\"
>>>>>> .\" You should have received a copy of the GNU General Public
>>>>>> .\" License along with this manual; if not, write to the Free
>>>>>> .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
>>>>>> 02111,
>>>>>> .\" USA.
>>>>>> .\"
>>>>>> .\"
>>>>>> .TH veth 4 2012-11-02 "Linux" "Linux Programmer's Manual"
>>>>>> .SH NAME
>>>>>> veth \- Virtual Ethernet Device
>>>>>> .SH DESCRIPTION
>>>>>> The
>>>>>> .B veth
>>>>>> devices are virtual Ethernet devices.
>>>>>>
>>>>>> They can act as tunnels between network namespaces to create
>>>>>> a bridge to a physical network device in another namespace, but
>>>>>> can also be used as standalone network devices.
>>>>>
>>>>>
>>>>> As far as understanding and using them I think this text is a bit weak.
>>>>> Perhaps something like:
>>>>>
>>>>> ip link add type veth creates a pair of directly connected ethernet
>>>>> devices.   What is transmited on one device is immediately received on
>>>>> the other device.  When either devices is down the link state of the
>>>>> pair is down.  veth device pairs are useful for combining the network
>>>>> facilities of the kernel together in interesting ways.  A particularly
>>>>> interesting use case is to place one end of a veth pair in one network
>>>>> namespace and another end of the veth pair in another network namespace
>>>>> allowing communication between network namespaces.
>>>>
>>>>
>>>> Ack
>>>>
>>>>> ethtool can be used to test if a networking device is a veth device,
>>>>> and to find the peer network interface.
>>>>
>>>>
>>>> This one requires clarification, I think. The ethtool will report you
>>>> just and ifindex of the peer, and the caller can do something useful
>>>> with it if the peer is still in the same net namespace as the original
>>>> device. But how would you find the peer device in case it already sits
>>>> in some other network namespace?
>>>
>>>
>>> Until just recently the ifindex of networking devices was universally
>>> unique so finding the other end of the device could be done with a brute
>>> force search through network namespaces.  Even without a guarantee of
>>> global uniqueness in the ifindex performing a bidirectional comparison
>>> of the return ifindicies of veth devices can give a strong hint that you
>>> have found both ends of the tunnel.
>>>
>>> For checkpoint/restart we may need to implement something better at some
>>> point.
>>>
>>>
>>> Eric
>>>
>>
>>
>>
>> --
>> Michael Kerrisk
>> Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
>> Author of "The Linux Programming Interface"; http://man7.org/tlpi/
>>
>



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html