Published on 22 Aug 2018
Payara Server 5が既にリリースされていますので、基本的な事柄をブラッシュアップするにはちょうど良い頃でしょう。これから、Payara ServerのCLIでできることをいくつか見てゆきたいと思います。
コマンドライン・インタフェース (CLI) はコマンドライン (またはターミナル) からPayara Serverをコントロールする手段であり、複数の方法でサーバーの起動、停止、編集を行うことができます。管理コンソールでも必要なあらゆる管理操作を実行することはできますが、CLIを用いると、特にヘッドレス・サーバー (GUIを持たないサーバー) を扱う場合において、あらゆる管理タスクをより素早く簡単に実行できる場合があります。
Asadmin
Payara ServerのCLIはasadminユーティリティ (“Application Server Administration” と、ちゃんと意味のあるものです) を使用します。これはPayara Serverをインストールした場所のbinディレクトリにあると思います。Payara Serverのすべての管理コマンドはこのユーティリティのサブコマンドであり、各コマンドの先頭にはasadminを追加しなければなりません(例: ./asadmin do-a-little-dance)。
asadminを各コマンドに付加しなくてもよいお手軽な方法は、asadmin自身を呼び出いことです (例: ./asadmin). これでasadminは対話モードで実行され、いくつかのコマンドを連続して実行しようとする場合にキー入力をいくらか減らすことができます。
CLIではほとんどのコマンドに追加のオプションを指定することが可能で、そのうちのいくつかは確実にコマンドを実行するために必須となります。コマンドが持っているオプションのリストは、コマンドの説明および例と同様に、--helpパラメータをコマンドに渡すことで表示できます (例: ./asadmin start-domain --help)。これらのオプションは “--" で始まらなければなりませんが、一部のオプションにはダッシュ1つでよい短縮バージョンが用意されています。例えば、
./asadmin start-domain --debug true
は以下と同様です。
./asadmin start-domain –d
起動と停止
ドメイン
既にPayara Serverをインストールされているようでしたらご存知かと思いますが、CLIを用いてドメイン、クラスタおよびインスタンスの起動及び停止が可能です。Payara Serverのインストール後に最初に行うことは、以下のようにCLIからデフォルトのドメインを起動することです。
./asadmin start-domain
start-domainコマンドはデフォルトでdomain1を起動します。他のドメインを起動するには、以下のように追加のパラメータでドメイン名を指定する必要があります。
./asadmin start-domain myDomain
先に注記したように、各コマンドで--helpを使用すると使用可能なパラメータのリストを取得できます。start-domain コマンドの場合は、dry-run、domaindir、upgrade、debug、verboseおよびwatchdogの各パラメータが表示されます。特にdebugおよびverboseオプションは、デバック時にとても役に立ちます。
ドメインの停止は起動と同様に簡単で、stop-domainコマンドを使用します。
./asadmin stop-domain
ドメインの起動と同様に、domain1が停止するドメインのデフォルトです。他のドメインを停止するには、停止するドメインを指定する必要があります。
./asadmin stop-domain myDomain
このコマンドで特筆すべきオプションはforceとkillです。これはのオプションはドメインをシャットダウンする際のふるまいを指定するのに有用です。forceオプションはドメインを即時に停止するか (true)、あるいはすべてのスレッドが終了するのを待ってからドメインを停止するか (false) を指定します。killオプションはドメインのプロセスを終了する方法を指定します。このデフォルトはfalseで、Javaプラットフォームがプロセスを停止することを意味します。このオプションでtrueを指定した場合には、オペレーティング・システムがドメインのプロセスを停止します。
./asadmin stop-domain --kill true domain1
インスタンス
Payara Serverのインスタンスを開始するasadminコマンドは2種類あります。start-instanceとstart-local-instanceです。この2つの最大の違いは、start-local-instanceコマンドはそのコマンドを実行するマシン上に存在するインスタンスのみを対象とすることです。start-instanceはローカル・インスタンスとリモート・インスタンスの双方に対して使用できます。
./asadmin start-instance instance1
./asadmin start-local-instance instance2
これらのコマンドに--debugオプションを付加することでデバッグも可能で、インスタンス起動時にデバッグ機能が有効となります。start-local-instance コマンドではデバッグ・オプションとしてさらに--verboseオプションを指定可能です。これによりインスタンス起動と同時にログ・メッセージをコンソールに出力するようになるため、何が起こっているのかを一目でわかるようになります。
他の特筆すべき有益なオプションは--syncです。このオプションは3種類のパラメータ、none、normal、fullを取ります。 このオプションを使用する場合には、これらのパラメータのうちいずれかを指定しなければなりません。syncオプションはインスタンスが自身をどのような方法でDAS (Domain Administration Server) と同期させるのかを指定するものです。
- noneパラメータは、インスタンスをDASと同期させないことを意味します。そのため、最後に同期してから行われた変更内容は反映されません。これは変更を行っていないことがあらかじめ分かっており、かつインスタンスをできるだけ素早く起動したい場合に有用です。
- normalでは、インスタンスは最後に同期が行われてから (通常、前回に同期した時はオンラインです) 変更された内容を同期します。--syncオプションを指定しなかった場合には、これがstart-instanceまたはstart-local-instanceコマンドのデフォルトとなります。補足すると、このパラメータはインスタンスに対してconfigディレクトリの同期と、サブディレクトリ内のアプリケーションおよびdocrootの更新を行います。ただし、既存のサブディレクトリの同期には例外があります。同期が行われるのはサブディレクトリの最上位に対する変更のみです。もしファイルシステム階層の下位で変更が行われた場合には、それは最上位ではありませんので、変更内容は同期されません。
- 最後のオプションであるfullにはこうした問題はありません。この同期パラメータはすべてのファイルについて、全く変更されていない場合であっても同期します。これはインスタンスを同期させる最も確実な方法ですが、副作用もあります。このオプションはnormalオプションやnoneオプションよりも時間がかかり、またDASが動作している必要があります。このコマンドの実行時にDASが動作していない場合にはこのコマンドは失敗し、インスタンスは再びDASに接続するまで起動できなくなります。
./asadmin start-local-instance --sync full --verbose true --debug true instance1
インスタンスを停止するコマンドはstop-instanceとstop-local-instanceです。2つのコマンドの違いはstartコマンドの場合と同様です。前者はローカル・インスタンスとリモート・インスタンスの双方に使用できますが、後者はローカル・インスタンスのみ使用可能です。
./asadmin stop-instance instance1
./asadmin stop-local-instance instance2
stop-domainコマンドと同様にforceおよびkillオプションを指定可能で、その動作はstop-domainコマンドと同じです。
デプロイメント・グループ
Payara Server 5の新機能であり、古いクラスタリングを置き換えるようなもので、よく似てはいますが、少し異なります。この新機能のためにasadminにいくつか新しいコマンドが追加されています。
以前のクラスタリングと同様に、デプロイメント・グループにもリモートとローカルのstart/stopコマンドに差異はありません。したがって、以下のコマンドを知っているだけでよいのです。
./asadmin start-deployment-group group1
./asadmin stop-deployment-group group1
これらのコマンドには個別のオプションがなく、そのままの動きをします。Startコマンドはデプロイメント・グループに登録されているすべてのインスタンスを起動するよう試み、stopコマンドは同様にこれらすべてを停止するよう試みます。
作成
ドメイン
これは少々複雑です。新しいドメインをデフォルト値で作成するだけであれば、以下を実行します。
./asadmin create-domain
ドメイン名、管理ユーザー名と管理パスワードを設定するよう促されます。その後、使用するデフォルト・ポートの一覧が表示され、自己署名証明書が作成されます。
ドメインをカスタマイズする場合には、多くのオプションが用意されています。以下にその一部を示します。
- adminport – このオプションは管理操作で使用するポート番号を指定します (デフォルトは4848)。
- instanceport – このオプションはWebアプリケーションのコンテキスト・ルートで使用されるポート番号を指定します (デフォルトは8080)。
- portbase – このオプションはポートの割り当てを決定します。adminport、instanceport、domainpropertiesと同時には使用できません。このオプションで指定する値はベース値で、必須のポート番号 (例: 管理ポート) をオフセットにより自動計算します。例えば、ポート・ベースに500を指定した場合には、管理ポートは548 (500 + 管理ポートのオフセット48) となります。それぞれのポート番号のオフセットについては、create-domainコマンドのヘルプを参照してください。
- template – マシンからマシンへコピーするためのドメイン・テンプレートが既に用意されている場合に有用です。このオプションを使用することでテンプレートに合わせたドメインを作成することができます。
- usemasterpassword – 追加のセキュリティのため、Payara Serverのキーストアをパスワードで保護することができます。特に指定されない場合、パスワードにはchangeitが使用されます。このデフォルトは非常によく知られていますので、Payara Serverをセキュアにする場合には変更するようにしてください。
- domainproperties – このオプションを使用すると、個々のポートをportbaseに依存しない形で設定することができます。ただし、このコマンドで指定した管理ポートとインスタンス・ポートはadminportおよびinstanceportオプション上書きできます。ポートのすべての一覧はコマンドのヘルプで確認することができますが、例えば、adminPort、domain.instancePort、http.ssl.port、java.debugger.portなどがあります。複数の値を指定する場合には、それらをコロンで区切ってください。例: domain.adminPort=3456:domain.instanceport=4567
ノード
Payara Serverの各種ノードを作成するコマンドとして、create-node-config、create-node-dcom、create-node-sshが用意されています。Configノードをデフォルトの設定で作成する場合には、ノード名だけを指定します。SSHノードまたはDCOMノードの場合は、ノード名に加えてノードを配置するマシンのホスト名を指定する必要があります。
./asadmin create-node-config configNode
./asadmin create-node-dcom --nodehost example.domain.co.uk dcomNode
./asadmin create-node-ssh --nodehost localhost sshNode
Configノード作成時にデフォルト値が適していない場合には、ノードのホスト名、インストール・ディレクトリ、ノード・ディレクトリをそれぞれnodehost、installdir、nodedirオプションで指定します。
./asadmin create-node-config --nodehost localhost --installdir /home/user/payara --nodedir /home/user/nodes configNode
これらのオプションはノードを配置するマシン、マシン上のPayara Serverのインストール・ディレクトリ、ノードを配置するディレクトリ (これら個々のオプションは多くの構成では省略が可能です) を参照します。デフォルトのインストール・ディレクトリはDASのインストール場所により決まります。デフォルトの設定ではPayara Serverはすべてのホストで同じ位置にインストールされているものとみなされます。
SSHノードやDCOMノードはConfigノードに比べて複雑であるため、作成および構成にはより多くのオプションを必要とします。すべてのオプションの一覧についてはhelpオプション (./asadmin create-node-ssh --help) でご確認いただくとして、ここではそのいくつかをご紹介します。
SSHノード:
- force – ノードの作成時に指定するパラメータの検証に失敗しても、DASの構成でノードを強制的に作成します。これは対象のノードが一時的に使用できないため検証に失敗したことが分かっている場合に有用です。このオプションはcreate-node-dcomでも使用できます。
- sshport – デフォルトのSSHポート (22) 以外を使用する場合に、このオプションで代替のポートを指定します。
- sshuser – ホストにSSH経由で接続する際に使用するユーザー名を指定します。デフォルトではDASを実行しているユーザーとなります。
DCOMノード:
- windowsuser – DCOM経由で接続する際に使用するWindowsユーザー名を設定します。省略した場合にはDASのプロセスを実行しているユーザーになります。
- windowsdomain – Windowsユーザーが所属しているWindowsドメインを指定します。デフォルトはサブコマンドを実行するユーザーが所属するWindowsドメインとなります。
- install - 指定したノードのホストにPayara Serverをインストールするかどうかを指定します。このオプションはcreate-node-sshでも使用できます。
デプロイメント・グループ
デプロイメント・グループの作成はとても簡単で、create-deployment-groupcommandに名前を指定するだけです。
./asadmin create-deployment-group guppy1
デプロイメント・グループの管理は複雑になりますが、以降のセクションでデプロイメント・グループへのインスタンスの追加と削除に重点を置いてご説明します。
インスタンス
インスタンスの作成にもcreate-instanceとcreate-local-instanceの2つのコマンドがあります。その名前から推察できるように、create-local-instanceコマンドは そのホスト上にインスタンスを作成する時のみ実行可能で、リモート・マシンのインスタンス作成には使用できません。このコマンドは共有、スタンドアロン、クラスタのいずれのインスタンス作成でも使用します。
./asadmin create-instance instance1
./asadmin create-local-instance instance2
デフォルトでは、インスタンスは自身の構成をdefault-configからコピーして作成します。--configオプションを使用するとこれを作成済みの構成に変更できます。
./asadmin create-instance --config instance-config-1 instance3
インスタンスが使用するリスン・ポートを指定するには--systempropertiesオプションを使用します。
インスタンスを作成するノードを指定するには、以下のように--nodeオプションを使用します。
./asadmin create-instance --node node1
パスワードの設定と変更
Payara Serverの管理パスワードとマスター・パスワードの設定と変更はCLIで行うことができます。2種類のパスワードは以下のコマンドで設定または変更します。
./asadmin change-admin-password
./asadmin change-master-password
change-admin-passwordコマンドはドメイン固有であり、domain_nameとdomaindirの2つのオプションでドメインを指定することができます。複数の管理ユーザーが存在する場合には、以下のようにユーザーを指定してパスワードを変更することができます。
./asadmin --user admin change-admin-password
change-master-passwordコマンドには次のオプションがあります。nodedirはパスワードを変更するノードが含まれるディレクトリを指定します。 domaindirは使用されるドメイン・ディレクトリを指定します。savemasterpasswordはマスター・パスワードをディスクに保存するかどうかを指定します (無自覚で使うのは非常に悪いプラクティスです)。
アプリケーションのデプロイ
アプリケーションのデプロイは、環境設定に依存した非常に複雑なものになりがちです。逆に、CLIによるアプリケーションのデプロイは、やり方を押さえておけば、管理コンソールによるデプロイよりも非常に素早く実行することができます。
アプリケーションをデフォルトのインスタンス (管理コンソールがインストールされているサーバー) にデプロイするには、単純に以下のコマンドを実行します。
./asadmin deploy $path_to_war
Payara Serverの環境を設定した後、デフォルトのサーバー・インスタンス以外にデプロイするような場合もあることでしょう。そのような場合にはtargetオプションを使用してデプロイ先を指定することになります。このオプションではコンポーネントのデプロイ先となるインスタンスまたはデプロイメント・グループを指定することができます。
./asadmin deploy --target group1 testWar
./asadmin deploy --target instance1 testWar
CLIのdeploy-remote-archiveは管理コンソールにないデプロイ・オプションも持っています。このコマンドはアプリケーションをURLからデプロイするだけでなく、MavenリポジトリからもGroup、Artifact、Version (GAV) 座標を使用してデプロイすることができます。
URLとMaven GAV座標を区別するフラグはありません。コマンドが両者を自動的に判別します。
./asadmin deploy-remote-archive https://raw.githubusercontent.com/Pandrex247/Payara_PatchedProjects/Payara-Maven-Deployer/fish/payara/testing/clusterjsp/1.1/clusterjsp-1.1.war
./asadmin deploy-remote-archive --additionalRepositories https://raw.github.com/Pandrex247/Payara_PatchedProjects/Payara-Maven-Deployer fish.payara.testing,clusterjsp,1.1
よく見ると、これまで言及していない--additionalRepositoriesというオプションにお気づきになるでしょう。このオプションには、アプリケーションの検索対象となるMavenリポジトリのカンマ区切りリストを指定します。デフォルトではMaven Centralのみを検索対象とします。
デプロイメント・グループのインスタンスの追加と削除
デプロイメント・グループが古いクラスタリングと大きく異なる点として、デプロイメント・グループ内のインスタンス配置がより柔軟になったことが挙げられます。インスタンスはもはやクラスタに関連付けられることはなく、そして1つ以上のデプロイメント・グループに所属することができます。
この柔軟性に対応するため、デプロイメント・グループのインスタンスを追加および削除する新しい2つのasadminコマンドがあります。
./asadmin add-instance-to-deployment-group --instance instance1 --deploymentgroup group1
./asadmin remove-instance-from-deployment-group --instance instance1 --deploymentgroup group1
これらのコマンドは全くもってそのままなのですが、削除するインスタンスと、そのインスタンスが属するデプロイメント・グループを指定する2つの構成オプションだけを取ります。これらの構成オプションはいずれも必須であり、指定しなかった場合には入力を促すプロンプトが表示されます。
ドメイン・データ・グリッドの管理
難しい話を置いておくと、Hazelcastは既にPayara ServerとPayara Micro全体に存在しています。特にPayara 5ではHazelcastとの統合が顕著になっていますので、その構成方法についてご説明しておく必要があるでしょう。
ドメイン・データ・グリッドはHazelcastを使用しているため、構成コマンドはそれに関連する名前となっています。
./asadmin get-hazelcast-configuration --target server-config
./asadmin set-hazelcast-configuration --target config1
setコマンドには多くのオプションがありますが、ここでは最もよく使用するものについてご紹介します。
- --enabled – Hazelcast (および拡張クラスタリング) を有効にするかどうかを指定します。
- --target – 対象とする構成を指定します。
- --dynamic – 変更の反映時にHazelcastを再起動するかどうかを指定します。
- --startport – バインドするポート番号(Hazelcastは空きポートが見つかるまでインクリメントする) を指定します。なお、この設定はドメイン全体に適用されます。
- --clustername – 参加するHazelcastクラスタ名を指定します。あるドメインのインスタンスが他のドメインと混ざってしまうのは好ましくなく、そうした場合にドメインを分割する効果があります。
- --clusterpassword – 参加するクラスタのパスワードを指定します。
- --lite – インスタンスを “lite” メンバーとして構成するかどうかを指定します。“lite” メンバーとは、データを自身のメモリに保存しないメンバーを言います。
Payara 5では新たに、Payaraインスタンスがどのような方法でお互いをクラスタ化するかを--clustermodeオプションで構成できるようになっています。なお、これはドメイン全体に作用するもう1つのオプションであるため、構成ごとに異なるクラスタ・モードを使用することはできません。
domainディスカバリー・モード
これはPayara Serverが使用するデフォルトのオプションであり、通常は初期状態から追加の構成を行う必要はないでしょう。
実際のところ、必要な操作はディスカバリー・モードをdomainに設定することだけです。各インスタンスがDASを検索するための通信について追加の構成は必要ありません。DASがHazelcastをバインドするアドレスから自動的に割り出されます。
./asadmin set-hazelcast-configuration --clustermode domain
TCP/IPモード
このクラスタ・モードは、クラウド環境のPayara Microでの使用を主な目的としているため、このブログでは詳細については触れません。
簡単にご説明すると、a) DASが存在せず、かつ b) マルチキャストが難しい (もしくは不可能な) 環境で使用します。機能的には、domainディスカバリー・モードと少し対照的です。domainディスカバリー・モードでは、各インスタンスに対してDASを検索する情報を与えます。TCP/IPモードでは、DASに対して他のインスタンスを検索する情報を与えます。
Multicastモード
これはPayara Server 4とPayara Micro 4の頃のクラスタリングでHazelcastが使用していた方法で、Payara Microでは現在もデフォルトです。
このモードについては (Payara Serverで使用する際に明示的に設定することを除けば) 変更されていません。それぞれのオプションにマルチキャスト・グループとポート番号を指定します。
./asadmin set-hazelcast-configuration --clustermode multicast --multicastgroup 224.2.2.3 --multicastport 54327
まとめ
Payara ServerのCLIのご紹介は以上です。CLIは技術的に奥が深いものですが、まずは最初の一歩を踏み出すことができたのではないかと思います。Payara Serverを管理する方法として、管理コンソールの代わりにCLIも使用可能であること、そしてCLIを使用することにより不必要に複雑な操作をしなくても済むことを、このブログを読んでお分かりいただければ幸いです。
