User Tools

Site Tools


hu:doc:uci

Az UCI Rendszer

Az UCI a Unified Configuration Interface rövidítése. Célja, hogy egységesítse az OpenWrt konfigurálását.

A rendszer beállításának egyszerűnek és egyértelműnek kéne lennie, megkönnyítve mindenki életét. Erről szól az UCI. Jelenleg az OpenWrt-ben a legfontosabb rendszerbeállítások az UCI konfigurációs felületével kezelhetők. Ezek azok a beállítások amik létfontosságúak az eszköz működéséhez, általában ezeket láthatjuk egy hagyományos router vagy beépített eszköz webes felületén. Ilyenek például az alapvető hálózati beállítások, wi-fi beállítások, loggolás és távoli elérés beállításai.

Ezeken kívül bizonyos külső programok is kompatibilisek az UCI rendszerrel, így ezek is sokkal könnyebben kezelhetőek. Szinte minden programnak saját konfigurációs fájlja van szanaszét elszórva a fájlrendszerben, (pl. /etc/network/interfaces, /etc/exports, /etc/dnsmasq.conf or /etc/samba/samba.conf), ráadásul ezek formátuma is teljesen eltérő. Az OpenWrt segítségével viszont nem kell foglalkoznod ezekkel, csak a megfelelő UCI fájlt kell módosítanod és a többit bízd a rendszerre! Természetesen a legtöbb szoftver még nincs felkészítve az UCI használatára, hiszen szükség lehet olyan speciális opciókra amikhez nélkülözhetetlen az alkalmazás saját konfigurácós felületének használata. Viszont egyre több olyan programot tesznek UCI-kompatibilissé az OpenWrt package-ek fejlesztői, amiknek előnyére válhat az egységesített beállítás. (Az UCI konfigurációs fájlok aktuális listája itt található).

A legtöbb alkalmazás esetén az UCI-kompatibilis konfigurációt úgy tették lehetővé, hogy indításkor a program eredeti konfigfájlja felülíródik a hozzá tartozó UCI fájl beállításaival. Az adott alkalmazásnak megfelelő formátumú konfigfájlt az /etc/init.d/ könyvtárban található indítóscriptek futásidőben generálják. További infók erről az Init scripts oldalon találhatóak. Ebből következik, hogyha egy UCI-kompatibilis indítószkripttel indítasz egy szolgáltatást akkor az előző konfigfájl elveszik. Például ha a Samba/CIFS szervert a /etc/init.d/samba start szkrippel indítod, akkor a /etc/samba/smb.conf fájl felülíródik a /etc/config/samba UCI konfigfájlban tárolt beállításokkal. Épp ezért legtöbbször az alkalmazások konfigfájlja nem is a flash meghajtón van tárolva, hanem a RAM-ban, mivel úgyis minden változtatásnál újraíródik az UCI fájl alapján. (Elvileg ki lehet kapcsolni az UCI-t azokban az esetekben mikor olyan opciókat szeretnél beállítani az eredeti konfigfájlban, amik az UCI-n keresztül nem elérhetőek. FIXME Biztos? Hogyan kell ezt?)

Az ilyen nem UCI-kompatibilis programokhoz hasznos a nem UCI-kompatibilis konfigfájlok listája. Ajánlott az ilyen alkalmazások saját dokumentációját tanulmányozni.

Egységes alapelvek

Az OpenWRT beállításai egy közös helyen, a /etc/config/ mappában lévő UCI fájlokban találhatóak. Minden fájl nagyjából a nevének megfelelő rendszerösszetevőt konfigurálja. A konfigurációs fájlok sima szövegszerkesztővel szerkeszthetőek vagy parancssorból az uci segédprogrammal módosíthatóak, továbbá számos API (pl. Shell, Lua és C) segítségével is kezelhetőek. A web interfészek, mint a LuCI is ezeket használják.

Egy UCI beállításfájl változtatása után (akár szövegszerkesztővel, akár parancssorból történt) az új beállítások érvényesítéséhez a hozzá tartozó szolgáltatást vagy programot újra kell indítani a megfelelő init.d hívással. A legtöbb alkalmazás UCI-kompatibilitásának kulcsa, hogy az init.d script futás közben készíti el program saját specifikus konfigfájlját. Az init.d script először kiírja a megfelelő konfigurációs fájlt az adott program által elvárt helyre, majd a program újraindításával beolvastatja azt. Mivel a konfigurációs változtatásokat az init.d script végzi, ezért egy alkamazás direkt, kézi (újra)indítása nem fogja újraolvasni az UCI konfigurációt. Ezért az UCI által konfigurált szolgáltatásokat minden esetben a megfelelő init.d scripttel kezeljük!

Nézzünk egy példát egy UCI beállítás módosítására: mondjuk, hogy meg szeretnénk változtatni az eszközünk IP címét az alapértelmezett 192.168.1.1-ről 192.168.2.1-re.

Ehhez először egy szövegszerkesztővel nyissuk meg a

/etc/config/network fájlt, majd az alábbi sort módosítsuk

option ipaddr 192.168.1.1

erre:

option ipaddr 192.168.2.1

Végül érvényesítsük a beállításokat a szolgáltatás újraindításával. Futtassuk a következő parancsot:

/etc/init.d/network restart

Természetesen ezután az eszközünk csak az új IP címen lesz elérhető!

Konfigurációs fájlok

Az aktuális UCI konfigfájlok listája az angol wikioldalon található. Magyar fordítások:

Fájl Leírás
/etc/config/dropbear SSH szerver beállítások
/etc/config/network Switch, interfészek és útvonalkonfiguráció

