インストールマニフェストのTips集

記事

Megumi Kakechi · 2024年3月20日 14m read

#システム管理 #ヒントとコツ #Caché #Ensemble #InterSystems IRIS #InterSystems IRIS for Health

%Installerという特別なツールを使用すると、目的のIRIS構成を記述するインストールマニフェストを定義できることはご存じでしょうか？
インストールマニフェストに作成したい IRIS 構成を記述すると、インストール中、またはターミナルやコードからマニフェストを実行した際に、構成設定が適用されます。

インストールマニフェストについては、以下の記事でご紹介しておりますので是非ご覧ください（Cachéの記事になりますがIRISでも同様です）。
%InstallerでInterSystems Cachéにアプリケーションをデプロイする

こちらの記事では、実際にマニフェストで追加できる主な項目について、サンプルコードとあわせてご紹介します。
今回は、以下の機能の設定例をご紹介します。

1. ライセンスファイルのコピーと適用
 2. ネームスペース・データベースの作成
 3. 構成情報(ポートやデータベースキャッシュ・メモリ設定など)の適用
 4. セキュリティ情報（ユーザ・サービスなど）のインポート　※同一バージョンのみ
 5. セキュリティ情報（ユーザ・ロールなど）の作成
 6. SQL情報の作成
 7. ジャーナル情報の作成
 8. ユーザ作成クラスやグローバルのインポート、メソッドの実行
 9. システムクラスのクラスメソッドを引数付きで実行
　－バックアップリストの作成
　－監査のシステムイベント設定と監査の有効化
　－データベースの暗号化
※Appendix：Manifest の簡単テスト手順　※ターミナルでマニフェストを実行

★１．ライセンスファイルのコピーと適用

<!-- copy iris.key to mgr -->
 <CopyFile Src="${SourceDir}\iris.key" Target="${MGRDIR}\iris.key" name="copyKey"/>
 <!--Activate license key -->
 <Invoke Class="%SYSTEM.License" Method="Upgrade" CheckStatus="false"/>
 <!-- インストール前にコピーすることも可能
  1. mkdir -p <install_dir>\mgr
  2. copy cache.key <install_dir>\mgr
  3. インストール実行時は適用のみ
 -->
XML
XML

※${SourceDir} は、マニフェストで使用できる事前定義変数になります。SourceDirは、インストール実行ファイルのあるディレクトリになります。詳細は以下のドキュメントをご覧ください。
マニフェストタグ内で使用できる事前定義変数

※マニフェストで使用できるタグの一覧は以下のドキュメントをご覧ください。
<Manifest> タグのリスト

★２．ネームスペース・データベースの作成

管理ポータル：
システム管理 > 構成 > システム構成 > ネームスペース

 <Namespace Name="TEST" Create="yes" Code="TEST" Data="TEST">
   <Configuration>
     <Database Name="TEST" Create="yes" Dir="C:\db\test" Resource="%DB_TEST"/>
   </Configuration>
   <CSPApplication Url="/csp/test" Directory="C:\db\csp\test" AuthenticationMethods="64"/>
 </Namespace>XML
XML

さらに、ネームスペースにルーチン等インポートの場合、

 <Namespace Name="TEST2" Create="yes" Code="TEST2" Data="TEST2">
   <Configuration>
     <Database Name="TEST2" Create="yes" Dir="C:\db\test2" MountRequired = "1"/>   // 起動時にマウント
   </Configuration>
   <CSPApplication Url="/csp/test2" Directory="C:\db\csp\test2" AuthenticationMethods="64"/>
   <Import File="C:\temp\test.xml" Flags="c"/>
 </Namespace>
 <!-- 
  パラメータMountRequired が、管理ポータル>ローカルデータベースの属性「開始時にマウントが必要?」
　設定値について、MountRequired 1 の値で「開始時にマウントが必要?」"はい"となります。
 -->XML
XML

※詳細設定については、%Installerクラスをご覧ください。
　ネームスペースに設定できるパラメータは、クラスリファレンス %Installer.Namespace 、
　データベースに設定できるパラメータは、クラスリファレンス %Installer.Database 、
　Webアプリケーションに設定できるパラメータは、クラスリファレンス %Installer.CSPApplication で確認できます。

