vios-proxy-commits October 2011

vios-proxy-commits@lists.stg.fedorahosted.org

2 participants
2 discussions

[vios-proxy] install manpages, update specfile
by Nuno Santos 18 Oct '11

18 Oct '11

commit fec66af136cabbd50b28f74be34e9d3a0a082bda Author: Nuno Santos <nsantos(a)redhat.com> Date: Tue Oct 18 14:16:32 2011 -0400 install manpages, update specfile src/CMakeLists.txt | 2 ++ src/rpm-spec/vios-proxy.spec | 24 +++++++++++++++++++++--- 2 files changed, 23 insertions(+), 3 deletions(-) --- diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt index eedd5d6..b7636fa 100644 --- a/src/CMakeLists.txt +++ b/src/CMakeLists.txt @@ -58,3 +58,5 @@ INSTALL(TARGETS vios_proxy_guest DESTINATION bin) add_subdirectory(test) + +INSTALL(FILES ../doc/man/vios-proxy-host.1.gz ../doc/man/vios-proxy-guest.1.gz DESTINATION share/man/man1) diff --git a/src/rpm-spec/vios-proxy.spec b/src/rpm-spec/vios-proxy.spec index 541199d..81563fb 100644 --- a/src/rpm-spec/vios-proxy.spec +++ b/src/rpm-spec/vios-proxy.spec @@ -1,5 +1,5 @@ Name: vios-proxy -Version: 0.1 +Version: 0.2 Release: 1%{?dist} Summary: Network proxy between a QEMU host and QEMU guests using virtioserial channels @@ -44,6 +44,18 @@ creates a listening network socket on the guest's localhost interface. When client programs connect to this socket then the vios-proxy-guest daemon opens a proxy channel to the host through the tunnel. +%package doc + +Summary: Documentation for vios-proxy +Group: System Environment/Daemons + +%description doc +The vios-proxy program suite creates a network tunnel between +a server in the QEMU host and a client in a QEMU guest. +The proxy server and client programs open normal TCP network +ports on localhost and the vios-proxy tunnel connects them using +QEMU virtioserial channels. + %prep %setup -q pushd src @@ -65,18 +77,24 @@ popd rm -rf $RPM_BUILD_ROOT -%files +%files doc %defattr(-,root,root,-) -%doc +%doc README.txt LICENSE NOTICE +%doc doc/ %files host %defattr(-,root,root,-) %{_bindir}/vios-proxy-host +%doc %{_mandir}/man1/vios-proxy-host.1.gz %files guest %defattr(-,root,root,-) %{_bindir}/vios-proxy-guest +%doc %{_mandir}/man1/vios-proxy-guest.1.gz %changelog +* Tue Oct 18 2011 Nuno Santos <nsantos(a)redhat.com> - 0.2-1 +- Added man pages + * Mon Sep 19 2011 Chuck Rolke <crolke(a)redhat.com> 0.1-1 - Initial revision

1 0

[vios-proxy] Add man pages.
by chug 11 Oct '11

11 Oct '11

