Skip to main content

Configuration Reference

Overview​

This document provides a comprehensive reference for configuring OmniCore deployments through hosts files. Configuration is primarily defined in host inventory files with minimal group_vars overrides needed for modern deployments.

For product-specific documentation, see:

Configuration Approach​

Modern OmniCore deployments use a simplified configuration model:

Key Principle: Most configuration is defined directly in the hosts file, and role defaults handle many settings. Some components, however, are configured exclusively from group_vars and have no role default — notably OmniCRM (see below). In those cases a missing value fails the run loudly rather than falling back to a default.

Security note: Several role defaults are insecure placeholders intended for lab use only and must be overridden for any real deployment. Examples include database passwords (e.g. sql_pass: password, omnitouch2024) and APT repository credentials (omni/omni). Always set real, unique secrets in your inventory or group_vars before deploying.

Network Planning​

Before configuring hosts, review the IP Planning Standard for guidance on:

  • Network segmentation strategies
  • IP address allocation
  • Subnet organization
  • Public IP handling

Common Host Parameters​

#ToDo - Just say to check hosts-file-configuration.md for this

Service-Specific Flags​

cdrs_enabled: True               # Enable CDR generation
in_pool: False                   # Exclude from load balancing pool
populate_crm: False              # Populate CRM with initial data

Global Variables (all:vars)​

The all:vars section contains deployment-wide settings. Modern deployments use minimal global variables, with many settings covered by role defaults. Note the exceptions below (OmniCRM, Grafana SMTP) where configuration must be supplied explicitly because no role default exists.

Essential Global Variables​

Authentication & Access​

ansible_connection: ssh
ansible_user: root
ansible_password: password
ansible_become_password: password

Alternative: Use SSH keys instead of passwords:

ansible_ssh_private_key_file: '/path/to/key.pem'

Customer Identity​

customer_name_short: omnitouch
customer_legal_name: "Customer Lab"
site_name: Customer-Site
region: AU
TZ: Australia/Melbourne

PLMN Configuration​

plmn_id:
  mcc: '001'              # Mobile Country Code (3 digits)
  mnc: '01'              # Mobile Network Code (2-3 digits)
  mnc_longform: '001'     # Zero-padded MNC (always 3 digits)

diameter_realm: epc.mnc{{ plmn_id.mnc_longform }}.mcc{{ plmn_id.mcc }}.3gppnetwork.org

Purpose: Uniquely identifies your mobile network. Used for Diameter realm construction.

Network Names​

network_name_short: Omni
network_name_long: Omnitouch
tac_list: [10100,100]            # Default TAC list (can override per-MME)

Displayed: Network names shown on UE devices in Settings > Mobile Network.

DNS Configuration​

manage_resolv_conf: True         # Set to False to prevent Ansible from managing /etc/resolv.conf

Note: When manage_resolv_conf is set to False, Ansible will not overwrite /etc/resolv.conf on that host. This is useful for hosts that require custom DNS configuration or are managed by external systems. Can be set per-host in the inventory or globally in all:vars.

APT Repository Configuration​

Automatic Defaults: When an apt_cache_servers group is defined with hosts:

  • use_apt_cache automatically defaults to True (unless explicitly set to False)
  • apt_repo.apt_server automatically defaults to the first cache server's IP
# Manual configuration (optional if apt_cache_servers group exists)
use_apt_cache: True              # Use local APT cache vs direct repo access

apt_repo:
  apt_server: "10.10.1.114"      # APT cache server or repo server
  # Credentials only needed when use_apt_cache: False
  # apt_repo_username: "omni"
  # apt_repo_password: "omni"

# Binary downloads and cache sync configuration
# Used for: (1) downloading binaries from /releases/ when use_apt_cache: false
#           (2) cache server syncing from Omnitouch when use_apt_cache: true
remote_apt_server: "apt.omnitouch.com.au"
remote_apt_user: "omni"
remote_apt_password: "omni"

See: APT Cache System

License Server​

# Optional: auto-derived from the `license_server` inventory group when unset.
# Each host in that group becomes https://<ansible_host>:8443/api.
license_server_api_urls: ["https://10.10.2.150:8443/api"]
license_enforced: false          # Effective default is false (roles/omnihss/defaults/main.yml)

Note: If a license_server group exists in the inventory, license_server_api_urls is derived automatically from its members; you only need to set it manually to override that behaviour.

See: License Server

MME Settings​

The MME selects S-GW and P-GW peers using a configurable method, set per gateway under omnimme. The method can be a single value or split by home/roaming traffic. Valid values are dns_lookup (resolve peers via DNS) and random_peer (pick from configured peers).

omnimme:
  sgw:
    selection_method: random_peer        # single value, or...
    # selection_method:
    #   home: random_peer
    #   roaming: dns_lookup
  pgw:
    selection_method:
      home: random_peer
      roaming: dns_lookup

SAEGW Settings​

mtu: 1400                        # Maximum Transmission Unit

OmniCRM Settings​

OmniCRM configuration is sourced exclusively from the customer's group_vars (under hosts/); no defaults are baked into the role. crm_env_override is required — it names the per-site .env template, and a missing value fails the run loudly rather than shipping another site's secrets. The remaining files are optional (skipped if unset). All paths are resolved relative to the customer's group_vars directory.

crm_env_override: my-site.env    # REQUIRED: per-site UI .env template (no default)
crm_config.yaml                  # API config (crm_config.yaml in group_vars; copied to the API)
cell_sites: cellSites.txt        # optional: cell site data for the UI
message_templates: constants.js  # optional: cell broadcast message templates
site_data: site_data.json        # optional: cell broadcast geo bounds

