Skip to contentSkip to conversation

net: update netdev stream/dgram man page

PATCH Superseded Laurent Vivier 2 participants 5 messages Jun 26, 2024 – Jul 4, 2024

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 net: update netdev stream/dgram man page

Add the description of "-netdev stream" and "-netdev dgram" in the QEMU manpage.

Add some examples on how to use them, including a way to use "-netdev stream" and "passt" in place of "-netdev user". ("passt" is a non privileged translation proxy between layer-2, like "-netdev stream", and layer-4 on host, like TCP, UDP, ICMP/ICMPv6 echo)

Fixes 5166fe0ae46d ("qapi: net: add stream and dgram netdevs")
Fixes 13c6be96618c ("net: stream: add unix socket")
Fixes 784e7a253104 ("net: dgram: add unix socket")
Fixes 148fbf0d58a6 ("net: stream: add a new option to automatically reconnect"
---
 qemu-options.hx | 189 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 189 insertions(+)
qemu-options.hx +189 -0
index 8ca7f34ef0c8..b8a1a65f05e7 100644
@@ -3353,6 +3353,195 @@ SRST
                          -device e1000,netdev=n1,mac=52:54:00:12:34:56 \\
                          -netdev socket,id=n1,mcast=239.192.168.1:1102,localaddr=1.2.3.4
 
+``-netdev stream,id=str[,server=on|off],addr.type=inet,addr.host=host,addr.port=port[,to=maxport][,numeric=on|off][,keep-alive=on|off][,mptcp=on|off][,addr.ipv4=on|off][,addr.ipv6=on|off][,reconnect=seconds]``
+    Configure a network backend to connect to another QEMU virtual machine or a proxy using a TCP/IP socket.
+
+    ``server=on|off``
+        if ``on`` create a server socket
+
+    ``addr.host=host,addr.port=port``
+        socket address to listen on (server=on) or connect to (server=off)
+
+    ``to=maxport``
+        if present, this is range of possible addresses, with port between ``port`` and ``maxport``.
+
+    ``numeric=on|off``
+        if ``on`` ``host`` and ``port`` are guaranteed to be numeric, otherwise a name resolution should be attempted (default: ``off``)
+
+    ``keep-alive=on|off``
+        enable keep-alive when connecting to this socket.  Not supported for passive sockets.
+
+    ``mptcp=on|off``
+        enable multipath TCP
+
+    ``ipv4=on|off``
+        whether to accept IPv4 addresses, default to try both IPv4 and IPv6
+
+    ``ipv6=on|off``
+        whether to accept IPv6 addresses, default to try both IPv4 and IPv6
+
+    ``reconnect=seconds``
+        for a client socket, if a socket is disconnected, then attempt a reconnect after the given number of seconds.
+        Setting this to zero disables this function.  (default: 0)
+
+    Example (two guests connected using a TCP/IP socket):
+
+    .. parsed-literal::
+
+        # first VM
+        |qemu_system| linux.img \\
+                      -device virtio-net,netdev=net0,mac=52:54:00:12:34:56 \\
+                      -netdev stream,id=net0,server=on,addr.type=inet,addr.host=localhost,addr.port=1234
+        # second VM
+        |qemu_system| linux.img \\
+                      -device virtio-net,netdev=net0,mac=52:54:00:12:34:57 \\
+                      -netdev stream,id=net0,server=off,addr.type=inet,addr.host=localhost,addr.port=1234,reconnect=5
+
+``-netdev stream,id=str[,server=on|off],addr.type=unix,addr.path=path[,abstract=on|off][,tight=on|off][,reconnect=seconds]``
+    Configure a network backend to connect to another QEMU virtual machine or a proxy using a TCP/UNIX socket.
+
+    ``server=on|off``
+        if ``on`` create a server socket
+
+    ``addr.path=path``
+        filesystem path to use
+
+    ``abstract=on|off``
+        if ``on``, this is a Linux abstract socket address.
+
+    ``tight=on|off``
+        if false, pad an abstract socket address with enough null bytes to make it fill struct sockaddr_un member sun_path.
+
+    ``reconnect=seconds``
+        for a client socket, if a socket is disconnected, then attempt a reconnect after the given number of seconds.
+        Setting this to zero disables this function.  (default: 0)
+
+    Example (using passt as a replacement of -netdev user):
+
+    .. parsed-literal::
+
+        # start passt server as a non privileged user
+        passt
+        UNIX domain socket bound at /tmp/passt_1.socket
+        # start QEMU to connect to passt
+        |qemu_system| linux.img \\
+                      -device virtio-net,netdev=net0 \\
+                      -netdev stream,id=net0,server=off,addr.type=unix,addr.path=/tmp/passt_1.socket
+
+    Example (two guests connected using a TCP/UNIX socket):
+
+    .. parsed-literal::
+
+        # first VM
+        |qemu_system| linux.img \\
+                      -device virtio-net,netdev=net0,mac=52:54:00:12:34:56 \\
+                      netdev stream,id=net0,server=on,addr.type=unix,addr.path=/tmp/qemu0
+        # second VM
+        |qemu_system| linux.img \\
+                      -device virtio-net,netdev=net0,mac=52:54:00:12:34:57 \\
+                      -netdev stream,id=net0,server=off,addr.type=unix,addr.path=/tmp/qemu0,reconnect=5
+
+``-netdev stream,id=str[,server=on|off],addr.type=fd,addr.str=file-descriptor[,reconnect=seconds]``
+    Configure a network backend to connect to another  QEMU  virtual machine or a proxy using a TCP socket file descriptor.
+
+    ``server=on|off``
+        if ``on`` create a server socket
+
+    ``addr.str=file-descriptor``
+        file descriptor number to use as a socket
+
+    ``reconnect=seconds``
+        for a client socket, if a socket is disconnected, then attempt a reconnect after the given number of seconds.
+        Setting this to zero disables this function.  (default: 0)
+
+``-netdev dgram,id=str,remote.type=inet,remote.host=maddr,remote.port=port[,local.type=inet,local.host=addr]``
+    Configure a network backend to connect to a multicast address.
+
+    ``remote.host=maddr,remote.port=port``
+        multicast address
+
+    ``local.host=addr``
+        specify the host address to send packets from
+
+    Example:
+
+    .. parsed-literal::
+
+        # launch one QEMU instance
+        |qemu_system| linux.img \\
+                      -device virtio-net,netdev=net0,mac=52:54:00:12:34:56 \\
+                      -netdev dgram,id=net0,remote.type=inet,remote.host=224.0.0.1,remote.port=1234
+        # launch another QEMU instance on same "bus"
+        |qemu_system| linux.img \\
+                      -device virtio-net,netdev=net0,mac=52:54:00:12:34:57 \\
+                      -netdev dgram,id=net0,remote.type=inet,remote.host=224.0.0.1,remote.port=1234
+        # launch yet another QEMU instance on same "bus"
+        |qemu_system| linux.img \\
+                      -device virtio-net,netdev=net0,mac=52:54:00:12:34:58 \\
+                      -netdev dgram,id=net0,remote.type=inet,remote.host=224.0.0.1,remote.port=1234
+
+``-netdev dgram,id=str,remote.type=inet,remote.host=maddr,remote.port=port[,local.type=fd,local.str=file-descriptor]``
+    Configure a network backend to connect to a multicast address using a UDP socket file descriptor.
+
+    ``remote.host=maddr,remote.port=port``
+        multicast address
+
+    ``local.str=file-descriptor``
+        File descriptor to use to send packets
+
+``-netdev dgram,id=str,local.type=inet,local.host=addr,local.port=port[,remote.type=inet,remote.host=addr,remote.port=port]``
+    Configure a network backend to connect to another QEMU virtual
+    machine or a proxy using an UDP/IP socket.
+
+    ``local.host=addr,local.port=port``
+        IP address to use to send the packets from
+
+    ``remote.host=addr,remote.port=port``
+        Destination IP address
+
+    Example (two guests connected using an UDP/IP socket):
+
+    .. parsed-literal::
+
+        # first VM
+        |qemu_system| linux.img \\
+                      -device virtio-net,netdev=net0,mac=52:54:00:12:34:56 \\
+                      -netdev dgram,id=net0,local.type=inet,local.host=localhost,local.port=1234,remote.type=inet,remote.host=localhost,remote.port=1235
+        # second VM
+        |qemu_system| linux.img \\
+                      -device virtio-net,netdev=net0,mac=52:54:00:12:34:56 \\
+                      -netdev dgram,id=net0,local.type=inet,local.host=localhost,local.port=1235,remote.type=inet,remote.host=localhost,remote.port=1234
+
+``-netdev dgram,id=str,local.type=unix,local.path=path[,remote.type=unix,remote.path=path]``
+    Configure a network backend to connect to another QEMU virtual
+    machine or a proxy using an UDP/UNIX socket.
+
+    ``local.path=path``
+        filesystem path to use to bind the socket
+
+    ``remote.path=path``
+        filesystem path to use as a destination (see sendto(2))
+
+    Example (two guests connected using an UDP/UNIX socket):
+
+    .. parsed-literal::
+
+        # first VM
+        |qemu_system| linux.img \\
+                      -device virtio-net,netdev=net0,mac=52:54:00:12:34:56 \\
+                      -netdev dgram,id=net0,local.type=unix,local.path=/tmp/qemu0,remote.type=unix,remote.path=/tmp/qemu1
+        # second VM
+        |qemu_system| linux.img \\
+                      -device virtio-net,netdev=net0,mac=52:54:00:12:34:57 \\
+                      -netdev dgram,id=net0,local.type=unix,local.path=/tmp/qemu1,remote.type=unix,remote.path=/tmp/qemu0
+
+``-netdev dgram,id=str,local.type=fd,local.str=file-descriptor``
+    Configure a network backend to connect to another QEMU virtual
+    machine or a proxy using an UDP socket file descriptor.
+
+    ``local.str=file-descriptor``
+        File descriptor to use to send packets
+
 ``-netdev l2tpv3,id=id,src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport],txsession=txsession[,rxsession=rxsession][,ipv6=on|off][,udp=on|off][,cookie64][,counter][,pincounter][,txcookie=txcookie][,rxcookie=rxcookie][,offset=offset]``
     Configure a L2TPv3 pseudowire host network backend. L2TPv3 (RFC3931)
     is a popular protocol to transport Ethernet (and other Layer 2) data