commit a6aadf21fef6c6ebf6e6ec24a201977b01c0ef83 Author: Chuck Rolke <crolke(a)redhat.com> Date: Tue Oct 11 14:29:23 2011 -0400 Add man pages. man/src/ holds two .pod files and a make script. They produce two .1.gz files in man/ that are checked in. doc/man/src/make-man-pages.sh | 12 ++ doc/man/src/vios-proxy-guest.pod | 277 ++++++++++++++++++++++++++++++++++++++ doc/man/src/vios-proxy-host.pod | 274 +++++++++++++++++++++++++++++++++++++ doc/man/vios-proxy-guest.1.gz | Bin 0 -> 4688 bytes doc/man/vios-proxy-host.1.gz | Bin 0 -> 4745 bytes 5 files changed, 563 insertions(+), 0 deletions(-) --- diff --git a/doc/man/src/make-man-pages.sh b/doc/man/src/make-man-pages.sh new file mode 100755 index 0000000..152a87a --- /dev/null +++ b/doc/man/src/make-man-pages.sh @@ -0,0 +1,12 @@ +#!/bin/bash +# +# Compile .pod files into .1.gz files in parent directory. +# From there an install script can move them to /usr/share/man/man1 +# +pod2man -c vios-proxy-host -n vios-proxy-host -d 0.1 vios-proxy-host.pod > vios-proxy-host.1 +pod2man -c vios-proxy-guest -n vios-proxy-guest -d 0.1 vios-proxy-guest.pod > vios-proxy-guest.1 + +gzip vios-proxy-host.1 +gzip vios-proxy-guest.1 + +mv *.1.gz ../ \ No newline at end of file diff --git a/doc/man/src/vios-proxy-guest.pod b/doc/man/src/vios-proxy-guest.pod new file mode 100644 index 0000000..17a0245 --- /dev/null +++ b/doc/man/src/vios-proxy-guest.pod @@ -0,0 +1,277 @@ +=head1 VIOS-PROXY-GUEST + +B<vios-proxy-guest> is the QEMU-guest process +of a network proxy between a QEMU host and QEMU guests. + +=head1 SYNOPSIS + +B<vios-proxy-guest> B<[>I<-h> | I<--help>B<]> B<[>I<host_directory> B<[>I<service_port> B<[>I<log_level>B<]]]> + +=head1 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. + +=over 4 + +=item Virtioserial overview + +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 L<http://fedoraproject.org/wiki/Features/VirtioSerial> + +=back + +B<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 B<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 B<vios-proxy-guest> relays data between the service socket +to the client and the virtioserial channel going to the host. + +B<vios-proxy-guest> is configured with a I<host_directory> path name and a I<service_port> +port number. + +=over 4 + +=item + +The I<host_directory> path name +identifies a single directory that holds virtioserial end points for channels to the host. + +=item + +The +I<service_port> port number is the localhost port opened by B<vios-proxy-guest> +for the host service that is being proxied. Note that I<service_port> port number +is not necessarily the same as the port number of the actual service on the QEMU host. + +=back + +Only one instance of B<vios-proxy-guest> is allowed per proxied network service. + +System administrators may run multiple instances +of B<vios-proxy-guest>, each configured to provide proxy service for different host services. + +B<vios-proxy-guest> assumes exclusive ownership of all virtioserial channels +in the I<host_directory> path. If multiple instances of B<vios-proxy-guest> are +run then they must not share I<host_directory> path names. + +Virtioserial connections are typically created synchronously with the +creation of the QEMU guest VM. +B<vios-proxy-guest> does not create virtioserial connections. If +virtioserial connections are created or destroyed dynamically by some other +QEMU agent then B<vios-proxy-guest> will recognize the action and use +or stop using the channels accordingly. + +=head1 OPTIONS + +=over 4 + +=item B<-h | --help> + +display a short help text + +=item B<[ host_directory> + +find virtioserial end points in host_directory instead of F</dev/virtio-ports> + +=item B<[ service_port> + +listen for localhost connections on service_port instead of 5672 + +=item B<[ log_level ] ] ]> + +enable logging for given level instead of INFO. Log level choices are FATAL, ALERT, ERROR, WARN, NOTICE, INFO, and DEBUG + +=back + +=head1 RETURN VALUE + + 0 Success + 1 Failure + +=head1 DIAGNOSTICS + +=over 4 + +=item + Specify listen port in range 1..65535 + +FATAL - Illegal port number specified on command line. + +=item + Failed to create proxy service: + +FATAL - Cannot create network socket. + +=item + Proxy service fcntl(F_GETFL): + +FATAL - Cannot set network socket to nonblocking. + +=item + Proxy service fcntl(F_SETFL): + +FATAL - Cannot set network socket to nonblocking. + +=item + Proxy service bind: + +FATAL - Cannot bind to network socket. + +=item + Proxy service listen: + +FATAL - Cannot listen to network socket. + +=item + Root path stat fail: + +FATAL - The command line host_directory is not accessable. + +=item + Root path is not a directory + +FATAL - The command line host_directory is not a directory. + +=item + Root path open error + +FATAL - The command line host_directory can not be opened. + +=item + fcntl(F_GETFL) on host channel: + +ERROR - Error accessing host file handle + +=item + fcntl(F_SETFL) on host channel + +ERROR - Error accessing host file handle + +=item + poll() + +FATAL - Poller error. + +=back + +=head1 EXAMPLES + +=head2 Configuring QEMU Host and Guest with Virtioserial Ports + +=over 4 + +=item +This script launches two guest VMs. Each guest VM has three virtiserial 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 + + +=back + +=head2 Launching vios-proxy-guest + +=over 4 + +=item Specifying a directory and port + +B<vios-proxy-guest> F</dev/red-service> 6677 + +=item Specifying a directory, a port, and a log level + +B<vios-proxy-guest> F</dev/green-service> 7766 ALERT + +=back + +=head1 BUGS + +=head1 RESTRICTIONS + +=over 4 + +=item Each virtioserial channel carries only one proxy connection. + +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. + +=back + +=head1 NOTES + +=head1 SEE ALSO + +=over 4 + +=item vios-proxy-host + +=back + +=head1 AUTHOR + +Chuck Rolke <crolke(a)redhat.com>. + +=head1 COPYRIGHT AND LICENSE + +Copyright 2011 by Chuck Rolke <crolke(a)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. + diff --git a/doc/man/src/vios-proxy-host.pod b/doc/man/src/vios-proxy-host.pod new file mode 100644 index 0000000..dec8622 --- /dev/null +++ b/doc/man/src/vios-proxy-host.pod @@ -0,0 +1,274 @@ +=head1 VIOS-PROXY-HOST + +B<vios-proxy-host> is the QEMU-host process +of a network proxy between a QEMU host and QEMU guests. + +=head1 SYNOPSIS + +B<vios-proxy-host> B<[>I<-h> | I<--help>B<]> B<[>I<guest_directory> B<[>I<service_port> B<[>I<log_level>B<]]]> + +=head1 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. + +=over 4 + +=item Virtioserial overview + +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 L<http://fedoraproject.org/wiki/Features/VirtioSerial> + +=back + +B<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, B<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. + +B<vios-proxy-host> is configured with a I<guest_directory> path name and a I<service_port> +port number. + +=over 4 + +=item + +The I<guest_directory> path name +identifies a directory that holds subdirectories where each subdirectory +holds virtioserial end points for a given virtual guest. + +=over 4 + +=item + +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. + +=back + +=item + +The +I<service_port> port number is the localhost port for the host service that is being proxied +to the guests. + +=back + +Only one instance of B<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 I<guest_directory> tree. + +System administrators may run multiple instances +of B<vios-proxy-host>, each configured to provide proxy service for different host services. + +B<vios-proxy-host> assumes exclusive ownership of all virtioserial channels +in the I<guest_directory> path. If multiple instances of B<vios-proxy-host> are +run then they must not share I<guest_directory> path names. + +A sysetm administrator may run several instances of B<vios-proxy-host> to proxy +the same network service I<service_port> as long as each instance has a +different I<guest_directory> path. + +Virtioserial connections are typically created synchronously with the +creation of the QEMU guest VM. +B<vios-proxy-host> does not create virtioserial connections. If +virtioserial connections are created or destroyed dynamically by some other +QEMU agent then B<vios-proxy-host> will recognize the action and use +or stop using the channels accordingly. + +=head1 OPTIONS + +=over 4 + +=item B<-h | --help> + +display a short help text + +=item B<[ guest_directory> + +find guest subdirectories in guest_directory instead of F</tmp/qpid> + +=item B<[ service_port> + +proxy given service_port instead of 5672 + +=item B<[ log_level ] ] ]> + +enable logging for given level instead of INFO. Log level choices are FATAL, ALERT, ERROR, WARN, NOTICE, INFO, and DEBUG + +=back + +=head1 RETURN VALUE + + 0 Success + 1 Failure + +=head1 DIAGNOSTICS + +=over 4 + +=item + Error accessing guest path + +FATAL - The command line guest_directory is not accessable. + +=item + Guest path is not a directory + +FATAL - The command line guest_directory is not a directory. + + +=item + Guest path open error + +FATAL - The command line guest_directory can not be opened. + +=item + poll() + +FATAL - Poller error. + +=item + Error accessing guest root path + +WARNING - A subdirectory of the command line guest_directory is not accessible. +This directory will not be processed. + +=item + Guest root path is not a directory + +WARNING - A subdirectory of the command line guest_directory is not a directory. +This directory will not be processed. + +=item + Guest root path open error + +WARNING - A subdirectory of the command line guest_directory can not be opened. +This directory will not be processed. + +=back + +=head1 EXAMPLES + +=head2 Configuring QEMU Host and Guest with Virtioserial Ports + +=over 4 + +=item +This script launches two guest VMs. Each guest VM has three virtiserial 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 + + +=back + +=head2 Launching vios-proxy-host + +=over 4 + +=item Specifying a directory and port + +B<vios-proxy-host> F</var/vios/red-service-root> 6677 + +=item Specifying a directory, a port, and a log level + +B<vios-proxy-host> F</var/vios/green-service-root> 7766 ALERT + +=back + +=head1 BUGS + +=head1 RESTRICTIONS + +=over 4 + +=item Each virtioserial channel carries only one proxy connection. + +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. + +=back + +=head1 NOTES + +=head1 SEE ALSO + +=over 4 + +=item vios-proxy-guest + +=back + +=head1 AUTHOR + +Chuck Rolke <crolke(a)redhat.com>. + +=head1 COPYRIGHT AND LICENSE + +Copyright 2011 by Chuck Rolke <crolke(a)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. + diff --git a/doc/man/vios-proxy-guest.1.gz b/doc/man/vios-proxy-guest.1.gz new file mode 100644 index 0000000..9fea377 Binary files /dev/null and b/doc/man/vios-proxy-guest.1.gz differ diff --git a/doc/man/vios-proxy-host.1.gz b/doc/man/vios-proxy-host.1.gz new file mode 100644 index 0000000..5feca41 Binary files /dev/null and b/doc/man/vios-proxy-host.1.gz differ

1 0

2025

2024

2023

2022

2021

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011

vios-proxy-commits October 2011