| 1 | Список команд мониторинга
|
|---|
| 2 | =========================
|
|---|
| 3 |
|
|---|
| 4 | 1. Общие положения
|
|---|
| 5 |
|
|---|
| 6 | 1.1. Все команды и ответы на них передаются в виде json-объектов.
|
|---|
| 7 |
|
|---|
| 8 | 1.2. json-объект команды передается по протоколу HTTP POST или GET запросом (рекомендуется POST)
|
|---|
| 9 | в параметре json URL /api.php, например: http://192.168.0.88/api.php?json={"cmd":"board"}
|
|---|
| 10 | В некоторых случаях вместо /api.php используется другой URL, о чем особо указывается ниже.
|
|---|
| 11 |
|
|---|
| 12 | 1.3. Вид команды передается в виде строки в поле "cmd", например {"cmd":"board"}.
|
|---|
| 13 |
|
|---|
| 14 | 1.4. При возникновении ошибки в процессе выполнения команды в ответе на команду присутствует
|
|---|
| 15 | поле "error", значением которого является строка с описанием ошибки (при некоторых ошибках
|
|---|
| 16 | аутентификации вместо поля "error" может присутствовать поле "error2" - см. описание аутентификации ниже).
|
|---|
| 17 |
|
|---|
| 18 | 1.5. Признаком успешного выполнения команды является отсутствие поля "error" ("error2") в ответе.
|
|---|
| 19 |
|
|---|
| 20 | 1.6. В ответе на команду также присутствует поле "cmd" с тем же значением, что и в запросе.
|
|---|
| 21 |
|
|---|
| 22 | 1.7. Все строки, включая имена полей, используют кодировку UTF-8.
|
|---|
| 23 |
|
|---|
| 24 | 2. Аутентификация
|
|---|
| 25 |
|
|---|
| 26 | Для выполнения большинства команд требуется аутентификация. Для выполнения аутентификации
|
|---|
| 27 | требуется передать запрос "login" на URL /login.php. Параметры запроса аутентификации:
|
|---|
| 28 | "login" - имя пользователя (строка);
|
|---|
| 29 | "password" - пароль пользователя (строка).
|
|---|
| 30 | Пример запроса аутентификации:
|
|---|
| 31 | http://192.168.0.88/login.php?json={"cmd":"login","login":"admin","password":"labuda"}
|
|---|
| 32 | В случае ошибки аутентификации в ответе на запрос присутствует поле "error" или "error2".
|
|---|
| 33 | При успешной аутентификации ответ сервера устанавливает cookies с данными аутентификации. Эти cookies
|
|---|
| 34 | должны присутствовать в последующих командах. Установленные данные аутентификации действительны в течение
|
|---|
| 35 | суток с момента их генерации.
|
|---|
| 36 |
|
|---|
| 37 | В случае, если при передаче команды данные аутентификации отсутствуют, неверны
|
|---|
| 38 | или устарели (сгенерированы более суток назад), команда мониторинга не выполняется, и в ответе присутствует поле
|
|---|
| 39 | "error" со значением "not logged in". При получении этой ошибки необходимо повторно выполнить аутентификацию.
|
|---|
| 40 |
|
|---|
| 41 | При наличии в запросе cookies с валиднми данными аутентификации в ответе на любую команду устанавливаются новые
|
|---|
| 42 | (обновленные) cookies. Таким образом, необходимость в повторной аутентификации возникает только если в течение суток
|
|---|
| 43 | блоку не передавалось ни одной команды.
|
|---|
| 44 |
|
|---|
| 45 | 3. Список команд.
|
|---|
| 46 |
|
|---|
| 47 | 3.1. Запрос списка плат
|
|---|
| 48 |
|
|---|
| 49 | Список плат производится командой "board". Параметров у этой команды нет.
|
|---|
| 50 | Пример запроса:
|
|---|
| 51 | {"cmd":"board"}
|
|---|
| 52 | Ответ на команду "board" содержит поле "boards", содержащее массив хэшей, каждый из которых описывает один слот кассеты.
|
|---|
| 53 | Каждый хэш имеет следующие поля:
|
|---|
| 54 | "slot" - номер слота (число);
|
|---|
| 55 | "present" - признак присутствия платы (boolean).
|
|---|
| 56 | Если в слоте присутствует плата, хэш дополнительно содержит следующие поля:
|
|---|
| 57 | "type" - тип платы (число);
|
|---|
| 58 | "variant" - вариант исполнения платы (число);
|
|---|
| 59 | "name" - название платы (строка);
|
|---|
| 60 | "alarm" - признак общей аварии платы (число);
|
|---|
| 61 | "comment" - комментарий пользователя (строка);
|
|---|
| 62 | "last_alarm" - последняя авария платы (строка);
|
|---|
| 63 | "last_alarm_time" - сремя начала последней аварии (число - UNIX time);
|
|---|
| 64 | "required" - при значении true плата является обязательной (и при ее отсутствии генерируется авария) (boolean).
|
|---|
| 65 | Пример ответа:
|
|---|
| 66 | {"cmd":"board","boards":[{"slot":1,"present":false},{"slot":9,"present":true,"required":false,"type":1,"variant":1,"name":"SW-01","alarm":0,"comment":"","last_alarm":"","last_alarm_time":0}]}
|
|---|
| 67 |
|
|---|
| 68 | 3.2. Запрос списка текущих аварий
|
|---|
| 69 |
|
|---|
| 70 | Запрос списка текущих аварий производится командой "alarms". Параметров у этой команды нет.
|
|---|
| 71 | Пример запроса:
|
|---|
| 72 | {"cmd":"alarms"}
|
|---|
| 73 | Ответ на команду "alarms" содержит поле "alarms", содержащее массив хэшей, каждый из которых описывает одну аварию.
|
|---|
| 74 | Каждый хэш содержит следующие поля:
|
|---|
| 75 | "slot" - номер слота, в котором возникла авария (число);
|
|---|
| 76 | "oid" - oid аварии (переменная платы) (строка);
|
|---|
| 77 | "start" - время начала аварии (число, UNIX time);
|
|---|
| 78 | "prio" - приоритет аварии: 1 - срочная, 2 и более - не срочная (число);
|
|---|
| 79 | "name" - имя аварии (имя переменной из MIB платы) (строка);
|
|---|
| 80 | "confirmed" - значение true означает, что авария подтверждена пользователем (boolean).
|
|---|
| 81 | Пример ответа:
|
|---|
| 82 | {"cmd":"alarms","alarms":[{"confirmed":false,"slot":2,"oid":".7.2.1.0","prio":1,"start":1367822543,"name":"port 2: LOS (Loss of signal)"}]}
|
|---|
| 83 |
|
|---|
| 84 | 3.3. Запрос счетчиков обмена с платами по внутренней шине блока
|
|---|
| 85 |
|
|---|
| 86 | Запрос счетчиков обмена с платами производится командой "slotcnt". Параметров у этой команды нет.
|
|---|
| 87 | Пример запроса:
|
|---|
| 88 | {"cmd":"slotcnt"}
|
|---|
| 89 | Ответ на команду "slotcnt" содержит поле "slots", содержащее массив хэшей, каждый из которых содержит счетчики одного слота кассеты.
|
|---|
| 90 | Каждый хэш содержит следующие поля:
|
|---|
| 91 | "slot" - номер слота (число);
|
|---|
| 92 | "rx_discarded" - счетчик rx_discarded (число);
|
|---|
| 93 | "rx_short" - счетчик rx_short (число);
|
|---|
| 94 | "rx_big" - счетчик rx_big (число);
|
|---|
| 95 | "rx_ok" - счетчик rx_ok (число);
|
|---|
| 96 | "rx_bad" - счетчик rx_bad (число);
|
|---|
| 97 | "tx_ok" - счетчик tx_ok (число);
|
|---|
| 98 | "tx_dropped" - счетчик tx_dropped (число);
|
|---|
| 99 | "rx_bytes" - счетчик rx_bytes (число);
|
|---|
| 100 | "tx_bytes" - счетчик tx_bytes (число);
|
|---|
| 101 | "un_requests" - счетчик un_requests (число).
|
|---|
| 102 | Пример ответа:
|
|---|
| 103 | {"cmd":"slotcnt","slots":[{"slot":1,"rx_discarded":0,"rx_short":12,"rx_big":32,"rx_ok":12,"rx_bad":78,"tx_ok":123,"tx_dropped":0,"rx_bytes:4323,"tx_bytes":7263,"un_requests":0}]}
|
|---|
| 104 |
|
|---|
| 105 | 3.4. Запрос (чтение) переменной платы
|
|---|
| 106 |
|
|---|
| 107 | Запрос (чтение) переменной платы производится командой "snmpget". Этой команде требуется параметр "varlist", содержащий
|
|---|
| 108 | массив строк, каждая из которых представляет собой OID запрашиваемой переменной. OID состоит из элементов, представляющих собой
|
|---|
| 109 | число от 0 до 255 с точкой перед ним. При обращении к переменной платы первый элемент OID должен быть равен 4,
|
|---|
| 110 | второй элемент - номеру слота. Элементы OID начиная с третьего являются идентификатором переменной внутри платы.
|
|---|
| 111 | OID должен завершаться элементом 0.
|
|---|
| 112 | Пример запроса имени платы, установленной в слоте 9:
|
|---|
| 113 | {"cmd":"snmpget","varlist":[".4.9.2.0"]}
|
|---|
| 114 | Отвер на команду "snmpget" содержит поле "result", хэш. Ключами хэша являются OID запрошенных переменных, значением - хэши
|
|---|
| 115 | с результатом запроса переменной. Каждый хэш результата имеет следующие поля:
|
|---|
| 116 | "oid" - OID переменной (строка);
|
|---|
| 117 | "status" - признак успешности операции чтения (строка). Может принимать следующие значения:
|
|---|
| 118 | "OK" - операция выполнена успешно;
|
|---|
| 119 | "Not found" - запрошенная переменная отсутствует (также этот статус возвращается в случае таймаута);
|
|---|
| 120 | "Error" - какая-то ошибка в процессе обработки запроса.
|
|---|
| 121 | Если поле "status" имеет значение "OK", то в хэше также присутствует поле "value", содержащее прочитанное значение переменной.
|
|---|
| 122 | Пример ответа на запрос переменной .4.9.2.0:
|
|---|
| 123 | {"cmd":"snmpget","result":{".4.9.2.0":{"oid":".4.9.2.0","status":"OK","value":"SW-01"}}}
|
|---|
| 124 | Команда snmpget может содержать параметр "strings2data" типа boolean. В случае, если его значение равно true,
|
|---|
| 125 | значения переменных типа строка преобразуются в массив чисел, по одному на каждый байт строки. Пример запроса и ответа
|
|---|
| 126 | переменной .4.9.2.0 с параметром "strings2data":
|
|---|
| 127 | {"cmd":"snmpget","varlist":[".4.9.2.0"],"strings2data":true}
|
|---|
| 128 | {"cmd":"snmpget","result":{".4.9.2.0":{"oid":".4.9.2.0","status":"OK","value":[83,87,45,48,49]}}}
|
|---|
| 129 |
|
|---|
| 130 | 3.5 Запрос (запись) переменной платы
|
|---|
| 131 |
|
|---|
| 132 | Запрос (запись) переменной платы производится командой "snmpset". Этой команде требуется параметр "varlist", содержащий
|
|---|
| 133 | OID записываемой переменной и ее новое значение.
|
|---|
| 134 | Пример записи переменной:
|
|---|
| 135 | {"cmd":"snmpset","varlist":{".4.14.6.0":3}}
|
|---|
| 136 | Пример ответа на данную запись:
|
|---|
| 137 | {"cmd":"snmpset","result":{".4.14.6.0":"OK"}}
|
|---|
