TR-069

TR-069

TR069-client implements CPE WAN Management Protocol (CWMP) for remote device management, which is standardized by the Broadband Forum (BBF). CWMP works over IP network using HTTP(S) to communicate with an Auto Configuration Server (ACS), which can monitor, configure attributes and update the firmware of a remote device. Typically used by ISPs to manage CPEs, but also can be used for Network Infrastructure Device management.

Requires tr069-client package.

Overview

TR-069 (also known as CWMP - CPE WAN Management Protocol) provides:

• Remote Configuration: ACS can query and modify router settings
• Firmware Management: Push RouterOS updates to devices
• Device Monitoring: Retrieve status information and performance metrics
• Automatic Provisioning: Devices can contact ACS on first boot or periodic intervals

Sub-menu

/tr069-client

Configuration Settings

Writable Settings

Client configuration settings.

Property	Description
enabled	Enable/disable CWMP protocol
acs-url	URL of ACS. Examples: https://example.com:8080/path/, https://192.168.1.100/
username	HTTP authentication username (used by CPE to “login” into ACS)
password	HTTP authentication password (used by CPE to “login” into ACS)
periodic-inform-enabled	Enable/disable CPE periodical session initiation. Timer is started after every successful session
periodic-inform-interval	Timer interval of periodic inform
client-certificate	Certificate of client/CPE, which can be used by ACS for extra authentication

Read-only Settings

Property	Description
status	Informative status of CWMP: disabled, waiting-URL, running
last-session-error	User-friendly error description indicating why the previous session didn’t finish successfully
retry-count	Consecutive unsuccessful session count. Resets to 0 on a successful session, disabled protocol or reboot

Commands

Command	Description
reset-tr069-config	Completely resets and forgets tr069-client configuration and state (without affecting other ROS configurations). Use when CWMP goes into unresponsive/hanged state

Basic Configuration

Enable TR-069 Client

/tr069-client set enabled=yes acs-url=https://acs.example.com:8443/ username=admin password=secret

Verify Status

/tr069-client print

Expected output:

Flags: X - disabled
 0    enabled=yes acs-url=https://acs.example.com:8443/ username=admin
      password=secret periodic-inform-enabled=yes periodic-inform-interval=1d
      status=running

Configure Periodic Inform

/tr069-client set periodic-inform-enabled=yes periodic-inform-interval=1h

This will initiate a session with the ACS every hour.

CWMP Session

CWMP client usually starts communication (Session) with ACS on different events:

• First boot
• Reboot
• Periodic interval
• Remote request
• Value change

In each session, CPE and ACS can call RPCs to be “executed” on the other side. CPE always starts with Inform RPC, which contains connection reason, device info and some Parameter values depending on configuration.

Parameters and Data Models

Parameters are simple name+value pairs and each vendor can decide which Parameters to support in its devices. A combination of all supported Parameters is called Data Model (DM). BBF defines three root Data Models (TR-098, TR-181:1, TR-181:2) on which vendors should base their supported Parameters.

RouterOS Data Model is based on “TR-181 Issue 2 Amendment 11”, which is the newest DM and recommended by BBF.

Download RPC

RouterOS Update (1 Firmware Upgrade Image)

CWMP standard defines that CPE’s firmware can be updated using Download RPC with FileType=“1 Firmware Upgrade Image”. Since MikroTik’s update is package-based, an XML file is used to describe firmware upgrade/downgrade:

<upgrade version="1" type="links">
   <config/>
   <links>
       <link>
          <url>https://example.com/routeros-mipsbe-7.14.npk</url>
       </link>
       <link>
          <url>https://example.com/tr069-client-7.14-mipsbe.npk</url>
       </link>
   </links>
</upgrade>

Use HTTPS in production for firmware management. Always test firmware updates on a local device first before rolling out to remote CPEs.

Configuration Change (3 Vendor Configuration File)

The same Download RPC can be used to perform:

• Full configuration overwrite - with any URL filename
• Configuration alteration - when URL’s filename ends with .alter

Alter Configuration

RouterOS provides a possibility to execute scripting language to configure any attribute. A configuration alteration can be performed using Download RPC with FileType=“3 Vendor Configuration File” and filename ending with .alter.

