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

%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. インストール実行時は適用のみ
 -->

※${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>

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

 <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 の値で「開始時にマウントが必要?」"はい"となります。
 -->

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

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

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

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

設定可能項目：

例：
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) -->

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

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

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

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

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

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

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

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

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

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

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

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

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

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

★ユーザ設定
※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>

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

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

★全設定
※^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>

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

<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"/>

※<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"/> <!-- デフォルトスキーマ -->

※各設定項目については、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
:

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

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

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

※各設定項目については、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")=0

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

インストールマニフェストタグ経由で設定できない項目は、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>

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

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

以下のようなクラスメソッドを作成し、<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")
 }
}

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

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

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

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

以下のようなクラスメソッドを作成します。実行方法は、上記 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)
}

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

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

以下のようなクラスメソッドを作成します。実行方法は、上記 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/")

}

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

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

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

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

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

 

※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")
}

}

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

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

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

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