> ## Documentation Index > Fetch the complete documentation index at: https://mintlify.com/ansible/awx/llms.txt > Use this file to discover all available pages before exploring further. # Configuration > Configure AWX settings, environment variables, and system parameters ## Overview AWX provides extensive configuration options through settings files, environment variables, and the REST API. Configuration settings control system behavior, authentication, logging, capacity, and more. ## Configuration Methods ### Database Settings AWX stores most configuration settings in the database, allowing runtime changes without restarts. Access settings via the REST API: ```bash theme={null} # View all setting categories curl -X GET https://awx.example.org/api/v2/settings/ \ -H "Authorization: Bearer " # View system settings curl -X GET https://awx.example.org/api/v2/settings/system/ \ -H "Authorization: Bearer " # Update a setting curl -X PATCH https://awx.example.org/api/v2/settings/system/ \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"SCHEDULE_MAX_JOBS": 20}' ``` ### File-Based Settings Settings defined in Python files take precedence over database settings. File-based settings are marked as read-only in the API. **Location**: `/etc/tower/conf.d/*.py` Example configuration file: ```python theme={null} # /etc/tower/conf.d/custom.py ALLOWED_HOSTS = ['awx.example.org', 'localhost'] DEBUG = False SESSION_COOKIE_AGE = 3600 ``` ### Environment Variables Many settings can be configured via environment variables: ```bash theme={null} # Container group settings export MY_POD_NAMESPACE=awx export AWX_CONTAINER_GROUP_DEFAULT_JOB_LABEL=ansible_job # Custom secret key export TOWER_SECRET_KEY= ``` ## Key Configuration Settings ### System Settings #### SECRET\_KEY **Location**: `/etc/tower/SECRET_KEY`\ **Purpose**: Encrypts sensitive data in the database (credentials, tokens, etc.) ```bash theme={null} # Generate a new secret key python3 -c "import base64, os; print(base64.encodebytes(os.urandom(32)).decode().rstrip())" # Store in file echo "" > /etc/tower/SECRET_KEY chmod 600 /etc/tower/SECRET_KEY ``` Changing SECRET\_KEY requires re-encrypting all secrets in the database. Use the `regenerate_secret_key` management command. #### ALLOWED\_HOSTS **Default**: `[]`\ **Description**: List of valid hostnames/domains for AWX ```python theme={null} ALLOWED_HOSTS = ['awx.example.org', '*.internal.example.com'] ``` #### TIME\_ZONE **Default**: `'UTC'`\ **Description**: System timezone ```python theme={null} TIME_ZONE = 'America/New_York' ``` ### Session Settings #### SESSION\_COOKIE\_AGE **Default**: `1800` (30 minutes)\ **Description**: Session lifetime in seconds ```python theme={null} SESSION_COOKIE_AGE = 3600 # 1 hour ``` #### SESSIONS\_PER\_USER **Default**: `-1` (unlimited)\ **Description**: Maximum concurrent sessions per user ```python theme={null} SESSIONS_PER_USER = 5 ``` #### SESSION\_COOKIE\_SECURE **Default**: `True`\ **Description**: Send session cookies only over HTTPS ```python theme={null} SESSION_COOKIE_SECURE = True ``` ### Database Settings #### PostgreSQL Configuration ```python theme={null} DATABASES = { 'default': { 'ENGINE': 'django.db.backends.postgresql', 'NAME': 'awx', 'USER': 'awx', 'PASSWORD': os.environ.get('DATABASE_PASSWORD'), 'HOST': 'postgres.example.org', 'PORT': '5432', 'ATOMIC_REQUESTS': True, 'OPTIONS': { 'sslmode': 'verify-full', 'sslrootcert': '/etc/pki/tls/certs/ca-bundle.crt', }, } } ``` #### Connection Pool Settings ```python theme={null} LISTENER_DATABASES = { 'default': { 'OPTIONS': { 'keepalives': 1, 'keepalives_idle': 5, 'keepalives_interval': 5, 'keepalives_count': 5, }, } } ``` ### Job Settings #### JOB\_EVENT\_WORKERS **Default**: `4`\ **Description**: Number of processes for processing job events ```python theme={null} JOB_EVENT_WORKERS = 8 # Increase for high-throughput systems ``` #### JOB\_EVENT\_BUFFER\_SECONDS **Default**: `1`\ **Description**: Time to buffer events before database write ```python theme={null} JOB_EVENT_BUFFER_SECONDS = 2 ``` #### SCHEDULE\_MAX\_JOBS **Default**: `10`\ **Description**: Maximum pending jobs from a single schedule ```python theme={null} SCHEDULE_MAX_JOBS = 20 ``` ### Task Manager Settings #### START\_TASK\_LIMIT **Default**: `100`\ **Description**: Maximum jobs to start per task manager cycle ```python theme={null} START_TASK_LIMIT = 200 ``` #### TASK\_MANAGER\_TIMEOUT **Default**: `300` (5 minutes)\ **Description**: Task manager timeout in seconds ```python theme={null} TASK_MANAGER_TIMEOUT = 600 # 10 minutes ``` ### Logging Settings #### LOG\_ROOT **Default**: `/var/log/tower/`\ **Description**: Directory for AWX log files ```python theme={null} LOG_ROOT = '/var/log/awx/' ``` #### Logging Configuration ```python theme={null} LOGGING = { 'version': 1, 'disable_existing_loggers': False, 'handlers': { 'file': { 'class': 'logging.handlers.RotatingFileHandler', 'filename': '/var/log/tower/tower.log', 'maxBytes': 1024 * 1024 * 100, # 100 MB 'backupCount': 10, }, }, 'loggers': { 'awx': { 'handlers': ['file'], 'level': 'INFO', }, }, } ``` ### Proxy and Network Settings #### PROXY\_IP\_ALLOWED\_LIST **Default**: `[]`\ **Description**: Trusted proxy IPs for X-Forwarded-For headers ```python theme={null} PROXY_IP_ALLOWED_LIST = ['10.0.1.100', '10.0.1.101'] REMOTE_HOST_HEADERS = ['HTTP_X_FORWARDED_FOR', 'REMOTE_ADDR', 'REMOTE_HOST'] ``` #### CSRF\_TRUSTED\_ORIGINS **Default**: `[]`\ **Description**: Trusted origins for CSRF protection ```python theme={null} CSRF_TRUSTED_ORIGINS = ['https://awx.example.org', 'https://awx-lb.example.org'] ``` ### Execution Environment Settings #### GLOBAL\_JOB\_EXECUTION\_ENVIRONMENTS **Description**: Default execution environments for jobs ```python theme={null} GLOBAL_JOB_EXECUTION_ENVIRONMENTS = [ { 'name': 'Custom EE', 'image': 'registry.example.org/ee:latest' } ] ``` #### CONTROL\_PLANE\_EXECUTION\_ENVIRONMENT **Description**: Execution environment for project updates ```python theme={null} CONTROL_PLANE_EXECUTION_ENVIRONMENT = 'quay.io/ansible/awx-ee:latest' ``` ### Container Group Settings #### AWX\_CONTAINER\_GROUP\_K8S\_API\_TIMEOUT **Default**: `10`\ **Description**: Kubernetes API timeout in seconds ```bash theme={null} export AWX_CONTAINER_GROUP_K8S_API_TIMEOUT=30 ``` #### AWX\_CONTAINER\_GROUP\_POD\_PENDING\_TIMEOUT **Default**: `"2h"`\ **Description**: Maximum time for pod to enter running state ```python theme={null} AWX_CONTAINER_GROUP_POD_PENDING_TIMEOUT = "4h" ``` ## Configuration Best Practices ### 1. Use File-Based Settings for Critical Config Store infrastructure settings in files to prevent accidental changes: ```python theme={null} # /etc/tower/conf.d/production.py DATABASES = {...} # Database connection ALLOWED_HOSTS = [...] # Valid hostnames SESSION_COOKIE_SECURE = True # Security settings ``` ### 2. Environment-Specific Configuration Organize settings by environment: ```bash theme={null} /etc/tower/conf.d/ ├── production.py # Production-specific settings ├── database.py # Database configuration └── security.py # Security settings ``` ### 3. Secrets Management * Never commit secrets to version control * Use environment variables for sensitive data * Rotate SECRET\_KEY regularly * Use external secret management (Vault, AWS Secrets Manager) ### 4. Configuration Version Control Track non-sensitive configuration: ```bash theme={null} # Track configuration files cd /etc/tower/conf.d git init git add *.py git commit -m "Initial AWX configuration" ``` ### 5. Validate Configuration Changes Test settings before applying: ```bash theme={null} # Check for configuration errors awx-manage check # Test database connectivity awx-manage check_db # Validate migrations awx-manage check_migrations ``` ## Management Commands ### View Current Settings ```bash theme={null} # List all settings awx-manage shell -c "from django.conf import settings; print(dir(settings))" # Check specific setting awx-manage shell -c "from django.conf import settings; print(settings.ALLOWED_HOSTS)" ``` ### Regenerate Secret Key Re-encrypt all database secrets with a new key: ```bash theme={null} # Generate and apply new key awx-manage regenerate_secret_key # Use custom key from environment export TOWER_SECRET_KEY= awx-manage regenerate_secret_key --use-custom-key ``` This operation is irreversible and affects all encrypted data. Backup your database first. ### Database Management ```bash theme={null} # Check database connection awx-manage check_db # Run migrations awx-manage migrate # Create preload data awx-manage create_preload_data ``` ## Troubleshooting ### Setting Not Taking Effect 1. Check if setting is file-defined (read-only): ```bash theme={null} curl https://awx.example.org/api/v2/settings/system/ | jq '.SETTING_NAME' ``` 2. Verify setting category: ```bash theme={null} curl https://awx.example.org/api/v2/settings/ ``` 3. Clear cache and restart services: ```bash theme={null} awx-manage shell -c "from django.core.cache import cache; cache.clear()" systemctl restart awx-service ``` ### Database Connection Issues ```bash theme={null} # Test PostgreSQL connection awx-manage check_db # Check database settings awx-manage shell -c "from django.conf import settings; print(settings.DATABASES)" ``` ### Permission Errors ```bash theme={null} # Verify file permissions chown awx:awx /etc/tower/SECRET_KEY chmod 600 /etc/tower/SECRET_KEY # Check directory permissions chown -R awx:awx /var/lib/awx chmod -R 750 /var/lib/awx ``` ## Related Resources * [Capacity Planning](/admin/capacity) - Configure instance capacity * [Security Configuration](/admin/security) - Security hardening * [Metrics Configuration](/admin/metrics) - Monitoring setup * [Backup and Restore](/admin/backup-restore) - Data protection This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.