Provisioning pomocí ACS a CWMP

Standard TR-069, ACS server a CWMP protokol

Standard TR-069 neboli CPE WAN Management Protocol je protokol pro vzdálenou správu (provisioning) zařízení vydaný konsorciem Broadband Forum. Pomocí tohoto protokolu je možno vzdáleně spravovat velké množství koncových zařízení bez nutnosti fyzické návštěvy v místě instalace koncových zařízení. Pro přenos dat používá standard textový protokol CWMP (CPE WAN Management Protocol). Zatím poslední verze Issue Amendment 6 Corrigendum 1 je z června 2020, ačkoliv první verze pochází již z roku 2006. Standard je tedy stále aktivně vyvíjen a přizpůsobován moderním technologiím.

Datové modely CWMP jsou rozděleny do dvou základních částí – Root a Service. Část Root popisuje základní funkce, které by mělo mít každé zařízení komunikující po síti a podporující protokol CWMP, jako jsou rozhraní, firmware, diagnostika a základní informace o zařízení (IP adresa, MAC adresa, uptime – tj. jak dlouho zařízení běží od posledního restartu, apod.). Část Service popisuje věci specifické pro specializovaná zařízení – FAP (Femto Access Point – přístupový bod pro malé buňky, typicky domácí router), Storage (úložiště), STB (Set-Top-Box) a Voice (hlasová zařízení, např. VoIP telefon).

Instalace ACS (CWMP) serveru GenieACS

• Před instalací samotného balíčku s GenieACS je potřeba nainstalovat prerekvizity Node.js a MongoDB a následně spustit službu mongodb

curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash -

sudo apt-get install -y nodejs
  	
apt update

apt install mongodb

service mongodb start

service mongodb enable

• Následně pomocí NPM provedeme instalaci GenieACS

sudo npm install -g genieacs@1.2.8

• Vytvořte systémového uživatele pro běh GenieACS démonů

sudo useradd --system --no-create-home --user-group genieacs

• Vytvořte adresáře pro uložení rozšíření a souboru prostředí

mkdir /opt/genieacs
mkdir /opt/genieacs/ext
chown genieacs:genieacs /opt/genieacs/ext

• Vytvořte soubor /etc/genieacs/genieacs.env, který slouží pro uchování konfiguračních nastavení předávaných do GenieACS jako proměnné prostředí.

GENIEACS_CWMP_ACCESS_LOG_FILE=/var/log/genieacs/genieacs-cwmp-access.log
GENIEACS_NBI_ACCESS_LOG_FILE=/var/log/genieacs/genieacs-nbi-access.log
GENIEACS_FS_ACCESS_LOG_FILE=/var/log/genieacs/genieacs-fs-access.log
GENIEACS_UI_ACCESS_LOG_FILE=/var/log/genieacs/genieacs-ui-access.log
GENIEACS_DEBUG_FILE=/var/log/genieacs/genieacs-debug.yaml
NODE_OPTIONS=--enable-source-maps
GENIEACS_EXT_DIR=/opt/genieacs/ext
GENIEACS_UI_JWT_SECRET=secret

• Nastavení vlastníka a práv souboru

sudo chown genieacs:genieacs /opt/genieacs/genieacs.env
sudo chmod 600 /opt/genieacs/genieacs.env

• Vytvořte adresář pro ukládání logů

mkdir /var/log/genieacs
chown genieacs:genieacs /var/log/genieacs

• Vytvořte jednotkové soubory pro systemd. Zde platí, že je potřeba pro každou ze čtyř GenieACS služeb vytvořit jeden jednotkový soubor.
• Každá služba má dva toky pro logování: logování přistupů a logování procesů. Zatímco logování pro přístupy je konfigurováno tak, aby bylo ukládáno do souborů ve /var/log/genieacs/, logování pro procesy probíhá v rámci journald. Ke zobrazení těchto logů lze následně použít journalctl.
• Pokud dojde k selhání při provádění příkazu pro vytvoření služeb, je možné vytvořit jednotkové soubory ručně.
• Vytvoření genieacs-cwmp služby

sudo systemctl edit --force --full genieacs-cwmp

• Do editoru vložte následující a uložte

[Unit]
Description=GenieACS CWMP
After=network.target

[Service]
User=genieacs
EnvironmentFile=/opt/genieacs/genieacs.env
ExecStart=/usr/bin/genieacs-cwmp

[Install]
WantedBy=default.target

• Vytvoření genieacs-nbi služby

sudo systemctl edit --force --full genieacs-nbi

• Do editoru vložte následující a uložte

[Unit]
Description=GenieACS NBI
After=network.target

[Service]
User=genieacs
EnvironmentFile=/opt/genieacs/genieacs.env
ExecStart=/usr/bin/genieacs-nbi

