diff --git a/doc/admin-guide-cloud/source/dashboard_sessions.rst b/doc/admin-guide-cloud/source/dashboard_sessions.rst index ed3a7e409e..594136caae 100644 --- a/doc/admin-guide-cloud/source/dashboard_sessions.rst +++ b/doc/admin-guide-cloud/source/dashboard_sessions.rst @@ -6,10 +6,7 @@ The dashboard uses `Django sessions framework `__ to handle user session data. However, you can use any available session back end. You customize the session back end through the -``SESSION_ENGINE`` setting in your :file:`local_settings` file (on Fedora/RHEL/ -CentOS: :file:`/etc/openstack-dashboard/local_settings`, on Ubuntu and Debian: -:file:`/etc/openstack-dashboard/local_settings.py`, and on openSUSE: -:file:`/srv/www/openstack-dashboard/openstack_dashboard/local/local_settings.py`). +``SESSION_ENGINE`` setting in your ``local_settings.py`` file. After architecting and implementing the core OpenStack services and other required services, combined with the Dashboard @@ -24,6 +21,7 @@ pertains to deploying the Dashboard. Local memory cache ~~~~~~~~~~~~~~~~~~ + 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: @@ -33,21 +31,24 @@ significant drawbacks: 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:: +use, or even for serious development work. - SESSION_ENGINE = 'django.contrib.sessions.backends.cache' - CACHES = { - 'default' : { - 'BACKEND': 'django.core.cache.backends.locmem.LocMemCache' - } - } +.. code-block:: python -You can use applications such as Memcached or Redis for external + SESSION_ENGINE = 'django.contrib.sessions.backends.cache' + CACHES = { + 'default' : { + 'BACKEND': 'django.core.cache.backends.locmem.LocMemCache' + } + } + +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 development. Memcached --------- + Memcached is a high-performance and distributed memory object caching system providing in-memory key-value store for small chunks of arbitrary data. @@ -57,18 +58,19 @@ Requirements: - Memcached service running and accessible. - Python module ``python-memcached`` installed. -Enabled by:: +.. code-block:: python - SESSION_ENGINE = 'django.contrib.sessions.backends.cache' - CACHES = { - 'default': { - 'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache', - 'LOCATION': 'my_memcached_host:11211', - } - } + SESSION_ENGINE = 'django.contrib.sessions.backends.cache' + CACHES = { + 'default': { + 'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache', + 'LOCATION': 'my_memcached_host:11211', + } + } Redis ----- + Redis is an open source, BSD licensed, advanced key-value store. It is often referred to as a data structure server. @@ -77,21 +79,22 @@ Requirements: - Redis service running and accessible. - Python modules ``redis`` and ``django-redis`` installed. -Enabled by:: +.. code-block:: python - 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", - } - } - } + 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", + } + } + } Initialize and configure the database ------------------------------------- + Database-backed sessions are scalable, persistent, and can be made high-concurrency and highly-available. @@ -100,83 +103,98 @@ 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. -#. Start the mysql command-line client:: +#. Start the MySQL command-line client. - $ mysql -u root -p + .. code-block:: console + + $ mysql -u root -p #. Enter the MySQL root user's password when prompted. -#. To configure the MySQL database, create the dash database:: +#. To configure the MySQL database, create the dash database. - mysql> CREATE DATABASE dash; + .. code-block:: console + + mysql> CREATE DATABASE dash; #. Create a MySQL user for the newly created dash database that has full control of the database. Replace DASH\_DBPASS with a password for the - new user:: + new user. - mysql> GRANT ALL PRIVILEGES ON dash.* TO 'dash'@'%' IDENTIFIED BY 'DASH_DBPASS'; - mysql> GRANT ALL PRIVILEGES ON dash.* TO 'dash'@'localhost' IDENTIFIED BY 'DASH_DBPASS'; + .. code-block:: console + + mysql> GRANT ALL PRIVILEGES ON dash.* TO 'dash'@'%' IDENTIFIED BY 'DASH_DBPASS'; + mysql> GRANT ALL PRIVILEGES ON dash.* TO 'dash'@'localhost' IDENTIFIED BY 'DASH_DBPASS'; #. Enter ``quit`` at the ``mysql>`` prompt to exit MySQL. -#. In the :file:`local_settings` file (on Fedora/RHEL/CentOS: - :file:`/etc/openstack-dashboard/local_settings`, on Ubuntu/Debian: - :file:`/etc/openstack-dashboard/local_settings.py`, and on openSUSE: - :file:`/srv/www/openstack-dashboard/openstack_dashboard/local/local_settings.py`), - change these options:: +#. In the ``local_settings.py`` file, change these options: - SESSION_ENGINE = 'django.contrib.sessions.backends.db' - DATABASES = { - 'default': { - # Database configuration here - 'ENGINE': 'django.db.backends.mysql', - 'NAME': 'dash', - 'USER': 'dash', - 'PASSWORD': 'DASH_DBPASS', - 'HOST': 'localhost', - 'default-character-set': 'utf8' - } - } + .. code-block:: python -#. After configuring the :file:`local_settings` file as shown, you can run the - ``manage.py syncdb`` command to populate this newly created database:: + SESSION_ENGINE = 'django.contrib.sessions.backends.db' + DATABASES = { + 'default': { + # Database configuration here + 'ENGINE': 'django.db.backends.mysql', + 'NAME': 'dash', + 'USER': 'dash', + 'PASSWORD': 'DASH_DBPASS', + 'HOST': 'localhost', + 'default-character-set': 'utf8' + } + } - # /usr/share/openstack-dashboard/manage.py syncdb +#. After configuring the ``local_settings.py`` file as shown, you can run the + :command:`manage.py syncdb` command to populate this newly created + database. - Note on openSUSE the path is :file:`/srv/www/openstack-dashboard/manage.py`. + .. code-block:: console -#. The following output is returned:: + # /usr/share/openstack-dashboard/manage.py syncdb - 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. +#. The following output is returned: + + .. code-block:: console + + 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. #. To avoid a warning when you restart Apache on Ubuntu, create a - :file:`blackhole` directory in the Dashboard directory, as follows:: + ``blackhole`` directory in the Dashboard directory, as follows. - # mkdir -p /var/lib/dash/.blackhole + .. code-block:: console + + # mkdir -p /var/lib/dash/.blackhole #. Restart the Apache service. -#. On Ubuntu, restart the nova-api service to ensure that the API server - can connect to the Dashboard without error:: +#. On Ubuntu, restart the ``nova-api`` service to ensure that the API server + can connect to the Dashboard without error. - # service nova-api restart + .. code-block:: console + + # service nova-api restart Cached database ~~~~~~~~~~~~~~~ + To mitigate the performance issues of database queries, you can use the Django ``cached_db`` session back end, which utilizes both your database and caching infrastructure to perform write-through caching and efficient retrieval. Enable this hybrid setting by configuring both your database and cache, -as discussed previously. Then, set the following value:: +as discussed previously. Then, set the following value: - SESSION_ENGINE = "django.contrib.sessions.backends.cached_db" +.. code-block:: python + + SESSION_ENGINE = "django.contrib.sessions.backends.cached_db" Cookies ~~~~~~~ + If you use Django 1.4 or later, the ``signed_cookies`` back end avoids server load and scaling problems.