APT Repository & Package Distribution

Overview

The Omnitouch APT system provides package distribution for all deployments. Two types of content are served:

APT Packages — Debian packages installed via apt install
Binary Releases — Pre-built binaries downloaded directly (Prometheus exporters, agents, etc.)

The packages page on the APT server also includes a Self-Setup (OmniCore) tab, which provides the omnicore package (served at /pool/main/o/omnicore/) containing the full Ansible automation toolkit for customers who want to deploy and manage their network themselves.

Two deployment models are supported:

Direct Access — VMs pull packages directly from apt.omnitouch.com.au
Local Cache Mirror — A local server syncs from Omnitouch and serves packages to VMs (for offline/airgapped deployments)

Architecture

Content Served

The APT server hosts all content required for deployments:

Content Type	Description	Path
Omnitouch Packages	Custom-built `.deb` packages (omnihss, omnimme, etc.)	`/dists/<distro>/`
OmniCore Toolkit	The `omnicore` package — full Ansible automation (roles, playbooks, deps) for self-service deployment	`/pool/main/o/omnicore/`
Ubuntu Packages	Cached Ubuntu packages with all dependencies	`/<distro>/pool/main/`
GitHub Releases	Pre-built binaries (Prometheus, Grafana, Homer, etc.)	`/releases/<org>/<repo>/`
Source Tarballs	Source archives for web apps (CGrateS_UI, speedtest)	`/repos/`
Third-Party Packages	Galera, FRR, InfluxDB, KeyDB, etc.	`/releases/<vendor>/`

Configuration Variables

Two separate variable sets control package distribution. Understanding their purposes is essential for correct configuration.

Variable Purposes

Variable Set	Purpose	Used For
`apt_repo`	Configures APT package sources	`/etc/apt/sources.list` and `/etc/apt/sources.list.d/*.list`
`remote_apt_*`	Configures binary download URLs	Downloading files from `/releases/` path (Node Exporter, Zabbix, Nagios, etc.)

When Each Variable Set Is Used

Scenario	APT Sources (`apt_repo`)	Binary Downloads (`remote_apt_*`)
`use_apt_cache: true`	Uses `apt_repo.apt_server`	Uses `apt_repo.apt_server`
`use_apt_cache: false`	Uses `apt_repo.*` with credentials	Uses `remote_apt_*` with credentials

When use_apt_cache: false, both variable sets are required.

Option 1: Direct Access

For deployments with internet connectivity, VMs pull packages directly from the Omnitouch APT server.

Network Requirements

Source IP Whitelisting: Your public IP address must be whitelisted on the Omnitouch APT server. During setup, provide your source subnets to Omnitouch. In return, you will receive:

Username and password for HTTP Basic Auth
FQDN for the APT server

Firewall Requirements: Outbound access to the following Omnitouch IP ranges must be allowed:

Network	Range
IPv4	`144.79.167.0/24`
IPv4	`160.22.43.0/24`
IPv6	`2001:df3:dec0::/48`
ASN	`AS152894`

Services requiring access to Omnitouch infrastructure:

Service	Port	Protocol	Purpose
APT Server	80	TCP	Package downloads
APT Server	53	TCP/UDP	DNS resolution for `apt.omnitouch.com.au`
License Server	123	UDP	NTP time synchronization for license validation
License Server	53	TCP/UDP	DNS resolution for license validation

Ensure HTTP (TCP/80), NTP (UDP/123), and DNS (TCP+UDP/53) traffic is allowed to the Omnitouch IP ranges.

Configuration

all:
  vars:
    use_apt_cache: false

    # APT package sources configuration
    # Configures /etc/apt/sources.list.d/omnitouch.list for apt install commands
    apt_repo:
      apt_server: "apt.omnitouch.com.au"
      apt_repo_username: "your-username"
      apt_repo_password: "your-password"

    # Binary downloads configuration
    # Used for downloading files from /releases/ path
    remote_apt_server: "apt.omnitouch.com.au"
    remote_apt_port: 80
    remote_apt_protocol: "http"
    remote_apt_user: "your-username"
    remote_apt_password: "your-password"

Parameters

APT Package Sources (`apt_repo`)

Parameter	Type	Required	Default	Description
`apt_repo.apt_server`	String	Yes	-	APT server hostname or IP address
`apt_repo.apt_repo_username`	String	Yes	-	HTTP Basic Auth username for APT sources
`apt_repo.apt_repo_password`	String	Yes	-	HTTP Basic Auth password for APT sources

