eko.one.pl - OpenWrt - Tajniki UCI

Praktyczne zastosowania interfejsu UCI

Ostatnia zmiana: 2019-06-29 20:53

Interfejs "uci" (Unified Configuration Interface - ujednolicony interfejs konfiguracyjny) jest sposobem konfiguracji systemu stosowanym w OpenWrt. W przeciwieństwie do stosowanego w starych wydaniach nvram ma też inne zalety - mniejsze zużycie flash (nie jest ciągle zapisywany ten sam obszar, tylko przydzielane jest losowo miejsce do zapisania pliku - wynika z właściwości systemu plików) czy możliwość zastosowania go w normalnych systemach plików (np. dla x86).

Budowa pliku konfiguracji

Domyślnie pliki konfiguracyjne zawarte są w katalogu /etc/config. Ważna jest nazwa pliku (przez nią odwołujemy się w poleceniach) oraz jego budowa w postaci wydzielonych sekcji, które zwykle wyglądają w następujący sposób:


    config 'example' 'test'
        option 'string' 'wartosc'
        option 'boolean' '1'
        list 'kolekcja' 'first item'
        list 'kolekcja' 'second item'

Definiuje to sekcje 'example' o nazwie 'test' (tzw. sekcja nazwana). Nazwy może nie być, wtedy sekcja jest anonimowa. Następnie są opcje definiowane przez 'option' o nazwie 'string' które mają wartość 'wartosc'. Oprócz słowa kluczowego option wyróżnia się jeszcze słowo 'list' które jest po prostu zbiorem wartości dla danej opcji. Opcje i wartości mogą być bez apostrofów lub z, opcjonalnie. Jeżeli wartość zawiera spacje musi być podana w apostrofach, np.


    option ifname 'eth0 wlan0'

Nazwy opcji nie mogą zawierać znaku "-".
W praktyce może to wyglądać następująco (na podstawie części przykładowego pliku /etc/config/firewall):


    config 'rule'
        option 'src' 'wan'
        option 'proto' 'udp'
        option 'dest_port' '68'
        option 'target' 'ACCEPT'

    config 'rule'
        option 'name' 'SSH'
        option 'src' 'wan'
        option 'target' 'ACCEPT'
        option 'proto' 'tcp'
        option 'dest_port' '22'

    config 'rule' 'poczta'
        option 'name' 'smtp'
        option 'src' 'wan'
        option 'target' 'ACCEPT'
        option 'proto' 'tcp'
        option 'dest_port' '25'

Definiuje to trzy sekcje 'rule' które zawierają przypisane określonych wartości do opcji. Większość przykładów będzie wykonywanych na tym pliku.

Składnia UCI

Odwołanie zawsze następuje wg schematu


    konfig.sekcja.nazwa_opcji=wartość

Gdzie konfig jest nazwą pliku z katalogu /etc/config. Niektóre elementy można pomiąć (np. dla uci show) wtedy zostanie wyświetlona całość konfiguracji, lub je podać, wtedy uzyskamy zawartość określonej sekcji.

Przykład
- wyświetlenie całej konfiguracji


    # uci show

- wyświetlenie konfiguracji z określonego pliku


    # uci show firewall

Odwołanie do sekcji

Poszczególne sekcje numerowane są od 0 (od góry) lub od -1 (od dołu).

Aby odwołać się do pierwszej sekcji wystarczy więc


    # uci show firewall.@rule[0]

Aby odwołać się do ostatniej sekcji wystarczy


    # uci show firewall.@rule[-1]

Aby odwołać się do trzeciej sekcji należy wydać polecenie (o ile znamy ile jest sekcji)


    # uci show firewall.@rule[2]

(sekcje są numerowane od 0, więc sekcja trzecia ma indeks 2)
Oczywiście możliwe jest także pobranie wartości konkretnej opcji, np.


    # uci get firewall.@rule[2].name

Jeżeli nie ma opcji o takiej nazwie to zostanie zwrócony błąd. Przydaje się wiec opcja -q programu, co powoduje że uci po prostu nie zwraca wartości


    # uci -q get firewall.@rule[2].name

Modyfikacje