★３．構成情報(ポートやデータベースキャッシュ・メモリ設定など)の適用

管理ポータル：
システム管理 > 構成

※Manifest ではなく、INSTALLERMANIFESTPARAMS でも設定可能です。

設定可能項目：

bbsiz	プロセスあたりの最大メモリ (KB)
globals4kb globals8kb globals16kb globals32kb globals64kb	**KBデータベースキャッシュ用メモリ (MB)
gmheap	共有メモリヒープサイズ (MB)
LibPath	LD_LIBRARY_PATH 環境変数にディレクトリを追加。UNIX® システムでのみ有効
Locksiz	ロックに使用する共有メモリの最大サイズ (KB)
MaxServerConn	ECP クライアントからの接続の最大数
Path	既定の PATH 環境変数にディレクトリを追加。UNIX® システムでのみ有効
routines	ルーチンキャッシュ用メモリ (MB)
ZFSize	$ZF の入力パラメータと出力パラメータ用に仮想メモリに割り当てられた合計バイト数
ZFString	$ZF ヒープ上の各出力バイト配列または文字列パラメーターに割り当てられたバイト数

例：
INSTALLERMANIFESTPARAMS="bbsiz=512000,globals4kb=20, globals8kb=30,globals16kb=40,globals32kb=50, globals64kb=100,routines=40,gmheap=10000, LibPath=c:\libpath\,locksiz=2179648,MaxServerConn=5, Path=c:\lib\,ZFSize=2000,ZFString=3000"

<Manifest> で追加する場合は、<SystemSetting> タグで追加します。

<!-- Memory settings -->
<SystemSetting Name="Config.config.gmheap" Value="262144"/>      <!-- 共有メモリヒープサイズ -->
<SystemSetting Name="Config.config.bbsiz" Value="262144"/>       <!-- プロセスあたりの最大メモリ -->
<SystemSetting Name="Config.config.locksiz" Value="16777216"/>   <!-- ロックに使用する共有メモリの最大サイズ -->
<SystemSetting Name="Config.Telnet.DNSLookup" Value="0FF"/>      <!-- Telnet クライアントアドレスを DNS で検索可能フラグ -->
<SystemSetting Name="Config.Telnet.Port" Value="2323"/>          <!-- Telnet ポート番号 -->
<SystemSetting Name="Config.config.routines" Value="128"/>       <!-- ルーチンキャッシュ用メモリ(MB) -->
<SystemSetting Name="Config.config.globals8kb" Value="1024"/>    <!-- 8KBデータベースキャッシュ用メモリ(MB) -->
XML
XML

※各設定項目については、Config.* クラスで確認できます。
Config.config クラス
 Config.Telnet クラス

管理ポータル：
システム管理 > 構成 > 追加の設定 > 互換性

<!-- Miscellaneous settings -->
<SystemSetting Name="Config.Miscellaneous.LogRollback" Value="1"/>   <!-- トランザクションロールバックをmessages.logに記録 -->XML
XML

※既存インスタンスの設定一覧は、ターミナルにて以下のようにして確認できます。

%SYS>set Status=##Class(Config.Miscellaneous).Get(.Properties)
 
%SYS>zwrite Properties
Properties("AsyncDisconnectErr")=0
Properties("AsynchError")=1
Properties("BreakMode")=1
Properties("CollectResourceStats")=0
ObjectScript
ObjectScript

管理ポータル：
システム管理 > 構成 > 追加の設定 > 開始

<!-- Startup settings -->
<SystemSetting Name="Config.Startup.ZSTU" Value="0"/>      <!-- ユーザ定義の起動を実行しない -->XML
XML

※既存インスタンスの設定一覧は、ターミナルにて以下のようにして確認できます。

%SYS>set Status=##Class(Config.Startup).Get(.Properties)
 
%SYS>zwrite Properties
Properties("CallinHalt")=1
Properties("CallinStart")=1
Properties("CliSysName")=""
Properties("DBSizesAllowed")=8192
Properties("DefaultPort")=1972
:ObjectScript
ObjectScript

