--- a/doc/book/en/admin/index.rst	Tue Mar 02 18:10:03 2010 +0100
+++ b/doc/book/en/admin/index.rst	Tue Mar 02 18:46:58 2010 +0100
@@ -19,6 +19,7 @@
    site-config
    multisources
    ldap
+   pyro
    gae
    additional-tips
 

--- a/doc/book/en/admin/instance-config.rst	Tue Mar 02 18:10:03 2010 +0100
+++ b/doc/book/en/admin/instance-config.rst	Tue Mar 02 18:46:58 2010 +0100
@@ -65,8 +65,8 @@
      base-url = http://localhost/demo
      https-url = `https://localhost/demo`
 
-Setting up the web
-------------------
+Setting up the web client
+-------------------------
 :`web.embed-allowed`:
     regular expression matching sites which could be "embedded" in
     the site (controllers 'embed')
@@ -93,22 +93,26 @@
 -----------------------------------
 Web server side:
 
-:`pyro-client.pyro-instance-id`:
+:`pyro.pyro-instance-id`:
     pyro identifier of RQL server (e.g. the instance name)
 
 RQL server side:
 
-:`pyro-server.pyro-port`:
-    pyro port number. If none is specified, a port is assigned
+:`main.pyro-server`:
+    boolean to switch on/off pyro server-side
+
+:`pyro.pyro-host`:
+    pyro host:port number. If no port is specified, it is assigned
     automatically.
 
 RQL and web servers side:
 
-:`pyro-name-server.pyro-ns-host`:
+:`pyro.pyro-ns-host`:
     hostname hosting pyro server name. If no value is
     specified, it is located by a request from broadcast
-:`pyro-name-server.pyro-ns-group` [cubicweb]:
-    pyro group in which to save the instance
+
+:`pyro.pyro-ns-group`:
+    pyro group in which to save the instance (will default to 'cubicweb')
 
 
 Configuring e-mail

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/admin/pyro.rst	Tue Mar 02 18:46:58 2010 +0100
@@ -0,0 +1,39 @@
+Working with a distributed client (using Pyro)
+==============================================
+
+In some circumstances, it is practical to split the repository and
+web-client parts of the application, for load-balancing reasons. Or
+one wants to access the repository from independant scripts to consult
+or update the database.
+
+For this to work, several steps have to be taken in order.
+
+You must first ensure that the apropriate software is installed and
+running (see ref:`setup`)::
+
+  pyro-nsd -x -p 6969
+
+Then you have to set appropriate options in your configuration. For
+instance::
+
+  pyro-server=yes
+  pyro-ns-host=localhost:6969
+
+  pyro-instance-id=myinstancename
+
+Finally, the client (for instance in the case of a script) must
+connect specifically, as in the following example code:
+
+.. sourcecode:: python
+
+    from cubicweb import dbapi
+
+    def pyro_connect(instname, login, password, pyro_ns_host):
+        cnx = dbapi.connect(instname, login, password, pyro_ns_host)
+        cnx.load_appobjects()
+        return cnx
+
+The 'cnx.load_appobjects()' line is optional. Without it you will get
+data through the connection roughly as you would from a DBAPI
+connection. With it, provided the cubicweb-client part is installed
+and accessible, you get the ORM goodies.