[Install]
WantedBy=default.target

• Vytvoření genieacs-fs služby

sudo systemctl edit --force --full genieacs-fs

• Do editoru vložte následující a uložte

[Unit]
Description=GenieACS FS
After=network.target

[Service]
User=genieacs
EnvironmentFile=/opt/genieacs/genieacs.env
ExecStart=/usr/bin/genieacs-fs

[Install]
WantedBy=default.target

• Vytvoření genieacs-ui služby

sudo systemctl edit --force --full genieacs-ui

• Do editoru vložte následující a uložte

[Unit]
Description=GenieACS UI
After=network.target

[Service]
User=genieacs
EnvironmentFile=/opt/genieacs/genieacs.env
ExecStart=/usr/bin/genieacs-ui

[Install]
WantedBy=default.target

• Uložte následující konfiguraci rotace log souborů za pomocí logrotate jako /etc/logrotate.d/genieacs

/var/log/genieacs/*.log /var/log/genieacs/*.yaml {
    daily
    rotate 30
    compress
    delaycompress
    dateext
}

• Povolení a spuštění vytvořených služeb

sudo systemctl enable genieacs-cwmp
sudo systemctl start genieacs-cwmp
sudo systemctl status genieacs-cwmp

sudo systemctl enable genieacs-nbi
sudo systemctl start genieacs-nbi
sudo systemctl status genieacs-nbi

sudo systemctl enable genieacs-fs
sudo systemctl start genieacs-fs
sudo systemctl status genieacs-fs

sudo systemctl enable genieacs-ui
sudo systemctl start genieacs-ui
sudo systemctl status genieacs-ui

• Po spuštění služeb je GUI GenieACS je dostupné na http://<IP zařízení>:3000

Instalace a konfigurace EasyCWMP na AP GL.iNet AR750 Creta

Předpokladem bezproblémové instalace CWMP klienta v podobě EasyCWMP (https://easycwmp.org/) na zařízení GL.iNet AR750 Creta, je oficiální firmware 3.203 od GL.iNetu s OWRT 19.07.7 a instalovanou LuCI.

• Nejprve je nutné doinstalovat závislosti v podobě balíčků libjson-c4_0.13.1-2_mips_24kc.ipk a libmicroxml_2015-03-18_mips_24kc.ipk. Ty nejsou součástí standardních repozitářů je proto nutné je nahrát na AP a následně nainstalovat přes příkazovou řádku. Baličky jsou dostupné zde a zde.

• Instalace proběhne na AP přes příkazovou řádku pomocí příkazu

opkg install libjson-c4_0.13.1-2_mips_24kc.ipk
opkg install libmicroxml_2015-03-18_mips_24kc.ipk

• Nyní je možné stáhnout, nahrát a doinstalovat balíček s EasyCWMP. Ten je dostupný zde.

opkg install easycwmp_1.8.6_mips_24kc.ipk

• Nastavení služby EasyCWMP provedeme úpravou příslušného souboru v adresáři /etc/config/, kde nastavíme url (ip adresu včetně portu) ACS serveru, uživatelské jméno a heslo (v případě ověřování uživatele na ACS serveru) a dále ID zařízení, které se skládá z předpony oui a sériového čísla. Nastavení unikátního ID pro každé zařízení je kritické, jelikož při instalaci balíčku EasyCWMP se negeneruje unikátní ID např. pomocí MAC adresy zařízení, ale použije se přednastavené ID FFFFFF-FFFFFF123456.

vim /etc/config/easycwmp

config local
    option enable '1'
    option interface 'eth0'
    option port '7547'
    option ubus_socket '/var/run/ubus.sock'
    option date_format '%FT%T%z'
    option authentication 'Digest'
    option logging_level '3'

config acs
    option url 'http://<IP_ACS>:7547'
    option username 'easycwmp'
    option password 'easycwmp'
    option periodic_enable '1'
    option periodic_interval '100'
    option periodic_time '0001-01-01T00:00:00Z'

config device
    option oui 'FFFFFF'
    option serial_number 'FFFFFF123xxx'
    option manufacturer 'OpenWrt https___openwrt.org_'
    option product_class 'Generic'
    option hardware_version 'v0'
    option software_version 'r11063-85e04e9f46'

• Ve výchozím stavu neumí EasyCwmp ovládat nastavení Radius serveru u zabezpečení Wi-Fi WPA2 Enterprise. Toto chování je potřeba doprogramovat (upravit příslušné textové soubory). Přejdeme do adresáře /usr/share/easycwmp/functions. Volitelně můžeme upravit soubor root, kde se nastavuje výchozí vstupní bod stromové struktury vlastností, které EasyCwmp dokáže spravovat. Přednastaveno je jméno Device, které můžeme změnit na libovolný textový řetězec, podle našich potřeb. Pokud změníme jméno tohoto výchozího bodu, musíme také odpovídajícím způsobem upravit příkazy na ACS serveru viz. níže.
• Dále je třeba upravit soubor wifi a ip a to tak, že ze všech příkazů, které obsahují přepínač -X u příkazu $UCI_GET/$UCI_SET/$UCI_SHOW , je potřeba tento přepínač -X odstranit.
• V souboru wifi je také nutno připsat funkce pro nastavení Radius serveru, Radius Accounting serveru a nastavení hesel pro tyto servery. Jelikož v rámci obsluhujícího Home serveru je Radius i Radius Accounting na stejném zařízení a používá stejné heslo, je možno sloučit nastavení do jedné funkce pro nastavení serverů a jedné pro nastavení hesel. Do funkce sub_entry_WiFi_SSID(), která slouží jako vstupní bod pro ovládání položek v podstromu SSID, přidáme řádky pro volání samotných funkcí

sub_entry_WiFi_SSID() {
    localj="$2"
    localiface="$3"
    case_param "$1" belongto "$DMROOT.WiFi.SSID.$j." && {
        ...
        common_execute_method_param "$DMROOT.WiFi.SSID.$j.Radius" "1" "wifi_ap_get_Radius $iface" "wifi_ap_set_Radius $iface"
        common_execute_method_param "$DMROOT.WiFi.SSID.$j.RadiusPass" "1" "wifi_ap_get_RadiusPass $iface" "wifi_ap_set_RadiusPass $iface"
        return 0
    }
    return $E_INVALID_PARAMETER_NAME;
}

• V následujících krocích přidáme nakonec souboru funkce ovládající vlastnosti Wi-Fi sítí
• Nastavení adresy Radius serveru a Radius Accounting serveru

wifi_ap_set_Radius() {
    $UCI_SET $1.auth_server=$2
    $UCI_SET $1.acct_server=$2
    uci commit wireless
}

• Nastavení hesla pro Radius server a Radius Accounting server

wifi_ap_set_RadiusPass() {
    $UCI_SET $1.auth_secret=$2
    $UCI_SET $1.acct_secret=$2
    uci commit wireless
}

• Zjištění adresy aktuálně nastaveného Radius serveru (a tím i Radius Accounting serveru)

wifi_ap_get_Radius() {
    local radius='$UCI_GET $1.auth_server'
    echo $radius
}

• Zjištění aktuálně nastaveného hesla pro Radius servery – ponecháno prázdné – z bezpečnostních důvodů by nemělo být možné vzdáleně zjistit heslo, tudíž funkce vrací 0

wifi_ap_get_RadiusPass() {
    return 0
}

• Spuštění EasyCWMP na AP

/etc/init.d/easycwmpd enable
/etc/init.d/easycwmpd start

GenieACS Provisions a Presets

Provision je kód napsaný v programovacím jazyce JavaScript, který je spouštěn na serveru v závislosti na stavu jednotlivých zařízení, či na základě přednastavené hodnoty. Tímto způsobem je možné implementovat složitější scénáře pro vzdálenou správu, a především je možné vzdálenou správu do určité míry automatizovat.

Provisions jsou mapovány k jednotlivým zařízením pomocí Presets. V případě potřeby je možné při přiřazování Preset k Provision skriptu předat argumenty, které jsou následně dostupné skrz globální proměnnou args.

Detailnější popis jednotlivých předdefinovaných funkcí lze najít zde.

Nastavení automatické vzdálené správy

Následuje popis nastavení automatizace vzdálené správy, která je prováděna periodicky každý den.

• Jednotlivé Provision skripty je možné vytvářet ve webovém rozhraní GenieACS. Zde stačí přejít do záložky Admin a dále zvolit v menu položku Provisions.
• Kliknutím na tlačítko New se zobrazí formulář, kde je nutné uvést název nového Provision skriptu (Name) a dále samotný kód skriptu (Script).
• Hodnoty parametrů spravovaného zařízení lze deklarovat pomocí předdefinované funkce declare(path, timestamps, values), která přijímá tři argumenty – path (cesta k danému parametru, viz dále), timestamps (objekt, kde klíčem je název atributu a hodnotou je celé číslo představující Unix časovou značku), values (objekt obsahem podobný objektu timestamps, ale jedná se o hodnotu parametru, kterou chceme nastavit na spravovaném zařízení).
• Parametr path může obsahovat wildcard (*), alias filtr ([název:hodnota]), popřípadě je možná jejich kombinace. Wildcard segment v cestě parametru aplikuje stanovenou konfiguraci na 0 až N parametrů, které se shodují s danou cestou, kdy platí, že zmíněný wildcard segment může být zastoupen jakýmkoliv názvem, nebo hodnotou. Alias filtr má podobou funkci jako wildcard s tím rozdílem, že provádí dodatečnou filtraci na parametrech následujících za tímto alias filtrem. Filtrace je prováděna na základě poskytnutého páru název-hodnota.
• Například cesta Device.WANDevice.1.WANConnectionDevice.1.WANIPConnection.[AddressingType:DHCP].ExternalIPAddress navrátí seznam všech ExternalIPAddress parametrů (0 a více), kde je hodnota parametru AddressingType nastavena jako DHCP.

• Příklad Provision skriptu pro vzdálenou správu konfigurace WLAN, která je prováděna periodicky každý den, lze vidět níže.

const informInterval = 300;

// Aktualizace každý den - 86400000 ms -> 1 den
const daily = Date.now(86400000);

// Unikátní ofset pro každé zařízení pro lepší rozložení zátěže
const informTime = daily % 86400000;

declare("InternetGatewayDevice.ManagementServer.PeriodicInformEnable", {value: daily}, {value: true});
declare("InternetGatewayDevice.ManagementServer.PeriodicInformInterval", {value: daily}, {value: informInterval});
declare("InternetGatewayDevice.ManagementServer.PeriodicInformTime", {value: daily}, {value: informTime});

declare("Device.ManagementServer.PeriodicInformEnable", {value: daily}, {value: true});
declare("Device.ManagementServer.PeriodicInformInterval", {value: daily}, {value: informInterval});
declare("Device.ManagementServer.PeriodicInformTime", {value: daily}, {value: informTime});

declare("InternetGatewayDevice.LANDevice.*.WLANConfiguration.*.Enable", {value: daily}, {value: false});

declare("InternetGatewayDevice.LANDevice.1.WLANConfiguration.*.Enable", {value: daily}, {value: true});
declare("InternetGatewayDevice.LANDevice.4.WLANConfiguration.*.Enable", {value: daily}, {value: true});

declare("Device.WiFi.SSID.1.Enable", {value: daily}, {value: true})
declare("Device.WiFi.SSID.1.Name", {value: daily}, {value: "wlan0"})
declare("Device.WiFi.SSID.1.SSID", {value: daily}, {value: "Test SSID"});
declare("Device.WiFi.SSID.1.LowerLayers", {value: daily}, {value: "Device.WiFi.Radio.1."})
declare("Device.WiFi.AccessPoint.1.Security.ModeEnabled", {value: daily}, {value: "WPA2-Enterprise"});
declare("Device.WiFi.SSID.1.Radius", {value: daily}, {value: "192.168.10.24"});
declare("Device.WiFi.SSID.1.RadiusPass", {value: daily}, {value: "nejakeHeslo1234"});

declare("Device.WiFi.SSID.4.Enable", {value: daily}, {value: true})
declare("Device.WiFi.SSID.4.Name", {value: daily}, {value: "wlan1"})
declare("Device.WiFi.SSID.4.SSID", {value: daily}, {value: "Eduroom"});
declare("Device.WiFi.SSID.4.LowerLayers", {value: daily}, {value: "Device.WiFi.Radio.2."})
declare("Device.WiFi.SSID.4.X_IPInterface", {value: daily}, {value: "Device.IP.Interface.2."})
declare("Device.WiFi.AccessPoint.4.Security.ModeEnabled", {value: daily}, {value: "WPA2-Personal"});
declare("Device.WiFi.AccessPoint.4.Status", {value: daily}, {value: "Enabled"});

• Po vyplnění požadovaných vstupních polí uložíme Provision skript kliknutím na tlačítko Save.
• Aby došlo k uplatnění Provision skriptu je nutné jej přiřadit k Preset. To provedeme v záložce Admin, kde následně zvolíme položku Presets.
• Kliknutím na tlačítko New dojde ke zobrazení formuláře s jednotlivými možnostmi nastavení Presetu.
• Zadáme libovolný název Presetu do vstupního pole Name, volbu Channel můžeme nastavit jako default, Weight zadáme například 800 a v rozevíracím seznamu u volby Provision vybereme název Provision skriptu vytvořeném v předchozích krocích.
• Preset uložíme kliknutím na tlačítko Save. Tímto způsobem jsme k vytvořenému Presetu přiřadili Provision skript. U zařízení, které jsou součástí vzdálené správy, by tak mělo dojít k nastavení jednotlivých parametrů dle kódu ve skriptu.
• Pokud není potřeba Provision skript spouštět periodicky, ale například pouze při restartu zařízení, je možné toho docílit volbou Events při nastavování Presetu. Jednotlivé hodnoty volby Events jsou následující.

• Více o Presets a jejich použití je možné nalézt zde.