Group Variables Configuration

Overview

The group_vars directory is where you store custom configuration files that override default templates.

This is where your customer-specific configurations live - SIP trunks, Diameter routing rules, SMS routing logic, dialplans, and any other customizations where you don't want the default config - It lives in group_vars.

Location: hosts/{Customer}/group_vars/

Roles resolve this directory at runtime as group_vars_omnicore - the group_vars/ directory sitting adjacent to the inventory directory ({{ inventory_dir.rsplit('/', 1)[0] }}/group_vars/). Wherever a file path below references {{ group_vars_omnicore }}, it points at this directory.

How It Works

Ansible roles have default configuration templates. To customize for a specific deployment, place your custom files in group_vars and reference them in your hosts file.

Role Default Template → group_vars Override (if specified) → Deployed Config

Example 1: Custom Configuration Template (OmniMessage)

Some components accept custom Jinja2 configuration templates.

File Structure

hosts/Customer/
└── group_vars/
    └── smsc_controller.exs        # Your custom config template

Reference in Hosts File

omnimessage:
  hosts:
    customer-smsc-controller01:
      ansible_host: 10.10.3.219
      gateway: 10.10.3.1
      host_vm_network: "vmbr3"
      smsc_template_config: smsc_controller.exs   # Reference your template filename in group_vars

What happens:

Ansible finds smsc_template_config: smsc_controller.exs
Looks in hosts/Customer/group_vars/smsc_controller.exs
Templates it with Jinja2 (can use {{ inventory_hostname }}, {{ plmn_id.mcc }}, etc.)
Deploys to /etc/omnimessage/runtime.exs
Restarts the service

Without smsc_template_config, the default template from the role is used.

Configuration details: See https://docs.omnitouch.com.au/docs/repos/OmniCall

Example 2: Configuration File Collections (OmniTAS Gateways & Dialplans)

Some components use directories of configuration files.

File Structure

hosts/Customer/
└── group_vars/
    ├── gateways_prod/              # SIP gateway configs
    │   ├── gateway_carrier1.xml
    │   ├── gateway_carrier2.xml
    │   └── gateway_emergency.xml
    ├── gateways_lab/               # Lab gateways
    │   └── gateway_test.xml
    ├── dialplan/                   # Call routing rules (default)
    │   ├── mo_dialplan.xml         # Mobile Originated (outgoing)
    │   ├── mt_dialplan.xml         # Mobile Terminated (incoming)
    │   └── emergency.xml
    └── dialplan_lab/               # Lab dialplans
        └── mo_dialplan.xml

Reference in Hosts File

applicationserver:
  hosts:
    customer-tas01:
      ansible_host: 10.10.3.60
      gateway: 10.10.3.1
      host_vm_network: "vmbr3"
      gateways_folder: "gateways_prod"   # Reference your gateway folder to use on this host
      dialplan_folder: "dialplan"         # Optional - defaults to "dialplan" if not set

What happens:

Ansible finds gateways_folder: "gateways_prod"
Copies all files from hosts/Customer/group_vars/gateways_prod/ to /etc/freeswitch/sip_profiles/
Copies all files from hosts/Customer/group_vars/dialplan/ (or the folder specified by dialplan_folder) to OmniTAS templates directory
Services load the configurations

Different environments: Use different folders per environment:

gateways_folder: "gateways_lab"
gateways_folder: "gateways_prod"
gateways_folder: "gateways_customer_specific"
dialplan_folder: "dialplan_lab"
dialplan_folder: "dialplan_prod"

Configuration details: See https://docs.omnitouch.com.au/docs/repos/OmniCall

Example 3: Custom Configuration Template (OmniHSS)

The Home Subscriber Server accepts custom runtime configuration templates.

File Structure

hosts/Customer/
└── group_vars/
    └── hss_runtime.exs.j2        # Your custom HSS config template

Reference in Hosts File

omnihss:
  hosts:
    customer-hss01:
      ansible_host: 10.10.3.50
      gateway: 10.10.3.1
      host_vm_network: "vmbr3"
      hss_template_config: hss_runtime.exs.j2   # Reference your template filename in group_vars

What happens:

