Omnitouch Network Services - Ansible Deployment System

Overview

This repository contains Ansible playbooks, roles, and configuration for deploying complete cellular network solutions (4G EPC, 5G Core, IMS, SS7) from Omnitouch Network Services. The system enables automated, repeatable deployments of production-grade telecom infrastructure.

What Gets Deployed

OmniCore (4G/5G Packet Core Platform)

• 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

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

OmniCall (Voice & Messaging Platform)

• OmniCall CSCF - Call Session Control (P-CSCF, I-CSCF, S-CSCF)
• OmniTAS - IMS Application Server (VoLTE, VoNR, VoWiFi)
• OmniMessage - SMS Center (SMS-C)
• OmniMessage SMPP - SMPP protocol support
• OmniSS7 - SS7 signaling components (STP, HLR, CAMEL)
• VisualVoicemail - Voicemail functionality

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

OmniCharge/OmniCRM

• OmniCRM - Customer relationship management, self-signup, billing

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

Support Services

• License Server - Centralized licensing
• DNS - Network DNS resolution
• Monitoring - Prometheus & Grafana
• APT Cache - Local package repository (optional)

Documentation

Getting Started

1. Introduction to Ansible Deployment
   • Overview of how Ansible is used to deploy cellular networks
   • Key concepts: inventory, roles, playbooks, variables
   • Deployment workflow and benefits

Core Concepts

2. IP Planning Standard

   • Network architecture and subnet allocation
   • Four-subnet deployment model
   • IP address assignment guidelines
   • Public IP handling
   • Implementation methods (separate NICs vs VLANs)

3. Hosts File Configuration

   • Defining your network topology
   • Configuring network functions and their parameters
   • Understanding PLMN configuration
   • Working with Jinja2 templates

4. Configuration Reference

   • Complete guide to all configuration variables
   • OmniCore component settings (HSS, PGW, SGW, DRA)
   • OmniCall component settings (TAS, Message, CSCF)
   • Runtime configuration explained
   • Variable reference with examples

5. Group Variables and Configuration

   • Customizing deployments without modifying roles
   • Variable precedence and merging
   • Jinja2 template integration
   • Best practices for configuration overrides

Infrastructure

6. APT Cache System

   • Package distribution options (local cache vs. public repository)
   • How pre-compiled packages are delivered
   • Setting up offline/air-gapped deployments
   • Local APT cache configuration

7. License Server

   • Centralized license management
   • Deployment models (local, cloud, hybrid)
   • License-controlled features
   • High availability and troubleshooting