管理ポータル：
システム管理 > 構成 > 追加の設定 > メモリ詳細

※既存インスタンスの設定一覧は、ターミナルにて以下のようにして確認できます。

%SYS>set Status=##Class(Config.config).Get(.Properties)
 
%SYS>zwrite Properties
Properties("BackoffDisabled")=0
Properties("ConsoleFile")=""
Properties("LargePagesDisabled")=0
Properties("LargePagesRequired")=0
Properties("LibPath")=""
Properties("LockSharedMemory")=0
:ObjectScript
ObjectScript

★４．セキュリティ情報（ユーザ・サービスなど）のインポート
　　　※同一バージョンのみ

管理ポータル：
システム管理 > セキュリティ

★ユーザ設定
※Security.Usersクラス、もしくは^SECURITYユーティリティでユーザ設定をエクスポートしたファイルを使用。
　＾SECURITYユーティリティの場合
　1) User setup > 6) Export users

<!-- Security settings -->
<Invoke Class="Security.Users" Method="Import" CheckStatus="true">
    <Arg Value="C:\temp\Security_Users.xml" />
</Invoke>XML
XML

★サービス設定
※Security.Servicesクラス、もしくは^SECURITYでサービス設定をエクスポートしたファイルを使用。

<Invoke Class="Security.Services" Method="Import" CheckStatus="true">
    <Arg Value="C:\temp\Security_Services.xml" />
</Invoke>XML
XML

★全設定
※^SECURITY ユーティリティで全設定を一括エクスポートしたファイルを使用。
12) System parameter setup > 5) Export All Security settings

<Invoke Class="Security.System" Method="ImportAll" CheckStatus="false">
     <Arg Value="${SetupDir}\NameSpace\KESecurityExport.xml"/>
</Invoke>
XML
XML

★５．セキュリティ情報（ユーザ・ロールなど）の作成

<User
    Username="Clerk1"
    PasswordVar="UserPwd"
    Roles="testrole"
    Fullname="Data Entry Clerk"
    Namespace=""
    Routine=""
    ExpirationDate=""
    ChangePassword="0"
    Enabled="1"
    Comment=""/>
<Resource
   Name="%accounting_user"
   Description="Accounting"
    Permission="RW"/>
<Role
   Name="testrole"
   Description=""
   Resources="%Development:U,%accounting_user:RWU"
    RolesGranted="%All"/>XML
XML

※<User> タグの PasswordVar パラメータはユーザのパスワードを格納した変数を指定します。
ユーザとパスワードの追加について

※変数設定例
<Var Name="UserPwd" Value="xxx"/>

★６．SQL情報の作成

管理ポータル：
システム管理 > 構成 > SQLとオブジェクトの設定 > SQL

<!-- SQL settings -->
<SystemSetting Name="Config.SQL.DelimitedIds" Value="0"/>     <!-- 区切り識別子サポート(なし=0) -->
<SystemSetting Name="Config.SQL.SaveMAC" Value="1"/>          <!-- クエリキャッシュのソースを保持(保持する=1) -->
<SystemSetting Name="Config.SQL.LockThreshold" Value="3000"/> <!-- ロックエスカレーション閾値 -->
<SystemSetting Name="Config.SQL.DefaultSchema" Value="Test"/> <!-- デフォルトスキーマ -->XML
XML

※各設定項目については、Config.SQLクラスで確認できます。

※既存インスタンスの設定一覧は、ターミナルにて以下のようにして確認できます。

%SYS>set Status=##Class(Config.SQL).Get(.Properties)
 
%SYS>zwrite Properties
Properties("ANSIPrecedence")=1
Properties("AdaptiveMode")=1
Properties("AllowRowIDUpdate")=0
Properties("AutoParallel")=1
Properties("AutoParallelThreshold")=3200
Properties("BiasQueriesAsOutlier")=0
Properties("Comment")=1
Properties("DBMSSecurity")=1
:ObjectScript
ObjectScript

★７．ジャーナル情報の作成