Fájlformátum

Az UCI konfigurációs fájlok két részből állnak: a config utasításból, amit section-nek is neveznek, és az ezen belül található option és list utasításokból, amik a konkrét beállításértékeket tartalmazzák. Egy fájl több config section-t is tartalmazhat. A config egy kategóriát jelez, az option pedig a benne lévő beállításokat.

Az UCI konfigfájlok rendkívül egyszerűek, mindössze három féle kulcsszót használnak:

  • config típus név – a beállítások kategóriája és a kategória neve
  • option név érték – egy érteket tartalmazó beállítás megadása (key-value pair)
  • list név érték – több értéket tartalmazó, felsorolásszerű beállítás megadása (több azonos levű list sort használunk)

Commenteket a # után írhatunk. Ezeket figyelmen kívül hagyják a scriptek, viszont bármikor törlődhetnek, ha az uci segédprogrammal módosítják a beállításfájlt!

Nézzünk meg egy példa konfigfájlt:

package 'example'

config 'example' 'test'
        option   'string'      'some value'
        option   'boolean'     '1'
        list     'collection'  'first item'
        list     'collection'  'second item'

  • A config 'example' 'test' utasítás jelzi a section kezdetét, aminek a típusa example és a neve test. Létezhetnek név nélküli, anonymous section-ok is, amiknek csak a típusuk van megadva de nevük nincs. A típus megadás kötelező mivel a feldolgozó scriptek ez alapján döntik el, hogyan kell kezelni a hozzá tartozó option sorokat.
  • Az option 'string' 'some value' és option 'boolean' '1' sorok egy-egy egyszerű paramétert állítanak be a section-ön belül. Az option kulcsszó utáni első érték a paraméter neve, a második pedig a paraméter értéke. A szöveges (string) és logikai (boolean) típusú változók megadása között nincs szintaktikai különbség, ugyanúgy először a nevet majd az értéket kell megadni. A logikai opciók értéke a következő lehet: igaz esetén '1' , 'on' 'true' vagy 'enabled', hamis esetén '0', 'off', 'false' vagy 'disabled' (lásd a /lib/functions.sh config_get_bool függvényét).
  • A list kulcsszóval több értéket tartalmazó, lista típusú paramétereket definiálhatunk (például usernevek listája). A list kulcsszó utáni első érték a lista neve, a második a lista-elem értéke. Az azonos nevű list sorok egy közös listává lesznek összefűzve a sorrend megtartásával. A példában lévő collection nevű lista értéke "first item, second item" lesz.
  • A behúzás alkamazása a option és list utasításoknál pusztán formai konvenció, ezzel olvashatóbb lesz a beállításfájl, de nem kötelező.
  • Ha egy opció nincs megadva és nem is kötelező, akkor végül a default érték lesz behelyettesítve (az adott programtól függően). Ha egy opció nincs megadva, de kötelező lenne a program számára, akkor az adott alkalmazás később hibát jelezhet vagy el sem indul.

Általában nem szükséges aposztrófokat használni az értékek megadásánál, csak akkor kötelezőek ha az érték szóközt, tabokat, vagy más különleges karaktereket tartalmaz. Ilyenkor megengedett az aposztróf és az idézőjel használata is, nincs köztük különbség.

Az alábbi példák mindegyike ugyanúgy érvényes és használható:

  • option example value
  • option 'example' value
  • option example "value"
  • option "example" 'value'
  • option 'example' "value"

Viszont az alábbi példák hibásak, ezekre ügyeljünk:

  • option 'example" "value' (az idézőjelek nem megfelelőek)
  • option example some value with space (a szpészt tartalmazó értékek nincsenek idézőjelben)

Fontos tudni, hogy az UCI azonosítók és a fájlnevek csak következő karakterekből állhatnak: a-z, 0-9 és _. Az option értékek a megfelelő idézőjelezéssel bármilyen karaktert tartalmazhatnak.

Parancssori segédprogram

Általában az UCI konfigfájlokat kézzel szoktuk módosítani. Ugyanakkor scripting célokra teljes körűen használható az uci parancssori segédprogram is. Segítségével a fejlesztők az UCI fájlokat egyszerűen feldolgozhatják anélkül, hogy awk-t grep-et vagy egyéb bizonytalan kimenetelű parancsokat kéne használniuk. Az uci utility segítségével egy UCI konfigfájl minden paramétere kényelmesen kiolvasható illetve módosítható.

Az uci használatakor a konfigfájlok mindig teljes egészében újraíródnak és a szükségtelen vagy az érvénytelen szintaxisú sorok kimaradnak. Ez azt jelenti, hogy minden felesleges sor törlődik, beleértve a kommenteket is! Ezért, ha magad szoktad szerkeszteni az UCI fájljaidat és szeretnéd megőrzni a kommeteket, akkor ne használd a parancsori segédprogramot, hanem továbbra is csak kézzel szerkeszd a fájlokat. Vannak olyan UCI fájlok (pl. az uhttpd konfigfájl), amik gyárilag tartalmaznak kommenteket a beállítások megkönnyítéséhez. Ezek ugyanúgy elvesznek az uci util használatakor. Továbbá fontos tudni, hogy néhány alkalmazás, köztük a LuCI webes felület is az uci segédprogramot használja és így bármikor felülírhatja az UCI fájlokat.

A parancssori segédprogram mellett az UCI beállítások shell scriptből is kényelmesen kezelhetőek.

Használati példák

Az ''uci'' utility leírása és használati példák az angol wiki oldalon találhatóak.

hu/doc/uci.txt · Last modified: 2013/12/28 19:25 (external edit)