1vios-proxy-guest(1) vios-proxy-guest vios-proxy-guest(1)
2
6 vios-proxy-guest is the QEMU-guest process of a network proxy between a
7 QEMU host and QEMU guests.
8
10 vios-proxy-guest [-h | --help] [host_directory [service_port
11 [log_level]]]
12
14 In a QEMU system, processes in the host need to communicate with
15 processes in guests even when there is no network configured between
16 the host and the guests. Vios-proxy is a network proxy framework that
17 uses virtioserial channels as the communications pipeline between the
18 host and the guests.
19 Virtioserial overview
21 Virtioserial comprises host device emulation, virtio-pci devices,
22 and drivers that provide a chardev interface between the QEMU host
23 and a QEMU guest. A single virtioserial channel appears to
24 application software as a domain socket path name in the QEMU host
25 and a file handle path name in the QEMU guest.
26 Learn more about virtioserial at
28 <http://fedoraproject.org/wiki/Features/VirtioSerial>
29 vios-proxy-guest is a process that runs on the QEMU guest. It opens a
31 network socket and listens for connection requests from QEMU guest
32 clients. Upon accepting a client connection vios-proxy-guest finds a
33 free virtioserial channel and begins negotiating with the QEMU host for
34 a proxy connection. After the connection is accepted by the QEMU host
35 vios-proxy-guest relays data between the service socket to the client
36 and the virtioserial channel going to the host.
37 vios-proxy-guest is configured with a host_directory path name and a
39 service_port port number.
40 · The host_directory path name identifies a single directory that
42 holds virtioserial end points for channels to the host.
43 · The service_port port number is the localhost port opened by vios-
45 proxy-guest for the host service that is being proxied. Note that
46 service_port port number is not necessarily the same as the port
47 number of the actual service on the QEMU host.
48 Only one instance of vios-proxy-guest is allowed per proxied network
50 service.
51 System administrators may run multiple instances of vios-proxy-guest,
53 each configured to provide proxy service for different host services.
54 vios-proxy-guest assumes exclusive ownership of all virtioserial
56 channels in the host_directory path. If multiple instances of vios-
57 proxy-guest are run then they must not share host_directory path names.
58 Virtioserial connections are typically created synchronously with the
60 creation of the QEMU guest VM. vios-proxy-guest does not create
61 virtioserial connections. If virtioserial connections are created or
62 destroyed dynamically by some other QEMU agent then vios-proxy-guest
63 will recognize the action and use or stop using the channels
64 accordingly.
65
67 -h | --help
68 display a short help text
69 [ host_directory
71 find virtioserial end points in host_directory instead of
72 /dev/virtio-ports
73 [ service_port
75 listen for localhost connections on service_port instead of 5672
76 [ log_level ] ] ]
78 enable logging for given level instead of INFO. Log level choices
79 are FATAL, ALERT, ERROR, WARN, NOTICE, INFO, and DEBUG
80
82 0 Success
83 1 Failure
84
86 Specify listen port in range 1..65535
87 FATAL - Illegal port number specified on command line.
88 Failed to create proxy service:
90 FATAL - Cannot create network socket.
91 Proxy service fcntl(F_GETFL):
93 FATAL - Cannot set network socket to nonblocking.
94 Proxy service fcntl(F_SETFL):
96 FATAL - Cannot set network socket to nonblocking.
97 Proxy service bind:
99 FATAL - Cannot bind to network socket.
100 Proxy service listen:
102 FATAL - Cannot listen to network socket.
103 Root path stat fail:
105 FATAL - The command line host_directory is not accessable.
106 Root path is not a directory
108 FATAL - The command line host_directory is not a directory.
109 Root path open error
111 FATAL - The command line host_directory can not be opened.
112 fcntl(F_GETFL) on host channel:
114 ERROR - Error accessing host file handle
115 fcntl(F_SETFL) on host channel
117 ERROR - Error accessing host file handle
118 poll()
120 FATAL - Poller error.
121
123 Configuring QEMU Host and Guest with Virtioserial Ports
124 This script launches two guest VMs. Each guest VM has three
125 virtiserial ports.
126 #!/bin/sh
127 #
128 # Define a common root directory for broker-side channels to guests.
129 #
130 QB_ROOT="/tmp/qpid"
131 #
132 # Launch some number of guests in a loop.
133 # On the host the channels to the first guest shall be
134 # /tmp/qpid/guest1/0
135 # /tmp/qpid/guest1/1
136 # /tmp/qpid/guest1/2
137 # Successive guests increment guest1 to guest2, guest3, and so on.
138 #
139 # On the guest the channels to the host shall be
140 # /dev/virtio-ports/qpid.0
141 # /dev/virtio-ports/qpid.1
142 # /dev/virtio-ports/qpid.2
143 # The guest-to-host channel names are the same for all guests.
144 #
145 #
146 for gNameSeq in `seq 1 2`
147 do
148 G_NAME="guest"$gNameSeq
149 mkdir -p ${QB_ROOT}/${G_NAME}
150 qemu-kvm -name "${G_NAME}" -m 192M -smp 2 -snapshot ~chug/v/images/v14a.img \
151 -device virtio-serial \
152 -chardev socket,path=${QB_ROOT}/${G_NAME}/0,server,nowait,id=${G_NAME}_0 \
153 -chardev socket,path=${QB_ROOT}/${G_NAME}/1,server,nowait,id=${G_NAME}_1 \
154 -chardev socket,path=${QB_ROOT}/${G_NAME}/2,server,nowait,id=${G_NAME}_2 \
155 -device virtserialport,chardev=${G_NAME}_0,name=qpid.0 \
156 -device virtserialport,chardev=${G_NAME}_1,name=qpid.1 \
157 -device virtserialport,chardev=${G_NAME}_2,name=qpid.2 \
158 &
159 PID=$!
160 echo "QEMU ${G_NAME} PID = $PID"
161 done
162 Launching vios-proxy-guest
164 Specifying a directory and port
165 vios-proxy-guest /dev/red-service 6677
166 Specifying a directory, a port, and a log level
168 vios-proxy-guest /dev/green-service 7766 ALERT
169
172 Each virtioserial channel carries only one proxy connection.
173 Data traffic between the QEMU host and QEMU guest across a
174 virtioserial channel is limited to one connection at a time. The
175 number of configured virtioserial channels between the QEMU host
176 and each QEMU guest is the maximum number of simultaneous
177 connections the QEMU guest may have to the proxied service.
178
181 vios-proxy-host
182
184 Chuck Rolke <crolke@redhat.com>.
185
187 Copyright 2011 by Chuck Rolke <crolke@redhat.com>.
188 Licensed to the Apache Software Foundation (ASF) under one
190 or more contributor license agreements. See the NOTICE file
191 distributed with this work for additional information
192 regarding copyright ownership. The ASF licenses this file
193 to you under the Apache License, Version 2.0 (the
194 "License"); you may not use this file except in compliance
195 with the License. You may obtain a copy of the License at
196 http://www.apache.org/licenses/LICENSE-2.0
198 Unless required by applicable law or agreed to in writing,
200 software distributed under the License is distributed on an
201 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
202 KIND, either express or implied. See the License for the
203 specific language governing permissions and limitations
204 under the License.
205perl v5.12.4 0.1 vios-proxy-guest(1)