openstack-manuals/doc/common/section_dashboard_sessions.xml

<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
  xmlns:xi="http://www.w3.org/2001/XInclude"
  xmlns:xlink="http://www.w3.org/1999/xlink"
  version="5.0"
  xml:id="dashboard-sessions">
    <title>Set up session storage for the dashboard</title>
    <para>The dashboard uses <link
            xlink:href="https://docs.djangoproject.com/en/dev/topics/http/sessions/"
            >Django sessions framework</link> to handle user session
        data. However, you can use any available session back end. You
        customize the session back end through the
            <literal>SESSION_ENGINE</literal> setting in your <filename>local_settings</filename> file
            (on Fedora/RHEL/CentOS: <filename>
            /etc/openstack-dashboard/local_settings</filename>, on Ubuntu and Debian:
            <filename>/etc/openstack-dashboard/local_settings.py</filename> and on openSUSE: <filename
        >/srv/www/openstack-dashboard/openstack_dashboard/local/local_settings.py</filename>).
   </para>
    <para>The following sections describe the pros and cons of each
        option as it pertains to deploying the dashboard.</para>
    <section xml:id="dashboard-session-local">
        <title>Local memory cache</title>
        <para>Local memory storage is the quickest and easiest session
            back end to set up, as it has no external dependencies
            whatsoever. It has the following significant
            drawbacks:</para>
        <itemizedlist>
            <listitem>
                <para>No shared storage across processes or
                    workers.</para>
            </listitem>
            <listitem>
                <para>No persistence after a process
                    terminates.</para>
            </listitem>
        </itemizedlist>
        <para>The local memory back end is enabled as the default for
            Horizon solely because it has no dependencies. It is not
            recommended for production use, or even for serious
            development work. Enabled by:</para>
        <programlisting language="python"><?db-font-size 75%?>SESSION_ENGINE = 'django.contrib.sessions.backends.cache'
CACHES = {
  'default' : {
    'BACKEND': 'django.core.cache.backends.locmem.LocMemCache'
  }
}</programlisting>
    </section>
    <section xml:id="dashboard-session-key-value-store">
        <?dbhtml stop-chunking?>
        <title>Key-value stores</title>
        <para>You can use applications such as Memcached or Redis for external
            caching. These applications offer persistence and shared storage
            and are useful for small-scale deployments and/or development.
       </para>
        <section xml:id="dashboard-session-memcached">
        <title>Memcached</title>
        <para>Memcached is a high-performance and distributed memory object caching system
              providing in-memory key-value store for small chunks of arbitrary data.</para>
        <para>Requirements:</para>
        <itemizedlist>
            <listitem>
                <para>Memcached service running and accessible.</para>
            </listitem>
            <listitem>
                <para>Python module <literal>python-memcached</literal> installed.</para>
            </listitem>
        </itemizedlist>
        <para>Enabled by:</para>
        <programlisting language="python"><?db-font-size 75%?>SESSION_ENGINE = 'django.contrib.sessions.backends.cache'
CACHES = {
  'default': {
    'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache',
    'LOCATION': 'my_memcached_host:11211',
  }
}</programlisting>
        </section>
        <section xml:id="dashboard-session-redis">
        <title>Redis</title>
        <para>Redis is an open source, BSD licensed, advanced key-value store. It is often referred
         to as a data structure server.</para>
        <para>Requirements:</para>
        <itemizedlist>
            <listitem>
                <para>Redis service running and accessible.</para>
            </listitem>
            <listitem>
                <para>Python modules <literal>redis</literal> and <literal>django-redis</literal> installed.</para>
            </listitem>
        </itemizedlist>
        <para>Enabled by:</para>
        <programlisting language="python"><?db-font-size 75%?>SESSION_ENGINE = 'django.contrib.sessions.backends.cache'
CACHES = {
    "default": {
        "BACKEND": "redis_cache.cache.RedisCache",
        "LOCATION": "127.0.0.1:6379:1",
        "OPTIONS": {
            "CLIENT_CLASS": "redis_cache.client.DefaultClient",
        }
    }
}</programlisting>
        </section>
    </section>
    <section xml:id="dashboard-session-database">
        <title>Initialize and configure the database</title>
        <para>Database-backed sessions are scalable, persistent, and
            can be made high-concurrency and highly-available.</para>
        <para>However, database-backed sessions are one of the slower
            session storages and incur a high overhead under heavy
            usage. Proper configuration of your database deployment
            can also be a substantial undertaking and is far beyond
            the scope of this documentation.</para>
        <procedure>
            <step>
                <para>Start the mysql command-line client:</para>
                <screen><prompt>$</prompt> <userinput>mysql -u root -p</userinput></screen>
            </step>
            <step>
                <para>Enter the MySQL root user's password when
                    prompted.</para>
            </step>
            <step>
                <para>To configure the MySQL database, create the dash
                    database:</para>
                <para><screen><prompt>mysql></prompt> <userinput>CREATE DATABASE dash;</userinput></screen></para>
            </step>
            <step>
                <para>Create a MySQL user for the newly created dash
                    database that has full control of the
                    database. Replace <replaceable>DASH_DBPASS</replaceable> with
                    a password for the new user:</para>
                <para><screen><prompt>mysql></prompt> <userinput>GRANT ALL PRIVILEGES ON dash.* TO 'dash'@'%' IDENTIFIED BY '<replaceable>DASH_DBPASS</replaceable>';</userinput>
