2. EL 6 ELS
  3. vios-proxy-guest
  4. vios-proxy-guest(1)

Scroll to navigation

vios-proxy-guest(1) vios-proxy-guest vios-proxy-guest(1)

VIOS-PROXY-GUEST

vios-proxy-guest is the QEMU-guest process of a network proxy between a QEMU host and QEMU guests.

SYNOPSIS

vios-proxy-guest [-h | --help] [host_directory [service_port [log_level]]]

DESCRIPTION

In a QEMU system, processes in the host need to communicate with processes in guests even when there is no network configured between the host and the guests. Vios-proxy is a network proxy framework that uses virtioserial channels as the communications pipeline between the host and the guests.

Virtioserial comprises host device emulation, virtio-pci devices, and drivers that provide a chardev interface between the QEMU host and a QEMU guest. A single virtioserial channel appears to application software as a domain socket path name in the QEMU host and a file handle path name in the QEMU guest.

Learn more about virtioserial at <http://fedoraproject.org/wiki/Features/VirtioSerial>

vios-proxy-guest is a process that runs on the QEMU guest. It opens a network socket and listens for connection requests from QEMU guest clients. Upon accepting a client connection vios-proxy-guest finds a free virtioserial channel and begins negotiating with the QEMU host for a proxy connection. After the connection is accepted by the QEMU host vios-proxy-guest relays data between the service socket to the client and the virtioserial channel going to the host.

vios-proxy-guest is configured with a host_directory path name and a service_port port number.

  • The host_directory path name identifies a single directory that holds virtioserial end points for channels to the host.
  • The service_port port number is the localhost port opened by vios-proxy-guest for the host service that is being proxied. Note that service_port port number is not necessarily the same as the port number of the actual service on the QEMU host.

Only one instance of vios-proxy-guest is allowed per proxied network service.

System administrators may run multiple instances of vios-proxy-guest, each configured to provide proxy service for different host services.

vios-proxy-guest assumes exclusive ownership of all virtioserial channels in the host_directory path. If multiple instances of vios-proxy-guest are run then they must not share host_directory path names.

Virtioserial connections are typically created synchronously with the creation of the QEMU guest VM. vios-proxy-guest does not create virtioserial connections. If virtioserial connections are created or destroyed dynamically by some other QEMU agent then vios-proxy-guest will recognize the action and use or stop using the channels accordingly.

OPTIONS

display a short help text
[ host_directory
find virtioserial end points in host_directory instead of /dev/virtio-ports
[ service_port
listen for localhost connections on service_port instead of 5672
[ log_level ] ] ]
enable logging for given level instead of INFO. Log level choices are FATAL, ALERT, ERROR, WARN, NOTICE, INFO, and DEBUG

RETURN VALUE

    0 Success
    1 Failure

DIAGNOSTICS

FATAL - Illegal port number specified on command line.
FATAL - Cannot create network socket.
FATAL - Cannot set network socket to nonblocking.
FATAL - Cannot set network socket to nonblocking.
FATAL - Cannot bind to network socket.
FATAL - Cannot listen to network socket.
FATAL - The command line host_directory is not accessable.
FATAL - The command line host_directory is not a directory.
FATAL - The command line host_directory can not be opened.
ERROR - Error accessing host file handle
ERROR - Error accessing host file handle
FATAL - Poller error.

EXAMPLES

Configuring QEMU Host and Guest with Virtioserial Ports

 #!/bin/sh
 #
 # Define a common root directory for broker-side channels to guests.
 #
 QB_ROOT="/tmp/qpid"
 #
 # Launch some number of guests in a loop.
 #   On the host the channels to the first guest shall be
 #      /tmp/qpid/guest1/0
 #      /tmp/qpid/guest1/1
 #      /tmp/qpid/guest1/2
 #   Successive guests increment guest1 to guest2, guest3, and so on.
 #
 #   On the guest the channels to the host shall be
 #      /dev/virtio-ports/qpid.0
 #      /dev/virtio-ports/qpid.1
 #      /dev/virtio-ports/qpid.2
 #   The guest-to-host channel names are the same for all guests.
 #   
 #
 for gNameSeq in `seq 1 2`
 do
     G_NAME="guest"$gNameSeq
     mkdir -p ${QB_ROOT}/${G_NAME}
     qemu-kvm -name "${G_NAME}" -m 192M -smp 2 -snapshot ~chug/v/images/v14a.img \
        -device virtio-serial \
        -chardev socket,path=${QB_ROOT}/${G_NAME}/0,server,nowait,id=${G_NAME}_0 \
        -chardev socket,path=${QB_ROOT}/${G_NAME}/1,server,nowait,id=${G_NAME}_1 \
        -chardev socket,path=${QB_ROOT}/${G_NAME}/2,server,nowait,id=${G_NAME}_2 \
        -device virtserialport,chardev=${G_NAME}_0,name=qpid.0 \
        -device virtserialport,chardev=${G_NAME}_1,name=qpid.1 \
        -device virtserialport,chardev=${G_NAME}_2,name=qpid.2 \
        &
     PID=$!
     echo "QEMU ${G_NAME} PID = $PID"
 done

Launching vios-proxy-guest

vios-proxy-guest /dev/red-service 6677
vios-proxy-guest /dev/green-service 7766 ALERT

BUGS

RESTRICTIONS

Data traffic between the QEMU host and QEMU guest across a virtioserial channel is limited to one connection at a time. The number of configured virtioserial channels between the QEMU host and each QEMU guest is the maximum number of simultaneous connections the QEMU guest may have to the proxied service.

NOTES

SEE ALSO

AUTHOR

Chuck Rolke <crolke@redhat.com>.

COPYRIGHT AND LICENSE

Copyright 2011 by Chuck Rolke <crolke@redhat.com>.

 Licensed to the Apache Software Foundation (ASF) under one
 or more contributor license agreements.  See the NOTICE file
 distributed with this work for additional information
 regarding copyright ownership.  The ASF licenses this file
 to you under the Apache License, Version 2.0 (the
 "License"); you may not use this file except in compliance
 with the License.  You may obtain a copy of the License at
   http://www.apache.org/licenses/LICENSE-2.0
 Unless required by applicable law or agreed to in writing,
 software distributed under the License is distributed on an
 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.
0.1 perl v5.12.4