1 Settings

     2 ========

     3 

     4 .. _cubicweb_settings:

     5 

     6 Cubicweb Settings

     7 -----------------

     8 

     9 Pyramid CubicWeb will **not** make use of the configuration entries

    10 found in the cubicweb configuration (a.k.a. `all-in-one.conf`) for any

    11 pyramid related configuration value.

    12 

    13 

    14 .. _pyramid_settings:

    15 

    16 Pyramid Settings

    17 ----------------

    18 

    19 If a ``pyramid.ini`` file is found in the instance home directory (where the

    20 ``all-in-one.conf`` file is), its ``[main]`` section will be read and used as the

    21 ``settings`` of the pyramid Configurator.

    22 

    23 This configuration file is almost the same as the one read by ``pserve``, which

    24 allow to easily add any pyramid extension and configure it.

    25 

    26 A typical ``pyramid.ini`` file is:

    27 

    28 .. code-block:: ini

    29 

    30     [main]

    31     pyramid.includes =

    32         pyramid_redis_sessions

    33 

    34     cubicweb.defaults = no

    35     cubicweb.includes =

    36         cubicweb.pyramid.auth

    37         cubicweb.pyramid.login

    38 

    39     cubicweb.profile = no

    40 

    41     redis.sessions.secret = your_cookie_signing_secret

    42     redis.sessions.timeout = 1200

    43 

    44     redis.sessions.host = mywheezy

    45 

    46 The Pyramid CubicWeb specific configuration entries are:

    47 

    48 .. confval:: cubicweb.instance (string)

    49 

    50     A CubicWeb instance name. Useful when the application is not run by

    51     :ref:`cubicweb-ctl_pyramid`.

    52 

    53 .. confval:: cubicweb.debug (bool)

    54 

    55     Enables the cubicweb debugmode. Works only if the instance is setup by

    56     :confval:`cubicweb.instance`.

    57 

    58     Unlike when the debugmode is set by the :option:`cubicweb-ctl pyramid --debug-mode`

    59     command, the pyramid debug options are untouched.

    60 

    61 .. confval:: cubicweb.includes (list)

    62 

    63     Same as ``pyramid.includes``, but the includes are done after the cubicweb

    64     specific registry entries are initialized.

    65 

    66     Useful to include extensions that requires these entries.

    67 

    68 .. confval:: cubicweb.bwcompat (bool)

    69 

    70     (True) Enable/disable backward compatibility. See :ref:`bwcompat_module`.

    71 

    72 .. confval:: cubicweb.bwcompat.errorhandler (bool)

    73 

    74     (True) Enable/disable the backward compatibility error handler.

    75     Set to 'no' if you need to define your own error handlers.

    76 

    77 .. confval:: cubicweb.defaults (bool)

    78 

    79     (True) Enable/disable defaults. See :ref:`defaults_module`.

    80 

    81 .. confval:: cubicweb.profile (bool)

    82 

    83     (False) Enable/disable profiling. See :ref:`profiling`.

    84 

    85 .. confval:: cubicweb.auth.update_login_time (bool)

    86 

    87     (True) Add a :class:`cubicweb.pyramid.auth.UpdateLoginTimeAuthenticationPolicy`

    88     policy, that update the CWUser.login_time attribute when a user login.

    89     

    90 .. confval:: cubicweb.auth.authtkt (bool)

    91 

    92     (True) Enables the 2 cookie-base auth policies, which activate/deactivate

    93     depending on the `persistent` argument passed to `remember`.

    94 

    95     The default login views set persistent to True if a `__setauthcookie`

    96     parameters is passed to them, and evals to True in

    97     :func:`pyramid.settings.asbool`.

    98 

    99     The configuration values of the policies are arguments for

   100     :class:`pyramid.authentication.AuthTktAuthenticationPolicy`.

   101 

   102     The first policy handles session authentication. It doesn't get

   103     activated if `remember()` is called with `persistent=False`:

   104 

   105     .. confval:: cubicweb.auth.authtkt.session.cookie_name (str)

   106 

   107         ('auth_tkt') The cookie name. Must be different from the persistent

   108         authentication cookie name.

   109 

   110     .. confval:: cubicweb.auth.authtkt.session.timeout (int)

   111 

   112         (1200) Cookie timeout.

   113 

   114     .. confval:: cubicweb.auth.authtkt.session.reissue_time (int)

   115 

   116         (120) Reissue time.

   117 

   118     The second policy handles persistent authentication. It doesn't get

   119     activated if `remember()` is called with `persistent=True`:

   120 

   121     .. confval:: cubicweb.auth.authtkt.persistent.cookie_name (str)

   122 

   123         ('auth_tkt') The cookie name. Must be different from the session

   124         authentication cookie name.

   125 

   126     .. confval:: cubicweb.auth.authtkt.persistent.max_age (int)

   127 

   128         (30 days) Max age in seconds.

   129 

   130     .. confval:: cubicweb.auth.authtkt.persistent.reissue_time (int)

   131 

   132         (1 day) Reissue time in seconds.

   133 

   134     Both policies set the ``secure`` flag to ``True`` by default, meaning that

   135     cookies will only be sent back over a secure connection (see

   136     `Authentication Policies documentation`_ for details). This can be

   137     configured through :confval:`cubicweb.auth.authtkt.persistent.secure` and

   138     :confval:`cubicweb.auth.authtkt.session.secure` configuration options.

   139 

   140     .. _`Authentication Policies documentation`: \

   141         http://docs.pylonsproject.org/projects/pyramid/en/latest/api/authentication.html

   142 

   143 .. confval:: cubicweb.auth.groups_principals (bool)

   144 

   145     (True) Setup a callback on the authentication stack that inject the user

   146     groups in the principals.