Configuration

Configure Ralph for LDAP authentication, OpenStack synchronization, and advanced features

This guide covers advanced configuration options for Ralph, including LDAP/Active Directory authentication and OpenStack cloud synchronization.

Configuration Structure

Ubuntu Package Installation

Configuration files are located in /etc/ralph/:

• /etc/ralph/ralph.conf - Main configuration
• /etc/ralph/conf.d/database.conf - Database settings
• /etc/ralph/conf.d/redis.conf - Redis cache settings
• /etc/ralph/conf.d/gunicorn.conf - Gunicorn server settings
• /etc/ralph/conf.d/cache.conf - Cache configuration

Settings are environment variables that Django reads on startup.

Docker Installation

Set environment variables in your docker-compose.yml file under the environment section.

LDAP Authentication

Ralph supports authentication via LDAP and Active Directory systems.

Installation

1. Install LDAP Requirements

   Ubuntu:

   pip install python-ldap django-auth-ldap
   

   Docker: LDAP dependencies are included in the base image.

2. Configure LDAP Backend

   Add LDAP as an authentication backend in your local settings file.

   Create /etc/ralph/conf.d/ldap.conf (Ubuntu) or add to environment:

   AUTHENTICATION_BACKENDS = (
       'django_auth_ldap.backend.LDAPBackend',
       'django.contrib.auth.backends.ModelBackend',
   )
   
   LOGGING['loggers']['django_auth_ldap'] = {
       'handlers': ['file'],
       'propagate': True,
       'level': 'DEBUG',
   }
   

Active Directory Configuration

Example configuration for Active Directory:

import ldap
from django_auth_ldap.config import LDAPSearch, GroupOfNamesType

# Server settings
AUTH_LDAP_SERVER_URI = "ldap://activedirectory.domain:389"
AUTH_LDAP_BIND_DN = "CN=ralph_service,OU=ServiceAccounts,DC=domain,DC=com"
AUTH_LDAP_BIND_PASSWORD = "your_secure_password"
AUTH_LDAP_PROTOCOL_VERSION = 3

# User search settings
AUTH_LDAP_USER_USERNAME_ATTR = "sAMAccountName"
AUTH_LDAP_USER_SEARCH_BASE = "DC=domain,DC=internal"
AUTH_LDAP_USER_SEARCH_FILTER = '(&(objectClass=user)({0}=%(user)s))'.format(
    AUTH_LDAP_USER_USERNAME_ATTR
)
AUTH_LDAP_USER_SEARCH = LDAPSearch(
    AUTH_LDAP_USER_SEARCH_BASE,
    ldap.SCOPE_SUBTREE,
    AUTH_LDAP_USER_SEARCH_FILTER
)

# User attribute mapping
AUTH_LDAP_USER_ATTR_MAP = {
    "first_name": "givenName",
    "last_name": "sn",
    "email": "mail",
    "company": "company",
    "manager": "manager",
    "department": "department",
    "employee_id": "employeeID",
    "location": "officeName",
    "country": "ISO-country-code",
}

OpenDJ Configuration

For OpenDJ LDAP servers, use uid for username:

AUTH_LDAP_USER_USERNAME_ATTR = "uid"

from django_auth_ldap.config import GroupOfUniqueNamesType

AUTH_LDAP_GROUP_TYPE = GroupOfUniqueNamesType()
AUTH_LDAP_GROUP_SEARCH = LDAPSearch(
    "DC=organization,DC=internal",
    ldap.SCOPE_SUBTREE,
    '(structuralObjectClass=groupOfUniqueNames)'
)

LDAP Group Mapping

Map LDAP groups to Ralph permissions:

from ralph.account.ldap import MappedGroupOfNamesType

