UCI beállítások használata scriptekből

Az OpenWrt által kínált standard shell procedúrák segítségével az UCI konfigfájlok beállításai hatékonyan kiolvashatóak és kezelhetőek shell scriptekből is. Ezek a shell wrapper-ek ugyanúgy az uci parancssori segédprogramot használják, de számos funkcióval megkönnyítik a használatát.

Hogy használni tudd az általános UCI procedúrákat, mindenek előtt includolni kell a /etc/functions.sh fájlt a scriptedbe az alábbi paranccsal (általában ez csak egy symlink a ../lib/functions.sh-ra):

Ezután a config_load name hívással tölthetsz be egy adott UCI beállításfájlt. Ez a funkció előbb ellenőrzi, hogy a name abszolút elérési út-e, és ha nem, akkor alapértelmezetten a /etc/config/ mapppából próbálja betölteni a filet (általában így szokás használni).

A UCI beállítások legegyszerűbben ezzel a módszerrel érhetők el. Ha előre ismert a section neve, akkor a benne lévő option-ok értékei szekvenciális feldolgozás alkalmazása nélkül, közvetlenül is elérhetőek. Ehhez a config_get és config_set függvényeket kell használni.

Konkrét opciók beolvasására a config_get használható. Két féle paramétezése van:

Használata (teljes): config_get <variable> <section> <option> [<default>]

Ekkor a config_get procedúra legalább három paramétert vár:

1. variable - a változó neve amibe a kiolvasott érték kerülni fog
2. section - a section ID-je amiben a kért option található
3. option - az option neve aminek az értékét tudni szeretnénk
4. default (opcionális) - alapértelmezett viszatérési érték, ha a keresett option nincs beállítva

Használata (egyszerűsített): config_get <section> <option>

Egyszerű elérésnél a paraméterek a következők:

1. section - a section ID-je amiben a kért option található
2. option - az option neve aminek az értékével a függvény visszatér

Az alábbi példaprogram a “loopback” hálózati interfész IP-címét olvassa be (ez alapesetben 127.0.0.1) előbb sikeresen, majd az option nevét elrontva sikertelenül, majd újra sikeres az egyszerűbb módszerrel:

#!/bin/sh
. /etc/functions.sh
local loopbackIP
config_load network
config_get loopbackIP loopback ipaddr
echo The loopback IP is: "$loopbackIP"
 
echo "trying to read a non-existant value results default value:"
config_get loopbackIP loopback ipaddress "invalid option"
echo The loopback IP is: "$loopbackIP"
 
echo "reading with the simple method:"
loopbackIP=$(config_get loopback ipaddr)
echo The loopback IP is: "$loopbackIP"

Eredmény:

Ha előre tudjuk hogy egy logikai típusú option-t szeretnénk beolvasni, akkor használjuk a config_get_bool függvényt. A logikai konfigurációs értékek elég változatosak lehetnek, az igaz értéket a következők bármelyike jelölheti on, true, enabled vagy 1. A hamis érték off, false, disabled vagy 0 is lehet.

The config_get_bool leegyszerűsíti ezek kezelését azáltal, hogy sima integerré konvertálja őket (1 lesz az igaz és 0 a hamis érték).

Használata: config_get_bool <variable> <section> <option> [<default>]

A paraméterei ugyanazok mint a config_get-nek:

1. variable - a változó neve amibe a kiolvasott érték kerülni fog
2. section - a section ID-je amiben a kért option található
3. option - az option neve aminek az értékét tudni szeretnénk
4. default (opcionális) - alapértelmezett viszatérési érték, ha a keresett option nincs beállítva

A lista típusú UCI option-ök több értéket tárolnak ugyanazzal a névvel. Például az alábbi network nevű listának két eleme van:

A config_get használata listák eléréséhez nem mindig célravezető, mivel a lista összes elemét összefűzve, szóközzel elválasztva adja vissza. A fenti network listánál ez nem okoz különösebb gondot az eredmény: lan wifi.

Viszont kicsit bonyolultabb a helyzet ha a lista elemei maguk is tartalmaznak szóközt, például:

Ekkor config_get a következő értéket adja vissza: White Elephant Mighty Unicorn és ez alapján nem lehet eldönteni, hogy meddig tartott az első, és hol kezdődik a második elem.

A probléma megoldására a config_list_foreach iterátor használható. Ez hasonlóan működik, mint a config_foreach (lásd később), csak a section-ök helyett a lista értékeit kezeli. Használatához először egy saját callback függvényt kell definiálni, ami paraméterben fogja egyesével megkapni a lista értékeit, minden egyes lista értéknél újra meghívódik.

A config_list_foreach legalább három paramétert vár:

1. Section - a section ID-je amiben a lista van
2. Option - a lista option neve, amit fel szeretnénk dolgozni
3. Function - a callback függvény neve, ami minden lista elemnél meghívódik
4. További paraméterek (opcionális) - minden további paramétert változtatás nélkül megkap a callback függvény

Például

Teljes példaprogram, az NTP szerverek kiíratása:

#!/bin/sh
. /etc/functions.sh
counter=0
handle_listvalue() {
    local value="$1"
    local custom="$2"
    echo The $counter. value of the list is $value
    counter=$((counter+1))
    }
 
config_load system
echo "value of ntp.server list by using config_get:"
config_get ntp server
 
echo "values using the config_list_foreach iterator:"
config_list_foreach ntp server handle_listvalue 

Eredmény:

A beállítások szekvenciális feldolgozására akkor van szükség,

• ha egy section, vagy egy egész konfigfájl összes option-ját ki szeretnénk értékelni,
• ha nem tudjuk előre, hogy hány sectiont kell feldolgozni,
• ha az anonymous section-öket is el szeretnénk érni.

