Система UCI

Див. також: UCI за замовчуванням, Мережеве скриптування

Абревіатура UCI розшифровується як Unified Configuration Interface — уніфікований інтерфейс конфігурації. Це система централізованого керування налаштуваннями сервісів у OpenWrt.

UCI прийшла на зміну конфігурації на основі NVRAM, яка використовувалася в серії прошивок White Russian. Це основний інтерфейс для налаштування ключових параметрів системи: мережі, бездротового зв’язку, журналювання, віддаленого доступу тощо.

Багато програм у репозиторії OpenWrt сумісні з UCI. Програми роблять сумісними з UCI шляхом автоматичної генерації конфігураційного файлу (який читає програма) на основі значень з відповідного UCI-файлу при запуску ініціалізаційного скрипта з директорії /etc/init.d/. Докладніше — Ініціалізаційні скрипти.

Отже, при запуску демонів через UCI-сумісний скрипт, оригінальний конфігураційний файл програми буде перезаписано. Наприклад, у випадку Samba/CIFS файл /etc/samba/smb.conf буде перезаписано значеннями з файлу /etc/config/samba після запуску /etc/init.d/samba start.

Більше того, такі файли часто зберігаються в RAM, а не у флеш-пам’яті, оскільки вони постійно оновлюються і не потребують зберігання в постійній пам’яті.

Якщо потрібно зберегти ручне керування оригінальними конфігураціями, які не доступні через UCI, можна вимкнути UCI для окремих сервісів. Приклад — в cifs.server описано, як це зробити для Samba.

Для програм, які не підтримують UCI, існує окремий список таких конфігураційних файлів. Зверніть увагу: більшість сторонніх програм мають власну документацію, до якої варто звертатися.

Централізовані конфігураційні файли OpenWrt розташовані в директорії /etc/config/. Кожен файл відповідає певному розділу системи. Редагувати конфігурацію можна:

• вручну через текстовий редактор (наприклад, vi),
• через командний інтерфейс uci,
• або через API (Shell, Lua, C), що використовується також у веб-інтерфейсах (наприклад, LuCI).

Після змін у файлах UCI, щоб ці зміни набули чинності, сервіси потрібно перезапустити (або, у деяких випадках, просто перезавантажити) за допомогою скриптів з /etc/init.d/.

Багато програм сумісні з UCI завдяки тому, що їхні скрипти init.d:

1. беруть значення з /etc/config/…,
2. генерують стандартний конфігураційний файл,
3. запускають відповідну програму.

‼️ Якщо ви просто перезапустите виконуваний файл напряму, минаючи скрипт init.d, зміни в UCI не застосуються.

Приклад: Щоб змінити IP-адресу пристрою з 192.168.1.1 на 192.168.2.1, змініть у файлі /etc/config/network:

option ipaddr 192.168.1.1

на

option ipaddr 192.168.2.1

Після цього застосуйте зміни:

/etc/init.d/network restart

Увага: після цього IP-адреса пристрою зміниться, тому для нового SSH-з’єднання використовуйте адресу 192.168.2.1.

Конфігураційні файли UCI зазвичай складаються з одного або кількох блоків config — так званих секцій, які містять одну або більше інструкцій option, що визначають конкретні значення.

Символ # використовується для коментарів. Якщо рядок містить # поза межами рядка в лапках, все після нього буде проігноровано.

Нижче приклад простого конфігураційного файлу (див. також uci_dataobject_model):

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

Пояснення:

• Інструкція config 'example' 'test' відкриває секцію типу example з ідентифікатором test. Секція може бути також анонімною (тобто без назви), але тип обов’язковий — він визначає, як програма має обробляти цю секцію.
• Рядки option 'string' 'some value' і option 'boolean' '1' задають прості значення в межах секції. В синтаксисі немає різниці між рядковими й булевими значеннями. Згідно конвенції, булеві значення можуть бути такими:
  1. false: 0, no, off, false, disabled
  2. true: 1, yes, on, true, enabled
