Skip to main content
Version: current

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 an 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. It is typically used by ISPs to manage CPEs, but can also be used for Network Infrastructure Device management.

Configuration​

TR069-client is configured from the /tr069-client menu.

The client configuration includes writable settings such as enabled, acs-url, username, password, periodic-inform-enabled, periodic-inform-interval, and client-certificate. Read-only settings (status, last-session-error, retry-count) monitor the state of the client. The /tr069-client/reset-tr069-config command completely resets and forgets the tr069-client configuration and state (without affecting other RouterOS configurations). Use this command when CWMP goes into an unresponsive or hung state and should be restored without reinstalling RouterOS.

For a full list of available parameters, see the CLI reference.

CWMP Session​

The CWMP client usually starts communication (session) with ACS on different events - first boot, reboot, periodic interval, remote request, value change, etc. In each session, CPE and ACS can call RPCs to be "executed" on the other side. CPE always starts with the Inform RPC, which contains connection reason, device info and some Parameter values depending on configuration. When CPE has nothing more to say, ACS executes its RPCs (which most of the time are Parameter management RPCs).

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 a 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".

RouterOS TR069 client-supported parameter reference

Download RPC​

RouterOS Update (1 Firmware Upgrade Image)​

The CWMP standard defines that CPE's firmware can be updated using Download RPC with FileType="1 Firmware Upgrade Image" and a single URL of a downloadable file (HTTP and HTTPS are supported). The standard also states that the downloaded file can be any type and vendor-specific process can be applied to finish firmware update. Because MikroTik's update is package based (and also for extra flexibility), an XML file is used to describe firmware upgrade/downgrade. For now, XML configuration supports providing multiple URLs of files, which will be downloaded and applied similarly to a regular RouterOS update through firmware/package file upload.

An example of a RouterOS bundle package and tr069-client package update (make sure to also update the tr069-client package). Place the XML file on an HTTP server that is accessible from the CPE for download. The downloadable RouterOS package files must be accessible the same way (they can be on any HTTP server). Using ACS, execute Download RPC with the URL pointing to the XML file (e.g. "https://example.com/path/upgrade.xml") with contents:

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

The CPE downloads the XML, parses and validates its contents, downloads files from the provided URLs, and attempts to upgrade. The result is reported with TransferComplete RPC.

info

Always make firmware updates incrementally - first, update a locally tested device and make sure that CWMP communication is resumed with the new version and required RouterOS functionality works. Then, repeat steps by updating groups of CPEs incrementally. You should not update all remote devices at once.

Use HTTPS in production for firmware management.

Configuration Change (3 Vendor Configuration File)​

