GenieACS TR-069 ACS on AWS User Guide

Overview

This image runs GenieACS 1.2.16, the fast and powerful open source TR-069 (CWMP) Auto Configuration Server used by ISPs and network operators to remotely provision, monitor and manage customer premises equipment (CPE) - routers, modems, ONTs, VoIP ATAs and other devices - at scale from a single web console. It is installed on the Node.js 20 LTS runtime and backed by a local MongoDB 8.0 datastore.

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

nginx fronts the management UI on port 80, reverse-proxying to the loopback UI listener. The northbound API and the UI process are bound to loopback only for safety - the NBI has full device control and no built-in authentication - while 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 instance a one-shot service generates all per-instance secrets: a unique UI admin password (applied by creating 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, and 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, independently resizable EBS data volume kept separate from the operating system disk.

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 allowing inbound TCP 22 (SSH) from your IP, TCP 80 (HTTP) from your operators, and TCP 7547 + 7567 from your CPE network.
• Recommended instance type: m5.large or larger.

Connecting to your instance

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

Step 1 - Launch from the AWS Marketplace console

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

Step 2 - Launch from the AWS CLI (alternative)

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 written on first boot. It is mode 0600 and owned by root, so read it with sudo:

sudo cat /root/genieacs-credentials.txt

You will see 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.

After signing in you land on the console. Open the Devices tab to see the managed CPE, each with 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:

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/ - via its TR-069 ACS URL setting (many devices set this over DHCP option 43 or via their own management page). On its next Inform the device registers itself and appears under the Devices tab.

The image ships a self-contained self-test that performs a full TR-069 session for a demo device and confirms the ACS ingested it, without any real hardware:

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

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

The first-boot admin user is created with 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 for safety - it has full device control and no built-in authentication. Reach it from the instance itself, over an SSH tunnel, or front it with your own authenticating reverse proxy. From the instance:

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

NBI HTTP 200

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

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, or 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

For CWMP/FS TLS (device connections over https/:7547), configure the GENIEACS_CWMP_SSL_CERT / GENIEACS_CWMP_SSL_KEY (and the FS equivalents) with your own certificates per the GenieACS documentation, then restart the affected services.

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-instance (for example to Amazon S3) on a schedule. Because the database lives on its own EBS volume, you can also snapshot that volume with Amazon EBS 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 cloudimg 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.

Support

cloudimg provides 24/7 technical support for this product by email and live chat, with a one-hour average response for critical issues. Our engineers help with GenieACS deployment, CWMP device onboarding and connection-request troubleshooting, presets and provisions, the northbound REST API, firmware campaigns, TLS termination, MongoDB backup strategies and scaling.

• Email: support@cloudimg.co.uk
• Live chat: available 24/7

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.