Hosts File Configuration

Overview

The hosts file (also called inventory file) is the central configuration document that defines your entire cellular network deployment. It specifies:

What network functions to deploy
Where they run (IP addresses, network segments)
How they're configured (service-specific parameters)
Customer-specific settings (PLMN, credentials, features)

File Location

Hosts files live under the top-level hosts/ directory (set as the Ansible inventory in ansible.cfg), organized by customer:

hosts/
└── Customer_Name/
    └── host_files/
        ├── Production.yml
        ├── Staging.yml
        └── Customer_Lab.yml

Filenames are arbitrary — there is one file per deployment, typically named after the deployment or site (e.g. Production.yml, Staging.yml) rather than a fixed production.yml/staging.yml/lab.yml scheme.

Example Hosts File Structure

Here's a simplified example showing the key sections:

# EPC Components
mme:
  hosts:
    customer-mme01:
      ansible_host: 10.10.1.15
      gateway: 10.10.1.1
      host_vm_network: "vmbr1"
      mme_code: 1
      network_name_short: Customer
      tac_list: [600, 601, 602]

sgw:
  hosts:
    customer-sgw01:
      ansible_host: 10.10.1.25
      gateway: 10.10.1.1
      cdrs_enabled: true

pgwc:
  hosts:
    customer-pgw01:
      ansible_host: 10.10.1.21
      gateway: 10.10.1.1
      ip_pools:
        - '100.64.16.0/24'

# IMS Components
pcscf:
  hosts:
    customer-pcscf01:
      ansible_host: 10.10.4.165

# Support Services
license_server:
  hosts:
    customer-licenseserver:
      ansible_host: 10.10.2.150

# Global Variables
all:
  vars:
    ansible_connection: ssh
    ansible_password: password
    customer_name_short: customer
    plmn_id:
      mcc: '001'
      mnc: '01'

Common Host Parameters

Network Configuration

Every host typically includes:

pcscf:
  hosts:
    customer-pcscf01:
      ansible_host: 10.10.1.15      # IP address for SSH access
      gateway: 10.10.1.1             # Default gateway
      host_vm_network: "vmbr1"       # name of NIC to use on Hypervisor

Note: For guidance on IP address planning and network segmentation strategies, see the IP Planning Standard which outlines the recommended four-subnet architecture for OmniCore deployments.

Proxmox Users: The host_vm_network parameter specifies which bridge to use. See Proxmox VM/LXC Deployment for automated provisioning.

VM Resource Allocation

For services needing specific resources:

num_cpus: 4                    # CPU cores
memory_mb: 8192                # RAM in megabytes
proxmoxLxcDiskSizeGb: 50      # Disk size in GB

Service-Specific Parameters

Each network function has its own parameters. Examples:

MME:

mme_code: 1                    # MME identifier (1-255)
mme_gid: 1                     # MME Group ID
network_name_short: Customer   # Network name (shown on phones)
network_name_long: Customer Network
tac_list: [600, 601, 602]     # Tracking Area Codes

PGW:

ip_pools:                      # IP pools for subscribers
  - '100.64.16.0/24'
  - '100.64.17.0/24'
combined_CP_UP: false          # Separate control/user plane

For detailed explanation of what each variable controls, see: Configuration Reference

Application Server:

online_charging_enabled: true  # Enable OCS integration
tas_branch: "main"             # Software branch to deploy
gateways_folder: "gateways_prod"  # SIP gateway configuration

Global Variables Section

The all:vars section contains settings that apply to the entire deployment:

all:
  vars:
    # Authentication
    ansible_connection: ssh
    ansible_password: password
    ansible_become_password: password

    # Customer Identity
    customer_name_short: customer
    customer_legal_name: "Customer Inc."
    site_name: "Chicago DC1"
    region: US

    # PLMN (Mobile Network) Identifier
    plmn_id:
      mcc: '001'              # Mobile Country Code
      mnc: '01'               # Mobile Network Code
      mnc_longform: '001'     # Zero-padded MNC

    # Network Names
    network_name_short: Customer
    network_name_long: Customer Network

    # APT Repository
    # Note: If apt_cache_servers group is defined with hosts,
    # use_apt_cache defaults to true and apt_repo.apt_server
    # defaults to the first cache server's IP automatically
    apt_repo:
      apt_server: "10.254.10.223"
      apt_repo_username: "customer"
      apt_repo_password: "secure-password"
    use_apt_cache: false

    # Timezone
    TZ: America/Chicago