Ansible finds hss_template_config: hss_runtime.exs.j2
Looks in hosts/Customer/group_vars/hss_runtime.exs.j2
Templates it with Jinja2 (can use {{ inventory_hostname }}, {{ plmn_id.mcc }}, etc.)
Deploys to /etc/omnihss/runtime.exs
Restarts the service

Without hss_template_config, the default template from the role is used.

Configuration details: See https://docs.omnitouch.com.au/docs/repos/OmniCore

Example 4: Custom Configuration Template (OmniMME)

The Mobility Management Entity accepts custom runtime configuration templates.

File Structure

hosts/Customer/
└── group_vars/
    └── mme_runtime.exs.j2        # Your custom MME config template

Reference in Hosts File

omnimme:
  hosts:
    customer-mme01:
      ansible_host: 10.10.3.51
      gateway: 10.10.3.1
      host_vm_network: "vmbr3"
      mme_template_config: mme_runtime.exs.j2   # Reference your template filename in group_vars

What happens:

Ansible finds mme_template_config: mme_runtime.exs.j2
Looks in hosts/Customer/group_vars/mme_runtime.exs.j2
Templates it with Jinja2 (can use {{ inventory_hostname }}, {{ plmn_id.mcc }}, etc.)
Deploys to /etc/omnimme/runtime.exs
Restarts the service

Without mme_template_config, the default template from the role is used.

Configuration details: See https://docs.omnitouch.com.au/docs/repos/OmniCore

Example 5: Required Configuration Files (OmniCRM)

OmniCRM is sourced exclusively from group_vars - there is no role default to fall back on. The API and UI config are deliberately not baked into the role so a missing file fails the run loudly rather than silently shipping another site's secrets.

File Structure

hosts/Customer/
└── group_vars/
    ├── crm_config.yaml          # API config (required)
    ├── customer_crm.env         # UI .env (required, referenced by crm_env_override)
    ├── cellSites.txt            # Optional cell site data
    ├── constants.js             # Optional cell broadcast message templates
    └── site_data.json           # Optional cell broadcast geo bounds

Reference in Hosts File

omnicrm:
  hosts:
    customer-crm01:
      ansible_host: 10.10.3.70
      gateway: 10.10.3.1
      host_vm_network: "vmbr3"
      crm_env_override: customer_crm.env   # REQUIRED - UI .env filename in group_vars
      cell_sites: cellSites.txt            # Optional
      message_templates: constants.js      # Optional
      site_data: site_data.json            # Optional

What happens:

The API role templates {{ group_vars_omnicore }}/crm_config.yaml to /etc/omnicrm/OmniCRM-API/crm_config.yaml. This file is required - there is no role default.
The UI role templates {{ group_vars_omnicore }}/{{ crm_env_override }} to /etc/omnicrm/OmniCRM-UI/.env. crm_env_override is required - if it is unset the run fails.
If cell_sites, message_templates, or site_data are set, their files are copied into the UI (cell site list, cell broadcast templates, and geo bounds respectively).

Important: Unlike the template-config examples above, there is no role fallback. Both crm_config.yaml and crm_env_override must be present or the deployment fails.

Configuration details: See https://docs.omnitouch.com.au/docs/repos/OmniCore

Example 6: Provisioning Data Directory (OmniHSS)

The OmniHSS provisioning service (services/provision_omnihss.yml) reads subscriber and profile data from a dedicated omnihss/ directory inside group_vars.

File Structure

hosts/Customer/
└── group_vars/
    └── omnihss/
        ├── subscribers.csv             # Subscribers to provision
        ├── apn_identifiers.json
        ├── apn_qos_profiles.json
        ├── apn_profiles.json
        ├── eir_rules.json
        ├── ims_profiles.json
        ├── epc_profiles.json
        ├── roaming_rules.json
        ├── roaming_profiles.json
        ├── flow_information_rules.json
        ├── charging_rules.json
        └── pcrf_profiles.json

What happens:

The service reads {{ group_vars_omnicore }}/omnihss/subscribers.csv for the list of subscribers to provision.
It reads the accompanying JSON files from the same omnihss/ directory (apn_identifiers.json, apn_qos_profiles.json, apn_profiles.json, eir_rules.json, ims_profiles.json, epc_profiles.json, roaming_rules.json, roaming_profiles.json, flow_information_rules.json, charging_rules.json, pcrf_profiles.json) to define the APN, QoS, IMS, EPC, roaming, flow, charging and PCRF data applied to those subscribers.