管理ポータル：
システム管理 > 構成 > システム構成 > ジャーナル

 <!-- Journal settings -->
 <SystemSetting Name="Config.Journal.CurrentDirectory" Value="xxx"/>     <!-- プライマリのジャーナル・ディレクトリ -->
 <SystemSetting Name="Config.Journal.AlternateDirectory" Value="xxx2"/>  <!-- セカンダリのジャーナル・ディレクトリ -->
 <SystemSetting Name="Config.Journal.FileSizeLimit" Value="2048"/>       <!-- 新しいジャーナルファイルに切り替えるサイズ (MB) -->XML
XML

※各設定項目については、Config. Journalクラスで確認できます。

※既存インスタンスの設定一覧は、ターミナルにて以下のようにして確認できます。

%SYS>set Status=##Class(Config.Journal).Get(.Properties)
 
%SYS>zwrite Properties
Properties("AlternateDirectory")="C:\InterSystems\IRIS\mgr\journal\"
Properties("BackupsBeforePurge")=2
Properties("CompressFiles")=1
Properties("CurrentDirectory")="C:\InterSystems\IRIS\mgr\journal\"
Properties("DaysBeforePurge")=2
Properties("FileSizeLimit")=1024
Properties("FreezeOnError")=0
Properties("JournalFilePrefix")=""
Properties("JournalcspSession")=0ObjectScript
ObjectScript

★８．ユーザ作成クラスやグローバルのインポート、メソッドの実行

インストールマニフェストタグ経由で設定できない項目は、ObjectScriptでメソッドを作成し、<Invoke> タグで実行します。
<Import> タグを使用すると、クラスファイルのロード/コンパイルに加え、グローバルをロードすることも可能です。

<Namespace Name="USER">
    <!-- 変数の指定 -->
    <Var Name="SourceDir" Value="C:\CacheInstallAcademy"/>
    <Import File="${SourceDir}\quote.gof" Flags=""/>
    <Import File="${SourceDir}\CustomerClasses.xml" Flags="ck"/>
    <Invoke Class="User.ManifestTest" Method="setBackupList" CheckStatus="" Return="">
       <Arg Value=""/>
    </Invoke>
</Namespace>
XML
XML

例：データベースバックアップリストの作成

管理ポータル：
システム管理 > 構成 > データベースバックアップ > データベースバックアップリスト

以下のようなクラスメソッドを作成し、<Invoke> タグを使用して実行します。

Class User.ManifestTest Extends %RegisteredObject
{
 ClassMethod setBackupList() [ Language = objectscript ]
 {
   Set rc=##class(Backup.General).ClearDatabaseList()          // リストのクリア
   Set rc=##class(Backup.General).AddDatabaseToList("TEST")    // リストに追加
   Set rc=##class(Backup.General).AddDatabaseToList("TEST2") 
   Set rc=##class(Backup.General).AddDatabaseToList("TEST3")
 }
}
ObjectScript
ObjectScript

※インストールマニフェストには以下のタグを追加して実行します。

<Import File="${SourceDir}\User.ManifestTest.xml" Flags="ck"  />
<Invoke Class="User.ManifestTest" Method="setBackupList" CheckStatus="false"/>XML
XML

例：監査のシステムイベント設定と監査の有効化

管理ポータル：
システム管理 > セキュリティ > 監査

以下のようなクラスメソッドを作成します。実行方法は、上記 setBackupList() と同じです。

ClassMethod setBackupList() [ Language = objectscript ]
{
  // システムイベント："%System/%Login/LoginFailure" を有効に設定する
  set Property("Enabled")=1
  set status=##class(Security.Events).Modify("%System","%Login","LoginFailure",.Property)
	
  // 監査ログを有効に設定する	
  // do ##class(Security.System).Get("SYSTEM",.Property2)    // 一覧を参照したいとき。zwrite Property2
  set Property2("AuditEnabled")=1
  do ##class(Security.System).Modify("SYSTEM",.Property2)
}
ObjectScript
ObjectScript

例：データベースの暗号化

管理ポータル：
システム管理 > 暗号化

以下のようなクラスメソッドを作成します。実行方法は、上記 setBackupList() と同じです。