AUTH_LDAP_GROUP_MAPPING = {
    'CN=_gr_ralph,OU=Groups,DC=domain,DC=com': "staff",
    'CN=_gr_ralph_assets_buyer,OU=Groups,DC=domain,DC=com': "assets-buyer",
    'CN=_gr_ralph_assets_staff,OU=Groups,DC=domain,DC=com': "assets-staff",
    'CN=_gr_ralph_admin,OU=Groups,DC=domain,DC=com': "superuser",
}

AUTH_LDAP_MIRROR_GROUPS = True
AUTH_LDAP_GROUP_TYPE = MappedGroupOfNamesType(name_attr="cn")
AUTH_LDAP_GROUP_SEARCH = LDAPSearch(
    "DC=organization,DC=internal",
    ldap.SCOPE_SUBTREE,
    '(objectClass=group)'
)

Nested LDAP Groups

For nested group support:

AUTH_LDAP_NESTED_GROUPS = {
    'CN=_gr_ralph_users,OU=Groups,DC=domain,DC=com': "staff",
}
AUTH_LDAP_QUERY_PAGE_SIZE = 500  # LDAP default page limit is 1000

User Filtering

Restrict which LDAP users can access Ralph:

AUTH_LDAP_USER_FILTER = '(|(memberOf=CN=_gr_ralph_group1,OU=IT,' \
    'DC=domain,DC=com)(memberOf=CN=_gr_ralph_group2,OU=IT,' \
    'DC=domain,DC=com))'

For OpenDJ, use isMemberOf instead of memberOf.

Synchronize Users

Sync LDAP users to Ralph database:

# Ubuntu
sudo ralphctl ldap_sync

# Docker
docker-compose exec web ralph ldap_sync

The script reports progress every 100 items.

ObjectClass Values by LDAP Implementation

• Active Directory: objectClass=user
• Novell eDirectory: objectClass=inetOrgPerson
• OpenLDAP: objectClass=posixAccount

OpenStack Synchronization

Ralph supports one-way synchronization with OpenStack clouds, importing projects and instances in read-only mode.

Installation

1. Install OpenStack Requirements

   Ubuntu:

   pip install openstacksdk python-keystoneclient python-novaclient
   

   Docker: OpenStack dependencies are included in the base Ralph image.

2. Configure OpenStack Instances

   Add OpenStack configuration to your settings file.

   Create /etc/ralph/conf.d/openstack.conf or add to your local settings:

   OPENSTACK_INSTANCES = [
       {
           'username':     'ralph_service',
           'password':     'secure_password',
           'tenant_name':  'admin',
           'version':      '2.0',
           'auth_url':     'http://openstack.example.com:35357/v2.0/',
           'tag':          'production'
       },
       {
           'username':     'ralph_service',
           'password':     'secure_password',
           'tenant_name':  'admin',
           'version':      '2.0',
           'auth_url':     'http://openstack-dev.example.com:35357/v2.0/',
           'tag':          'development'
       },
   ]
   

   Configuration Parameters:

   • username: OpenStack user with permissions to list all projects and instances
   • tenant_name: Project/tenant for authentication
   • version: OpenStack API version (currently only 2.x supported)
   • auth_url: OpenStack Keystone API endpoint
   • tag: Tag added to all imported Cloud Projects and Cloud Hosts

Run Synchronization

Execute OpenStack sync manually:

# Ubuntu
sudo ralphctl openstack_sync

# Docker
docker-compose exec web ralph openstack_sync

Automated Synchronization

Schedule regular syncs using cron (Ubuntu):

# Edit crontab
sudo crontab -e

# Add sync every hour
0 * * * * /usr/bin/ralphctl openstack_sync >> /var/log/ralph/openstack_sync.log 2>&1

For Docker, use a scheduler container or external cron job:

0 * * * * docker-compose -f /path/to/docker-compose.yml exec -T web ralph openstack_sync

How It Works

1. First Run: Imports all Cloud Projects, Cloud Hosts, and Cloud Flavors from OpenStack
2. Subsequent Runs: Updates existing objects and deletes those no longer in OpenStack
3. Read-Only Import: Most fields are read-only; only Service Environment, Tags, and Remarks can be modified
4. Inheritance: Cloud Host service environments inherit from their parent Cloud Project