Binary Downloads (`remote_apt_*`)

Parameter	Type	Required	Default	Description
`remote_apt_server`	String	Yes	-	Server hostname or IP for binary downloads
`remote_apt_port`	Integer	No	`80`	Server port for binary downloads
`remote_apt_protocol`	String	No	`http`	Protocol (`http` or `https`)
`remote_apt_user`	String	Yes	-	HTTP Basic Auth username for downloads
`remote_apt_password`	String	Yes	-	HTTP Basic Auth password for downloads

General

Parameter	Type	Required	Default	Description
`use_apt_cache`	Boolean	Yes	-	Must be `false` for direct access

URL Patterns (Direct Access)

APT Package Sources (configured in /etc/apt/sources.list.d/omnitouch.list):

deb [trusted=yes] http://{apt_repo_username}:{apt_repo_password}@{apt_server}/ noble main

Binary Downloads (used by Ansible get_url tasks):

http://{remote_apt_user}:{remote_apt_password}@{remote_apt_server}:{remote_apt_port}/releases/prometheus/node_exporter/node_exporter-1.8.1.linux-amd64.tar.gz

How It Works

VMs authenticate with HTTP Basic Auth for both APT packages and binary downloads. Ubuntu system packages are also served from the Omnitouch server (pre-cached), so VMs do not need access to Ubuntu mirrors.

Package Signing (GPG)

The Omnitouch APT server generates a repository signing key and serves the armored public key at /omnitouch.gpg. For direct-access hosts, the common role automatically fetches that key and installs it into /etc/apt/trusted.gpg.d/omnitouch.gpg so apt-get update verifies repository metadata without NO_PUBKEY warnings. This happens automatically; no manual key management is required.

Cache-mirror mode does not use GPG verification — hosts pulling from a local cache use [trusted=yes] instead (see Option 2).

Option 2: Local Cache Mirror

For offline, airgapped, or bandwidth-constrained deployments, deploy a local APT cache that syncs all content from Omnitouch.

Architecture

Configuration

Define the cache server in your hosts file with its repository configuration:

apt_cache_servers:
  hosts:
    customer-apt-cache:
      ansible_host: 192.168.1.100
      gateway: 192.168.1.1
  vars:
    # Cache server syncs packages from authenticated repository
    remote_apt_server: "apt.omnitouch.com.au"
    remote_apt_port: 80
    remote_apt_protocol: "http"
    remote_apt_user: "your-username"
    remote_apt_password: "your-password"

all:
  vars:
    # use_apt_cache: true  # Auto-set when apt_cache_servers group exists
    # apt_repo.apt_server: auto-derived to 192.168.1.100 (first cache server)

How it works:

Cache server (192.168.1.100): Uses remote_apt_* credentials to sync packages from apt.omnitouch.com.au:80
All other hosts: Automatically derive apt_repo.apt_server: "192.168.1.100" and pull from cache at port 8080 without credentials

Parameters

APT Package Sources (`apt_repo`)

Parameter	Type	Required	Default	Description
`apt_repo.apt_server`	String	Yes	Auto-derived	Local cache server IP. Automatically derived from first `apt_cache_servers` host if not specified.
`apt_repo.apt_repo_username`	String	No	-	Not required when using cache (no auth needed)
`apt_repo.apt_repo_password`	String	No	-	Not required when using cache (no auth needed)

Cache Server Sync (`remote_apt_*`)

These variables configure how the cache server syncs content from Omnitouch:

Parameter	Type	Required	Default	Description
`remote_apt_server`	String	Yes	-	Omnitouch APT server to sync from
`remote_apt_port`	Integer	No	`80`	Omnitouch APT server port
`remote_apt_protocol`	String	No	`http`	Protocol for sync connection
`remote_apt_user`	String	Yes	-	Credentials for syncing from Omnitouch
`remote_apt_password`	String	Yes	-	Credentials for syncing from Omnitouch

General

Parameter	Type	Required	Default	Description
`use_apt_cache`	Boolean	No	`true`	Automatically set to `true` when `apt_cache_servers` group exists
`apt_repo.apt_repo_port`	Integer	No	`8080`	Port hosts use to reach the local cache server. (Replaces the deprecated `apt_cache_port`.)

