ovirt-imageio-proxy
===================

Overview
--------

The oVirt ImageIO Proxy provides a proxy server allowing clients to
perform I/O with VM disk images and ISOs located within the oVirt
virtualization environment.

The proxy provides the following service:

- images service    read and write data to/from the imageio daemon.
                    By default this service is available via HTTPS
                    on port 54323.  This service is accessed by
                    clients wishing to transfer data to/from images
                    that do not wish to transfer directly via the
                    daemon.


Image Session Flow (via Engine WebAdmin)
----------------------------------------

This illustrates the role the proxy plays in a typical image upload
operation.  The client is the Engine UI via a browser.

- Client initiates an upload via the UI.
- Engine creates an access token for ovirt-imageio-proxy and a
  session token for ovirt-image-daemon.
- Engine asks Vdsm to prepare the image.
- Engine asks Vdsm to add a ticket allowing access to the image.
- Vdsm adds the ticket to ovirt-imageio-daemon.
- Engine returns the signed access token and ovirt-imageio-proxy
  connection info to the client.  The access token contains the
  session token and image ovirt-imageio-daemon connection details.
- Client authenticates with ovirt-imageio-proxy using the signed
  access token.
- ovirt-imageio-proxy decodes and verifies the signed token, creates
  a session, and stores the token contents in the session state.
- ovirt-imageio-proxy returns the session id to the client.
- Client performs image operations with ovirt-imageio-proxy, using
  the ovirt-imageio-daemon session token and ovirt-imageio-proxy
  session id.
- ovirt-imageio-proxy relays image operations to ovirt-imageio-daemon
  using the session token.
- When the client is done, it asks Engine to finalize the operation.
- Engine ask vdsm to revoke the ticket.
- Vdsm deletes session from ovirt-imageio-daemon.
- Engine ask vdsm to tear down the image.
- Image verification and other necessary finalization actions
  involving Vdsm and Engine are performed.

Tickets are ephemeral; a client needs to ask Engine to renew the
ticket from time to time, otherwise a ticket will expire and the
ongoing image operations will be aborted.

Tickets are not persisted.  In case of an ovirt-imageio-proxy crash
or reboot, Engine will provide a new ticket and possibly point the
client to another host to continue the operation.


Installation
------------

The image proxy can be installed on most hosts that have a working
Python 2 environment with the needed dependencies.  To install the
rpm package:

  sudo yum install ovirt-imageio-proxy
  engine-setup

This will install all necessary dependencies and launch the setup,
which is a module run by the oVirt engine setup program.  The prompts
during setup depend on other installed packages; if ovirt-engine is
on the host you may be prompted with additional questions.  On a
separate host, you will be prompted to perform manual steps for the
PKI setup.

Installation from source is not recommended.  If you want to run the
proxy without installing the packages and runing engine-setup, it's
best to run it in-place using the --config_file option to supply the
runtime configuration.


Installation with ovirt-engine developer environment
======================================================
For setting up ovirt-imageio-proxy in an ovirt dev environment, run:

  make
  make install-dev ENGINE_PREFIX=<engine prefix>

Example:

   make install-dev ENGINE_PREFIX=/home/user/my-ovirt-engine

If ovirt-imageio-proxy wasn't configured yet, run engine setup, and 
choose "Yes" when prompted to install oVirt ImageIO proxy. After engine 
setup finishes to run, run `ovirt-imageio-proxy`.


SSL installation
----------------

For using imageIO via the webadmin, the client will need to install
oVirt's CA in its browser. oVirt's CA certificate can be fetched from
the following link, as specified in oVirt's PKI wiki page
http://www.ovirt.org/develop/release-management/features/infra/pki/:

http://<engine_url>/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA


SSL keys in imageIO
-------------------

In order to securly cooperate with the webadmin and
ovirt-imageio-daemon, ovirt-imageio-proxy is using SSL keys which
are managed by the engine. some of which are created specially for
ovirt-imageio service, and some are being used internally by the
engine. The keys paths are configured in
/etc/ovirt-imageio-proxy/ovirt-imageio-proxy.conf, and each is used
as followed:

* keys/image-proxy.key.nopass:

	The private key of the ovirt-imageio-proxy service which is
	used to implement the SSL server.
	This key is generated by engine-setup.

* certs/image-proxy.cer:

	The public key of ovirt-imageio-proxy service which is also
        used to implement the SSL server. This certificate is signed
	by the engine's CA, which is what makes the webadmin trust
	this server (as long as the engine's CA is registered in the
        browser, as described in the previous section).
	This key is generated by engine-setup.

* certs/engine.cer:

	The ovirt-engine's certificate, which is being used to decode
        the authorization header sent in requests to the proxy. This
        header is encoded in the engine's backend with the engine's
	private	key.

* ca.pem:

	The engine's CA-certificate. Being used to verify the
	certificate that is being attached to the
	ovirt-imageio-daemon responses. The daemon itself also
	implements an SSL server which is using VDSM's keys, therefore
	its certificate is also signed by the engine's CA. This ca is
	also being used to verify the authentication header which is
	attached to the proxy requests.


Development
-----------

Patches are welcome!

For setting up ovirt-imageio-proxy in an ovirt dev environment, please
refer to the previous section.

During development you may want to build/install the proxy.  There are
a few ways to go about this:

  `ovirt-imageio-proxy [options]` - run the proxy in-place, with debug
   options and alternate paths to configuration files, if desired.

  `python setup.py install` - Build/install the lib files and main
   script, but not the service/log/etc files.

  `make install` - Build/install everything (with DESTDIR specified
   if packaging); this uses python-setuptools for some of the work.

  `make rpm` - Build the proxy and setup rpms; this uses
   python-setuptools for some of the work.

When using an editor with code completion, it may be useful to have run
`make generated-files` to create any files with constants that depend
on the environment.

Before submitting changes, please be sure to:

 - Apply the git commit template
   (`git config commit.template commit-template.txt`).

 - Verify that unit tests pass (`make check` or `py.test`).  As of this
   writing, running the unit tests on Fedora 23 requires the pytest and
   python-pytest-cov packages.

Please send any patches to:

  gerrit.ovirt.org/ovirt-imageio


Packaging
---------

Multiple packaging options are available:
  make dist  ## compile and create a distribution tarball
  make rpm   ## compile and create an rpm


Getting Help
------------

Please send mail to one of the following lists for help.

 - For discussion of proxy usage and general help:
   http://lists.ovirt.org/mailman/listinfo/users

 - For technical discussion about the project and its code:
   http://lists.ovirt.org/mailman/listinfo/devel


Licensing
---------

The oVirt ImageIO Proxy is provided under the terms of the GPLv2 License.
The oVirt ImageIO Proxy setup plugin is provided under the terms of the
Apache License, Version 2.0.

Please see the COPYING files in the proxy and proxy/setup directories
for complete license terms.

-- End of readme