Signature · 1 line
2.45.2
#1 lore raw

Hi

Quoted 9 lines · Laurent Vivier

Add the description of "-netdev stream" and "-netdev dgram" in the QEMU manpage.

Add some examples on how to use them, including a way to use "-netdev stream" and "passt" in place of "-netdev user". ("passt" is a non privileged translation proxy between layer-2, like "-netdev stream", and layer-4 on host, like TCP, UDP, ICMP/ICMPv6 echo)

Quoted 7 lines
Fixes 5166fe0ae46d ("qapi: net: add stream and dgram netdevs")
Fixes 13c6be96618c ("net: stream: add unix socket")
Fixes 784e7a253104 ("net: dgram: add unix socket")
Fixes 148fbf0d58a6 ("net: stream: add a new option to automatically

reconnect"

Could be easier to review if this documentation addition is splitted in various patches.

Quoted 65 lines
---
 qemu-options.hx | 189 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 189 insertions(+)
qemu-options.hx +0 -0
index 8ca7f34ef0c8..b8a1a65f05e7 100644
@@ -3353,6 +3353,195 @@ SRST
                          -device e1000,netdev=n1,mac=52:54:00:12:34:56 \\
                          -netdev socket,id=n1,mcast=239.192.168.1:1102

,localaddr=1.2.3.4

+``-netdev stream,id=str[,server=on|off],addr.type=inet,addr.host=host,addr.port=port[,to=maxport][,numeric=on|off][,keep-alive=on|off][,mptcp=on|off][,addr.ipv4=on|off][,addr.ipv6=on|off][,reconnect=seconds]``
+ Configure a network backend to connect to another QEMU virtual
machine or a proxy using a TCP/IP socket.

qemu-options.hx +9 -0
+
+    ``server=on|off``
+        if ``on`` create a server socket
+
+    ``addr.host=host,addr.port=port``
+        socket address to listen on (server=on) or connect to (server=off)
+
+    ``to=maxport``
+        if present, this is range of possible addresses, with port

between ``port`` and ``maxport``.

qemu-options.hx +3 -0
+
+    ``numeric=on|off``
+        if ``on`` ``host`` and ``port`` are guaranteed to be numeric,

otherwise a name resolution should be attempted (default: ``off``)

qemu-options.hx +3 -0
+
+    ``keep-alive=on|off``
+        enable keep-alive when connecting to this socket.  Not supported

for passive sockets.

qemu-options.hx +6 -0
+
+    ``mptcp=on|off``
+        enable multipath TCP
+
+    ``ipv4=on|off``
+        whether to accept IPv4 addresses, default to try both IPv4 and

IPv6

qemu-options.hx +3 -0
+
+    ``ipv6=on|off``
+        whether to accept IPv6 addresses, default to try both IPv4 and

IPv6

qemu-options.hx +3 -0
+
+    ``reconnect=seconds``
+        for a client socket, if a socket is disconnected, then attempt a

reconnect after the given number of seconds.

qemu-options.hx +9 -0
+        Setting this to zero disables this function.  (default: 0)
+
+    Example (two guests connected using a TCP/IP socket):
+
+    .. parsed-literal::
+
+        # first VM
+        |qemu_system| linux.img \\
+                      -device

virtio-net,netdev=net0,mac=52:54:00:12:34:56 \\
+ -netdev
stream,id=net0,server=on,addr.type=inet,addr.host=localhost,addr.port=1234

qemu-options.hx +3 -0
+        # second VM
+        |qemu_system| linux.img \\
+                      -device
Quoted 9 lines

virtio-net,netdev=net0,mac=52:54:00:12:34:57 \\
+ -netdev
stream,id=net0,server=off,addr.type=inet,addr.host=localhost,addr.port=1234,reconnect=5
+
+``-netdev stream,id=str[,server=on|off],addr.type=unix,addr.path=path[,abstract=on|off][,tight=on|off][,reconnect=seconds]``
+ Configure a network backend to connect to another QEMU virtual
machine or a proxy using a TCP/UNIX socket.

"TCP/UNIX": just UNIX instead?

+

Quoted 31 lines
qemu-options.hx +11 -0
+    ``server=on|off``
+        if ``on`` create a server socket
+
+    ``addr.path=path``
+        filesystem path to use
+
+    ``abstract=on|off``
+        if ``on``, this is a Linux abstract socket address.
+
+    ``tight=on|off``
+        if false, pad an abstract socket address with enough null bytes

to make it fill struct sockaddr_un member sun_path.

qemu-options.hx +3 -0
+
+    ``reconnect=seconds``
+        for a client socket, if a socket is disconnected, then attempt a

reconnect after the given number of seconds.

qemu-options.hx +13 -0
+        Setting this to zero disables this function.  (default: 0)
+
+    Example (using passt as a replacement of -netdev user):
+
+    .. parsed-literal::
+
+        # start passt server as a non privileged user
+        passt
+        UNIX domain socket bound at /tmp/passt_1.socket
+        # start QEMU to connect to passt
+        |qemu_system| linux.img \\
+                      -device virtio-net,netdev=net0 \\
+                      -netdev

stream,id=net0,server=off,addr.type=unix,addr.path=/tmp/passt_1.socket

qemu-options.hx SRST · line 3432

Quoted 3 lines
qemu-options.hx +3 -0
+
+    Example (two guests connected using a TCP/UNIX socket):
+

same

Quoted 12 lines
qemu-options.hx +5 -0
+    .. parsed-literal::
+
+        # first VM
+        |qemu_system| linux.img \\
+                      -device

virtio-net,netdev=net0,mac=52:54:00:12:34:56 \\
+ netdev
stream,id=net0,server=on,addr.type=unix,addr.path=/tmp/qemu0

qemu-options.hx +3 -0
+        # second VM
+        |qemu_system| linux.img \\
+                      -device

virtio-net,netdev=net0,mac=52:54:00:12:34:57 \\

Quoted 9 lines

+ -netdev
stream,id=net0,server=off,addr.type=unix,addr.path=/tmp/qemu0,reconnect=5
+
+``-netdev stream,id=str[,server=on|off],addr.type=fd,addr.str=file-descriptor[,reconnect=seconds]``
+ Configure a network backend to connect to another QEMU virtual
machine or a proxy using a TCP socket file descriptor.
+

I guess it would work with either a TCP or UNIX socket. Perhaps just say "a socket file descriptor" ?

Quoted 86 lines
qemu-options.hx +8 -0
+    ``server=on|off``
+        if ``on`` create a server socket
+
+    ``addr.str=file-descriptor``
+        file descriptor number to use as a socket
+
+    ``reconnect=seconds``
+        for a client socket, if a socket is disconnected, then attempt a

reconnect after the given number of seconds.

qemu-options.hx +3 -0
+        Setting this to zero disables this function.  (default: 0)
+
+``-netdev

dgram,id=str,remote.type=inet,remote.host=maddr,remote.port=port[,local.type=inet,local.host=addr]``

qemu-options.hx +15 -0
+    Configure a network backend to connect to a multicast address.
+
+    ``remote.host=maddr,remote.port=port``
+        multicast address
+
+    ``local.host=addr``
+        specify the host address to send packets from
+
+    Example:
+
+    .. parsed-literal::
+
+        # launch one QEMU instance
+        |qemu_system| linux.img \\
+                      -device

virtio-net,netdev=net0,mac=52:54:00:12:34:56 \\
+ -netdev
dgram,id=net0,remote.type=inet,remote.host=224.0.0.1,remote.port=1234

qemu-options.hx +3 -0
+        # launch another QEMU instance on same "bus"
+        |qemu_system| linux.img \\
+                      -device

virtio-net,netdev=net0,mac=52:54:00:12:34:57 \\
+ -netdev
dgram,id=net0,remote.type=inet,remote.host=224.0.0.1,remote.port=1234

qemu-options.hx +3 -0
+        # launch yet another QEMU instance on same "bus"
+        |qemu_system| linux.img \\
+                      -device

virtio-net,netdev=net0,mac=52:54:00:12:34:58 \\
+ -netdev
dgram,id=net0,remote.type=inet,remote.host=224.0.0.1,remote.port=1234
+
+``-netdev dgram,id=str,remote.type=inet,remote.host=maddr,remote.port=port[,local.type=fd,local.str=file-descriptor]``
+ Configure a network backend to connect to a multicast address using a
UDP socket file descriptor.

qemu-options.hx +8 -0
+
+    ``remote.host=maddr,remote.port=port``
+        multicast address
+
+    ``local.str=file-descriptor``
+        File descriptor to use to send packets
+
+``-netdev

dgram,id=str,local.type=inet,local.host=addr,local.port=port[,remote.type=inet,remote.host=addr,remote.port=port]``

qemu-options.hx +16 -0
+    Configure a network backend to connect to another QEMU virtual
+    machine or a proxy using an UDP/IP socket.
+
+    ``local.host=addr,local.port=port``
+        IP address to use to send the packets from
+
+    ``remote.host=addr,remote.port=port``
+        Destination IP address
+
+    Example (two guests connected using an UDP/IP socket):
+
+    .. parsed-literal::
+
+        # first VM
+        |qemu_system| linux.img \\
+                      -device

virtio-net,netdev=net0,mac=52:54:00:12:34:56 \\
+ -netdev
dgram,id=net0,local.type=inet,local.host=localhost,local.port=1234,remote.type=inet,remote.host=localhost,remote.port=1235

qemu-options.hx +3 -0
+        # second VM
+        |qemu_system| linux.img \\
+                      -device

virtio-net,netdev=net0,mac=52:54:00:12:34:56 \\
+ -netdev
dgram,id=net0,local.type=inet,local.host=localhost,local.port=1235,remote.type=inet,remote.host=localhost,remote.port=1234 +
+``-netdev
dgram,id=str,local.type=unix,local.path=path[,remote.type=unix,remote.path=path]``

qemu-options.hx

Quoted 2 lines
qemu-options.hx +2 -0
+    Configure a network backend to connect to another QEMU virtual
+    machine or a proxy using an UDP/UNIX socket.

Here also, that kind of notation is confusing. What's the use case, since afaik there is no multicast with UNIX socket? Perhaps this shouldn't be allowed at all.

+

Quoted 39 lines
qemu-options.hx +13 -0
+    ``local.path=path``
+        filesystem path to use to bind the socket
+
+    ``remote.path=path``
+        filesystem path to use as a destination (see sendto(2))
+
+    Example (two guests connected using an UDP/UNIX socket):
+
+    .. parsed-literal::
+
+        # first VM
+        |qemu_system| linux.img \\
+                      -device

virtio-net,netdev=net0,mac=52:54:00:12:34:56 \\
+ -netdev
dgram,id=net0,local.type=unix,local.path=/tmp/qemu0,remote.type=unix,remote.path=/tmp/qemu1

qemu-options.hx +3 -0
+        # second VM
+        |qemu_system| linux.img \\
+                      -device

virtio-net,netdev=net0,mac=52:54:00:12:34:57 \\
+ -netdev
dgram,id=net0,local.type=unix,local.path=/tmp/qemu1,remote.type=unix,remote.path=/tmp/qemu0

qemu-options.hx +8 -0
+
+``-netdev dgram,id=str,local.type=fd,local.str=file-descriptor``
+    Configure a network backend to connect to another QEMU virtual
+    machine or a proxy using an UDP socket file descriptor.
+
+    ``local.str=file-descriptor``
+        File descriptor to use to send packets
+
 ``-netdev

l2tpv3,id=id,src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport],txsession=txsession[,rxsession=rxsession][,ipv6=on|off][,udp=on|off][,cookie64][,counter][,pincounter][,txcookie=txcookie][,rxcookie=rxcookie][,offset=offset]``
Configure a L2TPv3 pseudowire host network backend. L2TPv3 (RFC3931)
is a popular protocol to transport Ethernet (and other Layer 2) data
--
2.45.2

