Deployment guide

GenieACS

Overview

GenieACS 1.2.16 is a fast, open source TR-069 (CWMP) Auto Configuration Server. ISPs and network operators use it to provision, monitor and manage customer premises equipment (CPE) at scale from a single web console. CPE includes routers, modems, ONTs, VoIP ATAs and other devices.

This image runs GenieACS on the Node.js 20 LTS runtime with a local MongoDB 8.0 datastore.

GenieACS runs as four services, each an unprivileged systemd unit under a dedicated genieacs account:

genieacs-cwmp: the TR-069 / CWMP device endpoint that CPE connect to, on :7547 (all interfaces)
genieacs-fs: the file server for firmware and configuration downloads, on :7567 (all interfaces)
genieacs-nbi: the northbound REST API for automation and OSS/BSS integration, on 127.0.0.1:7557 (loopback)
genieacs-ui: the management web UI, on 127.0.0.1:3000 (loopback)

nginx serves the management UI on port 80 and reverse-proxies to the loopback UI listener. The northbound API and the UI process are bound to loopback only, because the NBI has full device control and no built-in authentication. The device-facing CWMP and file-server ports listen on all interfaces so your CPE fleet can reach them.

Secure by default. On the first boot of every deployed VM, a one-shot service generates all per-VM secrets:

A unique UI admin password. The service creates an admin user in MongoDB with a per-VM salt and a PBKDF2-SHA512 hash, plus a full admin permission set, so anonymous console access is disabled.
A unique token-signing secret for UI sessions.
A unique MongoDB password. The genieacs database user is created and MongoDB authentication is enabled.

The admin password is written to /root/genieacs-credentials.txt (mode 0600, root only). No shared or default credential ships in the image. The four GenieACS services start only after first boot has written these secrets, so a VM can never come up on an unauthenticated console.

The device database (MongoDB dbPath /var/lib/mongodb) lives on a dedicated Azure managed data disk, separate from the operating system disk. You can resize the disk independently.

What you get

GenieACS 1.2.16 (AGPL-3.0), installed stock and unmodified from npm and pinned to the exact upstream release
Node.js 20 LTS (NodeSource) and MongoDB 8.0 (official mongodb-org repository)
Four GenieACS systemd services plus an nginx reverse proxy on port 80
A sensible default GenieACS UI configuration, so the device list and device pages are useful the moment you sign in
A per-VM UI admin password, token-signing secret and MongoDB password generated on first boot, with no default login in the image
A dedicated Azure managed data disk for the MongoDB device database, mounted at /var/lib/mongodb
A built-in TR-069 self-test that proves the ACS ingests and manages a device on every boot
An Ubuntu 24.04 LTS base, patched at build time, with unattended security updates enabled
24/7 SecureAnyCloud support

Prerequisites

You need an active Azure subscription, an SSH key, and a VNet with a subnet.

Standard_B2s (2 vCPU / 4 GB) is the recommended size. Choose a larger size for a large CPE fleet or a short polling interval.

Configure the network security group (NSG) with these inbound rules:

Allow 22/tcp from your management CIDR for SSH.
Allow 80/tcp from the CIDR that needs the management UI.
Allow 7547/tcp (CWMP) and 7567/tcp (file server) from your CPE management network, so devices can reach the ACS.

The northbound API, the UI process and MongoDB are bound to loopback, so the NSG never exposes them.

Connect over SSH

Connect to your VM as azureuser, the default login user. Replace <vm-ip> with the public IP of your VM.

ssh azureuser@<vm-ip>

Confirm the services and version

Run the command below. All six services should report active, and the VM should show GenieACS 1.2.16 on an Ubuntu 24.04 LTS base, patched at build time.

sudo systemctl is-active mongod genieacs-cwmp genieacs-nbi genieacs-fs genieacs-ui nginx grep version /opt/genieacs/lib/node_modules/genieacs/package.json ; grep PRETTY_NAME /etc/os-release

Confirm the listeners

List the listening ports. The UI, northbound API and MongoDB are bound to loopback. The device-facing CWMP and file server listen on all interfaces. nginx serves the UI on port 80.

sudo ss -tlnp | grep -E ':(80|3000|7547|7557|7567|27017) '

Retrieve the per-VM admin password

First boot writes a credentials file. It is mode 0600 and owned by root, so read it with sudo:

sudo cat /root/genieacs-credentials.txt

The file holds the unique URL and admin password generated for this VM.

Sign in to the management UI

Browse to http://<vm-ip>/ and sign in as user admin with the password from the previous step.

Open the Devices tab to see your managed CPE, with serial number, product class, manufacturer, model and software version. Each device has inline actions to reboot, factory-reset, push a file, delete or tag it.

Manage a device

Click Show on any device to open its detail page. The page lists the full parameter tree (device info, management server, WiFi, WAN and more) and the fault log.

Use the per-parameter refresh to pull the latest value on demand, or push a change down to the device.

Onboard a device over CWMP

Point your CPE at the CWMP endpoint, http://<vm-ip>:7547/, in its TR-069 ACS URL setting. Many devices take this setting over DHCP option 43 or on their own management page.