Configuration details: See https://docs.omnitouch.com.au/docs/repos/OmniCore

Example 7: Grafana SMTP Credentials (Monitoring)

The monitoring role's grafana.ini template wires the Grafana alert email (SMTP) settings from group_vars. The user and password have no role default - they are deliberately not baked in, so a missing value fails the run loudly rather than shipping credentials.

Reference in Hosts File

monitoring:
  hosts:
    customer-oam01:
      ansible_host: 10.10.3.135
      gateway: 10.10.3.1
      host_vm_network: "vmbr3"
      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 - defaults to in-v3.mailjet.com:587

What happens:

grafana_smtp_user and grafana_smtp_password are templated into the [smtp] section of /etc/grafana/grafana.ini. Both are required - there is no fallback.
grafana_smtp_host is optional and defaults to in-v3.mailjet.com:587 if not set.

Configuration details: See https://docs.omnitouch.com.au/docs/repos/OmniCore

Real-World Directory Structure Example

hosts/Customer/
├── host_files/
│   └── production.yml          # Hosts file references group_vars files
└── group_vars/
    ├── smsc_controller.exs     # OmniMessage custom template
    ├── smsc_smpp.exs           # OmniMessage SMPP custom template
    ├── tas_runtime.exs.j2      # TAS custom template
    ├── hss_runtime.exs.j2      # HSS custom template
    ├── mme_runtime.exs.j2      # MME custom template
    ├── dra_runtime.exs.j2      # DRA custom template
    ├── pgwc_runtime.exs.j2     # PGW custom template
    ├── dea_runtime.exs.j2      # DEA custom template
    ├── upf_config.yaml         # UPF configuration
    ├── crm_config.yaml         # CRM configuration
    ├── stp.j2                  # SS7 STP template
    ├── hlr.j2                  # SS7 HLR template
    ├── camel.j2                # SS7 CAMEL template
    ├── ipsmgw.j2               # IP-SM-GW template
    ├── omnicore_smsc_ims.yaml.j2  # SMSC IMS config
    ├── pytap.yaml              # TAP3 configuration
    ├── sip_profiles/           # SIP gateways (folder)
    │   └── gateway_otw.xml
    ├── dialplan/               # Call routing rules (folder)
    │   ├── mo_dialplan.xml     # Mobile Originated
    │   ├── mt_dialplan.xml     # Mobile Terminated
    │   └── mo_emergency.xml    # Emergency routing
    └── omnihss/                # OmniHSS provisioning data (folder)
        ├── subscribers.csv         # Subscribers to provision
        ├── apn_identifiers.json
        ├── apn_qos_profiles.json
        ├── apn_profiles.json
        ├── eir_rules.json
        ├── ims_profiles.json
        ├── epc_profiles.json
        ├── roaming_rules.json
        ├── roaming_profiles.json
        ├── flow_information_rules.json
        ├── charging_rules.json
        └── pcrf_profiles.json

Common Parameters That Reference group_vars

