# Модуль для работы с Sysrepo в Klish3


## Обзор

Модуль klish-plugin-sysrepo предназначен для работы с хранилищем конфигурации
[Sysrepo](#https://www.sysrepo.org/) из программы
[Klish версии 3](#https://klish.libcode.org). Klish позволяет организовать
интерфейс командной строки, содержащий только команды, заданные пользователем при
конфигурировании klish. Хранилище Sysrepo использует язык моделирования данных
[YANG](#https://datatracker.ietf.org/doc/html/rfc6020) для формирования схемы
хранимой конфигурации, а также хранит саму конфигурацию. Обычно хранимая
конфигурация относится к какой-либо встроенной системе, например к
маршрутизатору. Принцип хранения и управления конфигурацией, используемый в
klish-plugin-sysrepo, похож на подход, применяемый в маршрутизаторах "Juniper".

Схема конфигурация описана YANG файлами, а доступ и редактирование элементов
конфигурации осуществляется с помощью специальных команд, доступных из klish.

Проект содержит файл `xml/sysrepo.xml`, который, будучи добавленным к файлам
конфигурации klish, объявляет новый `VIEW` с именем "sysrepo". Этот `VIEW`
содержит готовые команды для редактирования конфигурации Sysrepo. Вся работа
модуля с Sysrepo осуществляется с помощью библиотечных функций Sysrepo и
библиотеки [`libyang`](#https://github.com/CESNET/libyang). Проекты Sysrepo,
libyang и klish требуются для сборки и работы модуля klish-plugin-sysrepo.

Далее будут описаны команды работы с конфигурацией, объявленные в
`xml/sysrepo.xml`.


## Хранилище конфигурации

Система Sysrepo поддерживает четыре хранилища конфигурации.

* `running` - текущая действующая конфигурация. Состояние системы соответствует
этой конфигурации. Но эта не та конфигурация, которую редактирует администратор.
* `candidate` - редактируемая конфигурация. "Кандидат" на то, чтобы стать
действующей конфигурацией. Однако изменения в `candidate` никак не влияют на
реальное состояние системы. Только по факту того, что администратор, специальной
командой, записывает содержимое `candidate` в `running` будут происходить
изменения в системе. Т.е. изменения применяются не по одному, а "все разом".
Таким образом поддерживается целостность и непротиворечивость действующей
конфигурации. Все описанные ниже команды работают с `candidate` конфигурацией,
если не указано иное.
* `startup` - конфигурация, сохраненная на диске. Только эта конфигурация
может пережить перезагрузку системы. В случае модуля klish-plugin-sysrepo
хранилища `startup` и `running` всегда идут в паре. Т.е. модуль поддерживает их
состояние одинаковым.
* `operational` - это хранилище не имеет прямого отношение к обсуждаемой теме и
упоминаться тут больше не будет.


## Путь KPath

Многие команды для работы с конфигурацией используют "путь". Это путь в YANG
схеме или вернее в заполненной значениями конфигурации, построенной по YANG
схеме. YANG схема является ветвистой и многоуровневой. Схема может содержать
"списки", в которых элементы идентифицируются по "ключу". Элементами пути могут
быть как узлы YANG схемы, так и ключи, потому что конфигурация ветвится в
зависимости от этих ключей. Проекты Sysrepo и libyang используют
["XPath"](#https://www.w3schools.com/xml/xpath_intro.asp) для доступа к
элементам конфигурации. Несмотря на то, что XPath имеет развитый синтаксис и
возможности, он не подходит для использования в интерфейсе командной строки.
XPath довольно сложен и не будет интуитивно понятен оператору. Поэтому для
доступа к элементам конфигурации в klish-plugin-sysrepo используется упрощенный
вариант пути. Для определенности, назовем его "KPath" (Klish path), чтобы потом
ссылаться на его формат и не путать с другими разновидностями путей.

Элементы пути в KPath отделяются друг от друга пробелами. Элементами пути
являются узлы YANG схемы, значения ключей и элементы `leaf-list` (см. YANG).
Если значение ключа или элемент `leaf-list` содержит пробелы, то они заключаются
в кавычки.

Предположим есть такой фрагмент YANG схемы:

```
module ttt {
  namespace "urn:ttt";
  prefix ttt;

  container test {
    list iface {
      key "name";

      leaf name {
        type string;
      }

      leaf comment {
        type string;
      }

      leaf type {
        type enumeration {
          enum ethernet;
          enum ppp;
          enum dummy;
        }
      }

    }
  }
}

```

Корректный KPath до элемента, определяющего тип "интерфейса" будет таким:
`test iface eth0 type`, где "eth0" - ключ списка "iface", соответствующий
элементу "name".

KPath до поля комментария для интерфейса "eth1" будет таким:
`test iface eth1 comment`.

В командах, где требуется ввести путь до элемента конфигурации, KPath будет
таким, как описано выше. Для команды `set`, которая устанавливает значение
элемента конфигурации, существует расширение формата KPath, так называемые
"однострочники". Однострочники позволяют задать значения нескольким элементам
конфигурации (`leaf`) одной строкой. Команда `set` вместе с аргументами может
выглядеть так:

```
# set test iface eth0 type ethernet comment "Comment with space"
```



## Команды конфигурирования


### Команда `set`

### Команда `del`
### Команда `edit`
### Команда `top`
### Команда `up`
### Команда `exit`
### Команда `insert`
### Команда `commit`
### Команда `check`
### Команда `rollback`
### Команда `show`
### Команда `diff`
### Команда `do`


## Настройки модуля

При подключении модуля к системе klish элементом `PLUGIN`, в теле элемента
`PLUGIN`  можно задать настройки для модуля. Настройки регулируют некоторые
особенности поведения модуля.


### Настройка `JuniperLikeShow`


### Настройка `FirstKeyWithStatement`


### Настройка `MultiKeysWithStatement`


### Настройка `Colorize`


### Пример настройки модуля

```
<PLUGIN name="sysrepo">
	JuniperLikeShow = y
	FirstKeyWithStatement = n
	MultiKeysWithStatement = y
	Colorize = y
</PLUGIN>
```