From ea96bb3a22ddeb6741c29ebfb2100c7cb6e566b3 Mon Sep 17 00:00:00 2001 From: Gabriel Hurley Date: Sun, 17 Mar 2013 16:07:37 -0700 Subject: [PATCH] Adds docs for settings/configuration. In addition to thoroughly documenting the settings and config options for Horizon/OpenStack Dashboard, this clarifies some misconceptions around how to enable Object Storage/Swift and Netowrking/Quantum in the OpenStack Dashboard. Fixes bug 1064412. DocImpact. Change-Id: I85fc7592c55111f5bc69a7cdab49679eaf81c6ca --- doc/source/_static/tweaks.css | 3 +- doc/source/index.rst | 1 + doc/source/topics/customizing.rst | 2 - doc/source/topics/deployment.rst | 21 ++ doc/source/topics/settings.rst | 294 ++++++++++++++++++ .../dashboards/project/loadbalancers/tests.py | 8 +- .../local/local_settings.py.example | 105 ++++--- 7 files changed, 378 insertions(+), 56 deletions(-) create mode 100644 doc/source/topics/settings.rst diff --git a/doc/source/_static/tweaks.css b/doc/source/_static/tweaks.css index 3f3fb3f07..9977c658d 100644 --- a/doc/source/_static/tweaks.css +++ b/doc/source/_static/tweaks.css @@ -58,6 +58,7 @@ div.related a { div.sphinxsidebarwrapper { padding-top: 0; + overflow: hidden; } pre { @@ -91,4 +92,4 @@ div.body { div.document { width: 960px; margin: 0 auto; -} \ No newline at end of file +} diff --git a/doc/source/index.rst b/doc/source/index.rst index de5feae56..592027a27 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -42,6 +42,7 @@ How to use Horizon in your own projects. quickstart topics/tutorial topics/deployment + topics/settings topics/customizing Developer Docs diff --git a/doc/source/topics/customizing.rst b/doc/source/topics/customizing.rst index 5566ae191..474f778ef 100644 --- a/doc/source/topics/customizing.rst +++ b/doc/source/topics/customizing.rst @@ -76,8 +76,6 @@ Or just remove it entirely:: projects_dashboard.unregister(instances_panel.__class__) - - .. NOTE:: ``my_project.overrides`` needs to be importable by the python process running diff --git a/doc/source/topics/deployment.rst b/doc/source/topics/deployment.rst index 872b96d38..fefae2dc8 100644 --- a/doc/source/topics/deployment.rst +++ b/doc/source/topics/deployment.rst @@ -5,6 +5,27 @@ Deploying Horizon This guide aims to cover some common questions, concerns and pitfalls you may encounter when deploying Horizon in a production environment. +.. seealso:: :doc:`settings` + +.. note:: + + The Service Catalog returned by the Identity Service after a user + has successfully authenticated determines the dashboards and panels + that will be available within the OpenStack Dashboard. If you are not + seeing a particular service you expected (e.g. Object Storage/Swift or + Networking/Quantum) make sure your Service Catalog is configured correctly. + + Prior to the Essex release of Horizon these features were controlled by + individual settings in the ``local_settings.py`` file. This code has been + long-since removed and those pre-Essex settings have no impact now. + +Configure Your Identity Service Host +==================================== + +The one thing you *must* do in order to run Horizon is to specify the +host for your OpenStack Identity Service endpoint. To do this, set the value +of the ``OPENSTACK_HOST`` settings in your ``local_settings.py`` file. + Logging ======= diff --git a/doc/source/topics/settings.rst b/doc/source/topics/settings.rst new file mode 100644 index 000000000..0cbd25ab6 --- /dev/null +++ b/doc/source/topics/settings.rst @@ -0,0 +1,294 @@ +================================== +Horizon Settings and Configuration +================================== + +Introduction +============ + +Horizon's settings tend to fall into three categories: + +* Horizon configuration options (contained in the ``HORIZON_CONFIG`` dict) + which are not OpenStack-specific and pertain only to the core framework. +* OpenStack-related settings which pertain to other projects/services and + are generally prefixed with ``OPENSTACK_`` in the settings file. +* Django settings (including common plugins like ``django-compressor``) which + can be (and should be) read about in their respective documentation. + +What follows is an overview of the Horizon and OpenStack-specific settings +and a few notes on the Django-related settings. + +.. note:: + + Prior to the Essex release of Horizon there were settings which controlled + whether features such as Object Storage/Swift or Networking/Quantum would be + enabled in the OpenStack Dashboard. This code has beenlong-since removed and + those pre-Essex settings have no impact now. + + In Essex and later, the Service Catalog returned by the Identity Service + after a user has successfully authenticated determines the dashboards and + panels that will be available within the OpenStack Dashboard. If you are not + seeing a particular service you expected make sure your Service Catalog is + configured correctly. + +Horizon Settings +================ + +The following options are available in order to configure/customize the +behavior of your Horizon installation. All of them are contained in the +``HORIZON_CONFIG`` dictionary. + +``dashboards`` +-------------- + +Default: ``None`` + +A list containing the slugs of any dashboards which should be active in this +Horizon installation. The dashboards listed must be in a Python module which +is included in the ``INSTALLED_APPS`` list and on the Python path. + +``default_dashboard`` +--------------------- + +Default: ``None`` + +The slug of the dashboard which should act as the first-run/fallback dashboard +whenever a user logs in or is otherwise redirected to an ambiguous location. + +``user_home`` +------------- + +Default: ``settings.LOGIN_REDIRECT_URL`` + +This can be either a literal URL path (such as the default), or Python's +dotted string notation representing a function which will evaluate what URL +a user should be redirected to based on the attributes of that user. + +``ajax_queue_limit`` +-------------------- + +Default: ``10`` + +The maximum number of simultaneous AJAX connections the dashboard may try +to make. This is particularly relevant when monitoring a large number of +instances, volumes, etc. which are all actively trying to update/change state. + +``ajax_poll_interval`` +---------------------- + +Default: ``2500`` + +How frequently resources in transition states should be polled for updates, +expressed in milliseconds. + +``help_url`` +------------ + +Default: None + +If provided, a "Help" link will be displayed in the site header which links +to the value of this settings (ideally a URL containing help information). + +``exceptions`` +-------------- + +Default: ``{'unauthorized': [], 'not_found': [], 'recoverable': []}`` + +A dictionary containing classes of exceptions which Horizon's centralized +exception handling should be aware of. + +``password_validator`` +---------------------- + +Default: {'regex': '.*', 'help_text': _("Password is not accepted")} + +A dictionary containing a regular expression which will be used for password +validation and help text which will be displayed if the password does not +pass validation. The help text should describe the password requirements if +there are any. + +This setting allows you to set rules for passwords if your organization +requires them. + +``password_autocomplete`` +------------------------- + +Default: ``"on"`` + +Controls whether browser autocompletion should be enabled on the login form. +Valid values are ``"on"`` and ``"off"``. + +``simple_ip_management`` +------------------------ + +Default: ``True`` + +Enable or disable simplified floating IP address management. + +"Simple" floating IP address management means that the user does not ever have +to select the specific IP addresses they wish to use, and the process of +allocating an IP and assigning it to an instance is one-click. + +The "advanced" floating IP management allows users to select the floating IP +pool from which the IP should be allocated and to select a specific IP address +when associating one with an instance. + + +OpenStack Settings +================== + +The following settings inform the OpenStack Dashboard of information about the +other OpenStack projects which are part of this cloud and control the behavior +of specific dashboards, panels, API calls, etc. + +``OPENSTACK_HOST`` +------------------ + +Default: ``"127.0.0.1"`` + +The hostname of the Keystone server used for authentication if you only have +one region. This is often the *only* settings that needs to be set for a +basic deployment. + + +``OPENSTACK_KEYSTONE_URL`` +-------------------------- + +Default: ``"http://%s:5000/v2.0" % OPENSTACK_HOST`` + +The full URL for the Keystone endpoint used for authentication. Unless you +are using HTTPS, running your Keystone server on a nonstandard port, or using +a nonstandard URL scheme you shouldn't need to touch this setting. + +``AVAILABLE_REGIONS`` +--------------------- + +Default: ``None`` + +A tuple of tuples which define multiple regions. The tuple format is +``('http://{{keystone_host}}:5000/v2.0', '{{region_name}}')``. If any regions +are specified the login form will have a dropdown selector for authenticating +to the appropriate region, and there will be a region switcher dropdown in +the site header when logged in. + +If you do not have multiple regions you should use the ``OPENSTACK_HOST`` and +``OPENSTACK_KEYSTONE_URL`` settings above instead. + +``OPENSTACK_KEYSTONE_DEFAULT_ROLE`` +----------------------------------- + +Default: "Member" + +The name of the role which will be assigned to a user when added to a project. +This name must correspond to a role name in Keystone. + +``OPENSTACK_SSL_NO_VERIFY`` +--------------------------- + +Default: ``False`` + +Disable SSL certificate checks in the OpenStack clients (useful for self-signed +certificates). + +``OPENSTACK_KEYSTONE_BACKEND`` +------------------------------ + +Default: ``{'name': 'native', 'can_edit_user': True, 'can_edit_project': True}`` + +A dictionary containing settings which can be used to identify the +capabilities of the auth backend for Keystone. + +If Keystone has been configured to use LDAP as the auth backend then set +``can_edit_user`` and ``can_edit_project`` to ``False`` and name to ``"ldap"``. + + +``OPENSTACK_HYPERVISOR_FEATURES`` +--------------------------------- + +Default: ``{'can_set_mount_point': True, 'can_encrypt_volumes': False}`` + +A dictionary containing settings which can be used to identify the +capabilities of the hypervisor for Nova. + +Some hypervisors have the ability to set the mount point for volumes attached +to instances (KVM does not). Setting ``can_set_mount_point`` to ``False`` will +remove the option to set the mount point from the UI. + +In the Havana release, there will be a feature for encrypted volumes +which will be controlled by the ``can_encrypt_volumes``. Setting it to ``True`` +in the Grizzly release will have no effect. + +``OPENSTACK_QUANTUM_NETWORK`` +----------------------------- + +Default: ``{'enable_lb': False}`` + +A dictionary of settings which can be used to enable optional services provided +by quantum. Currently only the load balancer service is available. + +``OPENSTACK_ENDPOINT_TYPE`` +--------------------------- + +Default: ``"internalURL"`` + +A string which specifies the endpoint type to use for the endpoints in the +Keystone service catalog. If Horizon is running external to the OpenStack +environment you may wish to use ``"publicURL"`` instead. + +``API_RESULT_LIMIT`` +-------------------- + +Default: ``1000`` + +The maximum number of objects (e.g. Swift objects or Glance images) to display +on a single page before providing a paging element (a "more" link) to paginate +results. + +``API_RESULT_PAGE_SIZE`` +------------------------ + +Default: ``20`` + +Similar to ``API_RESULT_LIMIT``. This setting currently only controls the +Glance image list page size. It will be removed in a future version. + +Django Settings (Partial) +========================= + +.. warning:: + + This is not meant to be anywhere near a complete list of settings for + Django. You should always consult the upstream documentation, especially + with regards to deployment considerations and security best-practices. + +There are a few key settings you should be aware of for development and the +most basic of deployments. Further recommendations can be found in the +Deploying Horizon section of this documentation. + +``DEBUG`` and ``TEMPLATE_DEBUG`` +-------------------------------- + +Default: ``True`` + +Controls whether unhandled exceptions should generate a generic 500 response +or present the user with a pretty-formatted debug information page. + +This setting should **always** be set to ``False`` for production deployments +as the debug page can display sensitive information to users and attackers +alike. + +``SECRET_KEY`` +-------------- + +This should absolutely be set to a unique (and secret) value for your +deployment. Unless you are running a load-balancer with multiple Horizon +installations behind it, each Horizon instance should have a unique secret key. + +The ``local_settings.py.example`` file includes a quick-and-easy way to +generate a secret key for a single installation. + +``SECURE_PROXY_SSL_HEADER``, ``CSRF_COOKIE_SECURE`` and ``SESSION_COOKIE_SECURE`` +--------------------------------------------------------------------------------- + +These three settings should be configured if you are deploying Horizon with +SSL. The values indicated in the default ``local_settings.py.example`` file +are generally safe to use. diff --git a/openstack_dashboard/dashboards/project/loadbalancers/tests.py b/openstack_dashboard/dashboards/project/loadbalancers/tests.py index 8a1510753..cbeb288e9 100644 --- a/openstack_dashboard/dashboards/project/loadbalancers/tests.py +++ b/openstack_dashboard/dashboards/project/loadbalancers/tests.py @@ -4,7 +4,7 @@ import json from mox import IsA from django import http -from django.core.urlresolvers import reverse +from django.core.urlresolvers import reverse, reverse_lazy from openstack_dashboard import api from openstack_dashboard.test import helpers as test @@ -23,7 +23,7 @@ class LoadBalancerTests(test.TestCase): self[attr] = value DASHBOARD = 'project' - INDEX_URL = reverse('horizon:%s:loadbalancers:index' % DASHBOARD) + INDEX_URL = reverse_lazy('horizon:%s:loadbalancers:index' % DASHBOARD) ADDPOOL_PATH = 'horizon:%s:loadbalancers:addpool' % DASHBOARD ADDVIP_PATH = 'horizon:%s:loadbalancers:addvip' % DASHBOARD @@ -204,7 +204,7 @@ class LoadBalancerTests(test.TestCase): res = self.client.post(reverse(self.ADDPOOL_PATH), form_data) self.assertNoFormErrors(res) - self.assertRedirectsNoFollow(res, self.INDEX_URL) + self.assertRedirectsNoFollow(res, str(self.INDEX_URL)) @test.create_stubs({api.quantum: ('network_list_for_tenant',)}) def test_add_pool_get(self): @@ -271,7 +271,7 @@ class LoadBalancerTests(test.TestCase): res = self.client.post(reverse(self.ADDMEMBER_PATH), form_data) self.assertNoFormErrors(res) - self.assertRedirectsNoFollow(res, self.INDEX_URL) + self.assertRedirectsNoFollow(res, str(self.INDEX_URL)) @test.create_stubs({api.lbaas: ('pools_get',), api.nova: ('server_list',)}) diff --git a/openstack_dashboard/local/local_settings.py.example b/openstack_dashboard/local/local_settings.py.example index 9202c6cb5..9615857ec 100644 --- a/openstack_dashboard/local/local_settings.py.example +++ b/openstack_dashboard/local/local_settings.py.example @@ -41,6 +41,9 @@ HORIZON_CONFIG = { # multiple floating IP pools or complex network requirements. # HORIZON_CONFIG["simple_ip_management"] = False +# Turn off browser autocompletion for the login form if so desired. +# HORIZON_CONFIG["password_autocomplete"] = "off" + LOCAL_PATH = os.path.dirname(os.path.abspath(__file__)) # Set custom secret key: @@ -57,7 +60,7 @@ LOCAL_PATH = os.path.dirname(os.path.abspath(__file__)) # We recommend you use memcached for development; otherwise after every reload # of the django development server, you will have to login again. To use -# memcached set CACHES to something like +# memcached set CACHES to something like # CACHES = { # 'default': { # 'BACKEND' : 'django.core.cache.backends.memcached.MemcachedCache', @@ -138,53 +141,57 @@ API_RESULT_PAGE_SIZE = 20 TIME_ZONE = "UTC" LOGGING = { - 'version': 1, - # When set to True this will disable all logging except - # for loggers specified in this configuration dictionary. Note that - # if nothing is specified here and disable_existing_loggers is True, - # django.db.backends will still log unless it is disabled explicitly. - 'disable_existing_loggers': False, - 'handlers': { - 'null': { - 'level': 'DEBUG', - 'class': 'django.utils.log.NullHandler', - }, - 'console': { - # Set the level to "DEBUG" for verbose output logging. - 'level': 'INFO', - 'class': 'logging.StreamHandler', - }, - }, - 'loggers': { - # Logging from django.db.backends is VERY verbose, send to null - # by default. - 'django.db.backends': { - 'handlers': ['null'], - 'propagate': False, - }, - 'horizon': { - 'handlers': ['console'], - 'propagate': False, - }, - 'openstack_dashboard': { - 'handlers': ['console'], - 'propagate': False, - }, - 'novaclient': { - 'handlers': ['console'], - 'propagate': False, - }, - 'keystoneclient': { - 'handlers': ['console'], - 'propagate': False, - }, - 'glanceclient': { - 'handlers': ['console'], - 'propagate': False, - }, - 'nose.plugins.manager': { - 'handlers': ['console'], - 'propagate': False, - } + 'version': 1, + # When set to True this will disable all logging except + # for loggers specified in this configuration dictionary. Note that + # if nothing is specified here and disable_existing_loggers is True, + # django.db.backends will still log unless it is disabled explicitly. + 'disable_existing_loggers': False, + 'handlers': { + 'null': { + 'level': 'DEBUG', + 'class': 'django.utils.log.NullHandler', + }, + 'console': { + # Set the level to "DEBUG" for verbose output logging. + 'level': 'INFO', + 'class': 'logging.StreamHandler', + }, + }, + 'loggers': { + # Logging from django.db.backends is VERY verbose, send to null + # by default. + 'django.db.backends': { + 'handlers': ['null'], + 'propagate': False, + }, + 'requests': { + 'handlers': ['null'], + 'propagate': False, + }, + 'horizon': { + 'handlers': ['console'], + 'propagate': False, + }, + 'openstack_dashboard': { + 'handlers': ['console'], + 'propagate': False, + }, + 'novaclient': { + 'handlers': ['console'], + 'propagate': False, + }, + 'keystoneclient': { + 'handlers': ['console'], + 'propagate': False, + }, + 'glanceclient': { + 'handlers': ['console'], + 'propagate': False, + }, + 'nose.plugins.manager': { + 'handlers': ['console'], + 'propagate': False, } + } }