• Інструкції list задають опцію з декількома значеннями. Усі рядки з однаковим ім'ям (наприклад, collection) будуть зібрані в один список у заданому порядку.
• Відступи в інструкціях option і list — лише для зручності читання, вони не є обов’язковими.
• Якщо опція відсутня, але не обов’язкова — буде використано значення за замовчуванням. Якщо опція обов’язкова, але відсутня — це може викликати помилки в роботі програми.
• Якщо секцію потрібно вимкнути, але вона не має параметра enabled — змініть її тип (наприклад, з example на disabled_identifier). UCI-скрипти не розпізнають такий тип, і секція буде проігнорована.

Ідентифікатори й значення зазвичай не потребують лапок. Але якщо значення містить пробіли або табуляцію, лапки обов’язкові. Дозволено використовувати як одинарні (''), так і подвійні ("") лапки.

Усі наведені нижче приклади — валідний UCI-синтаксис:

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

Неправильний синтаксис:

# значення містить пробіли, але без лапок
option  example   v_a l u-e
 
# незбалансовані лапки
option 'example" "value'

Увага: Ідентифікатори (назви опцій, секцій, файлів) можуть містити лише символи: a-z, 0-9 та _. Символи - (дефіси) не допускаються. Значення опцій можуть містити будь-які символи (якщо вони належно обгорнуті в лапки).

Підсвічування синтаксису в Vim: vim-uci Добре працює разом із sshfs (потрібен openssh-sftp-server).

Для зміни налаштувань зазвичай редагують UCI-конфігураційні файли напряму. Однак для скриптів вся конфігурація UCI може бути також прочитана й змінена за допомогою утиліти командного рядка uci.

Для розробників, яким потрібно автоматично аналізувати UCI-конфігурацію, використання інструментів типу awk або grep — зайве, неефективне й помилкове. Утиліта uci надає повну функціональність для читання, зміни та обробки UCI.

Нижче наведено синтаксис і приклади використання цієї потужної утиліти.

Коли в конфігурації є кілька секцій одного типу, UCI підтримує масивоподібну адресацію. Наприклад, якщо у файлі /etc/config/system задано 8 NTP-серверів, ви можете звертатися до них так:

- system.@timeserver[0] — перший - system.@timeserver[7] — останній

Також можна використовувати негативні індекси: - -1 — останній - -2 — передостанній

Це дуже зручно при додаванні нових правил у кінець списку.

Дивіться приклади нижче.

Множинні секції: UCI дозволяє використовувати “масивний” синтаксис, якщо у файлі кілька секцій одного типу. Наприклад, якщо у файлі /etc/config/system вказано 8 серверів часу NTP, ви можете звернутися до них так:

- system.@timeserver[0] — перший - system.@timeserver[7] — останній - system.@timeserver[-1] — також останній - system.@timeserver[-2] — передостанній

Цей синтаксис дуже зручний, особливо для додавання нових записів у кінець списку.

# uci
Використання: uci [<опції>] <команда> [<аргументи>]

Команди:
  batch
  export     [<config>]
  import     [<config>]
  changes    [<config>]
  commit     [<config>]
  add        <config> <section-type>
  add_list   <config>.<section>.<option>=<string>
  del_list   <config>.<section>.<option>=<string>
  show       [<config>[.<section>[.<option>]]]
  get        <config>.<section>[.<option>]
  set        <config>.<section>[.<option>]=<value>
  delete     <config>.<section>[.<option>]
  rename     <config>.<section>[.<option>]=<name>
  revert     <config>[.<section>[.<option>]]
  reorder    <config>.<section>=<position>

Опції:
  -c <path>  вказати шлях до конфігураційних файлів (типово: /etc/config)
  -d <str>   задати роздільник для спискових значень у команді uci show
  -f <file>  використовувати вхідні дані з <file>, а не з stdin
  -m         при імпорті — об'єднувати дані з наявним пакетом
  -n         називати безіменні секції при експорті (типово)
  -N         не називати безіменні секції
  -p <path>  додати шлях пошуку для файлів змін конфігурацій
  -P <path>  додати шлях і встановити його як типовий
  -q         тихий режим (не виводити помилки)
  -s         увімкнути строгий режим (зупинка при помилках синтаксису, типовий)
  -S         вимкнути строгий режим
  -X         не використовувати розширений синтаксис у 'show'

