[[PageOutline]]
= はじめに =
このドキュメントはJ-PARC加速器向けに[https://epicsarchiver.readthedocs.io/en/latest/index.html Archiver Appliance (AA)]をインストールして立ち上げた際の作業メモなので、適宜読み替えて頂きたい。
* AAの[https://epicsarchiver.readthedocs.io/en/latest/sysadmin/installguide.html インストールガイド]を良く読んでおくこと。
* AAの[https://epicsarchiver.readthedocs.io/en/latest/sysadmin/installguide.html インストールガイド]を良く読んでおくこと。
* [https://epicsarchiver.readthedocs.io/en/latest/sysadmin/quickstart.html Quickstart]はあくまでもAAを試食するためのセットアップ方法なので、ここでは見ないでおく。よく読むと「Quickstartの方法では設定が保存されない。AAを再起動したら、アーカイブしたいPVを再度AAに設定しなければならない」旨が書いてある。
* jkjarchiver-ap.mr.jkcontにインストールする
* OS : Alma Linux 9 / x86_64
* epicsアカウントで作業する
* 作業ディレクトリ: /home/epics/archappl
* AAのインストール先: /opt/archappl
* AAのデータ保存先: /localdata/archappl
* 各種設定ファイル・起動スクリプトは(できるだけ)mercurialでバージョン管理している
* インストールの際に、X Window System上での作業が必要
* あらかじめdnfでインストールしておくもの
* gcc
* httpd
* patch
* mariadb-server mariadb
* zenity
* (java-17-openjdk-devel) ※ 後述
* AAインストール後の運用については[[wiki:Archiver Appliance 運用メモ|Archiver Appliance 運用メモ]]を参照のこと
= ダウンロード =
AAに必要なソフトウェアをあらかじめダウンロードしておく。ここでは/home/epics/archappl/downloadにダウンロードする。
== Archiver Appliance ==
[https://github.com/archiver-appliance/epicsarchiverap/releases github]からダウンロードする。
インストールするのはバイナリの配布物だが、ソースコードに管理用のスクリプトの例が含まれているので一緒にダウンロードしておく。
* バイナリ
{{{
% wget https://github.com/archiver-appliance/epicsarchiverap/releases/download/1.1.0/archappl_v1.1.0.tar.gz
}}}
* ソースコード
{{{
% wget https://github.com/archiver-appliance/epicsarchiverap/archive/refs/tags/1.1.0.tar.gz
}}}
== Apache Tomcat ==
AAを走らせるにはApache Tomcat 7.0.61以降が必要。[https://tomcat.apache.org/download-90.cgi Apache Tomcat配布元]から9.0.33のCoreからtar.gzをダウンロードした。
* Tomcat 10系では(まだ)動かない
== MySQL ==
AAはアーカイブするレコードの情報を記録するのにMySQL/MariaDBを利用する。
AlmaLinux9の配布物からmariadb 10.5をdnfでインストールした。
{{{
# yum install mariadb mariadb-server
}}}
今回は
* AAを実行するマシンでMariaDBサーバも走らせる
* MariadDBのテーブルはNFSサーバ上に置く
という構成にした。MariaDBサーバはAAとは独立したマシンにした方がよかったかもしれない。
== MySQL クライアント jar ==
mysql-connector-javaを[http://dev.mysql.com/downloads/connector/j/ MySQL本家]のArchiveから、
* Product Version → 8.0.33
* Operating System → Platform Independent
を選んでtarをダウンロードする。
AAのインストール後に、インストール先ディレクトリのapache-tomcat-x.y.z/libに置いてあるjarを差し替えることで、javaクライアントを入れ替えることができる。
== JDK 17 ==
制御計算機ではAdoptiumのOpenJDKU-jdk_x64_linux_hotspot_17.0.12_7.tar.gzを用いた。
* Alma Linux 9のjava-17-openjdk-develをdnfで入れてもOK
== tar ballの展開 ==
{{{
% mkdir -p ~/archappl/workspace
% cd ~/archappl/workspace
% tar xf ../download/archappl_v1.1.0.tar.gz
% tar xf ../download/mysql-connector-j-8.0.33.tar.gz
}}}
= MySQLのセットアップ =
* rootで作業する
== dbを置くディレクトリ ==
AlmaLinux9標準のディレクトリのままにする場合はこの手順は飛ばしてよい。
制御計算機ではdbは/svrdbに置く。NFSサーバがexportしているディレクトリを/svrdbにマウントする。
{{{
jkjds01.ccr.jkcont:/svrdb /svrdb nfs bg,intr,soft,timeo=10,retrans=15,nfsvers=3 0 0
}}}
/svrdbを掘ってマウントし、パーミッションを設定する。mysqlの起動スクリプトがroot権限でこのディレクトリに書き込もうとするので、NFSサーバも設定しておく。
{{{
# mkdir /svrdb
# mount /svrdb
# mkdir /svrdb/mariadb10.5/jkjarchiver-ap
# chown mysql:mysql /svrdb/mariadb10.5/jkjarchiver-ap
}}}
== MariaDBの設定 ==
* /etc/my.cnf.d/mariadb-server.cnfを書き換える
* MariaDBのテーブルを置くディレクトリ
* MySQL 5.3あたりからutf8mb4 (4-bytes unicode)がデフォルトになった。このままだとインデックスのキー長の上限である767バイトを超えるので、3-bytes unicodeを使う
* いまはutf8はutf8mb3の別名だが、そのうちutf8mb4の別名になる(らしい)
* キー長を768バイト以上にする方法もある(らしい)
{{{
...
[mysqld]
#datadir=/var/lib/mysql
datadir=/svrdb/mariadb10.5/jkjarchiver-ap
...
# Disabling symbolic-links is recommended to prevent assorted security risks
symbolic-links=0
# Use utf8 (3-bytes unicode) to avoid 767-bytes problem.
# Column size will exceed 767-bytes when the default charset, utf8mb4 (4-bytes unicode) is used.
character-set-server = utf8mb3
collation-server = utf8_general_ci
#
innodb_flush_log_at_trx_commit = 1
}}}
* /etc/my.cnf.d/mysql-clients.cnfも書き換える
{{{
...
[mysql]
default-character-set = utf8
...
}}}
== logrotate ==
/etc/logrotate.d/mariadb に手順が書いてある。後回し。
== mysqlサーバ自動起動の設定 ==
MariaDBをインストールしただけでは自動起動しない。自動起動するように設定しておく
{{{
# systemctl enable mariadb
}}}
== MySQLサーバの起動 ==
MariaDBの回起動時に(dbが存在しなければ)dbを作ってくれる
{{{
# systemctl start mariadb
}}}
== /usr/bin/mysql_secure_installation ==
MySQLの初期設定を行う。質問をよく読む。質問をよく読んでから答える
{{{
# /usr/bin/mysql_secure_installation
}}}
* Enter current password for root (enter for none): ← ルートのパスワード を入力する
* Switch to unix_socket authentication [Y/n] ← n
* Change the root password? [Y/n] ← n
* Remove anonymous users? [Y/n] ← y
* Disallow root login remotely? [Y/n] ← nが安全だが状況に応じて
* Remove test database and access to it? [Y/n] ← いらないのでy
* Reload privilege tables now? [Y/n] ← y
== schemaの作成 ==
DB(archappl), ユーザー(archappl)とパスワード(archappl)を作る
* rootで作業する
{{{
% mysql -u root -p
Enter password:
Welcome to the MariaDB monitor. Commands end with ; or \g.
Your MariaDB connection id is 14
Server version: 10.5.22-MariaDB MariaDB Server
Copyright (c) 2000, 2018, Oracle, MariaDB Corporation AB and others.
Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
mysql> CREATE DATABASE IF NOT EXISTS archappl;
Query OK, 1 row affected (0.001 sec)
mysql> GRANT ALL PRIVILEGES ON archappl.* TO 'archappl'@'localhost' IDENTIFIED BY 'archappl';
Query OK, 0 rows affected (0.002 sec)
}}}
== テーブルの作成 ==
AA用のテーブルはAAのインストールスクリプト(後述)が作ってくれる。
= Archiver Applianceのインストール =
インストールスクリプトを走せると、
1. MariaDBのテーブル
1. Tomcatのデプロイ
1. アプライアンスの設定ファイルの作成
1. 起動スクリプトの作成
をやってくれる
== インストール先のディレクトリ ==
AAをインストールするディレクトリ(/opt/archappl)をあらかじめ掘っておく
* rootで作業する
{{{
# mkdir -p /opt/archappl
# chown epics:epics /opt/archappl
}}}
== ポリシーファイル ==
ポリシーファイルは AAにレコードを登録する際に用いられるファイルで、
* LTS/MTS/STSの設定
* レコードをサンプルする方法(monitor/scan)とサンプリング時間
* 値と一緒に保存するHIGH/HIGH/LOW/LOLO等のフィールド
等をPythonのdictionaryとして記述する。
インストールスクリプトを走らせる前に、ポリシーファイルを用意しておく。雛形が
{{{
epicsarchiverap.git/src/sitespecific/tests/classpathfiles/policies.py
}}}
に用意されている
* このページのAtachmentsにもある
* インストールスクリプトがポリシーファイルの所在を尋ねてくる。存在しないファイルを指定すると、スクリプトの実行に失敗する
* 中身は後で書き換えるので、ここでは気にしない
* AAのクラスタを組む場合は、各ノードに同じファイルのコピーを置くか、共有ディレクトリに置いておく
制御計算機用のポリシーファイルは
{{{
/jk/dev/operation_app/jkControl/ArchiverAppliance/deploy/policies.py
}}}
に置いてある
=== LTS/MTS/STS ===
* STS ... PARTITION_HOUR
* MTS ... PARTITION_DAY&hold=5&gather=1
* LTS ... PARTITION_MONTH
=== sampling method/sampling period ===
* 基本的にはMONITORにする
* 25Hzで更新されるLIのPVはSCAN 1.0secにする
=== metaFields ===
HIHI等のメタフィールドは保存しない。pvPolicyDict\["archiveFields"\]は空のarrayにしておく
== JAVA_HOME ==
JAVA_HOMEを設定してく
{{{
% export JAVA_HOME=/usr/lib/jvm/java-17
}}}
== インストールスクリプト ==
予めインストール先のディレクトリを作っておく。epicsアカウントで書き込めるようにownerを変更しておく:
* rootで作業する
{{{
# mkdir -p /opt/archappl
# chown epics.epics /opt/archappl
}}}
インストールスクリプトが呼び出すdeployMultipleTomcats.pyはpython2向けに書かれているので、python3でも動くようにパッチをあてる
* あるいはパッチ済みのものをこのページのAttachmentsからダウンロードして使う
{{{
cd ~epics/archappl/workspace
curl https://cerldev.kek.jp/trac/EpicsUsersJP/raw-attachment/wiki/epics/Archiver%20Appliance%20%E3%82%A4%E3%83%B3%E3%82%B9%E3%83%88%E3%83%BC%E3%83%AB%E3%83%A1%E3%83%A2/install_scripts_python3.patch
patch -p0 < install_scripts_python3.patch
}}}
AAを展開したディレクトリでインストールスクリプトを走らせる。AAを実行するアカウント(ここではepics)で走らせること。
sample_site_specific_contentをディレクトリごとsite_specific_contentにコピーして内容を編集しておくと、管理用ページのhtmlページの文言やヘッダに表示する図を差し替えることができる。
スクリプトを走らせると、ダイアログが開いて
* DEPLOY_DIR (tomcatを展開するディレクトリ) → /opt/archappl
* apache-tomcat-x.y.z.tar.gz の所在
* mysql-connector-java-x.y.z-bin.jar の所在
* 環境変数ARCHAPPL_APPLIANCESが設定されていない場合、先に進むかどうか → Yesを答えると自動的に設定してくれる
* mysqlサーバに接続するためのmysqlコマンドに渡す引き数 → ここでは--user=archappl --password=archappl --database=archappl
* ポリシーファイル(policies.py)の所在
を尋ねてくる。
{{{
% cd ~archappl/workspace
% install_scripts/single_machine_install.sh
This script runs thru a typical install scenario for a single machine
You can use this to create a standard multi-instance (one Tomcat for ear WAR) tomcat deployment in a multi machine cluster by setting the ARCHAPPL_APPLIANCES and the ARCHAPPL_MYIDENTITY
For installations in a cluster, please do create a valid appliances.xml and export ARCHAPPL_APPLIANCES and ARCHAPPL_MYIDENTITY
...
...
Setting TOMCAT_HOME to the mgmt webapp in /opt/archappl/mgmt
Setting TOMCAT_HOME to /opt/archappl/apache-tomcat-9.0.33
Calling deploy release with /opt/archappl/deployRelease.sh /home/epics/archappl/workspace
Deploying a new release from /home/epics/archappl/workspace onto /opt/archappl
/opt/archappl/mgmt/webapps ~/archappl/workspace
~/archappl/workspace
/opt/archappl/engine/webapps ~/archappl/workspace
~/archappl/workspace
/opt/archappl/etl/webapps ~/archappl/workspace
~/archappl/workspace
/opt/archappl/retrieval/webapps ~/archappl/workspace
~/archappl/workspace
Done deploying a new release from /home/epics/archappl/workspace onto /opt/archappl
Do you have a site specific policies.py file?
Where's your site specific policies.py file?
Setting ARCHAPPL_POLICIES to /home/epics/archappl/policies.py
Done with the installation. Please use /opt/archappl/sampleStartup.sh to start and stop the appliance and /opt/archappl/deployRelease.sh to deploy a new release.
}}}
== アプライアンスの設定 ==
appliances.xmlでノードのidentityと各webappが使うURLを設定する
* デフォルトでは/opt/archappl/appliances.xmlが使われる
* 起動スクリプトの環境変数でファイル名を指定する
* AAのクラスタを組む場合は、各ノードに同じファイルのコピーを置くか、共有ディレクトリに置いておく
{{{
appliance0
jkjarchiver-ap.mr.jkcont:16670
http://jkjarchiver-ap.mr.jkcont:17665/mgmt/bpl
http://jkjarchiver-ap.mr.jkcont:17666/engine/bpl
http://jkjarchiver-ap.mr.jkcont:17667/etl/bpl
http://localhost:17668/retrieval/bpl
http://jkjarchiver-ap.mr.jkcont:17668/retrieval
}}}
== プロパティファイル ==
archappl.propertiesでAAの動作を設定する。
* デフォルトでは各web appのWEB-INF/classes/archappl.propertiesが使われる
* 例えば: /opt/archappl/engine/webapps/engine/WEB-INF/classes/archappl.properties
* 起動スクリプトの環境変数ARCHAPPL_PROPERTIES_FILENAMEでファイル名を指定する
アーカイブエンジンのバッファがあふれるので、プロパティファイルでマージンを大きめにとることにする:
{{{
...
# Increase buffer capacity adjustment in order to avoid buffer overflow in J-PARC MR.
org.epics.archiverappliance.config.PVTypeInfo.sampleBufferCapacityAdjustment = 5.0
...
}}}
サンプリング間隔の補正は無効にしておく:
{{{
...
# J-PARC MR
org.epics.archiverappliance.engine.epics.scanJitterFactor=1.00
...
}}}
デフォルトでは、AAに追加したPVが24時間経過しても見つからなかったら、諦めてそのPVのアーカイブは取りやめてしまう。無効にする:
{{{
# For the moment, don't abort never connected PVs for J-PARC MR
org.epics.archiverappliance.mgmt.MgmtRuntimeState.abortArchiveRequestInMins = -1
}}}
pbファイルのディレクトリの区切りに使う文字を指定する。とりあえずデフォルトのままにしたが、アンダースコア("_")も含めておいた方がよかったかもしれない。
{{{
org.epics.archiverappliance.config.ConvertPVNameToKey.siteNameSpaceSeparators = [\\:\\-]
}}}
== TOMCATの設定 ==
=== ${TOMCAT_HOME}/conf/server.xml ===
* mgmt webappが使うポートを、8080(tomcatのデフォルト)からappliances.xmlで指定したポート番号に合わせて17665にする。
{{{
...
...
}}}
* apache httpdとAJPを使った連携をする場合は、AJP Connectorの設定のコメントを外し適切に設定する:
{{{
...
...
}}}
* SHUTDOWNコマンドの使うポートは8005のままにしておく。
=== ${TOMCAT_HOME}/conf/context.xml にMySQLの設定を追加する ===
* に'jdbc/archappl'の設定を追加する:
{{{
...
...
}}}
=== ${TOMCAT_HOME}/lib/log4j.properties ===
* logローテーションを仕掛けたい。が、とりあえずそのままにしておく
{{{
# Set root logger level and its only appender to A1.
log4j.rootLogger=ERROR, A1
log4j.logger.config.org.epics.archiverappliance=INFO
log4j.logger.org.apache.http=ERROR
# A1 is set to be a DailyRollingFileAppender
log4j.appender.A1=org.apache.log4j.DailyRollingFileAppender
log4j.appender.A1.File=arch.log
log4j.appender.A1.DatePattern='.'yyyy-MM-dd
# A1 uses PatternLayout.
log4j.appender.A1.layout=org.apache.log4j.PatternLayout
log4j.appender.A1.layout.ConversionPattern=%-4r [%t] %-5p %c %x - %m%n
}}}
== 起動スクリプトの修正 ==
インストールスクリプトがAAの起動スクリプトsampleStartup.shを生成するので、環境に合わせて書き換える。
* setEPICSEnv.shへのパスを修正する
* JAVA_OPTSを修正する
* -XX:MaxPermSize=128Mを削除する
* -Xmx4Gと-Xms1Gはメモリサイズに合わせて適宜調整する
=== アプライアンスの設定 ===
{{{
export ARCHAPPL_APPLIANCES=/jk/dev/operation_app/jkControl/ArchiverAppliance/deploy/appliances.xml
export ARCHAPPL_MYIDENTITY="appliance0"
}}}
=== EPICSの設定 ===
EPICS用の環境変数を設定するshスクリプトをsourceする:
{{{
source /jk/dev/operation_app/jkControl/ArchiverAppliance/deploy/setEPICSEnv.sh
}}}
{{{
export EPICS_CA_ADDR_LIST=...
#export EPICS_CA_AUTO_ADDR_LIST=false
#export EPICS_CA_SERVER_PORT=5064
#export EPICS_CA_REPEATER_PORT=5065
export EPICS_TS_MIN_WEST=-540
#export EPICS_CA_MAX_ARRAY_BYTES=6000000
export EPICS_CA_MAX_ARRAY_BYTES=65536
}}}
=== ポリシーファイルの設定 ===
ポリシーファイルは環境変数で指定する。インストールスクリプトを実行した際に指定したファイルを指しているので、運転用のポリシーファイルを指すように書き換える:
{{{
export ARCHAPPL_POLICIES=/jk/dev/operation_app/jkControl/ArchiverAppliance/deploy/policies.py
}}}
=== プロパティファイルの設定 ===
インストールスクリプトが作るAAの起動スクリプトには何も書かれていないが、プロパティファイルも起動スクリプトから環境変数で指定する:
{{{
export ARCHAPPL_PROPERTIES_FILENAME=/jk/dev/operation_app/jkControl/ArchiverAppliance/deploy/archappl.properties
}}}
=== ストレージの設定 ===
{{{
export ARCHAPPL_SHORT_TERM_FOLDER=/localdata/archappl/sts/ArchiverStore
export ARCHAPPL_MEDIUM_TERM_FOLDER=/localdata/archappl/mts/ArchiverStore
export ARCHAPPL_LONG_TERM_FOLDER=/localdata/archappl/lts/ArchiverStore
}}}
== データ保存先の作成 ==
起動スクリプトでの設定に合うように、データを保存するディレクトリを作り、epicsアカウントで書き込めるようにownerを変更しておく
* rootで作業する
{{{
# mkdir -p /localdata/archappl/lts
# mkdir -p /localdata/archappl/mts
# mkdir -p /localdata/archappl/sts
# chown epics.epics /localdata/archappl
# chown epics.epics /localdata/archappl/lts
# chown epics.epics /localdata/archappl/mts
# chown epics.epics /localdata/archappl/sts
}}}
= Apache httpdとの連携 =
AAの各web appにポート80番でアクセスできるようにするため、jkjarchiver-apにリバースプロキシを立ち上げる。ここではAJPを使わずに、naiiveなhttpプロキシにする
* rootで作業する
{{{
# yum install httpd httpd-tools
}}}
* /etc/httpd/conf/httpd.confには触らないようにする
* Attachmentsにあるファイルを/etc/httpd/conf.dにコピーして適宜書き換える
* 00-default.conf
* 00-proxy.conf
}}}
== 基本的な設定 ==
* conf.d/00-default.cont
{{{
Timeout 600
}}}
* conf.d/00-mpm.conf
{{{
...
MaxConnecitonPerChild 2000
}}}
== リバースプロキシの設定 ==
* conf.d/proxy.conf
{{{
ProxyRequests Off
ProxyPass /mgmt http://localhost:17665/mgmt
ProxyPassReverse /mgmt http://localhost:17665/mgmt
ProxyPass /retrieval http://localhost:17668/retrieval
ProxyPassReverse /retrieval http://localhost:17668/retrieval
Order deny,allow
Allow from all
}}}
== httpdの自動起動の設定 ==
{{{
# systemctl enable httpd
# systemctl start httpd
}}}
= AAの起動と確認 =
== 自動起動/自動停止させる ==
systemdのUnitファイルを用意し、マシンの起動時/停止時にepicsアカウントでAAが自動的に起動/停止するようにする。
* Attatchmentからダウンロードする
{{{
# cp archappl.service /etc/systemd/systemc
# systemctlc enable archappl.service
}}}
* AAを実行するUser/Groupをepicsにする
== 手動で起動する ==
{{{
# systemctl start archappl
}}}
== webブラウザで管理用web appにアクセスする ==
次のURLにアクセスする:
{{{
http://jkjarchiver-ap.mr.jkcont:17665/mgmt
}}}
* http://jkjarchiver-ap.mr.jkcont:17665/mgmt/ui/index.html にforwardされる
* 各web appが起動する前にアクセスすると503が返ってきて"数分待て"と表示されるが、数分では起動しない。気長に待て
* 各web appが起動する前にアクセスすると503が返ってきて"数分待て"と表示されるが、数分では起動しない。気長に待て
* [[wiki:Archiver Appliance 運用メモ|Archiver Appliance 運用メモ]]に続く
= 参考 =
* [https://epicsarchiver.readthedocs.io/en/latest/sysadmin/installguide.html Archiver Appliance Install Guide]
* [https://epicsarchiver.readthedocs.io/en/latest/sysadmin/admin.html Archiver Appliance Administration Guide]
* [https://epicsarchiver.readthedocs.io/en/latest/developer/mgmt_scriptables.html Business Process Logics for scripting]
* [https://github.com/jeonghanlee/epicsarchiverap-sites Site-specific (ESS) EPICS Archiver Appliance Deployment (for CentOS7)]