Parameter	Component	References	Type
`smsc_template_config`	omnimessage	Jinja2 template file (e.g., `smsc_controller.exs`)	File
`smsc_smpp_template_config`	omnimessage_smpp	Jinja2 template file (e.g., `smsc_smpp.exs`)	File
`gateways_folder`	applicationserver	Folder name (e.g., `gateways_prod`)	Folder
`dialplan_folder`	applicationserver	Folder name (e.g., `dialplan`) - defaults to `dialplan` if not set	Folder
`tas_runtime_template`	applicationserver	Jinja2 template file (e.g., `tas_runtime.exs.j2`) - defaults to `tas_runtime.exs.j2` if not set	File
`hss_template_config`	omnihss	Jinja2 template file (e.g., `hss_runtime.exs.j2`)	File
`mme_template_config`	omnimme	Jinja2 template file (e.g., `mme_runtime.exs.j2`)	File
`dra_template_config`	dra	Jinja2 template file (e.g., `dra_runtime.exs.j2`)	File
`pgwc_template_config`	pgwc	Jinja2 template file (e.g., `pgwc_runtime.exs.j2`)	File
`frr_template_config`	omniupf	Jinja2 template file (e.g., `frr.conf.j2`)	File
SS7 templates	ss7 (various roles)	Jinja2 template files (e.g., `stp.j2`, `hlr.j2`, `camel.j2`)	File
`crm_config.yaml`	omnicrm	API config file - required, sourced only from `{{ group_vars_omnicore }}/crm_config.yaml` (no role default)	File
`crm_env_override`	omnicrm	UI .env filename (e.g., `customer_crm.env`) - required, no role default	File
`cell_sites`	omnicrm	Optional cell site data file (e.g., `cellSites.txt`)	File
`message_templates`	omnicrm	Optional cell broadcast message templates (e.g., `constants.js`)	File
`site_data`	omnicrm	Optional cell broadcast geo bounds (e.g., `site_data.json`)	File
`grafana_smtp_user`	monitoring	Grafana SMTP user - required, no role default	Value
`grafana_smtp_password`	monitoring	Grafana SMTP password - required, no role default	Value
`grafana_smtp_host`	monitoring	Optional Grafana SMTP host - defaults to `in-v3.mailjet.com:587`	Value
OmniHSS provisioning	omnihss	`omnihss/` directory with `subscribers.csv` + profile JSON files	Folder
Config YAMLs	Various components	Direct config files (e.g., `upf_config.yaml`, `crm_config.yaml`)	File

Key Points

group_vars holds customizations - Overrides for default configurations
Reference by name - Use parameters like smsc_template_config or gateways_folder
Templates support Jinja2 - Access any Ansible variable with {{ variable_name }}
Folders deploy everything - All files in referenced folders are copied
Version control everything - Commit all group_vars to Git

When to Use group_vars

✅ Use group_vars for:

Custom component configuration templates
SIP gateway definitions
Call routing dialplans
Diameter routing rules
Customer-specific settings that override defaults

❌ Don't use group_vars for:

Basic host configuration (IPs, hostnames) - Use hosts file
One-off testing - Use host-specific vars in hosts file
Temporary changes - Edit on target, commit to group_vars if permanent

Configuration Reference - All host parameters and what they do
Hosts File Configuration - How to structure hosts files
OmniCall Configuration: https://docs.omnitouch.com.au/docs/repos/OmniCall - What goes in the config files
OmniCore Configuration: https://docs.omnitouch.com.au/docs/repos/OmniCore - Component configuration details

Overview​

How It Works​

Example 1: Custom Configuration Template (OmniMessage)​

File Structure​

Reference in Hosts File​

Example 2: Configuration File Collections (OmniTAS Gateways & Dialplans)​

File Structure​

Reference in Hosts File​

Example 3: Custom Configuration Template (OmniHSS)​

File Structure​

Reference in Hosts File​

Example 4: Custom Configuration Template (OmniMME)​

File Structure​

Reference in Hosts File​

Example 5: Required Configuration Files (OmniCRM)​

File Structure​

Reference in Hosts File​

Example 6: Provisioning Data Directory (OmniHSS)​

File Structure​

Example 7: Grafana SMTP Credentials (Monitoring)​

Reference in Hosts File​

Real-World Directory Structure Example​

Common Parameters That Reference group_vars​

Key Points​

When to Use group_vars​

Related Documentation​

Overview

How It Works

Example 1: Custom Configuration Template (OmniMessage)

File Structure

Reference in Hosts File

Example 2: Configuration File Collections (OmniTAS Gateways & Dialplans)

File Structure

Reference in Hosts File

Example 3: Custom Configuration Template (OmniHSS)

File Structure

Reference in Hosts File

Example 4: Custom Configuration Template (OmniMME)

File Structure

Reference in Hosts File

Example 5: Required Configuration Files (OmniCRM)

File Structure

Reference in Hosts File

Example 6: Provisioning Data Directory (OmniHSS)

File Structure

Example 7: Grafana SMTP Credentials (Monitoring)

Reference in Hosts File

Real-World Directory Structure Example

Common Parameters That Reference group_vars

Key Points

When to Use group_vars

Related Documentation