astrovideoguide_v3/LocCorr/doc/spec_server.tex

%
%   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}