Database Configuration

MySQL Configuration

Ubuntu (/etc/ralph/conf.d/database.conf):

DATABASE_ENGINE=mysql
DATABASE_NAME=ralph_ng
DATABASE_USER=ralph_ng
DATABASE_PASSWORD=secure_password
DATABASE_HOST=localhost
DATABASE_PORT=3306

Docker (docker-compose.yml):

services:
  web:
    environment:
      DATABASE_ENGINE: mysql
      DATABASE_NAME: ralph_ng
      DATABASE_USER: ralph_ng
      DATABASE_PASSWORD: secure_password
      DATABASE_HOST: db
      DATABASE_PORT: 3306

PostgreSQL Configuration

Ubuntu:

DATABASE_ENGINE=postgresql
DATABASE_NAME=ralph_ng
DATABASE_USER=ralph_ng
DATABASE_PASSWORD=secure_password
DATABASE_HOST=localhost
DATABASE_PORT=5432

Redis Configuration

Ubuntu (/etc/ralph/conf.d/redis.conf):

REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0
REDIS_PASSWORD=""
REDIS_TIMEOUT=10.0
REDIS_CONNECT_TIMEOUT=1.0

Redis Sentinel (High Availability)

REDIS_SENTINEL_ENABLED=1
REDIS_SENTINEL_HOSTS="sentinel1:26379,sentinel2:26379,sentinel3:26379"
REDIS_CLUSTER_NAME="ralph-master"
REDIS_SENTINEL_SOCKET_TIMEOUT=0.2

Gunicorn Configuration

Ubuntu (/etc/ralph/conf.d/gunicorn.conf):

GUNICORN_BIND=0.0.0.0:8000
GUNICORN_WORKERS=4
GUNICORN_ACCESSLOG=/var/log/ralph/gunicorn.access.log
GUNICORN_ERRORLOG=/var/log/ralph/gunicorn.error.log
GUNICORN_LOGLEVEL=info
GUNICORN_USER=ralphsrv
GUNICORN_GROUP=ralphsrv
GUNICORN_TIMEOUT=30

Set GUNICORN_WORKERS to (2 * CPU_cores) + 1 for optimal performance.

Cache Configuration

Enable Redis caching for improved performance:

Ubuntu (/etc/ralph/conf.d/cache.conf):

# Store sessions in Redis
STORE_SESSIONS_IN_REDIS=1

# Use Redis for Django cache
USE_REDIS_CACHE=1

# Optional: Use different Redis DB for cache
REDIS_CACHE_DB=1
REDIS_CACHE_PASSWORD=""

Logging Configuration

Ubuntu (/etc/ralph/ralph.conf):

LOG_FILEPATH=/var/log/ralph/ralph.log
LOG_LEVEL=INFO  # DEBUG, INFO, WARNING, ERROR, CRITICAL

Static Files and Media

STATIC_ROOT=/usr/share/ralph/static
MEDIA_ROOT=/var/local/ralph/media

After changing static file settings, collect static files:

# Ubuntu
sudo ralphctl collectstatic --noinput

# Docker
docker-compose exec web ralph collectstatic --noinput

Security Settings

Debug Mode

Never enable debug mode in production!

# Development only
RALPH_DEBUG=1

# Production
RALPH_DEBUG=0

Allowed Hosts

For production, specify allowed hostnames:

ALLOWED_HOSTS = ['ralph.example.com', 'ralph-internal.example.com']

Secret Key

Generate a unique secret key for your installation:

python -c 'from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())'

Add to configuration:

SECRET_KEY='your-generated-secret-key-here'

Applying Configuration Changes

After modifying configuration:

Ubuntu:

sudo systemctl restart ralph.service

Docker:

docker-compose restart web

Next Steps

Data Migration

Learn how to import data from Ralph 2 or other sources