The same Download RPC can be used to perform complete configuration overwrite (as intended by the standard) OR configuration alteration (when URL's filename extension is ".alter").

Alter configuration​

RouterOS has a lot of configuration attributes and not everything can be ported to CWMP Parameters. That is why RouterOS provides the ability to execute its powerful scripting language to configure any attribute. A configuration alteration (which is a regular script execution) can be performed using Download RPC with FileType="3 Vendor Configuration File" and a downloadable file extension ".alter". This feature can be used to configure any RouterOS attributes that are not available through CWMP Parameters.

Overwrite all configurations​

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

warning

The provided configuration file (script) must be robust enough to apply configuration correctly right after reboot. This is especially important when using an uploaded configuration file with Upload RPC, because it only contains exported values. Some things that must be added manually:

RouterOS default configuration change (X MIKROTIK Factory Configuration File)​

This vendor-specific FileType allows the change of the RouterOS default configuration script that is executed when the /system/reset-configuration command is executed (or by other means when the router configuration is being reset).

warning

If the default configuration script is changed, it will not be displayed by /system/default-configuration/print as it is the case if that script is altered with the Netinstall tool. That command will always show the default script set up by MikroTik.

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

FactoryReset RPC​

This is a CWMP standard RPC, which performs RouterOS configuration factory-reset. The reset process is performed in the same way as executing the command:

/system/reset-configuration skip-backup=yes

Note that the default factory configuration can be different for each device (see Default configurations) and execution of this command removes all configurations and executes the internally stored default-configuration script.

Upload RPC​

Upload current configuration (1 Vendor Configuration File)​

The result is a file uploaded to the ACS, same as the output of the /export command in RouterOS.

Upload log file (2 Vendor Log File)​

The result is a file uploaded to the ACS, similar to the output of the /log/print command in RouterOS.

Upload default configuration (X MIKROTIK Factory Configuration File)​

The result is a file uploaded to the ACS that has the contents of the current default configuration script that will be executed if the /system/reset-configuration command is executed. It may differ from the one returned by /system/default-configuration/print.

Security​

  • Use HTTP only when testing the initial setup in a secured or private network, because a man-in-the-middle attacker could read or change configuration parameters. In a production environment, you must use HTTPS.
  • CWMP's incoming connection validation is safe by design, because the CPE will not communicate with any device other than the previously configured ACS. Connection Request only signals the CPE to start a new connection and session with the previously configured ACS.

Get the router ready for use with TR069​

This best practices guide shows an example of RouterOS initial setup when a safe, preconfigured factory-reset with custom configuration is needed, especially when TR-069 is used. It can be useful when the device has been misconfigured into a non-reversible state (by the user or provider, unknowingly). The factory-reset configuration can be applied using TR069 FactoryReset RPC, through RouterOS /system/reset-configuration, or by using the reset button on the router.

Overriding factory default-configurations on Netinstall​

When performing Netinstall, the default-configuration script can be adapted to specific needs and installed by overwriting the MikroTik default one. Providers who want FactoryReset as a backup to make the device reachable again after an unresolvable misconfiguration should do this. In the TR-069 case, the default-configuration script should at minimum import certificates, set up the IP layer connectivity, enable and configure tr069-client, and configure the firewall. After that, other configurations can be performed by the ACS.

warning

On factory-reset all certificates are removed, so if they are needed after reset, the default-configuration script must import them.

Example script​

The following example default-configuration script assumes that the board is using ether1 as a WAN port for reaching the ACS, a dummy CA certificate is used, and the initial IP configuration is received by a DHCP client.

note

Values of certificate, acs-url, username, and password must be replaced and extra configurations will most probably be added. You also might want to define your own interface-list for discovery from the LAN side.

# Install certificate
:global acsCaCertTxt "-----BEGIN CERTIFICATE-----
MIIDCDCCAfCgAwIBAgIIBQ68Phid9+owDQYJKoZIhvcNAQELBQAwDzENMAsGA1UE
AwwEbXlDYTAeFw03MDAxMDIwMDM0MDZaFw03MTAxMDIwMDM0MDZaMA8xDTALBgNV
BAMMBG15Q2EwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDILvvnEc/8
53jevX3MW4qjn9CNdHLexUZSL8qSXzE5sik1kaNOdckOXC8/Ku0qO95elaBaXmLe
QsIQbVtZ768SBQc7q4RaG3AEauLfNl0BS3kl91/nSvYKp20Nvn7LP7CVZj8D81S+
z4lYgab00X6hT65r8cOI4idaJNWkB9+vFujiPpg0H4IEthgslvCu0i2C7VMrZps/
lTI4xD7kUU4ySzpMUDD3SiA1cEtR8SC5gspYFqtUB2Chk4DTeqWzPCT9eIKclIKM
eh/5w7eLCKyjqIBDwWixuHGW7uFffHjmkgtmzG35W/qmgXGXG+BC8NomxmKxdxCT
ZpQCbisMKieTAgMBAAGjaDBmMA8GA1UdEwEB/wQFMAMBAf8wDgYDVR0PAQH/BAQD
AgEGMB0GA1UdDgQWBBR5poVfi8tXHrD3sEidlLLzm1k3xzAkBglghkgBhvhCAQ0E
FxYVR2VuZXJhdGVkIGJ5IFJvdXRlck9TMA0GCSqGSIb3DQEBCwUAA4IBAQChVt7s
YNL+U7p0OoxdKgCqP3JyrVOAYDs51243IR83BM3WQybWaDcEv50/R668icnnNHgN
GKQ6OjgQbia7ZW38JWlD/n59WDjk9T63lHh5RHmrhPlIDUN8Wh89v6N2q8YQy+rj
o2lOcbZOJTSIirSBcokMRw45yJNO9HU02E9Bl5nb1hq6/xP4pbTS3t8bL+Xpg0eJ
herz/Ap62k/ToRP+yFYN90z8sDHHvKWnq1W60xreLQ95D5IOego0dIWDC8J/a551
Z2AklvEhKfJTQ6zylrhPDy5bySadxy8lAV82+gEZ1AQyS2UXzRAUgCCCzdEmgiWE
6Du6ubASPAEmYfhC
-----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 while ether ifaces show up
:local count 0;
:while ([/interface/ethernet/find] = "") do={
    :if ($count = 30) do={
        /quit;
    }
    :delay 1s; :set count ($count +1);
};


# Set as secure settings as possible for tr069-client to work
/ip/firewall {
    filter add chain=input action=accept connection-state=established,related \
comment="defconf: accept established,related"
    /filter/add chain=input action=drop in-interface=ether1 \
comment="defconf: drop all from WAN"
}
/ip/neighbor/discovery-settings/set discover-interface-list=none


# Configure IP level, so that tr069-client can work
/ip/dhcp-client/add interface=ether1 disabled=no comment="defconf";
/tr069-client/set acs-url="https://example.com:7777/" enabled=yes \
username=exampleusername password=examplesecurepassword

Tested ACSs​

Ordering is alphabetical. MikroTik does not imply any one vendor's superiority over another.

Commercial​

MikroTik has tested and verified the following commercial ACS solutions:

Open Source​