Overwrite All Configurations

Full ROS configuration overwrite can be performed using Download RPC with FileType=“3 Vendor Configuration File” with any URL file name (except with .alter extension).

Provided configuration file must be “smart” enough to apply configuration correctly. Include:

• Delay at beginning for interfaces to show up
• Hidden passwords for users
• Certificates

RouterOS Default Configuration Change (X MIKROTIK Factory Configuration File)

This vendor-specific FileType allows changing the RouterOS default configuration script executed when /system reset-configuration is run.

Use this with caution as failure of uploaded script may render device inoperable and/or inaccessible by the ACS

FactoryReset RPC

This CWMP standard RPC performs RouterOS configuration factory-reset, equivalent to:

/system reset-configuration skip-backup=yes

Upload RPC

FileType	Description
1 Vendor Configuration File	Upload current configuration (same as /export)
2 Vendor Log File	Upload log file (same as /log print)
X MIKROTIK Factory Configuration File	Upload default configuration script

Security

• HTTP should only be used for testing in secured/private networks
• HTTPS is mandatory in production - Man-in-the-middle attacker could read/change configuration parameters
• CWMP’s incoming connection validation is safe - CPE will not communicate with any device except previously configured ACS
• Connection Request only signals CPE to start a new session with previously configured ACS
• Import Root CA certificate when using HTTPS ACS

Import Certificate for HTTPS ACS

If ACS uses HTTPS, import the Root CA certificate on the router:

/certificate import file-name=root-ca.crt

Verify the certificate is imported:

/certificate print

Get the Router Ready for Use with TR-069

This Best Practices Guide shows an example of RouterOS initial setup for safe/preconfigured factory-reset with custom configuration.

Example Default Configuration Script

This example assumes ether1 is the WAN port for reaching ACS:

# Install certificate
:global acsCaCertTxt "-----BEGIN CERTIFICATE-----
MIIDCDCCAfCgAwIBAgIIBQ68Phid9+owDQYJKoZIhvcNAQELBQAwDzENMAsGA1UE
AwwEbXlDYTAeFw03MDAxMDIwMDM0MDZaFw03MTAxMDIwMDM0MDZaMA8xDTALBgNV
BAMMBG15Q2EwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDILvvnEc/8
... (certificate contents) ...
-----END CERTIFICATE-----";

/file print file=tmp_acs_ca_cert.txt
:delay 2
/file set tmp_acs_ca_cert.txt contents=$acsCaCertTxt
/certificate import file-name=tmp_acs_ca_cert.txt passphrase=""
/file remove tmp_acs_ca_cert.txt

# Wait for ether interfaces to show up
:local count 0
:while ([/interface ethernet find] = "") do={
    :if ($count = 30) do={ /quit }
    :delay 1s
    :set count ($count + 1)
}

# Set secure firewall settings for tr069-client
/ip firewall filter add chain=input action=accept connection-state=established,related
/ip firewall filter add chain=input action=drop in-interface=ether1
/ip neighbor discovery-settings set discover-interface-list=none

# Configure IP level for tr069-client
/ip dhcp-client add interface=ether1 disabled=no
/tr069-client set acs-url="https://example.com:7777/" enabled=yes username=user password=pass

Note

Replace certificate, acs-url, username, and password values with your actual configuration.

Tested ACS Solutions

Commercial

• AVSystem
• Axiros
• Friendly Tech

Open Source

• GenieACS

Troubleshooting

Check Connection Status

/tr069-client print

View Last Session Error

/tr069-client get last-session-error

Reset TR-069 Configuration

If CWMP becomes unresponsive:

/tr069-client reset-tr069-config

Common Issues

Issue	Solution
Status shows “waiting-URL”	Configure ACS URL: /tr069-client set acs-url=https://...
Certificate error	Import Root CA: /certificate import file-name=ca.crt
Session fails	Check firewall allows HTTPS outbound on port 443
Retry count increases	Check ACS is reachable, verify username/password

Related Features

• DHCP Client - Can provide ACS URL via DHCP Option 43
• System Reset Configuration - Works with TR-069 FactoryReset RPC
• Certificates - Required for HTTPS ACS