--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/pyramid/settings.rst	Mon Sep 26 14:52:12 2016 +0200
@@ -0,0 +1,146 @@
+Settings
+========
+
+.. _cubicweb_settings:
+
+Cubicweb Settings
+-----------------
+
+Pyramid CubicWeb will **not** make use of the configuration entries
+found in the cubicweb configuration (a.k.a. `all-in-one.conf`) for any
+pyramid related configuration value.
+
+
+.. _pyramid_settings:
+
+Pyramid Settings
+----------------
+
+If a ``pyramid.ini`` file is found in the instance home directory (where the
+``all-in-one.conf`` file is), its ``[main]`` section will be read and used as the
+``settings`` of the pyramid Configurator.
+
+This configuration file is almost the same as the one read by ``pserve``, which
+allow to easily add any pyramid extension and configure it.
+
+A typical ``pyramid.ini`` file is:
+
+.. code-block:: ini
+
+    [main]
+    pyramid.includes =
+        pyramid_redis_sessions
+
+    cubicweb.defaults = no
+    cubicweb.includes =
+        cubicweb.pyramid.auth
+        cubicweb.pyramid.login
+
+    cubicweb.profile = no
+
+    redis.sessions.secret = your_cookie_signing_secret
+    redis.sessions.timeout = 1200
+
+    redis.sessions.host = mywheezy
+
+The Pyramid CubicWeb specific configuration entries are:
+
+.. confval:: cubicweb.instance (string)
+
+    A CubicWeb instance name. Useful when the application is not run by
+    :ref:`cubicweb-ctl_pyramid`.
+
+.. confval:: cubicweb.debug (bool)
+
+    Enables the cubicweb debugmode. Works only if the instance is setup by
+    :confval:`cubicweb.instance`.
+
+    Unlike when the debugmode is set by the :option:`cubicweb-ctl pyramid --debug-mode`
+    command, the pyramid debug options are untouched.
+
+.. confval:: cubicweb.includes (list)
+
+    Same as ``pyramid.includes``, but the includes are done after the cubicweb
+    specific registry entries are initialized.
+
+    Useful to include extensions that requires these entries.
+
+.. confval:: cubicweb.bwcompat (bool)
+
+    (True) Enable/disable backward compatibility. See :ref:`bwcompat_module`.
+
+.. confval:: cubicweb.bwcompat.errorhandler (bool)
+
+    (True) Enable/disable the backward compatibility error handler.
+    Set to 'no' if you need to define your own error handlers.
+
+.. confval:: cubicweb.defaults (bool)
+
+    (True) Enable/disable defaults. See :ref:`defaults_module`.
+
+.. confval:: cubicweb.profile (bool)
+
+    (False) Enable/disable profiling. See :ref:`profiling`.
+
+.. confval:: cubicweb.auth.update_login_time (bool)
+
+    (True) Add a :class:`cubicweb.pyramid.auth.UpdateLoginTimeAuthenticationPolicy`
+    policy, that update the CWUser.login_time attribute when a user login.
+    
+.. confval:: cubicweb.auth.authtkt (bool)
+
+    (True) Enables the 2 cookie-base auth policies, which activate/deactivate
+    depending on the `persistent` argument passed to `remember`.
+
+    The default login views set persistent to True if a `__setauthcookie`
+    parameters is passed to them, and evals to True in
+    :func:`pyramid.settings.asbool`.
+
+    The configuration values of the policies are arguments for
+    :class:`pyramid.authentication.AuthTktAuthenticationPolicy`.
+
+    The first policy handles session authentication. It doesn't get
+    activated if `remember()` is called with `persistent=False`:
+
+    .. confval:: cubicweb.auth.authtkt.session.cookie_name (str)
+
+        ('auth_tkt') The cookie name. Must be different from the persistent
+        authentication cookie name.
+
+    .. confval:: cubicweb.auth.authtkt.session.timeout (int)
+
+        (1200) Cookie timeout.
+
+    .. confval:: cubicweb.auth.authtkt.session.reissue_time (int)
+
+        (120) Reissue time.
+
+    The second policy handles persistent authentication. It doesn't get
+    activated if `remember()` is called with `persistent=True`:
+
+    .. confval:: cubicweb.auth.authtkt.persistent.cookie_name (str)
+
+        ('auth_tkt') The cookie name. Must be different from the session
+        authentication cookie name.
+
+    .. confval:: cubicweb.auth.authtkt.persistent.max_age (int)
+
+        (30 days) Max age in seconds.
+
+    .. confval:: cubicweb.auth.authtkt.persistent.reissue_time (int)
+
+        (1 day) Reissue time in seconds.
+
+    Both policies set the ``secure`` flag to ``True`` by default, meaning that
+    cookies will only be sent back over a secure connection (see
+    `Authentication Policies documentation`_ for details). This can be
+    configured through :confval:`cubicweb.auth.authtkt.persistent.secure` and
+    :confval:`cubicweb.auth.authtkt.session.secure` configuration options.
+
+    .. _`Authentication Policies documentation`: \
+        http://docs.pylonsproject.org/projects/pyramid/en/latest/api/authentication.html
+
+.. confval:: cubicweb.auth.groups_principals (bool)
+
+    (True) Setup a callback on the authentication stack that inject the user
+    groups in the principals.