Signature · 1 line
Marc-André Lureau
#2 lore raw

Hi Marc-André,

thank you for your comments, you're right I should not mix TCP/UDP and unix socket. I'm going to fix that.

Thanks,
Laurent

Quoted 281 lines · Marc-André Lureau

Hi

On Wed, Jun 26, 2024 at 7:53 PM Laurent Vivier <[email protected] <mailto:[email protected]>> wrote:

Add the description of "-netdev stream" and "-netdev dgram" in the QEMU manpage.

Add some examples on how to use them, including a way to use "-netdev stream" and "passt" in place of "-netdev user". ("passt" is a non privileged translation proxy between layer-2, like "-netdev stream", and layer-4 on host, like TCP, UDP, ICMP/ICMPv6 echo)

Fixes 5166fe0ae46d ("qapi: net: add stream and dgram netdevs")
Fixes 13c6be96618c ("net: stream: add unix socket")
Fixes 784e7a253104 ("net: dgram: add unix socket")
Fixes 148fbf0d58a6 ("net: stream: add a new option to automatically reconnect"
Signed-off-by Laurent Vivier <[email protected] <mailto:[email protected]>>

Could be easier to review if this documentation addition is splitted in various patches.

    ---
      qemu-options.hx | 189 ++++++++++++++++++++++++++++++++++++++++++++++++
      1 file changed, 189 insertions(+)

    diff --git a/qemu-options.hx b/qemu-options.hx
    index 8ca7f34ef0c8..b8a1a65f05e7 100644
    --- a/qemu-options.hx
    +++ b/qemu-options.hx
    @@ -3353,6 +3353,195 @@ SRST
                               -device e1000,netdev=n1,mac=52:54:00:12:34:56 \\
                               -netdev socket,id=n1,mcast=239.192.168.1:1102
    <http://239.192.168.1:1102>,localaddr=1.2.3.4

    +``-netdev
    stream,id=str[,server=on|off],addr.type=inet,addr.host=host,addr.port=port[,to=maxport][,numeric=on|off][,keep-alive=on|off][,mptcp=on|off][,addr.ipv4=on|off][,addr.ipv6=on|off][,reconnect=seconds]``
    +    Configure a network backend to connect to another QEMU virtual machine or a proxy
    using a TCP/IP socket.
    +
    +    ``server=on|off``
    +        if ``on`` create a server socket
    +
    +    ``addr.host=host,addr.port=port``
    +        socket address to listen on (server=on) or connect to (server=off)
    +
    +    ``to=maxport``
    +        if present, this is range of possible addresses, with port between ``port``
    and ``maxport``.
    +
    +    ``numeric=on|off``
    +        if ``on`` ``host`` and ``port`` are guaranteed to be numeric, otherwise a
    name resolution should be attempted (default: ``off``)
    +
    +    ``keep-alive=on|off``
    +        enable keep-alive when connecting to this socket.  Not supported for passive
    sockets.
    +
    +    ``mptcp=on|off``
    +        enable multipath TCP
    +
    +    ``ipv4=on|off``
    +        whether to accept IPv4 addresses, default to try both IPv4 and IPv6
    +
    +    ``ipv6=on|off``
    +        whether to accept IPv6 addresses, default to try both IPv4 and IPv6
    +
    +    ``reconnect=seconds``
    +        for a client socket, if a socket is disconnected, then attempt a reconnect
    after the given number of seconds.
    +        Setting this to zero disables this function.  (default: 0)
    +
    +    Example (two guests connected using a TCP/IP socket):
    +
    +    .. parsed-literal::
    +
    +        # first VM
    +        |qemu_system| linux.img \\
    +                      -device virtio-net,netdev=net0,mac=52:54:00:12:34:56 \\
    +                      -netdev
    stream,id=net0,server=on,addr.type=inet,addr.host=localhost,addr.port=1234
    +        # second VM
    +        |qemu_system| linux.img \\
    +                      -device virtio-net,netdev=net0,mac=52:54:00:12:34:57 \\
    +                      -netdev
    stream,id=net0,server=off,addr.type=inet,addr.host=localhost,addr.port=1234,reconnect=5
    +
    +``-netdev
    stream,id=str[,server=on|off],addr.type=unix,addr.path=path[,abstract=on|off][,tight=on|off][,reconnect=seconds]``
    +    Configure a network backend to connect to another QEMU virtual machine or a proxy
    using a TCP/UNIX socket.

 "TCP/UNIX": just UNIX instead?

+
+    ``server=on|off``
+        if ``on`` create a server socket
+
+    ``addr.path=path``
+        filesystem path to use
+
+    ``abstract=on|off``
+        if ``on``, this is a Linux abstract socket address.
+
+    ``tight=on|off``
+        if false, pad an abstract socket address with enough null bytes to make it fill struct sockaddr_un member sun_path.
+
+    ``reconnect=seconds``
+        for a client socket, if a socket is disconnected, then attempt a reconnect after the given number of seconds.
+        Setting this to zero disables this function.  (default: 0)
+
+    Example (using passt as a replacement of -netdev user):
+
+    .. parsed-literal::
+
+        # start passt server as a non privileged user
+        passt
+        UNIX domain socket bound at /tmp/passt_1.socket
+        # start QEMU to connect to passt
+        |qemu_system| linux.img \\
+                      -device virtio-net,netdev=net0 \\
+                      -netdev stream,id=net0,server=off,addr.type=unix,addr.path=/tmp/passt_1.socket +
+    Example (two guests connected using a TCP/UNIX socket):
+

same

    +    .. parsed-literal::
    +
    +        # first VM
    +        |qemu_system| linux.img \\
    +                      -device virtio-net,netdev=net0,mac=52:54:00:12:34:56 \\
    +                      netdev stream,id=net0,server=on,addr.type=unix,addr.path=/tmp/qemu0
    +        # second VM
    +        |qemu_system| linux.img \\
    +                      -device virtio-net,netdev=net0,mac=52:54:00:12:34:57 \\
    +                      -netdev
    stream,id=net0,server=off,addr.type=unix,addr.path=/tmp/qemu0,reconnect=5
    +
    +``-netdev
    stream,id=str[,server=on|off],addr.type=fd,addr.str=file-descriptor[,reconnect=seconds]``
    +    Configure a network backend to connect to another  QEMU  virtual machine or a
    proxy using a TCP socket file descriptor.
    +

I guess it would work with either a TCP or UNIX socket. Perhaps just say "a socket file descriptor" ?

+    ``server=on|off``
+        if ``on`` create a server socket
+
+    ``addr.str=file-descriptor``
+        file descriptor number to use as a socket
+
+    ``reconnect=seconds``
+        for a client socket, if a socket is disconnected, then attempt a reconnect
after the given number of seconds.
+        Setting this to zero disables this function.  (default: 0)
+
+``-netdev dgram,id=str,remote.type=inet,remote.host=maddr,remote.port=port[,local.type=inet,local.host=addr]`` +    Configure a network backend to connect to a multicast address.
+
+    ``remote.host=maddr,remote.port=port``
+        multicast address
+
+    ``local.host=addr``
+        specify the host address to send packets from
+
+    Example:
+
+    .. parsed-literal::
+
+        # launch one QEMU instance
+        |qemu_system| linux.img \\
+                      -device virtio-net,netdev=net0,mac=52:54:00:12:34:56 \\
+                      -netdev
dgram,id=net0,remote.type=inet,remote.host=224.0.0.1,remote.port=1234
+        # launch another QEMU instance on same "bus"
+        |qemu_system| linux.img \\
+                      -device virtio-net,netdev=net0,mac=52:54:00:12:34:57 \\
+                      -netdev
dgram,id=net0,remote.type=inet,remote.host=224.0.0.1,remote.port=1234
+        # launch yet another QEMU instance on same "bus"
+        |qemu_system| linux.img \\
+                      -device virtio-net,netdev=net0,mac=52:54:00:12:34:58 \\
+                      -netdev
dgram,id=net0,remote.type=inet,remote.host=224.0.0.1,remote.port=1234
+
+``-netdev dgram,id=str,remote.type=inet,remote.host=maddr,remote.port=port[,local.type=fd,local.str=file-descriptor]`` +    Configure a network backend to connect to a multicast address using a UDP socket
file descriptor.
+
+    ``remote.host=maddr,remote.port=port``
+        multicast address
+
+    ``local.str=file-descriptor``
+        File descriptor to use to send packets
+
+``-netdev dgram,id=str,local.type=inet,local.host=addr,local.port=port[,remote.type=inet,remote.host=addr,remote.port=port]`` +    Configure a network backend to connect to another QEMU virtual
+    machine or a proxy using an UDP/IP socket.
+
+    ``local.host=addr,local.port=port``
+        IP address to use to send the packets from
+
+    ``remote.host=addr,remote.port=port``
+        Destination IP address
+
+    Example (two guests connected using an UDP/IP socket):
+
+    .. parsed-literal::
+
+        # first VM
+        |qemu_system| linux.img \\
+                      -device virtio-net,netdev=net0,mac=52:54:00:12:34:56 \\
+                      -netdev dgram,id=net0,local.type=inet,local.host=localhost,local.port=1234,remote.type=inet,remote.host=localhost,remote.port=1235 +        # second VM
+        |qemu_system| linux.img \\
+                      -device virtio-net,netdev=net0,mac=52:54:00:12:34:56 \\
+                      -netdev dgram,id=net0,local.type=inet,local.host=localhost,local.port=1235,remote.type=inet,remote.host=localhost,remote.port=1234 +
+``-netdev
dgram,id=str,local.type=unix,local.path=path[,remote.type=unix,remote.path=path]``
+    Configure a network backend to connect to another QEMU virtual
+    machine or a proxy using an UDP/UNIX socket.

Here also, that kind of notation is confusing. What's the use case, since afaik there is no multicast with UNIX socket? Perhaps this shouldn't be allowed at all.

    +
    +    ``local.path=path``
    +        filesystem path to use to bind the socket
    +
    +    ``remote.path=path``
    +        filesystem path to use as a destination (see sendto(2))
    +
    +    Example (two guests connected using an UDP/UNIX socket):
    +
    +    .. parsed-literal::
    +
    +        # first VM
    +        |qemu_system| linux.img \\
    +                      -device virtio-net,netdev=net0,mac=52:54:00:12:34:56 \\
    +                      -netdev
    dgram,id=net0,local.type=unix,local.path=/tmp/qemu0,remote.type=unix,remote.path=/tmp/qemu1
    +        # second VM
    +        |qemu_system| linux.img \\
    +                      -device virtio-net,netdev=net0,mac=52:54:00:12:34:57 \\
    +                      -netdev
    dgram,id=net0,local.type=unix,local.path=/tmp/qemu1,remote.type=unix,remote.path=/tmp/qemu0
    +
    +``-netdev dgram,id=str,local.type=fd,local.str=file-descriptor``
    +    Configure a network backend to connect to another QEMU virtual
    +    machine or a proxy using an UDP socket file descriptor.
    +
    +    ``local.str=file-descriptor``
    +        File descriptor to use to send packets
    +
      ``-netdev
    l2tpv3,id=id,src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport],txsession=txsession[,rxsession=rxsession][,ipv6=on|off][,udp=on|off][,cookie64][,counter][,pincounter][,txcookie=txcookie][,rxcookie=rxcookie][,offset=offset]``
          Configure a L2TPv3 pseudowire host network backend. L2TPv3 (RFC3931)
          is a popular protocol to transport Ethernet (and other Layer 2) data
    -- 
    2.45.2
