eddy/astrovideoguide_v3
1
0
Fork 0
mirror of https://github.com/eddyem/astrovideoguide_v3.git synced 2026-03-21 17:20:58 +03:00
Code Issues Packages Projects Releases Wiki Activity

Added documentation

Browse Source
This commit is contained in:
Edward Emelianov
2021-10-29 20:40:38 +03:00
parent 39b9cee77c
commit b2a3d68513
10 changed files with 471 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files

242
LocCorr/doc/spec_server.tex Normal file
View File

@@ -0,0 +1,242 @@
%
% spec_server package description
%
Демон \t{spec\_server} представляет собой \t{HTTP(S)/Websocket} сервер и, соответственно, является
серверной частью программного пакета интерфейсов наблюдателя и состояния спектрографа.
Данный программный пакет реализован на языках \t{C++} (\t{spec\_server})
и \t{Javascript}, \t{HTML}, \t{CSS} для клиентской части.
Сетевая (\t{HTTP(S)/WebSocket} сервер, связь с демоном \t{loccorr}) часть демона реализована с помощью сторонних библиотек
\verb|IXWebsocket|\footnote{\url{https://machinezone.github.io/IXWebSocket/}} и
\verb|ASIO|\footnote{\url{https://think-async.com}}. Кроме того, дополнительно были использованы сторонние библиотеки
\verb|spdlog|\footnote{\url{https://github.com/gabime/spdlog}}, \verb|fmtlib|\footnote{\url{https://github.com/fmtlib/fmt})}
и \verb|OpenSSL|\footnote{\url{https://github.com/fmtlib/fmt}}.
\begin{table}[t]
\caption{Ключи командной строки демона \t{spec\_server}}\label{specserv_cmdkey}
% \begin{tabular}{ll}
\begin{tabular}{p{0.45\textwidth}p{0.45\textwidth}}
\hline\hline
Ключ & описание \\
\hline
\verb|-h| & распечатать в устройство стандартного вывода краткую справку и выйти\\
&\\
\verb|-d [config-filename]| & записать параметры конфигурации по умолчанию в файл
\verb|config-filename| и выйти. Если \verb|config-filename| не задан,
то будет использовано имя по умолчанию \verb|server-config.dat|\\
\hline\hline
\end{tabular}
\end{table}
Для старта демона необходимо выполнить команду:
\begin{verbatim}
spec_server [cfg-filename] [-h] [-d] [dump-config-filename]
\end{verbatim}
Предполагается, что у пользователя есть права на запуск бинарного файла \t{spec\_server} и путь к этому
файлу есть в переменной среды \verb|PATH|.
В Таблице~\ref{specserv_cmdkey} представлены опциональные ключи командной строки, которые принимает исполняемый
файл демона в качестве параметров. Необязательным позиционным параметром запуска
демона является имя файла, в котором заданы параметры конфигурации. Например, следующая командная строка
запускает демон с конфигурационными параметрами в файле \verb|/etc/server-config.dat|:
\begin{verbatim}
spec_server /etc/server-config.dat
\end{verbatim}
\afterpage{%
\begin{longtable}{p{0.2\textwidth}p{0.15\textwidth}p{0.5\textwidth}}
\caption{Параметры конфигурации демона \t{spec\_server}}
\label{specserv_params}\\
% \begin{tabular}{lll}
\hline\hline
имя параметра & тип & описание \\
\hline
\t{caFile} & строка & полное имя файла доверенного корневого сертификата. Специальные значения: \\
& & \t{SYSTEM} -- использовать системное хранилище доверенных корневых сертификатов; \\
& & \t{NONE} -- отключить верификацию сертификатов сетевого соединения. \\
& & По умолчанию -- пустая строка (не использовать корневой сертификат) \\
& & \\
\t{certFile} & строка & полное имя файла \t{SSL}-сертификата демона. По умолчанию -- пустая строка (не
использовать протокол \t{HTTPS}) \\
& & \\
\t{certKeyFile} & строка & полное имя файла ключа \t{SSL}-сертификата демона. По умолчанию -- пустая
строка (не использовать протокол \t{HTTPS}) \\
& & \\
\t{http\_host} & строка & \t{IP}-адрес сетевого интерфейса для прослушивания входящих \t{HTTP(S)}
соединений. \\
& & По умолчанию 0.0.0.0 \\
& & \\
\t{http\_path} & строка & полный путь к каталогу файловой системы где хранятся \t{HTML}, \t{Javascript} и
\t{CSS} файлы интерфейса наблюдателя. \\
& & По умолчанию -- пустая строка (текущий каталог) \\
& & \\
\t{http\_port} & целое число & номер порта для входящих \t{HTTP(S)} соединений. По умолчанию 8080 \\
& & \\
\t{log\_filename} & строка & полное имя лог-файла демона.Параметр может иметь специальные значения
\t{stdout} и
\t{stderr} для логирования в стандартные устройства вывода и ошибок соответственно.
Если значение пустая строка, то логирование будет отключено \\
& & \\
\t{log\_level} & строка & уровень логирования. Возможные значения (регистр не важен):
\t{TRACE}, \t{DEBUG}, \t{INFO}, \t{WARN}, \t{ERROR}, \t{CRITICAL}, \t{OFF}. По умолчанию задано \t{INFO}\\
& & \\
\t{logrot\_num} & целое число & количество сохраняемых лог-файлов, если задано ротирование. Если
больше 0, то логирование
будет выполняться по принципу ротирования файлов по достижению заданного максимального размера файла.
По умолчанию 0 -- ротирование отключено \\
& & \\
\t{logrot\_size} & целое число & максимальный размер лог-файла в случае включенного ротирования.
Размер задается в байтах. По умолчанию 10485760 (10 мегабайт)\\
& & \\
\t{obs\_timeout} & целое число & таймаут бездействия соединения для интерфейса наблюдателя. Время
задается в минутах.
По умолчанию 60 ({\bf не реализовано!!!}) \\
& & \\
\t{passwd\_hash} & 16-ричное число & \t{SHA-256} хэш-сумма строки пароля авторизации для интерфейса
наблюдателя.
По умолчанию значение соответствует паролю \t{123} \\
& & \\
\t{ping\_int} & целое число & ``пинг-понг'' интервал для \t{Websocket} соединений. Время задается в
секундах.
По умолчанию 45 \\
& & \\
\t{specdev\_port} & целое число & номер порта для сетевого соединения с демоном \t{loccorr}. По
умолчанию 12345 \\
& & \\
\t{specdev\_rtimeout} & целое число & таймаут для операций чтения из сокета для сетевого соединения с
демоном \t{loccorr}.
Время задается в миллисекундах. По умолчанию 1000 \\
& & \\
\t{specdev\_wtimeout} & целое число & таймаут для операций записи в сокет для сетевого соединения с
демоном \t{loccorr}.
Время задается в миллисекундах. По умолчанию 1000 \\
& & \\
\t{view\_timeout} & целое число & таймаут бездействия соединения для интерфейса просмотра состояния
спектрографа.
Время задается в минутах. По умолчанию 60 ({\bf не реализовано!!!}) \\
& & \\
\t{websock\_host} & строка & \t{IP}-адрес сетевого интерфейса для прослушивания входящих \t{Websocket}
соединений. По умолчанию 0.0.0.0 \\
& & \\
\t{websock\_port} & целое число & номер порта для входящих \t{Websocket} соединений. По умолчанию 8888 \\
\hline\hline
% \end{tabular}
\end{longtable}
}
При старте демон \t{spec\_server} начинает прослушивать заданные в конфигурации порты для входящих
\t{HTTP(S)} и \t{Websocket} соединений, а затем пытается выполнить сетевое соединение с демоном \t{loccorr}.
Если заданный пользователем файл конфигурации не найден или у пользователя нет прав на его чтение, то демон
аварийно завершает работу.
Функционирование демона полностью задается параметрами в конфигурационном файле. Конфигурационный файл
имеет текстовый формат, параметры задаются парой ``ключ -- значение'' как \verb|key=value|, в каждой строке
может присутствовать только одна пара ``ключ -- значение'', строки начинающиеся с символа \verb|#| являются
комментариями и игнорируются, пустые (содержащие только пробелы) строки также игнорируются.
В паре \verb|key=value| ``\verb|value|'' может быть пустой строкой, что означает ``параметр имеет специальное значение''
(см. Таблицу~\ref{specserv_params}). В Таблице~\ref{specserv_params} описаны возможные параметры
конфигурации демона \t{spec\_server}. Файлы сертификатов и их ключей должны быть в \t{PEM}-формате.
Критичным для работы интерфейса пользователя является параметр \verb|http_path|, задающий
корневой каталог в файловой системе ОС управляющего компьютера, в котором хранятся необходимые
\verb|HTML|, \verb|CSS| и \verb|Javascript| файлы. Главный \verb|HTML| файл интерфейса (\verb|observer.html|)
предполагает жестко заданную структуру содержимого корневого каталога. Положим, что пользователь в своем конфигурационном
файле определил его как \verb|http_path = /etc/fiber_spec_cfg|, тогда его содержимое должно выглядеть
следующим образом:
\begin{verbatim}
/etc/fiber_spec_cfg/
js/
uikit-icons.min.js
uikit.min.js
css/
uikit.min.css
index.html
observer.html
viewer.html
start-disp.jpg
init_connection.js
observer_handlers.js
observer_websocket_handler.js
\end{verbatim}
\begin{table}[t]
\caption{Состав программного пакета \t{spec\_server}}\label{specserv_files}
% \begin{tabular}{ll}
\begin{tabular}{p{0.45\textwidth}p{0.45\textwidth}}
\hline\hline
Имя файла & описание \\
\hline
\verb|spec_server| & исполняемый файл \t{HTTP(S)/Websocket} сервера \\
& \\
\verb|index.html| & \t{HTML} индекс-файл \t{HTTP(S)}-сервера \\
& \\
\verb|observer.html| & \t{HTML} файл интерфейса наблюдателя \\
& \\
\verb|viewer.html| & \t{HTML} файл интерфейса состояния спектрографа ({\bfв разработке!!!})\\
& \\
\verb|start-disp.jpg| & \t{JPEG} файл стартового изображения подсмотра волокна \\
& \\
\verb|init_connection.js| & \t{Javascript} файлы логики интерфейса наблюдателя \\
\verb|observer_handlers.js| & \\
\verb|observer_websocket_handler.js| & \\
& \\
\verb|uikit-icons.min.js| & \t{Javascript} файлы библиотеки \t{UIkit} \\
\verb|uikit.min.js| & \\
& \\
\verb|uikit.min.css| & \t{CSS} файл библиотеки \t{UIkit} \\
\hline\hline
\end{tabular}
\end{table}
Состав и краткое описание файлов программного пакета представлены в Таблице~\ref{specserv_files}.
Для авторизации наблюдателя при начальной загрузке интерфейса потребуется ввод пароля. \verb|SHA-256| хэш-сумма
пароля задается в конфигурации ключом \verb|passwd_hash|. Чтобы сгенерировать хэш-сумму можно, например, воспользоваться
стандартной \verb|GNU| утилитой \verb|Linux| ОС \verb|sha256sum|:
\begin{verbatim}
echo -n "obs-password-here" | sha256sum
\end{verbatim}
Полученная сумма прописывается в конфигурационом файле как
\begin{verbatim}
passwd_hash=82774de1a23f679abab412e24279157fa99c44f3ff400d09d45d4d01e64fce60
\end{verbatim}
(без пробелов после символа '\verb|=|'!!!). {\bf Важно: } в текущей реализации демона \t{loccorr} возможно лишь единственное
соединение к интерфейсу наблюдателя. Если одно уже открыто, то всем остальным будет отказано в доступе.
Для обеспечения сетевой безопасности демон \t{spec\_server} может работать
как \verb|HTTPS| сервер и, в этой конфигурации, использовать \verb|TLS|-шифрование для \verb|Websocket| соединений. Возможны несколько
вариантов конфигурирования \verb|HTTPS| сервера (\verb|TLS|-шифрования). Краткое описание вариантов можно просмотреть на странице библиотеки
\verb|IXWebsocket|\footnote{\url{https://machinezone.github.io/IXWebSocket/usage/\#tls-support-and-configuration}}. Отметим
здесь, что наиболее простой вариант это использование доверенного (подписанного доверенным центром
сертификации) сертификата сервера,
тогда параметры конфигурации могут быть заданы следующим образом:
\begin{verbatim}
caFile = SYSTEM
certFile = server-crt.pem
certKeyFile = server-key.pem
\end{verbatim}
Если используется так называемый самоподписанный сертификат, то конфигурация может быть задана как:
\begin{verbatim}
caFile = NONE
certFile = server-crt.pem
certKeyFile = server-key.pem
\end{verbatim}
Однако, такая конфигурация потребует дополнительных настроек в используемых интернет-браузерах (потребуется разрешить
браузеру использовать соединения защищенные недоверенным сертификатом и т.д.).
Демон \t{spec\_server} обрабатывает 4 сигнала ОС: \verb|SIGINT|, \verb|SIGTERM|, \verb|SIGUSR1| и \verb|SIGUSR2|. Первые два
предназначены для останова \t{HTTP(S)/WebSocket} сервера и выхода демона в ОС. \verb|SIGUSR1| используется для
рестарта \t{HTTP(S)/WebSocket} сервера (с закрытием всех активных браузерных соединений) и реинициализации соединения
с \t{loccorr} демоном. При получении сигнала \verb|SIGUSR2| демон только реинициализирует соединение с \t{loccorr} демоном.
Например, для останова демона нужно выполнить команду
\begin{verbatim}
killall -TERM spec_server
\end{verbatim}
Остальные варианты обработки сигналов могут быть полезны, например, в случае аварийного перезапуска \t{loccorr} демона.
Например, следующая команда запросит демон \t{spec\_server} закрыть существующее и открыть новое сетевое соединение с
демоном \t{loccorr}:
\begin{verbatim}
killall -USR2 spec_server
\end{verbatim}