1 files changed, 69 insertions, 0 deletions
diff --git a/docs/narr/vhosting.rst b/docs/narr/vhosting.rst
new file mode 100644
index 000000000..2cd1346e3
--- /dev/null
+++ b/docs/narr/vhosting.rst
@@ -0,0 +1,69 @@
+.. _vhosting_chapter:
+
+Virtual Hosting
+===============
+
+:mod:`repoze.bfg` supports a traditional form of virtual hosting
+provided by packages like Paste's `urlmap
+<http://pythonpaste.org/modules/urlmap.html>`_ middleware, where you
+can host a :mod:`repoze.bfg` application as a "subset" of some other
+site (e.g. ``http://example.com/mybfgapplication``).  Nothing special
+needs to be done within a :mod:`repoze.bfg` application to make this
+work.
+
+However, :mod:`repoze.bfg` also supports "virtual roots", which can be
+used in :term:`traversal` -based (but not :term:`URL-dispatch` -based)
+applications.  These are explained below.
+
+Virtual Root Support
+--------------------
+
+Virtual root support is useful when you'd like to host some model in a
+:mod:`repoze.bfg` model graph as an application under a URL pathname
+that does not include the model path itself.  For example, you might
+want to serve the object at the traversal path ``/cms`` as an
+application on reachable via ``http://example.com/`` (as opposed to
+``http://example.com/cms``). To specify a virtual root, cause an
+environment variable to be inserted into the WSGI environ named
+``HTTP_X_VHM_ROOT`` with a value that is the absolute pathname to the
+model object in the traversal graph that should behave as the "root"
+model.  As a result, the traversal machinery will respect this value
+during traversal (prepending it to the PATH_INFO before traversal
+starts), and the ``repoze.bfg.url.model_url`` API will generate the
+"correct" virtually-rooted URLs.
+
+An example of an Apache ``mod_proxy`` configuration that will host the
+``/cms`` subobject as ``http://www.example.com/`` using this facility
+is below:
+
+.. code-block:: xml
+
+    NameVirtualHost *:80
+
+    <VirtualHost *:80>
+      ServerName www.example.com
+      RewriteEngine On
+      RewriteRule ^/(.*) http://127.0.0.1:6543/$1 [L,P]
+      ProxyPreserveHost on
+      RequestHeader add X-Vhm-Root /cms
+    </VirtualHost>
+
+For a :mod:`repoze.bfg` application running under ``mod_wsgi``, the
+same can be achieved using ``SetEnv``:
+
+.. code-block:: xml
+
+    <Location />
+       SetEnv HTTP_X_VHM_ROOT /cms
+     </Location>
+
+Setting a virtual root has no effect when using an application based
+on :term:`URL dispatch`.
+
+Further Documentation and Examples
+----------------------------------
+
+The API documentation in :ref:`traversal_module` documents a
+``repoze.bfg.traversal.virtual_root`` API.  When called, it returns
+the virtual root object (or the physical root object if no virtual
+root has been specified).