⚠️ Примітка: Ви не можете повністю видалити конфігураційний файл командою uci delete, наприклад, uci delete umdns — не спрацює. Щоб повністю очистити конфігурацію, використайте такий скрипт:

while uci -q delete umdns.@umdns[0]; do :; done

UCI-модель складається з таких частин:

• config — основна група конфігурації (наприклад: network, system, firewall). Відповідає одному файлу в /etc/config.
• sections — кожна конфігурація розбита на секції (розділи), які можуть бути іменованими або безіменними.
• types — кожна секція має тип, який визначає її роль. Наприклад, у файлі network часто є секції типу interface з іменами lan, wan, loopback, wan6.
• options — параметри в секції, які визначають конкретні значення.
• values — значення опцій.

Секції можуть бути:

• іменованими — з фіксованим ім’ям (наприклад, wan)
• безіменними — з автоматично згенерованим ID (наприклад, cfg073777)

Безіменні секції:

• Відображаються як @тип[індекс] (наприклад, @switch[0])
• Ідентифікатори типу cfgxxxxx (наприклад, cfg073777) призначаються автоматично.

🔍 Приклад (анонімна секція):

# uci show network
network.@switch[0]=switch
network.@switch[0].name='switch0'
network.@switch[0].reset='1'
network.@switch[0].enable_vlan='1'

🔍 Той самий запис із CFGID:

# uci show network.@switch[0]
network.cfg073777=switch
network.cfg073777.name='switch0'
network.cfg073777.reset='1'
network.cfg073777.enable_vlan='1'

Секції UCI можуть бути подані в різних виглядах:

• Зручно для людини — так, як у файлах або команді:

uci export <config>

• Програмно — командою:

uci show <config>, з доступом до:

1. іменованої секції
2. безіменної секції за @тип[індекс]
3. безіменної секції за cfgID

Тип подання
Зрозуміле для людини, іменована секція (uci export network)	Зрозуміле для людини, безіменна секція (uci export network)
Програмне, іменована секція (uci show network.wan)	Програмне, безіменна секція (uci show network)	Програмне, через CFGID (uci show network.@switch[0])

Якщо потрібно змінити порт прослуховування вебсервера uHTTPd з 80 на 8080, змініть конфігурацію в /etc/config/uhttpd так:

uci set uhttpd.main.listen_http='8080'
uci commit uhttpd
/etc/init.d/uhttpd restart

Готово — конфігураційний файл оновлено, і uHTTPd тепер слухає порт 8080.

uci export назва_конфігурації

Приклади доступних конфігурацій: defaults, dnsmasq, dropbear, firewall, fstab, net, qos, samba, system, wireless.

uci show назва_конфігурації

Приклад:

# uci show system 
system.@system[0]=system 
system.@system[0].hostname='OpenWrt' 
system.@system[0].timezone='UTC' 
system.ntp=timeserver 
system.ntp.server='0.openwrt.pool.ntp.org' '1.openwrt.pool.ntp.org' '2.openwrt.pool.ntp.org' '3.openwrt.pool.ntp.org' 
system.ntp.enabled='1' 
system.ntp.enable_server='0'

uci get httpd.@httpd[0].port

uci add_list system.ntp.server='0.de.pool.ntp.org'

uci delete system.ntp.server
uci add_list system.ntp.server='0.de.pool.ntp.org'
uci add_list system.ntp.server='1.de.pool.ntp.org'
uci add_list system.ntp.server='2.de.pool.ntp.org'

uci add назва_конфігурації тип_секції