On its next Inform, the device registers itself and appears under the Devices tab.

To test without real hardware, run the self-test that ships with the image. It performs a full TR-069 session for a demo device and confirms that the ACS ingested it:

sudo /usr/local/sbin/genieacs-selftest

Presets, provisions and permissions

Open the Admin tab to define presets and provisions. These rules push configuration, parameter values and firmware across your device fleet, on a schedule or in response to CWMP events.

The first-boot admin user has a full permission set (read and write, access level 3, across every resource), so anonymous access is disabled. Manage roles under Admin > Permissions.

Use the northbound REST API

The northbound API (genieacs-nbi) is bound to loopback because it has full device control and no built-in authentication. Reach it from the VM itself, over an SSH tunnel, or behind your own authenticating reverse proxy. From the VM, run:

curl -s -o /dev/null -w 'NBI HTTP %{http_code}\n' http://127.0.0.1:7557/devices/

Use this API to query devices, tasks, presets, provisions and files, and to create connection-request tasks. It lets you integrate the ACS with your OSS/BSS systems. See the GenieACS API documentation for the full resource model.

Enable HTTPS (recommended)

The UI is served over plain HTTP on port 80 by default. For production, terminate TLS at an upstream Azure Application Gateway or Load Balancer. Alternatively, obtain a certificate directly on the VM with certbot:

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d acs.example.com

To enable TLS for CWMP and the file server (device connections over https/:7547), set GENIEACS_CWMP_SSL_CERT / GENIEACS_CWMP_SSL_KEY and the file-server equivalents to your own certificates, as described in the GenieACS documentation. Then restart the affected services.

Back up the device database

All ACS state lives in MongoDB. Take a consistent dump with mongodump, authenticating with the generated database credentials from the secret env file:

sudo bash -c 'source /etc/genieacs/genieacs-secret.env; mongodump --uri="$GENIEACS_MONGODB_CONNECTION_URL" --out /var/backups/genieacs-$(date +%F)'

Copy the resulting directory off the VM on a schedule, for example to Azure Blob Storage. The database also sits on its own Azure managed data disk, so you can snapshot that disk with Azure managed-disk snapshots.

Software version and source (AGPL-3.0)

This image ships stock, unmodified upstream GenieACS 1.2.16 (genieacs@1.2.16 from npm). GenieACS is licensed under the GNU Affero General Public License, version 3 (AGPL-3.0). In accordance with AGPL section 13, the complete corresponding source for the exact version shipped is the upstream release, publicly available at:

https://github.com/genieacs/genieacs/tree/v1.2.16

All SecureAnyCloud customisation (systemd units, the nginx reverse proxy, the configuration env files, the default UI configuration and the first-boot secret-generation script) is external to the GenieACS source; the AGPL-licensed application itself is not patched.

Support

SecureAnyCloud provides 24/7 technical support for this product by email and live chat, with a one-hour average response for critical issues. Our engineers can help with:

GenieACS deployment and CWMP device onboarding
Connection-request troubleshooting, presets and provisions
The northbound REST API and firmware campaigns
TLS termination, MongoDB backup strategies and scaling

All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.

Deploy on Azure

Launch GenieACS 1.2.16 TR-069 Auto Configuration Server on Ubuntu 24.04 LTS on Azure with 24/7 support from SecureAnyCloud.

View this image

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com

Deploy on Azure

Overview

This image runs GenieACS on the Node.js 20 LTS runtime with a local MongoDB 8.0 datastore.

GenieACS runs as four services, each an unprivileged systemd unit under a dedicated genieacs account:

genieacs-cwmp: the TR-069 / CWMP device endpoint that CPE connect to, on :7547 (all interfaces)
genieacs-fs: the file server for firmware and configuration downloads, on :7567 (all interfaces)
genieacs-nbi: the northbound REST API for automation and OSS/BSS integration, on 127.0.0.1:7557 (loopback)
genieacs-ui: the management web UI, on 127.0.0.1:3000 (loopback)

Secure by default. On the first boot of every deployed instance, a one-shot service generates all per-instance secrets:

A unique UI admin password. The service creates an admin user in MongoDB with a per-VM salt and a PBKDF2-SHA512 hash, plus a full admin permission set, so anonymous console access is disabled.
A unique token-signing secret for UI sessions.
A unique MongoDB password. The genieacs database user is created and MongoDB authentication is enabled.

The admin password is written to /root/genieacs-credentials.txt (mode 0600, root only). No shared or default credential ships in the image.

The device database (MongoDB dbPath /var/lib/mongodb) lives on a dedicated EBS data volume, separate from the operating system disk. You can resize the volume independently.

The default security group for this listing opens port 22 (SSH), port 80 (HTTP UI), port 7547 (CWMP) and port 7567 (file server). Scope the CWMP and file-server ports to your CPE management network.

Prerequisites

An AWS account subscribed to this product in AWS Marketplace.
An EC2 key pair in your target region for SSH access.
A security group that allows inbound TCP 22 (SSH) from your IP, TCP 80 (HTTP) from your operators, and TCP 7547 and 7567 from your CPE network.
An instance type of m5.large or larger (recommended).

