| Message ID | 20240626155140.74752-1-lvivier@redhat.com |
|---|---|
| State | New |
| Headers | show |
| Series | net: update netdev stream/dgram man page | expand |
Hi On Wed, Jun 26, 2024 at 7:53 PM Laurent Vivier <lvivier@redhat.com> 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 <lvivier@redhat.com> > 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 > ,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 > > >
Hi On Wed, Jun 26, 2024 at 7:53 PM Laurent Vivier <lvivier@redhat.com> 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) > 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.
On 02/07/2024 10:08, Marc-André Lureau wrote: > Hi > > On Wed, Jun 26, 2024 at 7:53 PM Laurent Vivier <lvivier@redhat.com > <mailto:lvivier@redhat.com>> 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) > > > 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
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 On 02/07/2024 09:39, Marc-André Lureau wrote: > Hi > > On Wed, Jun 26, 2024 at 7:53 PM Laurent Vivier <lvivier@redhat.com > <mailto:lvivier@redhat.com>> 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 <lvivier@redhat.com <mailto:lvivier@redhat.com>> > > > 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 > > > > > -- > Marc-André Lureau
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,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
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 <lvivier@redhat.com> --- qemu-options.hx | 189 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 189 insertions(+)