Це створить нову безіменну секцію заданого типу всередині вказаного файлу конфігурації. Після цього до секції можна додавати опції як зазвичай. Команда поверне автоматично згенеровану назву секції (наприклад, cfg03ab1d), яку можна використати для подальших змін.

Приклад — додавання секції rule до firewall з посиланням через індекс:

uci add firewall rule
uci set firewall.@rule[-1].src='wan'

Те саме, але з використанням збереженого ідентифікатора:

sid=$(uci add firewall rule)
uci set firewall.$sid.src='wan'

Щоб додати іменовану секцію певного типу, використовуйте скорочену форму команди uci set — без ключового слова option:

touch /etc/config/example
uci set example.this_name=blah
uci set example.this_name.xxx=yyy
uci set example.other_name=blah
uci set example.other_name.yyy=zzz
uci commit example

Перевірка:

uci show example

example.this_name=blah
example.this_name.xxx=yyy
example.other_name=blah
example.other_name.yyy=zzz

Файл конфігурації після цього:

cat /etc/config/example

config blah 'this_name'
    option xxx 'yyy'
    
config blah 'other_name'
    option yyy 'zzz'

Щоб побачити всі зміни, які ще не були збережені:

uci changes

uci commit назва_конфігурації 
reload_config

uci commit
reload_config

Цей приклад зберігає ID новоствореної секції, повернутий командою uci add, і використовує його для подальшого додавання опцій до цієї секції. Таким чином, не потрібно вручну вписувати ідентифікатор — зручно і для інтерактивної роботи, і для скриптів.

🔧 Універсальний шаблон:

section_id=$(uci add <config> <section-type>) 
uci batch << EOI
set <config>.$section_id.<option1>='value'
set <config>.$section_id.<option2>='value'
set <config>.$section_id.<option3>='value'
...
EOI
uci commit

📌 Приклад для фаєрволу:

rule_id=$(uci add firewall rule) 
uci batch << EOI
set firewall.$rule_id.enabled='1'
set firewall.$rule_id.target='ACCEPT'
set firewall.$rule_id.src='wan'
set firewall.$rule_id.proto='tcp udp'
set firewall.$rule_id.dest_port='111'
set firewall.$rule_id.name='NFS_share'
EOI
uci commit

Уявімо такий приклад конфігураційного файлу:

config bar 'first'
  option name 'Mr. First'
config bar
  option name 'Mr. Second'
config bar 'third'
  option name 'Mr. Third'

Тоді всі ці шляхи звертаються до одних і тих самих записів:

# Mr. First
uci get foo.@bar[0].name
uci get foo.@bar[-0].name
uci get foo.@bar[-3].name
uci get foo.first.name
 
# Mr. Second
uci get foo.@bar[1].name
uci get foo.@bar[-2].name
# uci get foo.second.name — не працює, оскільки 'second' не має імені
 
# Mr. Third
uci get foo.@bar[2].name
uci get foo.@bar[-1].name
uci get foo.third.name

🔍 Команда `uci show foo` покаже:

foo.first=bar
foo.first.name='Mr. First'
foo.@bar[0]=bar
foo.@bar[0].name='Mr. Second'
foo.third=bar
foo.third.name='Mr. Third'

А команда `uci show foo.@bar[0]` покаже лише:

foo.first=bar
foo.first.name='Mr. First'

💡 Це може збивати з пантелику, але пояснюється особливостями внутрішнього мапінгу імен у UCI.

Це гарний приклад як додати правило фаєрволу для переспрямування TCP-порту SSH, а також приклад використання негативного індексу (-1) у синтаксисі `uci`.

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='22'
uci commit firewall
/etc/init.d/firewall restart

uci get wireless.@wifi-iface[0].ssid

Див. UCI (Unified Configuration Interface) – технічна довідка

Див. також: UCI extras

Якщо ви вручну редагували файли в /etc/config, можливо, деякі з них містять помилки синтаксису, які можуть спричинити їх пошкодження.

Приклад помилки парсингу:

# uci show fstab
uci: Parse error (invalid command) at line 20, byte 0