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

Scroll to navigation

vios-proxy-host(1) vios-proxy-host vios-proxy-host(1)

VIOS-PROXY-HOST

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

SYNOPSIS

vios-proxy-host [-h | --help] [guest_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-host is a process that runs on the QEMU host. It opens a series of virtioserial channels and listens for connection requests from the peer vios-proxy-guest processes in the QEMU guests. During connection negotiation with a guest, vios-proxy-host opens a network socket to the service in the QEMU host and relays data between the service socket on the host to the virtioserial channel going to the guest.

vios-proxy-host is configured with a guest_directory path name and a service_port port number.

•
The guest_directory path name identifies a directory that holds subdirectories where each subdirectory holds virtioserial end points for a given virtual guest.
•
Note that having the guest endpoints in separate directories is only a convenience for system management. Separate directories make the system easier to specify, examine, maintain, and diagnose. There is no functional requirement for virtioserial guest endpoints to be in separate subdirectories.
•
The service_port port number is the localhost port for the host service that is being proxied to the guests.

Only one instance of vios-proxy-host is required per proxied network service. This instance will proxy any number of virtioserial channels to any number of QEMU guests as long as the guest virtioserial channel end points are configured to be in the guest_directory tree.

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

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

A sysetm administrator may run several instances of vios-proxy-host to proxy the same network service service_port as long as each instance has a different guest_directory path.

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

OPTIONS

display a short help text
[ guest_directory
find guest subdirectories in guest_directory instead of /tmp/qpid
[ service_port
proxy given 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 - The command line guest_directory is not accessable.
FATAL - The command line guest_directory is not a directory.
FATAL - The command line guest_directory can not be opened.
FATAL - Poller error.
WARNING - A subdirectory of the command line guest_directory is not accessible. This directory will not be processed.
WARNING - A subdirectory of the command line guest_directory is not a directory. This directory will not be processed.
WARNING - A subdirectory of the command line guest_directory can not be opened. This directory will not be processed.

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-host

vios-proxy-host /var/vios/red-service-root 6677
vios-proxy-host /var/vios/green-service-root 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