Understanding Host Groups

Ansible organizes hosts into groups that correspond to roles:

When you run a playbook targeting mme, it applies to all hosts in the mme:hosts: section.

The diagram above shows only a handful of groups. Many more exist, including ocs, crm, smsc, omnimessage, dra, xcap, homer, cbc, and the 5GC groups amf, smf, and upf, among others.

Configuration with Jinja2 Templates

Ansible uses Jinja2 templating to generate configuration files from the variables defined in your hosts file and group_vars.

How Jinja2 Works

Example Template Usage

Hosts file defines:

plmn_id:
  mcc: '001'
  mnc: '01'
customer_name_short: acme

Jinja2 template (in role):

# mme_config.yml.j2
network:
  plmn:
    mcc: {{ plmn_id.mcc }}
    mnc: {{ plmn_id.mnc }}
  operator: {{ customer_name_short }}
  realm: epc.mnc{{ plmn_id.mnc_longform }}.mcc{{ plmn_id.mcc }}.3gppnetwork.org

Generated configuration file:

network:
  plmn:
    mcc: 001
    mnc: 01
  operator: acme
  realm: epc.mnc001.mcc001.3gppnetwork.org

Common Jinja2 Patterns

Accessing nested variables:

{{ plmn_id.mcc }}
{{ apt_repo.apt_server }}

Conditional logic:

{% if online_charging_enabled %}
  charging:
    enabled: true
    ocs_ip: {{ ocs_ip }}
{% endif %}

Loops:

tracking_areas:
{% for tac in tac_list %}
  - {{ tac }}
{% endfor %}

Formatting:

# Zero-pad to 3 digits
mnc{{ '%03d' | format(plmn_id.mnc|int) }}

Overriding Variables with group_vars

While the hosts file defines infrastructure and host-specific settings, group_vars can override defaults for groups of hosts.

See: Group Variables Configuration

Complete Example Hosts File

Here's a more complete example (with sensitive data obscured):

# EPC Core
mme:
  hosts:
    customer-mme01:
      ansible_host: 10.10.1.15
      gateway: 10.10.1.1
      host_vm_network: "vmbr1"
      mme_code: 1
      mme_gid: 1
      network_name_short: Customer
      network_name_long: Customer Network
      tac_list: [600, 601, 602, 603]
      omnimme:
        sgw_selection_method: "random_peer"
        pgw_selection_method: "random_peer"

sgw:
  hosts:
    customer-sgw01:
      ansible_host: 10.10.1.25
      gateway: 10.10.1.1
      host_vm_network: "vmbr1"
      cdrs_enabled: true

pgwc:
  hosts:
    customer-pgw01:
      ansible_host: 10.10.1.21
      gateway: 10.10.1.1
      host_vm_network: "vmbr1"
      ip_pools:
        - '100.64.16.0/24'
      combined_CP_UP: false

hss:
  hosts:
    customer-hss01:
      ansible_host: 10.10.2.140
      gateway: 10.10.2.1
      host_vm_network: "vmbr2"

# IMS Core
pcscf:
  hosts:
    customer-pcscf01:
      ansible_host: 10.10.4.165
      gateway: 10.10.4.1
      host_vm_network: "vmbr4"

icscf:
  hosts:
    customer-icscf01:
      ansible_host: 10.10.3.55
      gateway: 10.10.3.1
      host_vm_network: "vmbr3"

scscf:
  hosts:
    customer-scscf01:
      ansible_host: 10.10.3.45
      gateway: 10.10.3.1
      host_vm_network: "vmbr3"

applicationserver:
  hosts:
    customer-as01:
      ansible_host: 10.10.3.60
      gateway: 10.10.3.1
      host_vm_network: "vmbr3"
      online_charging_enabled: false
      gateways_folder: "gateways_prod"

# Support Services
license_server:
  hosts:
    customer-licenseserver:
      ansible_host: 10.10.2.150
      gateway: 10.10.2.1
      host_vm_network: "vmbr2"