Grafana SMTP Settings​

Used by the monitoring role for Grafana alert email. grafana_smtp_user and grafana_smtp_password are required (no default — they must be set); grafana_smtp_host defaults to in-v3.mailjet.com:587. See roles/monitoring/templates/grafana/grafana.ini.

grafana_smtp_user: "smtp-user"           # REQUIRED, no default
grafana_smtp_password: "smtp-password"   # REQUIRED, no default
grafana_smtp_host: "in-v3.mailjet.com:587"  # optional, this is the default

IMS Settings​

ims_dra_support: False           # Route IMS through DRA
enable_homer: False              # Enable Homer SIP capture

RAN Monitor Configuration​

use_nokia_monitor: True
use_casa_monitor: True
install_influxdb: True

influxdb_user: monitor
influxdb_password: "secure-password"
influxdb_organisation_name: omnitouch
influxdb_nokia_bucket_name: nokia-monitor
influxdb_casa_bucket_name: casa-monitor
influxdb_operator_token: "generated-token"
influxdb_url: http://127.0.0.1:8086

enable_pm_collection: False
enable_alarm_collection: False
enable_location_collection: False
enable_ran_status_collection: True
enable_nokia_rectifier_collection: False
collection_interval_in_seconds: 120

ran_monitor:
  sql:
    user: ran_monitor
    password: "secure-password"
    database_host: 127.0.0.1
    database_name: ran_monitor
  influxdb:
    address: 10.10.2.135
    port: 8086
  nokia:
    airscales:
    - address: 10.7.15.66
      name: site-Lab-Airscale
      port: 8080
      web_password: nemuuser
      web_username: Nemuadmin

Firewall Configuration​

firewall:
  allowed_ssh_subnets:
    - '10.0.1.0/24'
    - '10.0.0.0/24'
  allowed_ue_voice_subnets:
    - '10.0.1.0/24'
  allowed_carrier_voice_subnets:
    - '10.0.1.0/24'
  allowed_signaling_subnets:
    - '10.0.1.0/24'

Roaming DNS Servers​

roaming_dns_servers:
  wildcard: ['10.0.99.1']
  # Carrier-specific DNS (PLMN-based)
  123456:                        # Example Carrier 1
    - '10.10.2.197'
  654321:                        # Example Carrier 2
    - '10.10.0.4'

Local Users (SSH Keys)​

local_users:
  usera:
    name: Example User A
    public_key: "ssh-rsa AAAAB3Nza..."
  userb:
    name: Example User B
    public_key: "ssh-ed25519 AAAAC3..."

Hypervisor Configuration​

Proxmox​

A site deploys as either VMs or LXC containers, selected per proxmoxServers entry via deployment_type (default vm). All entries in a site must agree; mixing fails validation. See Proxmox Deployment for the full walkthrough.

VM site​

proxmoxServers:
  customer-prxmx01:
    # deployment_type omitted → defaults to "vm"
    proxmoxServerAddress: 10.10.0.100
    proxmoxServerPort: 8006
    proxmoxApiTokenName: AnsibleToken
    proxmoxApiTokenSecret: "token-secret"
    proxmoxNodeName: pve01
    proxmoxTemplateName: ubuntu-24.04-cloud-init-template
    proxmoxTemplateId: 9000
    proxmoxTemplateUser: omnitouch        # optional cloud-init username; defaults to the first local_users key
    proxmoxTemplatePassword: omnitouch    # optional cloud-init password; defaults to the cloud-init username
    storage: SSD_RAID0            # optional, default VM storage

LXC site​

proxmox_lxc_nameserver: "1.1.1.1"  # optional, injected into LXCs at create

proxmoxServers:
  customer-prxmx01:
    deployment_type: lxc
    proxmoxServerAddress: 10.10.0.100
    proxmoxServerPort: 8006
    proxmoxApiTokenName: AnsibleToken
    proxmoxApiTokenSecret: "token-secret"
    proxmoxNodeName: pve01
    proxmoxLxcOsTemplate: "local:vztmpl/ubuntu-24.04-standard_24.04-2_amd64.tar.zst"
    proxmoxLxcDefaultStorage: SSD_RAID0   # optional, rootfs fallback

Group-level overrides (both types)​

dns:
  vars:
    proxmox_interface: vmbr0              # required: bridge
    gateway: 10.10.0.1                    # required
    netmask: 255.255.255.0                # required
    vlanid: 100                           # optional
    proxmoxLxcCores: 2                    # optional (LXC only)
    proxmoxLxcMemoryMb: 4096              # optional (LXC only)
    proxmoxLxcDiskSizeGb: 30              # optional (LXC only)
    proxmoxLxcRootFsStorageName: SSD_RAID0 # optional (LXC only)
    host_vm_network: vmbr1                # optional bridge override

VMware vCenter​

vcenter_ip: "vcenter.example.com"
vcenter_username: "administrator@vsphere.local"
vcenter_password: "password"
vcenter_datacenter: "DC1"
vcenter_vm_template: ubuntu-24.04-model
vcenter_vm_disk_size: 50
vcenter_folder: "Omnicore"
host_vm_network: "Management"

vhosts:
  "10.0.0.23":
    vcenter_cluster_ip: 10.0.0.23
    vcenter_datastore: "datastore1 (3)"

netmask: 255.255.255.0

Product Documentation​

For detailed operational guides and advanced configuration:

Last updated on