Connecting to your instance

SSH in as the default login user for your operating system variant, using the key pair you launched with.

For Ubuntu 24.04, the login user is ubuntu. For example: ssh -i your-key.pem ubuntu@<instance-public-ip>

Step 1 - Launch from the AWS Marketplace console

Open the product page in AWS Marketplace. Choose Continue to Subscribe, then Continue to Configuration.
Select the software version and your AWS Region, then choose Continue to Launch.
Choose an instance type (m5.large or larger), your VPC subnet, the security group described above, and your EC2 key pair.
Launch the instance. Wait for it to reach the running state with status checks passed.

Step 2 - Launch from the AWS CLI (alternative)

Run the command below. Replace the AMI id, key name, security group and subnet with your own values:

aws ec2 run-instances \
  --image-id ami-xxxxxxxxxxxxxxxxx \
  --instance-type m5.large \
  --key-name your-key \
  --security-group-ids sg-xxxxxxxx \
  --subnet-id subnet-xxxxxxxx \
  --metadata-options "HttpTokens=required" \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=genieacs}]'

Step 3 - Retrieve the per-instance admin password

SSH to the instance and read the credentials file that first boot wrote. It is mode 0600 and owned by root, so read it with sudo:

sudo cat /root/genieacs-credentials.txt

The file holds the unique URL and admin password generated for this instance:

GENIEACS_URL=http://<instance-public-ip>/ GENIEACS_ADMIN_USER=admin GENIEACS_ADMIN_PASSWORD=<GENIEACS_ADMIN_PASSWORD>

Step 4 - Sign in to the management UI

Browse to http://<instance-public-ip>/ and sign in as user admin with the password from the previous step.

Open the Devices tab to see the managed CPE. Each device has inline actions to reboot, factory-reset, push a file, delete or tag it.

Step 5 - Confirm the stack

Check that all six services are active. The expected output follows the command.

sudo systemctl is-active mongod genieacs-cwmp genieacs-nbi genieacs-fs genieacs-ui nginx

active active active active active active

Confirm the listeners. The UI, northbound API and MongoDB are bound to loopback. The device-facing CWMP and file server listen on all interfaces:

sudo ss -tlnp | grep -E ':(80|3000|7547|7557|7567|27017) ' | awk '{print $1,$4}'

LISTEN 127.0.0.1:3000 LISTEN 127.0.0.1:27017 LISTEN 0.0.0.0:80 LISTEN 127.0.0.1:7557 LISTEN [::]:80 LISTEN *:7547 LISTEN *:7567

Step 6 - Onboard a device over CWMP

Point your CPE at the CWMP endpoint, http://<instance-public-ip>:7547/, in its TR-069 ACS URL setting. Many devices take this setting over DHCP option 43 or on their own management page.

On its next Inform, the device registers itself and appears under the Devices tab.

To test without real hardware, run the self-test that ships with the image. It performs a full TR-069 session for a demo device and confirms that the ACS ingested it:

sudo /usr/local/sbin/genieacs-selftest

selftest: sending BOOTSTRAP Inform for demo device CAFE01-selftest-ST97BAC57627B7 selftest: sending empty POST to end the CWMP session (commits the device) selftest: polling NBI for the device selftest: removing the demo device selftest PASS: ACS ingested + managed demo device CAFE01-selftest-ST97BAC57627B7

Step 7 - Presets, provisions and permissions

Open the Admin tab to define presets and provisions. These rules push configuration, parameter values and firmware across your device fleet, on a schedule or in response to CWMP events.

The first-boot admin user has a full permission set (read and write, access level 3, across every resource), so anonymous access is disabled. Manage roles and permissions under Admin > Permissions.

Step 8 - Use the northbound REST API

The northbound API (genieacs-nbi) is bound to loopback because it has full device control and no built-in authentication. Reach it from the instance itself, over an SSH tunnel, or behind your own authenticating reverse proxy. From the instance, run:

curl -s -o /dev/null -w 'NBI HTTP %{http_code}\n' http://127.0.0.1:7557/devices/

NBI HTTP 200

Step 9 - Enable HTTPS (recommended)

The UI is served over plain HTTP on port 80 by default. For production, terminate TLS at an upstream AWS Application Load Balancer or CloudFront. Alternatively, obtain a certificate directly on the instance with certbot:

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d acs.example.com

Step 10 - Back up the device database

All ACS state lives in MongoDB. Take a consistent dump with mongodump, authenticating with the generated database credentials from the secret env file:

sudo bash -c 'source /etc/genieacs/genieacs-secret.env; mongodump --uri="$GENIEACS_MONGODB_CONNECTION_URL" --out /var/backups/genieacs-$(date +%F)'

Copy the resulting directory off the instance on a schedule, for example to Amazon S3. The database also sits on its own EBS volume, so you can snapshot that volume with Amazon EBS snapshots.

Software version and source (AGPL-3.0)

https://github.com/genieacs/genieacs/tree/v1.2.16

All SecureAnyCloud customisation (systemd units, the nginx reverse proxy, the configuration env files, and the first-boot secret-generation script) is external to the GenieACS source; the AGPL-licensed application itself is not patched.