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