Signature · 1 line
Marc-André Lureau
#3 lore raw
In reply to Laurent Vivier

Hi

Quoted 9 lines · Laurent Vivier

Add the description of "-netdev stream" and "-netdev dgram" in the QEMU manpage.

Add some examples on how to use them, including a way to use "-netdev stream" and "passt" in place of "-netdev user". ("passt" is a non privileged translation proxy between layer-2, like "-netdev stream", and layer-4 on host, like TCP, UDP, ICMP/ICMPv6 echo)

Was there any plan to have passt fallback (default / "-net passt") when slirp is disabled ? spawning the process with -F fd etc. That would help migrating away from slirp for some systems.

Signature · 1 line
Marc-André Lureau
#4 lore raw
Quoted 7 lines · Marc-André Lureau

Hi

On Wed, Jun 26, 2024 at 7:53 PM Laurent Vivier <[email protected] <mailto:[email protected]>> wrote:

Add the description of "-netdev stream" and "-netdev dgram" in the QEMU manpage.

Quoted 8 lines

Add some examples on how to use them, including a way to use "-netdev stream" and "passt" in place of "-netdev user". ("passt" is a non privileged translation proxy between layer-2, like "-netdev stream", and layer-4 on host, like TCP, UDP, ICMP/ICMPv6 echo)

Was there any plan to have passt fallback (default / "-net passt") when slirp is disabled ? spawning the process with -F fd etc. That would help migrating away from slirp for some systems.

Yes, I'm planning to add a "-netdev passt" that will start passt and connect it to a stream socket to QEMU. Perhaps at some point we can have a "-netdev slirp" and "-netdev user" will us by default passt?

I'm also working on a vhost-user interface for passt that will also improve performance of user mode networking with QEMU.

Thanks,
Laurent