aboutgitcodebugslistschat
path: root/qrap.1
blob: 98cc877b3d20af3532cc9ef8107ac4f0f39e2f60 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
.\" SPDX-License-Identifier: GPL-2.0-or-later
.\" Copyright (c) 2020-2021 Red Hat GmbH
.\" Author: Stefano Brivio <sbrivio@redhat.com>
.TH qrap 1

.SH NAME
.B qrap
\- temporary qemu wrapper connecting UNIX domain socket to file descriptor

.SH SYNOPSIS
.B qrap
[\fIFDNUM\fR \fIQEMU_CMD\fR] [\fIQEMU_ARG\fR]...
.SH DESCRIPTION
\fBqrap\fR is a wrapper, designed specifically for usage with \fBqemu\fR(1) and
\fBpasst\fR(1), connecting a UNIX domain socket to a file descriptor, and
running \fBqemu\fR(1) with given arguments.

A running instance of \fBpasst\fR(1) is probed checking for UNIX domain sockets,
answering a dummy ARP request, with names starting from
\fI/tmp/passt_1.socket\fR up to \fI/tmp/passt_64.socket\fR.

If first and second arguments are not a socket number and a command, that is,
respectively, \fIFDNUM\fR and \fIQEMU_CMD\fR, \fBqrap\fR will try to locate a
qemu executable in \fBPATH\fR and patch the command line to specify a network
device and a \fInetdev\fR back-end for usage with \fBpasst\fR(1).

If \fBqrap\fR patches the command line, it will remove any potentially
conflicting network device, that is, any \fI-netdev\fR or \fI-net\fR option, or
any \fI-device\fR option with argument starting with \fIvirtio-net-pci,\fR,
\fIvirtio-net-ccw,\fR, \fIe1000,\fR, \fIe1000e,\fR, or \fIrtl8139,\fR.

.SH EXAMPLES

.BR "Start qemu explicitly passing its command name and a socket number"
.RS
.nf
$ ./qrap 5 kvm test.qcow2 -m 1024 -display none -nodefaults -nographic -net socket,fd=5 -net nic,model=virtio
.fi
.RE

.BR "Start qemu without command name and socket number, patching arguments"
.RS
.nf
$ ./qrap test.qcow2 -m 1024 -display none -nodefaults -nographic
.fi
.RE

.SH NOTES

This wrapper is temporary: qemu commit 13c6be96618c ("net: stream: add unix
socket") introduces native AF_UNIX socket support, and it should be included in
qemu starting from the 7.2 release. It will be around for a little bit longer to
give users enough time to switch.

.SH AUTHOR

Stefano Brivio <sbrivio@redhat.com>

.SH REPORTING BUGS

No public bug tracker is available at this time. For the moment being, report
issues to Stefano Brivio <sbrivio@redhat.com>.

.SH COPYRIGHT

Copyright (c) 2020-2021 Red Hat GmbH.

\fBqrap\fR is free software: you can redistribute is 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. 

.SH SEE ALSO

\fBqemu\fR(1), \fBpasst\fR(1).

High-level documentation is available at https://passt.top/passt/about/.