Deprecated: apt_cache_port is no longer used. The port hosts connect to is now set via apt_repo.apt_repo_port (defaults to 8080 when omitted).

URL Patterns (Cache Mode)

APT Package Sources (configured in /etc/apt/sources.list.d/omnitouch.list):

deb [trusted=yes] http://192.168.1.100:8080/noble noble main

Binary Downloads (used by Ansible get_url tasks):

http://192.168.1.100:8080/releases/prometheus/node_exporter/node_exporter-1.8.1.linux-amd64.tar.gz

No credentials required for cache access—it uses [trusted=yes] APT configuration.

Deploying the Cache

Provision the cache server (VM or LXC container with 50+ GB disk)

Run the cache setup playbook:

ansible-playbook -i hosts/customer/production.yml services/apt_cache.yml

Verify the cache by browsing to http://192.168.1.100:8080/

What Gets Synced

The cache mirror syncs all content from the Omnitouch APT server. The mechanism differs by content type:

APT packages (/dists/ + /pool/ for both Omnitouch and Ubuntu) are synced with curl driven by the Debian repository index. The mirror fetches the upstream Release file (and short-circuits if it is unchanged), parses Packages.gz for the authoritative filename/SHA256/size of every package, and downloads only files that are missing or whose SHA256 does not match the local copy. Each downloaded file is SHA256-verified before being committed.
Binary releases and source tarballs (/releases/, /repos/) have no Debian-style index, so they fall back to wget --recursive --timestamping, which only re-downloads files with a newer Last-Modified upstream.

Content directories synced:

Path	Content
`/dists/<distro>/`	APT repository metadata (Packages, Release files)
`/pool/main/`	Omnitouch custom .deb packages
`/<distro>/pool/main/`	Ubuntu packages and all dependencies
`/releases/`	GitHub releases (Prometheus, Grafana, Zabbix, etc.)
`/repos/`	Source tarballs (Erlang, Elixir, CGrateS_UI, etc.)

After initial sync, the cache can serve all packages without internet connectivity.

How It Works

The cache mirror authenticates with HTTP Basic Auth for all content. APT packages are synced with curl against the Debian repository index (Release + Packages.gz), downloading only files whose SHA256 differs from the local copy and verifying each one after download; /releases/ and /repos/ fall back to wget --recursive --timestamping. Either way, subsequent syncs only fetch new or changed files.

Automatic Configuration

When an apt_cache_servers group exists in your inventory, the system automatically:

Sets use_apt_cache: true for all hosts (unless explicitly overridden)
Derives apt_repo.apt_server from the first cache server's ansible_host IP

Minimal Configuration Example

apt_cache_servers:
  hosts:
    apt-cache-01:
      ansible_host: 192.168.1.100
      gateway: 192.168.1.1
  vars:
    # Cache server syncs content from Omnitouch repository
    remote_apt_server: "apt.omnitouch.com.au"
    remote_apt_user: "your-username"
    remote_apt_password: "your-password"

What happens automatically:

All hosts (except cache server) get use_apt_cache: true
All hosts (except cache server) get apt_repo.apt_server: "192.168.1.100"
All hosts pull from http://192.168.1.100:8080/ without credentials
Cache server syncs packages from http://your-username:your-password@apt.omnitouch.com.au/

Override Automatic Behavior

To force direct access even with cache servers defined:

all:
  vars:
    use_apt_cache: false  # Force direct access even with cache servers defined

    apt_repo:
      apt_server: "apt.omnitouch.com.au"
      apt_repo_username: "user"
      apt_repo_password: "pass"

    remote_apt_server: "apt.omnitouch.com.au"
    remote_apt_user: "user"
    remote_apt_password: "pass"

Configuration Summary

Scenario 1: Direct Access to APT Server (No Cache)

All hosts pull packages directly from the APT repository server.

all:
  vars:
    use_apt_cache: false

    # APT package sources - used by all hosts
    apt_repo:
      apt_server: "apt.omnitouch.com.au"
      apt_repo_username: "user"
      apt_repo_password: "pass"

    # Binary downloads - used by all hosts
    remote_apt_server: "apt.omnitouch.com.au"
    remote_apt_port: 80
    remote_apt_protocol: "http"
    remote_apt_user: "user"
    remote_apt_password: "pass"

Result: All hosts generate deb [trusted=yes] http://user:pass@apt.omnitouch.com.au/ noble main

