235 lines
12 KiB
XML
235 lines
12 KiB
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.core.cache.backends.db.DatabaseCache'
|
||
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>
|