ClassMethod setEncryption() [ Language = objectscript ]
{
// (1) 暗号化キーの作成
  // $system.Encryption.CreateAutoEncryptionKeyOnly(キーファイル名,ｾｷｭﾘﾃｨﾚﾍﾞﾙ, Description,管理者名,パスワード)
	set status=$system.Encryption.CreateAutoEncryptionKeyOnly("/usr/irishealth/mgr/autofile.key",128,"Key for automatic activation at startup",.username,.password)
    
  // (2) 暗号化キーの有効化
  // $system.Encryption.ActivateAutoEncryptionKey(キーファイル名,管理者名,パスワード,iristemp,journal,audit)
  // 生成された管理名,パスワードを指定、iristemp,journal,audit を暗号化する場合は それぞれ1 を指定
  set status=$system.Encryption.ActivateAutoEncryptionKey("/usr/irishealth/mgr/autofile.key",.username,.password,0,0,0)
    
  // (3) 既存データベースの暗号化
  // ##class(SYS.Database).DismountDatabase(データベースファイルパス) ; 暗号化の前にディスマウント
  // ##class(SYS.Database).EncryptDatabase(データベースファイルパス)  ; 暗号化
  // データベースファイルの暗号化はキーの有効化の後に実施する必要があります
  set status=##class(SYS.Database).DismountDatabase("/usr/irishealth/mgr/test/")
  set status=##class(SYS.Database).EncryptDatabase("/usr/irishealth/mgr/test/")

}
ObjectScript
ObjectScript

★９．システムクラスのクラスメソッドを引数付きで実行

例：他環境よりエクスポートしたタスクスケジュールをインポートします。

※他環境からエクスポートする方法は、こちらの記事をご覧ください。

管理ポータル：
システムオペレーション > タスクマネージャー > タスクスケジュール

<Invoke Class="%SYS.TaskSuper" Method="ImportTasks" CheckStatus="1" Return="">
    <Arg Value="c:\temp\exportedTasks.xml"/>
</Invoke>  XML
XML

※Appendix：Manifest の簡単テスト手順

Manifest は、既存のインスタンスで動作確認をすることができます。
以下のマニフェストは、サイレントインストール時にそのまま INSTALLERMANIFEST="C:\MyInstaller.cls" もしくは、INSTALLERMANIFEST="C:\MyInstaller.xml" のように指定することが可能です。

1. 以下のようなマニフェストを作成します。

/*------ User.MyInstaller.cls -----------------------*/
Include %occInclude
Class User.MyInstaller Extends %RegisteredObject
{

XData MyInstall [ XMLNamespace = INSTALLER ]
{
<Manifest>
 <Namespace Name="TEST" Create="yes" Code="TEST" Data="TEST" Ensemble="0">
   <Configuration>
     <Database Name="TEST" Create="yes" Dir="${MGRDIR}test" Resource="%DB_TEST"/>
   </Configuration>
   <CSPApplication Url="/csp/test" Directory="${CSPDIR}test" AuthenticationMethods="64" Recurse="1"/>
 </Namespace>
</Manifest>
}

ClassMethod setup(ByRef pVars, pLogLevel As %Integer = 3, 
   pInstaller As %Installer.Installer, 
   pLogger As %Installer.AbstractLogger) 
   As %Status [ CodeMode = objectgenerator, Internal ]
{
    Quit ##class(%Installer.Manifest).%Generate(%compiledclass, %code, "MyInstall")
}

}
ObjectScript
ObjectScript

※Webアプリケーションの認証方法の設定例：4=Kerberos、32=password、64=unauthenticated

2. ターミナルで以下のように実行します（%SYSネームスペースで実行します）。

%SYS>Do ##class(User.MyInstaller).setup()ObjectScript
ObjectScript

3. 管理ポータルで、TESTネームスペースと、TESTデータベースができているのを確認します。

インストールマニフェストのTips集

★４．セキュリティ情報（ユーザ・サービスなど）のインポート ※同一バージョンのみ

例：データベースバックアップリストの作成

例：監査のシステムイベント設定と監査の有効化

例：データベースの暗号化

★４．セキュリティ情報（ユーザ・サービスなど）のインポート
　　　※同一バージョンのみ