Manual:TR069-client: Difference between revisions

From MikroTik Wiki
Jump to navigation Jump to search
(initial commit of the text)
 
m (redirect?)
Line 1: Line 1:
tr069-client implements CPE WAN Management Protocol (CWMP) for remote device management, which is standardized by Broadband Forum (BBF).
http://wiki.mikrotik.com/wiki/Manual:TR069-client
CWMP works over IP network using HTTP(S) to communicate with 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.
 
Typical use-case:
 
***to-do insert your picture here***
 
 
 
==Configuration Settings==
Parameters of TR-069-client menu
 
====Writable settings====
 
{| cellpadding="2"
!width="300px" style="background:#cccccc; border-bottom:1px solid gray;"| Property
!width="450px" style="background:#cccccc; border-bottom:1px solid gray;"| Desciption
|-
|style="border-bottom:1px solid gray;" valign="top"|'''enabled'''
|style="border-bottom:1px solid gray;" valign="top"|enable/disable CWMP protocol
|-
|style="border-bottom:1px solid gray;" valign="top"|'''acs-url'''
|style="border-bottom:1px solid gray;" valign="top"|URL of ACS. Examples: "https://example.com:8080/path/", "http://192.168.1.100/"
|-
|style="border-bottom:1px solid gray;" valign="top"|'''username'''
|style="border-bottom:1px solid gray;" valign="top"|HTTP authentication username (used by CPE to "login" into ACS)
|-
|style="border-bottom:1px solid gray;" valign="top"|'''password'''
|style="border-bottom:1px solid gray;" valign="top"|HTTP authentication password (used by CPE to "login" into ACS)
|-
|style="border-bottom:1px solid gray;" valign="top"|'''periodic-inform-enabled'''
|style="border-bottom:1px solid gray;" valign="top"|enable/disable CPE periodical session initiation. Timer is started after every successful session. When session is started by periodic interval then Inform RPC contains "2 PERIODIC" event. Maps to "Device.ManagementServer.PeriodicInformEnable" Parameter.
|-
|style="border-bottom:1px solid gray;" valign="top"|'''periodic-inform-interval'''
|style="border-bottom:1px solid gray;" valign="top"|timer interval of periodic inform. Maps to "Device.ManagementServer.PeriodicInformInterval"
|-
|style="border-bottom:1px solid gray;" valign="top"|'''client-certificate'''
|style="border-bottom:1px solid gray;" valign="top"|certificate of client/CPE, which can be used by ACS for extra authentication.
|}
 
====Read only settings====
 
{| cellpadding="2"
!width="300px" style="background:#cccccc; border-bottom:1px solid gray;"| Property
!width="450px" style="background:#cccccc; border-bottom:1px solid gray;"| Desciption
|-
|style="border-bottom:1px solid gray;" valign="top"| '''status'''
|style="border-bottom:1px solid gray;" valign="top"| informative status of CWMP. disabled - protocol disabled, waiting-URL - protocol enabled, but ACS URL not configured, running - CWMP is configured correctly and will communicate with ACS on events
|-
|style="border-bottom:1px solid gray;" valign="top"|'''last-session-error'''
|style="border-bottom:1px solid gray;" valign="top"|user-friendly error description indicating why the previous session didn't finish successfully
|-
|style="border-bottom:1px solid gray;" valign="top"|'''retry-count'''
|style="border-bottom:1px solid gray;" valign="top"|consecutive unsuccessful session count. If > 0, then last-session-error should indicate error. Resets to 0 on a successful session, disabled protocol or reboot.
|}
 
====Commands====
 
{| cellpadding="2"
!width="300px" style="background:#cccccc; border-bottom:1px solid gray;"| Command
!width="450px" style="background:#cccccc; border-bottom:1px solid gray;"| Desciption
|-
|style="border-bottom:1px solid gray;" valign="top"|'''reset-tr069-config'''
|style="border-bottom:1px solid gray;" valign="top"|completely resets and forgets tr069-client configuration and state (without affecting other ROS configurations). Use when CWMP goes into unresponsive/hanged state and should be restored without re-installation of the RouterOS.
|}
 
 
==CWMP Session==
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 Inform RPC, which contains connection reason, device info and some Parameter values depending on configuration.
When CPE has nothing more to say, then 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 ''Data Model'' (DM).
BBF defines some Data Models on which vendors should base their supported Parameters.TR-181 issue 2 (Device:2) - The new Data Model recommended by BBF which supersedes TR-098 and TR-181-1 and is periodically updated with new Parameters. Also, defines network stack for more flexible networking configuration.
 
'''Mikrotik's ''Data Model'' is based on TR-181-2 DM'''
 
MikroTik does not support older DM's such as:
 
* TR-098 (InternetGatewayDevice.) - First ''Data Model'' which was meant for managing Gateway/Router type of devices
 
* TR-181 issue 1 (Device:1) - ''Data Model'' which was meant for non-gateway device management. Some Parameters overlap with TR-098.
 
 
 
==RouterOS update via TR-069-client==
CWMP standard defines that CPE's firmware can be updated using Download RPC with FileType="1 Firmware Upgrade Image" and single URL of a downloadable file (HTTP and HTTPS are supported). Standard also states that 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 as regular RouterOS update through firmware/package file upload.
 
An example of RouterOS bundle package and tr069-client package update (don't forget to also update tr069-client package).
An XML file should be put on some HTTP server, which is accessible from CPE for download.
Also, downloadable RouterOS package files should be accessible the same way (can be on any HTTP server).
Using ACS execute Download RPC with URL pointing to 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>
 
CPE will download XML, parse/validate its contents, download files from provided URLs and try to upgrade. The result will be reported with TransferComplete RPC.
 
{{Warning|Use HTTPS in production for firmware management}}
 
{{Note|Always make firmware updates incremental - first, update locally tested device and make sure that CWMP communication is resumed with a new version and required ROS functionality works. Secondly, repeat steps by updating groups of CPEs incrementally. We do not recommend updating all remote devices at once.}}
 
 
 
==Remote Script Execution==
RouterOS has a lot of configuration attributes and not everything can be ported as CWMP Parameters, that is why ROS provides a possibility to execute its powerful scripting language to configure any attribute.
The script can be executed by performing Download RPC with ''FileType="3 Vendor Configuration File"'' and putting script file on HTTP server accessible by CPE.
 
{{Note|This functionality will probably change a little in future versions because the same "FileType" could also be used to apply complete ROS configuration (by removing previous). Note that it will be an extension (not removal) of functionality.}}
 
 
 
==Security==
* HTTP should only be used when testing initial setup in the secured/private network because Man-in-the-middle attacker could read/change configuration parameters.'''In the production environment, HTTPS is a MUST'''.
* CWMP's incoming connection validation by design is safe because CPE will not communicate with any other device except previously configured ACS. Connection Request only signals CPE to start a new connection + new session
with previously configured ACS.
 
 
 
==Tested ACSs==
Ordering is alphabetical. MikroTik does not imply any one vendor superiority of another. If some ACS is missing you can notify us of the existence of it and it might be added to the list.
 
====Commercial====
* Axiros
* Friendly Tech
 
====Open source====
 
{{Warning| Our suggestion is to only use ACS that is actively maintained, however, ones in the list appear to be abondoned}}
* GenieACS
* LibreACS

Revision as of 12:06, 11 November 2016

http://wiki.mikrotik.com/wiki/Manual:TR069-client

Retrieved from "https://wiki.mikrotik.com/index.php?title=Manual:TR069-client&oldid=28826"