Configuring¶
After you installed your Ganeti Web Manager instance with setup script it’s time for some configuration.
Configuration of Ganeti Web Manager can be defined with YAML, a human-readable markup
language. Ganeti Web Manager also supports configuration through settings.py
.
Ganeti Web Manager supports settings.py
for those that do not wish to use YAML; however,
YAML configuration is preferred. The YAML configuration method makes it much
easier to store settings outside of the project’s repository, which makes
managing settings with a configuration management tool easier and safer.
The YAML configuration file is always named config.yml
. You can customize
the location Ganeti Web Manager looks for this file by setting the GWM_CONFIG_DIR
environmental variable. The current default is /opt/ganeti_webmgr/config
.
By default you will need to put your yaml config in
/opt/ganeti_webmgr/config/config.yml
. If you want to customize the location
you can set GWM_CONFIG_DIR
like so:
$ export GWM_CONFIG_DIR='/etc/ganeti_webmgr'
This will cause Ganeti Web Manager to look for your config file at
/etc/ganeti_webmgr/config.yml
.
When both config.yml
and settings.py
are present, any settings stored in
settings.py
take precedence.
Note
A quick note about settings. Any setting value which contains an
-
or :
, or any other character used by yaml, must be wrapped
in quotes.
Example: localhost:8000
becomes "localhost:8000"
.
Creating configuration files¶
To get started configuring Ganeti Web Manager with YAML, copy the config.yml.dist
to
config.yml
in the directory where you want your settings:
$ cp /path/to/gwm/ganeti_webmgr/ganeti_web/settings/config.yml.dist /opt/ganeti_webmgr/config/config.yml
Alternatively, to configure Ganeti Web Manager with the standard Django settings.py
,
copy settings.py.dist
to settings.py
in the same directory it is in:
$ cp /path/to/gwm/ganeti_webmgr/ganeti_web/settings/settings.py.dist \
/path/to/gwm/ganeti_webmgr/ganeti_web/settings/settings.py
Databases¶
Ganeti Web Manager supports PostgreSQL, MySQL, Oracle, and SQLite databases. The type of
database and other configuration options must be defined in either
settings.py
or config.yml
. These settings are not set by default
like most other settings in Ganeti Web Manager. Be sure to actually configure your database
settings.
Configuring SQLite in config.yml
:
DATABASES:
default:
ENGINE: django.db.backends.sqlite3
NAME: /opt/ganeti_webmgr/ganeti.db
USER: # Not used with sqlite3.
PASSWORD: # Not used with sqlite3.
HOST: # Set to empty string for localhost.
# Not used with sqlite3.
PORT: # Set to empty string for default.
#Not used with sqlite3.
Configuring SQLite in settings.py
:
DATABASES = {
'default': {
'ENGINE': 'django.db.backends.sqlite3',
'NAME': '/opt/ganeti_webmgr/ganeti.db',
'USER': '', # Not used with sqlite3.
'PASSWORD': '', # Not used with sqlite3.
'HOST': '', # Set to empty string for localhost.
# Not used with sqlite3.
'PORT': '', # Set to empty string for default.
#Not used with sqlite3.
}
}
For PostgreSQL, Oracle, and MySQL, replace .sqlite
in the engine field with
.postgresql_psycopg2
, .oracle
, or .mysql
respectively:
# config.yml
DATABASES:
default:
ENGINE: django.db.backends.mysql
NAME: database_name
USER: database_user
PASSWORD: database_password
HOST: db.example.com
PORT: # leave blank for default port
Secret Keys¶
By default Ganeti Web Manager creates a SECRET_KEY
and a WEB_MGR_API_KEY
for you the
first time you run a command using django-admin.py
, and puts this key into a
file located at /opt/ganeti_webmgr/.secrets/SECRET_KEY.txt
. This is to make
initial setup easier, and less hassle for you. This key is used for protection
against CSRF attacks as well as encrypting your Ganeti cluster password in the
database. Once set, you should avoid changing this if possible.
If you want to have better control of this setting you can set the
SECRET_KEY
setting in config.yml
like so:
SECRET_KEY: ANW61553mYBKJft6pYPLf1JbTeHKLutU
Please do not use this value, but instead generate something random yourself. You do not want to share this, or make it publicly accessible. This can be used to avoid protections Ganeti Web Manager has implemented for you.
If you are using the SSH Keys feature to add keys to VMs with Ganeti Web Manager, you
will also need to set the WEB_MGR_API_KEY
setting in config.yml
or keep
the value created for you in
/opt/ganeti_webmgr/.secrets/WEB_MGR_API_KEY.txt
. This is the same value you
will use when running the sshkeys.py
or sshkeys.sh
scripts. Similarly,
it should be something impossible to guess, much like the SECRET_KEY
setting:
WEB_MGR_API_KEY: 3SqmsCnNiuDY9lAVIh3Tx3RIJfql6sIc
Again, do not use the value above. If anyone gains access to this key, and you are using the sshkeys feature, it will allow them to add arbitrary ssh keys to your Virtual Machines.
Note
We have not included these settings in the example config.yml
at the bottom of this page for security reasons. We do not want anyone
copying the values we’ve used in our examples for security prone
settings such as this. If you wish to set these yourself, you will
need to manually add them to config.yml
.
Time zone and locale¶
Ganeti Web Manager supports time zones, translations and localizations for currency, time, etc. To find the correct time zone for your locale, visit the List of time zones. For language codes, see List of language codes. Not every language is supported by Ganeti Web Manager.
Date and datetime format follows the Django date format. For instance,
d/m/Y
will result in dates formatted with two-digit days, months, and four-
digit years.
A standard configuration might look something like this:
TIME_ZONE: America/Los_Angeles
DATE_FORMAT: d/m/Y
DATETIME_FORMAT: "d/m/Y H:i"
LANGUAGE_CODE: "en-US"
# Enable i18n (translations) and l10n (locales, currency, times).
USE_I18N: True
# If you set this to False, Django will not format dates, numbers and
# calendars according to the current locale
USE_L10N: True
Registration and e-mails¶
To set up Ganeti Web Manager to send registration emails, you’ll need access to an SMTP server. You can configure the SMTP host, port, and email address:
EMAIL_HOST: localhost
EMAIL_PORT: 25
DEFAULT_FROM_EMAIL: noreply@example.org
For more complicated email setups, refer to the Django email documentation.
Allowing open registration means that users can create their own new accounts in
Ganeti Web Manager. The users will then have the number of days set in
ACCOUNT_ACTIVATION_DAYS
to activate their account:
ALLOW_OPEN_REGISTRATION: True
ACCOUNT_ACTIVATION_DAYS: 7
More details can be found in the Open Registration documentation.
Site root and static files¶
The site root, static root, and static url must also be set when configuring Ganeti Web Manager.
The SITE_ROOT
is the subdirectory on the website:
http://example.com/<SITE_ROOT>
. The current default is empty.
The STATIC_ROOT
is the directory on the filesystem that Ganeti Web Manager‘s static
files will be placed when you run django-admin.py collectstatic
. The current
default is /opt/ganeti_webmgr/collected_static
.
STATIC_URL
is the full url where Ganeti Web Manager will look when trying to obtain
static files. The default for this is currently /static
which means it will
try looking at the same domain it is hosted on. For example if your hostname is
www.yourwebsite.com it will look for them at www.yourwebsite.com/static
.
A standard configuration, putting Ganeti Web Manager at the root of the domain, might look like this:
SITE_ROOT: /web_admin
STATIC_ROOT: /opt/ganeti_webmgr/collected_static
STATIC_URL: www.yourwebsite.com/static
Haystack Search Settings¶
Haystack is Ganeti Web Manager‘s way of performing search indexing. It currently has one setting which you need to worry about.
HAYSTACK_WHOOSH_PATH
is the path to a location on the filesystem which Ganeti Web Manager
will store the search index files. This location needs to be readable and
writable by whatever user is running Ganeti Web Manager. Example users might be the apache
or nginx user, or whatever user you’ve set the Ganeti Web Manager process to run as.
The default path for this setting is /opt/ganeti_webmgr/whoosh_index
.
An example of this setting might be:
HAYSTACK_WHOOSH_PATH: /opt/ganeti_webmgr/whoosh_index
More details can be found in the search documentation.
Sentry¶
Ganeti Web Manager can log server errors to Sentry, an online exception tracker. To enable
tracking, copy the raven.py.dist
settings file to raven.py
and set the
dsn
value. If you are using hosted Sentry, you can get the dsn
value by
logging into your Sentry account and copying it directly from
their documentation.
Other settings¶
ITEMS_PER_PAGE
is a setting allowing you to globally limit or extend the
number of items on a page listing things. This this currently defaults to 15
items per page, so your pages will have up to 15 VMs, clusters and node’s listed
on a single page. You might adjust this to a lower value if you find that
loading a large number on a single page slows things down.
ITEMS_PER_PAGE: 20
Set VNC_PROXY
to the hostname:port
pair of your VNCAuthProxy server.
The VNC AuthProxy does not need to run on the same server as Ganeti Web Manager.
VNC_PROXY: "localhost:8888"
LAZY_CACHE_REFRESH
(milliseconds) is the fallback cache timer that is checked
when the object is instantiated. It defaults to 600000ms, or ten minutes.
LAZY_CACHE_REFRESH: 600000
RAPI_CONNECT_TIMEOUT
is how long Ganeti Web Manager will wait in seconds before timing
out when requesting data from the ganeti cluster.
RAPI_CONNECT_TIMEOUT: 10
Sample configuration¶
An annotated sample YAML configuration file is shown below:
# config.yml
# Django settings for ganeti_webmgr project.
##### Database Configuration #####
DATABASES:
default:
ENGINE: django.db.backends.sqlite3
# django.db.backends.sqlite3
# django.db.backends.postgresql
# django.db.backends.mysql
# django.db.backends.oracle
# django.db.backends.postgresql_psycopg2
# Or path to database file if using sqlite3.
NAME: /opt/ganeti_webmgr/ganeti.db
USER: # Not used with sqlite3.
PASSWORD: # Not used with sqlite3.
HOST: # Not used with sqlite3.
PORT: # Set to empty string for default.
#Not used with sqlite3.
##### End Database Configuration #####
# Site name and domain referenced by some modules to provide links back to
# the site.
SITE_NAME: Ganeti Web Manager
SITE_DOMAIN: "localhost:8000"
# http://en.wikipedia.org/wiki/List_of_tz_zones_by_name
TIME_ZONE: America/Los_Angeles
DATE_FORMAT: d/m/Y
DATETIME_FORMAT: "d/m/Y H:i"
# Language code for this installation. All choices can be found here:
# http://www.i18nguy.com/unicode/language-identifiers.html
LANGUAGE_CODE: "en_US"
##### End Locale Configuration #####
# Enable i18n (translations) and l10n (locales, currency, times).
# You really have no good reason to disable these unless you are only
# going to be using GWM in English.
USE_I18N: True
# If you set this to False, Django will not format dates, numbers and
# calendars according to the current locale
USE_L10N: True
# prefix used for the site. ie. http://myhost.com/<SITE_ROOT>
# for the django standalone server this should be
# for apache this is the url the site is mapped to, probably /tracker
SITE_ROOT: ""
# Absolute path to the directory that holds media.
# Example: /home/media/media.lawrence.com/
STATIC_ROOT: /opt/ganeti_webmgr/collected_static
# URL that handles the media served from STATIC_ROOT.
# XXX contrary to django docs, do not use a trailing slash. It makes urls
# using this url easier to read. ie. {{STATIC_URL}}/images/foo.png
STATIC_URL: /static
##### Registration Settings #####
ACCOUNT_ACTIVATION_DAYS: 7
# Email settings for registration
EMAIL_HOST: localhost
EMAIL_PORT: 25
DEFAULT_FROM_EMAIL: noreply@example.org
# Whether users should be able to create their own accounts.
# False if accounts can only be created by admins.
ALLOW_OPEN_REGISTRATION: True
##### End Registration Settings #####
####### Haystack Search Index settings #######
HAYSTACK_WHOOSH_PATH: /opt/ganeti_webmgr/whoosh_index
####### End Haystack Search Index settings #######
# GWM Specifics
# The maximum number of items on a single list page
ITEMS_PER_PAGE: 15
# Ganeti Cached Cluster Objects Timeouts
# LAZY_CACHE_REFRESH (milliseconds) is the fallback cache timer that is
# checked when the object is instantiated. It defaults to 600000ms, or ten
# minutes.
LAZY_CACHE_REFRESH: 600000
# VNC Proxy. This will use a proxy to create local ports that are forwarded to
# the virtual machines. It allows you to control access to the VNC servers.
#
# Expected values:
# String syntax: HOST:CONTROL_PORT, for example: localhost:8888. If
# localhost is used then the proxy will only be accessible to clients and
# browsers on localhost. Production servers should use a publicly accessible
# hostname or IP
#
# Firewall Rules:
# Control Port: 8888, must be open between Ganeti Web Manager and Proxy
# Internal Ports: 12000+ must be open between the Proxy and Ganeti Nodes
# External Ports: default is 7000-8000, must be open between Proxy and Client
# Flash Policy Server: 843, must open between Proxy and Clients
VNC_PROXY: "localhost:8888"
# This is how long gwm will wait before timing out when requesting data from the
# ganeti cluster.
RAPI_CONNECT_TIMEOUT: 10