Erre két féle módszer használható: a visszahívásos módszer (callback) és az utólagos iteráció.

Ha a callback módszert szeretnéd használni a beállítások feldolgozásához, akkor ehhez felül definiálni kell bizonyos shell függvényeket a /etc/functions.sh includolása után, de még a config_load hívása előtt.

Ebben az esetben a keretscript a konfigfájlt soronként olvassa be és minden sorhoz meghívja a hozzá tartozó callback függvényt:

• config kulcsszónál a config_cb
• option kulcsszónál az option_cb
• list kulcsszó esetén pedig a list_cb

fut le. Ezeket nekünk kell definiálni a scriptünkben a config_load hívása előtt. (Alapesetben ezek a függvények nem csinálnak semmit, mindössze egy return 0-val visszatérnek.)

A callback függvényeken belül az aktuális section ID-je a $CONFIG_SECTION változóban érhető el.

A feldolgozás során minden új UCI section kezdeténél (config kulcsszónál) meghívódik a config_cb függvény.

A config_cb ebben az esetben két paramétert kap:

1. Type - a section típusa, pl. a config interface wan sor esetén az interface.
2. Name - a section neve, pl. a config interface wan sornál a wan, vagy anonymous section-ök esetén (pl. config route) egy automatikusan generált ID lesz, pl. cfg13abef.

A config_load függvény végén egy további, paraméterek nélküli config_cb hívás is történik, így nem csak az option-ok előtt hanem az összes section feldolgozása után is hajthatsz végre saját parancsokat. Számíts rá, hogy ilyenkor a paramétereknek nem lesz értéke, szűrd ki az esetet pl. egy if-fel.

Hasonló módon, minden egyes új option sor elérésekor az option_cb függvény hívódik meg.

Az option_cb mindig két paramétert kap:

1. Name - az option neve, pl. ifname az option ifname eth0 sor esetén
2. Value - az option értéke, pl. eth0 az option ifname eth0 sor esetén

Az option_cb függvényt a config_cb függvényből is módosíthatod a section típusa szerint. Így lehetőség van típusonként külön option_cb függvényt alkalmazva minden egyes config section-t a saját típusának megfelelően feldolgozni.

A harmadik kulcsszó sem kivétel, minden egyes új list sor elérésekor a list_cb függvény fut le. Mivel minden egyes lista elem külön list sorban van, így a függvény elemenként egyszer lesz meghívva. Ugyanazon lista elemeinek ugyanaz a nevük.

Az list_cb mindig két paramétert kap:

1. Name - a lista neve neve, pl. icmp_type a list icmp_type echo-reply sor esetén
2. Value - az option értéke, pl. echo_reply a list icmp_type echo-reply sor esetén

Írassuk ki a default system configot! A teszt pillanatában nekem így nézett ki a /etc/config/system fájl:

Az alábbi példaprogram segítségével élesben is tesztelheted a callback függvények működését. Mentsd el tetszőleges néven, majd adj rá futtatási jogot és indítsd el.

#!/bin/sh
. /etc/functions.sh
config_cb() {
    local type="$1"
    local name="$2"
    if [ ! -z $type ] ;then
      echo New section - type: "$type", name: "$name"
    else
      echo "End of configuration"
    fi
    }
 
option_cb() {
    local name="$1"
    local value="$2"
    echo "  new option - name:" "$name", value: "$value", in section: $CONFIG_SECTION
    }
 
list_cb() {
    local name="$1"
    local value="$2"
    echo "  new list element - name:" "$name", value: "$value", in section: $CONFIG_SECTION
    }
 
echo Loading system config:
config_load system

Eredmény

Három dolgot kell észrevenni:

1. a system section anonymous, ezért generálódott neki egy ideiglenes név
2. a lista típusú opciók esetén (mint a system.ntp) is meghívódik az option_cb callback. Ez valószinűleg a keretscript hibája, reméljük, hogy kijavítják valamikor.
3. a betöltés legvégén van egy paraméterek nélküli config_cb hívás, amit a függvényen belül le kell kezelni

A másik módszer a konfigurációs fájlok feldolgozására, hogy előbb betöltjük az egész fájlt a memóriába, majd sorban végigmegyünk a section-ökön a config_foreach procedúra használatával. Ez inkább akkor használatos, ha a section-ök típusa adott (tudjuk, hogy milyen option-ok vannak bennük), de nem tudjuk előre, hogy hány ilyen típusú section lesz. Sajnos option_foreach procedúra jelenleg nincs a rendszerben.

A config_foreach procedúrának egy kötelező és további opcionális paraméterei vannak:

1. Function - egy előre definiált saját függvény neve, ami minden új section esetén meghívódik
2. Type (opcionális) - ha meg van adva, akkor csak az adott típusú section-ök lesznek feldolgozva, a többit kihagyja
3. További paraméterek (opcionális) - minden további paramétert változtatás nélkül megkap az első paraméterben hívott függvény

Az alábbi példában a saját handle_interface procedúra meghívódik minden egyes config interface section-höz a /etc/config/network fájlban. A test string extra paraméterként átadódik a saját procedúránknak.

#!/bin/sh
. /etc/functions.sh
handle_interface() {
    local config="$1"
    local custom="$2"
    echo New section: "$config", custom parameter: "$custom"
    # minden új section esetén futtatandó parancsok
    }
config_load network
config_foreach handle_interface interface test

Megszakíthatjuk az iterációt, ha nem nulla értékkel térünk vissza a függvényből (return 1).

A section-ön belül a config_get vagy a config_set függvények segítségével beolvashatók vagy megváltoztathatók az option-ok értékei.