• Netplan Configuration - Host network/interface configuration
• Proxmox Deployment - Provisioning VMs on Proxmox
• Service Playbooks - Reference for the services/*.yml playbooks
• OmniHSS Replication & Node Operations - Active-active mesh, adding/seeding HSS nodes, validation

Observability

• Centralized Logging - Log aggregation pipeline
• Monitoring & Observability - Prometheus, Grafana and metrics

Utilities

8. Utility Playbooks
   • Health Check: Generate HTML reports of system health, service status and versions
   • Common/Setup Users: Base system and user configuration
   • Reboot: Graceful system reboots
   • IP Plan Generator: Network topology documentation
   • Backup/Restore: services/backup.yml for backups, util_playbooks/restore_hss.yml to restore the HSS
   • Troubleshooting: Packet capture retrieval, MTU updates

Complete Picture

9. Deployment Architecture Overview
   • How all components fit together
   • Network segmentation and security
   • Service dependencies and deployment order
   • Scaling and high availability patterns

Quick Start

Prerequisites

• Ubuntu 22.04+ control node (amd64)
• uv — required; manages the Python environment and dependencies
• Python 3.12+ (uv can install a suitable interpreter automatically)
• SSH access to target hosts
• Appropriate credentials for APT repository
• Valid Omnitouch license

Installation

1. Get the Repository

2. Install uv if it isn't already installed. Use whichever method suits your control node — see the uv installation docs. For example:

pipx install uv                                    # via pipx
curl -LsSf https://astral.sh/uv/install.sh | sh    # standalone installer

3. Install Ansible and dependencies. This creates a python venv.

On Ubuntu and Debian:

apt install libssh-dev
uv sync

On MacOS (using brew):

brew install libssh
CFLAGS="-I $(brew --prefix)/include -I ext -L $(brew --prefix)/lib -lssh" uv sync

4. Activate the environment (keep it activated for all ansible commands):

source .venv/bin/activate

5. Install the required Ansible collections (from requirements.yml):

ansible-galaxy collection install -r requirements.yml

6. Verify installation:

ansible --version

Linting

ansible-lint runs in CI. To run it yourself:

uv sync --group lint            # installs ansible-lint (a dev-only group, not shipped in the .deb)
uv run ansible-lint [paths...]  # whole repo, or just the files you touched

Configuration

1. Create your hosts file based on your network design. Customer inventories live under the top-level hosts/ directory (services/hosts is a symlink to it). Copy an existing example as a starting point:

cp hosts/Omnicore_Omnitouch/host_files/yktn_Nick2.yml hosts/YourCustomer/host_files/production.yml

See: Hosts File Configuration

2. Customize with group_vars (optional):

mkdir -p hosts/YourCustomer/group_vars
# Create customization files as needed

See: Group Variables Configuration

3. Configure APT repository access in your hosts file:

For deployments with a local APT cache server (recommended):

apt_cache_servers:
  hosts:
    your-apt-cache:
      ansible_host: 192.168.1.100
      gateway: 192.168.1.1

# No additional configuration needed!
# use_apt_cache and apt_repo.apt_server are automatically set

Or for direct repository access:

all:
  vars:
    apt_repo:
      apt_server: "packages.omnitouch.com"
      apt_repo_username: "your-username"
      apt_repo_password: "your-password"
    use_apt_cache: false  # Use public repo directly (not cache)

See: APT Cache System

4. Configure license server:

all:
  vars:
    license_server_api_urls: ["https://licenses.omnitouch.com/api"]
    license_enforced: true

See: License Server

Deployment

Deploy your complete network:

# Deploy entire network
ansible-playbook -i services/hosts/YourCustomer/host_files/production.yml services/all.yml

# Or deploy specific components:
ansible-playbook -i services/hosts/YourCustomer/host_files/production.yml services/epc.yml
ansible-playbook -i services/hosts/YourCustomer/host_files/production.yml services/ims.yml

# Support services deploy via individual playbooks (no combined infra playbook):
ansible-playbook -i services/hosts/YourCustomer/host_files/production.yml services/dns.yml
ansible-playbook -i services/hosts/YourCustomer/host_files/production.yml services/monitoring.yml
ansible-playbook -i services/hosts/YourCustomer/host_files/production.yml services/license_server.yml
ansible-playbook -i services/hosts/YourCustomer/host_files/production.yml services/apt_cache.yml

Repository Structure

Omnicore/
├── README.md                    # This file
├── docs/                        # Documentation
│   ├── ansible-introduction.md
│   ├── IP_Planning_Standard.md
│   ├── hosts-file-configuration.md
│   ├── group-vars-configuration.md
│   ├── apt-cache-system.md
│   ├── license-server.md
│   ├── utility-playbooks.md     # Utility playbooks guide
│   ├── service-playbooks.md     # Service playbooks guide
│   └── deployment-architecture.md
├── hosts/                       # Customer inventories (top-level)
│   └── Customer_Name/
│       ├── host_files/          # Inventory files
│       └── group_vars/          # Variable overrides
├── services/                    # Ansible playbooks
│   ├── hosts -> ../hosts        # Symlink to top-level hosts/
│   ├── epc.yml                  # Deploy 4G core
│   ├── ims.yml                  # Deploy IMS
│   ├── omniss7.yml              # Deploy SS7 stack
│   ├── dns.yml                  # Deploy DNS support service
│   ├── backup.yml               # Backup core databases
│   ├── all.yml                  # Deploy everything
│   ├── common.yml               # Base system configuration
│   ├── setup_users.yml          # User management
│   ├── reboot.yml               # Graceful reboot utility
│   └── ...                      # Component-specific playbooks
├── util_playbooks/              # Operational utilities
│   ├── health_check.yml         # System health reporting
│   ├── ip_plan_generator.yml    # Network documentation
│   ├── restore_hss.yml          # Restore HSS from backup
│   ├── getLocalCapture.yml      # Packet capture retrieval
│   └── ...                      # Other utilities
├── roles/                       # Ansible roles
│   ├── common/                  # Base configuration
│   ├── omnihss/                 # OmniHSS deployment
│   ├── omnisgwc/                # OmniSGW deployment
│   ├── omnipgwc/                # OmniPGW deployment
│   ├── applicationserver/       # OmniTAS (IMS Application Server)
│   ├── omnimessage/             # OmniMessage deployment
│   ├── license_server/          # License server
│   ├── monitoring/              # Prometheus/Grafana
│   └── ...                      # Other component roles
├── packaging/                   # .deb build config (nfpm, build.sh)
├── .github/workflows/build-deb.yml  # CI build of the omnicore .deb
├── requirements.yml             # Ansible collection requirements (ansible-galaxy)
├── pyproject.toml               # Python dependencies (uv)
└── uv.lock                      # Pinned Python dependency lock

OmniCore is also installable as an omnicore .deb package from the apt server — built by packaging/build.sh and .github/workflows/build-deb.yml.

Key Features

Automated Deployment

• Complete cellular network deployed in hours
• Consistent configuration across environments
• Repeatable deployments for dev, test, and production

Flexible Configuration

• Jinja2 templates for dynamic configuration generation
• group_vars for customer-specific customization
• No need to modify core roles

Package Management

• Pre-compiled binary packages (.deb)
• Local APT cache for offline deployments
• Public repository for internet-connected sites

Infrastructure as Code

• All configuration in Git version control
• Track changes and enable rollback
• Review changes before deployment

Common Playbooks

Playbook	Purpose
services/all.yml	Deploy complete network
services/epc.yml	Deploy 4G EPC components
services/ims.yml	Deploy IMS voice services
services/omniss7.yml	Deploy SS7 stack
services/dns.yml	Deploy DNS support service
services/monitoring.yml	Deploy monitoring only
services/license_server.yml	Deploy license server only
services/apt_cache.yml	Set up local APT cache
util_playbooks/proxmox.yml	Create VMs on Proxmox

Supported Platforms

Hypervisors

• Proxmox VE
• VMware vSphere
• Cloud instances (Vultr / AWS / GCP)

Deployment Models

• On-premise (customer data center)
• Cloud (AWS, Azure, GCP via vLab)
• Hybrid (mix of on-prem and cloud)
• Air-gapped (completely offline)

---

Getting Help

1. Check the documentation for detailed guides
2. Review example hosts files for reference
3. Consult product documentation at https://docs.omnitouch.com.au/
4. Contact Omnitouch support for deployment assistance

Next Steps

1. Read the Introduction to Ansible Deployment
2. Review the IP Planning Standard to plan your network architecture
3. Review the Deployment Architecture Overview
4. Create your hosts file
5. Customize with group_vars as needed
6. Deploy your network!