Scenario 2: APT Cache Server Defined in Hosts File (Automatic)

Cache server is in your inventory and will be deployed/synced by Ansible.

apt_cache_servers:
  hosts:
    cache-server:
      ansible_host: 192.168.1.100
      gateway: 192.168.1.1
  vars:
    # Cache server syncs packages from authenticated repository
    remote_apt_server: "apt.omnitouch.com.au"
    remote_apt_port: 80
    remote_apt_protocol: "http"
    remote_apt_user: "user"
    remote_apt_password: "pass"

# No configuration needed in all: vars:
# Everything auto-derived from apt_cache_servers group

Result:

Cache server: Syncs from http://user:pass@apt.omnitouch.com.au:80/
All other hosts: Generate deb [trusted=yes] http://192.168.1.100:8080/noble noble main (no credentials)

Scenario 3: Remote APT Cache NOT in Hosts File (Manual)

Cache server exists elsewhere and is already set up (not managed by your Ansible).

all:
  vars:
    use_apt_cache: true

    # Point all hosts to the external cache server
    apt_repo:
      apt_server: "192.168.1.100"  # IP of external cache server
      apt_repo_port: 8080           # Cache typically runs on port 8080

# No apt_cache_servers group needed
# No remote_apt_* needed (cache is already set up externally)

Result: All hosts generate deb [trusted=yes] http://192.168.1.100:8080/noble noble main (no credentials)

Complete Example

Here's a complete working example showing cache server configuration with multiple application hosts:

# APT Cache Server Group
apt_cache_servers:
  hosts:
    customer-apt-cache:
      ansible_host: 10.179.1.114
      gateway: 10.179.1.1
      host_vm_network: "vmbr0"
      num_cpus: 4
      memory_mb: 16384
      proxmoxLxcDiskSizeGb: 120
  vars:
    # Cache server syncs packages from authenticated repository
    remote_apt_server: "apt.omnitouch.com.au"
    remote_apt_port: 80
    remote_apt_protocol: "http"
    remote_apt_user: "customer-username"
    remote_apt_password: "customer-secure-token"

# Application Servers
hss:
  hosts:
    customer-hss01:
      ansible_host: 10.179.2.140
      gateway: 10.179.2.1

mme:
  hosts:
    customer-mme01:
      ansible_host: 10.179.1.15
      gateway: 10.179.1.1

dns:
  hosts:
    customer-dns01:
      ansible_host: 10.179.2.177
      gateway: 10.179.2.1

# Global Configuration
all:
  vars:
    # Auto-configuration (no manual config needed):
    # - use_apt_cache: true (auto-enabled when apt_cache_servers exists)
    # - apt_repo.apt_server: "10.179.1.114" (auto-derived from cache server)

What happens during deployment:

Cache server (10.179.1.114):
- Uses remote_apt_* from its vars: section
- Downloads all packages from http://customer-username:customer-secure-token@apt.omnitouch.com.au:80/
- Serves packages on port 8080 via nginx
Application hosts (customer-hss01, customer-mme01, customer-dns01):
- Auto-detect apt_cache_servers group exists
- Auto-set use_apt_cache: true
- Auto-derive apt_repo.apt_server: "10.179.1.114"
- Generate: deb [trusted=yes] http://10.179.1.114:8080/noble noble main
- Pull all packages from cache server (no credentials required)

Updating the Cache

To sync new packages or updates:

ansible-playbook -i hosts/customer/production.yml services/apt_cache.yml

This incrementally syncs all content from the Omnitouch APT server:

New Omnitouch package versions
New Ubuntu packages and dependencies
New GitHub releases
Updated source tarballs

Re-syncs are incremental: APT packages are compared against the upstream Debian index by SHA256 (and skipped entirely if the upstream Release file is unchanged), while /releases/ and /repos/ use wget --timestamping. Existing unchanged files are skipped, making re-sync fast.

Note: The Omnitouch APT server (apt.omnitouch.com.au) is the single source of truth for all packages. Omnitouch builds and publishes packages to it; running services/apt_cache.yml on cache mirrors then syncs whatever is currently published.

Troubleshooting

APT Update Fails with 401 Unauthorized

Symptoms:

Failed to fetch http://10.179.1.115:80/noble/dists/noble/main/binary-amd64/Packages  401  Unauthorized