<prompt>mysql></prompt> <userinput>GRANT ALL PRIVILEGES ON dash.* TO 'dash'@'localhost' IDENTIFIED BY '<replaceable>DASH_DBPASS</replaceable>';</userinput></screen></para>
            </step>
            <step>
                <para>Enter quit at the <literal>mysql></literal>
                    prompt to exit MySQL.</para>
            </step>
            <step>
                <para>In the <filename>local_settings</filename> file
                (on Fedora/RHEL/CentOS: <filename>
                /etc/openstack-dashboard/local_settings</filename>, on Ubuntu/Debian:
                <filename>/etc/openstack-dashboard/local_settings.py</filename> and on openSUSE: <filename
                >/srv/www/openstack-dashboard/openstack_dashboard/local/local_settings.py</filename>),
                    change these options:</para>
                <programlisting language="python"><?db-font-size 75%?>SESSION_ENGINE = 'django.contrib.sessions.backends.db'
DATABASES = {
    'default': {
        # Database configuration here
        'ENGINE': 'django.db.backends.mysql',
        'NAME': 'dash',
        'USER': 'dash',
        'PASSWORD': '<replaceable>DASH_DBPASS</replaceable>',
        'HOST': 'localhost',
        'default-character-set': 'utf8'
    }
}</programlisting>
            </step>
            <step>
                <para>After configuring the <filename>local_settings</filename>
                    as shown, you can run the <command>manage.py
                        syncdb</command> command to populate this
                    newly created database.</para>
                <screen><prompt>#</prompt> <userinput>/usr/share/openstack-dashboard/manage.py syncdb</userinput></screen>
                <para>Note on openSUSE the path is <filename>/srv/www/openstack-dashboard/manage.py</filename>.
                </para>
                <para>As a result, the following output is
                    returned:</para>
                <screen><computeroutput>Installing custom SQL ...
Installing indexes ...
DEBUG:django.db.backends:(0.008) CREATE INDEX `django_session_c25c2c28` ON `django_session` (`expire_date`);; args=()
No fixtures found.</computeroutput></screen>
            </step>
            <step>
                <para>To avoid a warning when you restart Apache on Ubuntu,
                    create a <filename>blackhole</filename> directory in the
                    dashboard directory, as follows:</para>
                <screen><prompt>#</prompt> <userinput>mkdir -p /var/lib/dash/.blackhole</userinput></screen>
            </step>
            <step>
                <title>Restart and refresh Apache</title>
                    <para>On Ubuntu:
                    <screen><prompt>#</prompt> <userinput>/etc/init.d/apache2 restart</userinput></screen>
                   </para>
                    <para>On Fedora/RHEL/CentOS:
                <screen><prompt>#</prompt> <userinput>service httpd restart</userinput></screen>
                <screen><prompt>#</prompt> <userinput>service apache2 restart</userinput></screen>
                   </para>
                    <para>On openSUSE:
                <screen><prompt>#</prompt> <userinput>systemctl restart apache2.service</userinput></screen>
                   </para>
            </step>
            <step>
                <para>On Ubuntu, restart the <systemitem class="service">nova-api</systemitem> service to ensure that the
                    API server can connect to the dashboard without
                    error:</para>
                <screen><prompt>#</prompt> <userinput>service nova-api restart</userinput></screen>
            </step>
        </procedure>
    </section>
    <section xml:id="dashboard-session-cached-database">
        <title>Cached database</title>
        <para>To mitigate the performance issues of database queries,
            you can use the Django <command>cached_db</command> session
            back end, which
            utilizes both your database and caching infrastructure to
            perform write-through caching and efficient retrieval.</para>
        <para>Enable this hybrid setting by configuring both your
            database and cache, as discussed previously. Then, set the
            following value:</para>
        <programlisting language="python"><?db-font-size 75%?>SESSION_ENGINE = "django.contrib.sessions.backends.cached_db"</programlisting>
    </section>
    <section xml:id="dashboard-session-cookies">
        <title>Cookies</title>
        <para>If you use Django 1.4 or later, the <command>signed_cookies</command>
            back end avoids server load and scaling problems.</para>
        <para>This back end stores session data in a cookie, which is
            stored by the user's browser. The back end uses a
            cryptographic signing technique to ensure session data is
            not tampered with during transport. This is not the same
            as encryption; session data is still readable by an
            attacker.</para>
        <para>The pros of this engine are that it requires no
            additional dependencies or infrastructure overhead, and it
            scales indefinitely as long as the quantity of session
            data being stored fits into a normal cookie.</para>
        <para>The biggest downside is that it places session data into
            storage on the user's machine and transports it over the
            wire. It also limits the quantity of session data that can
            be stored.</para>
        <para>See the Django <link
                xlink:href="https://docs.djangoproject.com/en/dev/topics/http/sessions/#using-cookie-based-sessions"
                >cookie-based sessions</link> documentation.</para>
    </section>
</section>