Ustawianie opcji


    # uci set firewall.@rule[0].name='test'

Jeżeli sekcja jest nazwana można tez odwołać się poprzez nazwę, np.


    # uci set firewall.poczta.name='test'

Dodanie listy


    # uci add_list firewall.@rule[0].name='test'

Usuwanie opcji


    # uci del firewall.@rule[0].name

jeżeli sekcja jest nazwana można tez odwołać się poprzez nazwę, np.


    # uci del firewall.poczta.name

Wyświetlenie zmian

Aby zobaczy listę zmian wystarczy wydać polecenie


    # uci changes firewall

Oczywiście przed zatwierdzeniem!

Zatwierdzanie zmian

Opcje ustawia się "w pamięci". Aby przetrwało to po restarcie systemu należy zapisać je na stałe do pliku poleceniem commit, np.


    # uci commit firewall

System, o ile korzysta z uci a nie z plików, widzi także zmiany wykonane w uci bez potrzeby zatwierdzania, wiec zadziała np.


    # uci set wireless.@wifi-device[0].disabled=0
    # wifi

czyli włączamy wifi, ale nie modyfikujemy tego w pliku. Po restarcie zmiana opcja nie będzie już widoczna bo brak było fizycznych zmian w pliku konfiguracyjnym.

Anulowanie zmian


    # uci revert firewall

Dzięki tej opcji możliwe jest anulowanie zmian wykonanych wcześniej (np. przez pomyłkę) ale oczywiście przed zatwierdzeniem! Można też... zrestartować router - ponieważ zmiany nie zostały zapisane to nie mają one odbicia w plikach konfiguracyjnych.

Dodawanie nowej sekcji


    # uci add firewall rule
    # uci set firewall.@rule[-1].name=poczta
    # uci set firewall.@rule[-1].src=wan
    # uci set firewall.@rule[-1].target=ACCEPT
    # uci set firewall.@rule[-1].proto=tcp
    # uci set firewall.@rule[-1].dest_port=110
    # uci commit firewall

Dodajemy nową sekcję 'rule'. Ponieważ nie wiemy która ona jest, odwołujemy się po prostu do ostatniej dodanej (przez podanie indeksu -1)

Aby nazwać sekcje zamiast "uci add firewall rule" wprowadzamy po prostu:


    # uci set firewall.poczta=rule

Usuwanie sekcji

 
    # uci delete firewall.@rule[2]

lub, jeżeli sekcja jest nazwana


    # uci delete firewall.poczta

Dodawanie grupowe

Możliwa jest także grupowa modyfikacja opcji bez potrzebny wołania za każdym razem uci. Składania tego polecenia jest następująca.


    # uci batch << EOF
        set firewall..
        set firewall..
        set firewall..
        del firewall...
    EOF

Zakończenie

UCI posiada także inne możliwości (import, eksport sekcji, zmiana położenia plików konfiguracyjnych itd), ale są one niezbyt często używane.
Opcje można ustawić także poprzez edycję określonego pliku, ale warto zaznajomić się z obsługą uci, bo może to być przydatne w zrozumieniu działania skryptów w systemie.

Przykłady

Dodanie nowej sekcji


    # uci add firewall rule
    # uci set firewall.@rule[-1].src=wan
    # uci set firewall.@rule[-1].target=ACCEPT
    # uci set firewall.@rule[-1].proto=tcp
    # uci set firewall.@rule[-1].dest_port=110
    # uci commit firewall

Wynikiem jest:


    config 'rule'
        option 'src' 'wan'
        option 'target' 'ACCEPT'
        option 'proto' 'tcp'
        option 'dest_port' '110'

Dodanie nowej sekcji nazwanej


    # uci set firewall.poczta=rule
    # uci set firewall.poczta.src=wan
    # uci set firewall.poczta.target=ACCEPT
    # uci set firewall.poczta.proto=tcp
    # uci set firewall.poczta.dest_port=110
    # uci commit firewall

Wynikiem jest:


    config 'rule' 'poczta'
        option 'src' 'wan'
        option 'target' 'ACCEPT'
        option 'proto' 'tcp'
        option 'dest_port' '110'