Possible causes:

apt_repo configuration defined in all: vars: instead of apt_cache_servers: vars:
Hosts trying to access authenticated repository directly instead of cache
Incorrect apt_repo_username or apt_repo_password
Source IP not whitelisted on Omnitouch APT server
Using cache credentials for direct access or vice versa

Resolution:

Check configuration scope: Ensure apt_repo with credentials is defined in apt_cache_servers: vars:, NOT in all: vars:
Verify cache mode: When using cache, hosts should connect to cache server (port 8080), not repository (port 80)
Check generated sources: On failing host, check /etc/apt/sources.list.d/omnitouch.list
- Correct (cache mode): deb [trusted=yes] http://10.179.1.114:8080/noble noble main
- Incorrect (has credentials in wrong place): deb [trusted=yes] http://user:pass@10.179.1.115:80/noble noble main
Verify credentials are correct for your deployment mode
Confirm your public IP is whitelisted with Omnitouch (if using direct access)

Binary Downloads Fail (Node Exporter, Zabbix, etc.)

Symptoms: Ansible playbook fails downloading files from /releases/ path

Possible causes:

remote_apt_* variables not configured
Incorrect remote_apt_user or remote_apt_password
Missing remote_apt_server when use_apt_cache: false

Resolution:

Ensure all remote_apt_* variables are defined
Verify credentials match those provided by Omnitouch
Check that remote_apt_server points to correct host

Cache Server Cannot Sync

Symptoms: Cache server playbook fails to download packages

Possible causes:

Cache server has no internet access
remote_apt_* credentials incorrect
Firewall blocking outbound connections to Omnitouch

Resolution:

Verify cache server can reach apt.omnitouch.com.au on port 80
Check remote_apt_* credentials
Review firewall rules for outbound access

Hosts File Configuration — Inventory and variable configuration
Configuration Reference — Complete parameter reference
Deployment Architecture — Overall system architecture
Proxmox Deployment — Deploying cache server as LXC container

Overview​

Architecture​

Content Served​

Configuration Variables​

Variable Purposes​

When Each Variable Set Is Used​

Option 1: Direct Access​

Network Requirements​

Configuration​

Parameters​

APT Package Sources (apt_repo)​

Binary Downloads (remote_apt_*)​

General​

URL Patterns (Direct Access)​

How It Works​

Package Signing (GPG)​

Option 2: Local Cache Mirror​

Architecture​

Configuration​

Parameters​

APT Package Sources (apt_repo)​

Cache Server Sync (remote_apt_*)​

General​

URL Patterns (Cache Mode)​

Deploying the Cache​

What Gets Synced​

How It Works​

Automatic Configuration​

Minimal Configuration Example​

Override Automatic Behavior​

Configuration Summary​

Scenario 1: Direct Access to APT Server (No Cache)​

Scenario 2: APT Cache Server Defined in Hosts File (Automatic)​

Scenario 3: Remote APT Cache NOT in Hosts File (Manual)​

Complete Example​

Updating the Cache​

Troubleshooting​

APT Update Fails with 401 Unauthorized​

Binary Downloads Fail (Node Exporter, Zabbix, etc.)​

Cache Server Cannot Sync​

Related Documentation​

Overview

Architecture

Content Served

Configuration Variables

Variable Purposes

When Each Variable Set Is Used

Option 1: Direct Access

Network Requirements

Configuration

Parameters

APT Package Sources (`apt_repo`)

Binary Downloads (`remote_apt_*`)

General

URL Patterns (Direct Access)

How It Works

Package Signing (GPG)

Option 2: Local Cache Mirror

Architecture

Configuration

Parameters

APT Package Sources (`apt_repo`)

Cache Server Sync (`remote_apt_*`)

General

URL Patterns (Cache Mode)

Deploying the Cache

What Gets Synced

How It Works

Automatic Configuration

Minimal Configuration Example

Override Automatic Behavior

Configuration Summary

Scenario 1: Direct Access to APT Server (No Cache)

Scenario 2: APT Cache Server Defined in Hosts File (Automatic)

Scenario 3: Remote APT Cache NOT in Hosts File (Manual)

Complete Example

Updating the Cache

Troubleshooting

APT Update Fails with 401 Unauthorized

Binary Downloads Fail (Node Exporter, Zabbix, etc.)

Cache Server Cannot Sync

Related Documentation