monitoring:
  hosts:
    customer-oam01:
      ansible_host: 10.10.2.135
      gateway: 10.10.2.1
      host_vm_network: "vmbr2"
      num_cpus: 4
      memory_mb: 8192

dns:
  hosts:
    customer-dns01:
      ansible_host: 10.10.2.177
      gateway: 10.10.2.1
      host_vm_network: "vmbr2"

# Global Variables
all:
  vars:
    ansible_connection: ssh
    ansible_password: password
    ansible_become_password: password

    customer_name_short: customer
    customer_legal_name: "Customer Network Inc."
    site_name: "Primary DC"
    region: US
    TZ: America/Chicago

    # PLMN Configuration
    plmn_id:
      mcc: '001'
      mnc: '01'
      mnc_longform: '001'
    diameter_realm: epc.mnc{{ plmn_id.mnc_longform }}.mcc{{ plmn_id.mcc }}.3gppnetwork.org

    # Network Names
    network_name_short: Customer
    network_name_long: Customer Network
    tac_list: [600, 601]

    # APT Configuration
    apt_repo:
      apt_server: "10.254.10.223"
      apt_repo_username: "customer"
      apt_repo_password: "secure-password"
    use_apt_cache: false

    # Charging Configuration
    charging:
      data:
        online_charging:
          enabled: false
      voice:
        online_charging:
          enabled: true
          domain: "mnc{{ plmn_id.mnc_longform }}.mcc{{ plmn_id.mcc }}.3gppnetwork.org"

    # Firewall Rules
    firewall:
      allowed_ssh_subnets:
        - '10.0.0.0/8'
        - '192.168.0.0/16'
      allowed_ue_voice_subnets:
        - '10.0.0.0/8'
      allowed_signaling_subnets:
        - '10.0.0.0/8'

    # Hypervisor Configuration (Proxmox VM example)
    proxmoxServers:
      customer-prxmx01:
        # deployment_type omitted → defaults to "vm"
        proxmoxServerAddress: 10.10.0.100
        proxmoxServerPort: 8006
        proxmoxApiTokenName: Customer
        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

    # For an LXC site, set deployment_type: lxc and
    # proxmoxLxcOsTemplate in each proxmoxServers entry instead.

See Proxmox VM/LXC Deployment for complete Proxmox setup and configuration details.

Product Documentation References

For detailed configuration of each component, refer to the official product documentation:

OmniCore Components:

OmniCore Documentation: https://docs.omnitouch.com.au/docs/repos/OmniCore
OmniHSS - Home Subscriber Server
OmniSGW - Serving Gateway (Control plane)
OmniPGW - Packet Gateway (Control plane)
OmniUPF - User Plane Function
OmniDRA - Diameter Routing Agent
OmniTWAG - Trusted WLAN Access Gateway

OmniCall Components:

OmniCall Documentation: https://docs.omnitouch.com.au/docs/repos/OmniCall
OmniTAS - IMS Application Server (VoLTE/VoNR)
OmniCall CSCF - Call Session Control Functions
OmniMessage - SMS Center
OmniMessage SMPP - SMPP Protocol Support
OmniSS7 - SS7 Signaling Stack
VisualVoicemail - Voicemail

OmniCharge/OmniCRM:

OmniCharge Documentation: https://docs.omnitouch.com.au/docs/repos/OmniCharge

Introduction to Ansible Deployment - Overall deployment process
Configuration Reference - Complete guide to all configuration variables
Group Variables Configuration - Overriding default configurations
IP Planning Standard - Network architecture and IP allocation guidelines
Netplan Configuration - Secondary IPs and advanced network configuration
APT Cache System - Package distribution
License Server - License management
Deployment Architecture Overview - Complete system view

Next Steps

Create your hosts file based on this template
Define your PLMN and network identity
Configure APT repository access
Set up license server
Customize with group_vars as needed
Deploy with Ansible playbooks

Overview​

File Location​

Example Hosts File Structure​

Common Host Parameters​

Network Configuration​

VM Resource Allocation​

Service-Specific Parameters​

Global Variables Section​

Understanding Host Groups​

Configuration with Jinja2 Templates​

How Jinja2 Works​

Example Template Usage​

Common Jinja2 Patterns​

Overriding Variables with group_vars​

Complete Example Hosts File​

Product Documentation References​

Related Documentation​

Next Steps​