この記事では、PaperCut MS SQL JDBCドライバを最新のバージョンにアップグレードする方法について記載します。
ドライバの新規インストール VS ドライバのアップグレード
PaperCut Ver.24以前のバージョンとVer.25以降のバージョンには重要な違いがあります。
● PaperCut Ver.25以降、下記のフォルダに安定したテスト済みのJDBCドライバが配置されています。
/<app-path>/PaperCut MF/server/repository/database-drivers/sqlserver
● PaperCut Ver.24以前のバージョンにはSQL Server用MS JDBCドライバ7.0が付属されていました。
現在、PaperCut Ver.24以前を使用している場合、
もしくはVer.25 より前のバージョンから25以降にアップグレードした場合、
MS JDBCドライバ7.0が使用されている可能性があります。
MS JDBCドライバのアップグレードを検討すべきです。(特にデフォルトのJDBCバージョン7.0ドライバを使用している場合)
● SQL Serverバージョンのサポート
MS SQL Server Ver.2019, 2022 およびそれ以降のバージョンを使用している場合、
Microsoft社のSQLバージョン互換性推奨を参照してください。
● パフォーマンスの向上
MS SQL Server2016以降を使用している場合、新しいバージョンのドライバを使用することでパフォーマンスが向上します。
SQL Server のCPUが高い場合、更新したJDBCドライバを使用することを推奨します。
パフォーマンスの詳細については、この記事の最後に記載している「MS SQL JDBCドライバのパフォーマンス」を参照してください。
● セキュリティ設定
組織のセキュリティ要件により、MSドライバの新しいバージョンが必要になる可能性があります。
1． アップグレード前のチェック
データベース・ドライバを更新する前に、
アプリケーション・サーバのバックアップ(可能な限りオフラインバックアップ)
もしくはスナップショットを作成することを強く推奨します。
これにより、必要に応じてロールバックすることができます。
本番環境アップグレード前のテスト
本番環境でデータベース・ドライバを適用する前に、
テスト環境にPaperCutをインストールし現在のドライバのバージョンと設定で
テスト用MS SQLデータベースに接続し、下記の手順を確認することを強く推奨します。
2． MS SQL JDBCドライバのダウンロード
PaperCut MF Ver.25以降のバージョン
Ver.25以降を実行している場合、推奨するMicrosoft SQL JDBCドライバはアプリケーション・サーバの次のディレクトリにあります:
[app server install dir]/server/repository/database-drivers/sqlserver
この場合、特定のバージョンのMS JDBCドライバを使用する必要がない限り、ドライバをダウンロードする必要はありません。
PaperCut MF Ver.24より前のバージョン(および特定のドライバ・バージョンが必要な場合)
PaperCut Ver.25より前のバージョンを実行している場合、もしくは下記のフォルダに含まれていない特定のドライババージョンが必要な場合、
下記の手順に従って適切なJDBCドライバをダウンロードしてください。
1． 「Microsoft SQL Server 用 JDBC Driver のダウンロード」のページにアクセスしてください。
【Microsoft SQL Server 用 JDBC Driver のダウンロード】
https://learn.microsoft.com/ja-jp/sql/connect/jdbc/download-microsoft-jdbc-driver-for-sql-server?view=sql-server-ver16
2． 必要なドライババージョンをダウンロードしてください。(詳細はMicrosoft社の「SQLバージョンの互換性」ページを参照してください)
PaperCut社ではVer.12.8.1を検証し、多くのお客様がそのバージョンを使用して成功しています。
このバージョンは、MS SQL Server Ver.2016以降と互換性があります。
環境固有の要件により、より新しいバージョンや特てのバージョンを使用する必要がある場合、事前にテスト環境で検証を行うことを強く推奨します。
【SQL バージョンの互換性】
https://learn.microsoft.com/ja-jp/sql/connect/jdbc/microsoft-jdbc-driver-for-sql-server-support-matrix?view=sql-server-ver16#sql-version-compatibility
例えば、MS SQL Server 2014を使用している場合、
Microsoft社はSQL Server2014でサポートされている現時点のMSデータベースドライバのバージョンとしてVer.12.6を挙げています。
3． JDBCファイルを解凍してください。「Jars」と「auth/x64」という2つの関連するサブフォルダを含むフォルダ構造が表示されます。
3． JDBCドライバとauth dllのアップグレード
注記
認証DLLは、MS SQL Server でWindows認証を使用する場合
(つまり、server.propertiesファイルでデータベースのユーザ名とパスワードを直接指定していない場合)のみ必要です。
そのため、これらの手順はWindowsにのみ適用されます。
注記
Windows認証を使用していて、db-toolsを実行する必要がある場合(例: init-db実行時)、
アプリケーションサーバがWindowsサービスとして実行される際に使用する、
既定のドキュメントに記載されているデフォルトのロケーション(server/bin/win/lib64/)に加え、
「server/bin/win/」ディレクトリに「jdbc-aut-*x64.dll」ファイルが存在することを確認してください。
通常動作時、アプリケーションサーバサービスが稼働しており、認証が機能しているためエラーは発生しません。
アプリケーションサーバサービスが停止した状態でinit-dbを実行すると
「Error: This driver is not configured for integrated authentication」というメッセージが表示されます。
ただし、jdbc-auth-*x64.dllファイルを「server/bin/win/」ディレクトリにコピーしている場合は、この限りではありません。
アプリケーションサーバ・クラスタの場合
HA環境で複数のアプリケーションサーバを使用している場合、下記の手順を実行してください。
① パッシブ・ノードに変更を適用
② フェイルオーバーして変更をアクティブにする
③ 残りのパッシブサーバに変更を適用
PaperCut Ver.25以降を新規インストールする場合のJDBCドライバのインストールまたはアップグレード
1． PaperCutインストール先のフォルダから「mssql-jdbc-12.x.x.jre11.jar」をコピーしてください。
[app-path]/server/repository/database-drivers/sqlserver
もしくはMSサイトからダウンロードしたMS JDBCドライバ内のjarsフォルダからコピー
そしてコピーしたjarファイルを次のフォルダに貼り付けてください。
[app-path] /server/lib-ext/
2． 【Windowsのみ】PaperCutインストール先のフォルダから「mssql-jdbc_auth-12.x.x.x64.dll」をコピーしてください。
[app-path]/ /server/repository/database-drivers/sqlserver
もしくはMSサイトからダウンロードしたMS JDBCドライバ内にあるauth/x64フォルダからコピー
そしてコピーしたdllファイルを次のフォルダへ貼り付けてください。
/server/bin/win
PaperCut Ver.24以前からVer.25以降にアップグレードする場合の
JDBCドライバのインストールまたはアップグレード
注記
PaperCut Ver.24以前のバージョンからVer.25以降にアップグレードすると、
最大3つのデータベース・ドライバの.jarファイルは「/server/lib/」から「/server/lib-ext/」へ自動的に移動します。
1． サービス「PaperCut Application Server」を停止
2． PaperCutインストール・フォルダ内の「[app-path]/server/lib/」へ移動してください。
3． 既存のmssqljdbc.jarファイル(例: mssql*.jar)をこのロケーションから一時フォルダへ移動してください。
必要に応じて変更をロールバックするために使用することができます。
このフォルダがデスクトップ上にあることを確認してください。
例えば「C:\Users\[username]\Desktop\」または「PaperCut MF」のインストールディレクトリ構造の外側にある他のロケーションです。
4． 次のロケーションへ移動してください:
[app-path]/server/lib-ext/
5． 既存のmssqljdbc.jarファイル(例: mssql*.jar)をこのロケーションから一時フォルダへ移動してください。
必要に応じて変更をロールバックするために使用できます。このフォルダがデスクトップ上にあることを確認してください。
例えば「C:\Users\[username]\Desktop\」または「PaperCut MF」のインストールディレクトリ構造の外側にある他のロケーションです。
6． 下記のロケーションから「mssql-jdbc-12.x.x.jre11.jar」ファイルをコピーしてください。
コピー元ロケーション:
<app-path>/server/repository/database-drivers/sqlserver
もしくは事前にダウンロードしたMS JDBCドライバ内のquth/x64フォルダから
コピー先ロケーション:
<app-path>/server/bin/win/lib64/
PaperCut Ver.24以前のバージョンに同梱されたJDBCドライバのアップグレード
(新規インストールまたはアップグレード)
注記: PaperCut MF/Plusをアップグレードする度に再適用が必要
この手順は、PaperCut MF/Plusのバージョン24以前を使用している場合です。
PaperCutのMF/Plusのアップグレードの度に、再適用する必要があります。
SQLドライバと認証DLLは、PaperCutアプリケーションサーバのアップグレード時に上書きされることに注意してください。
つまり、PaperCutアプリケーションサーバのアップグレードのプロセスの一環として、アップグレードする度にこの手順を再適用する必要があります。
● アプリケーションサーバが最新のバージョンにアップグレードされた場合、インストーラはパッケージ化されたドライバと認証ファイを置き換えます。
下記のドキュメントにあるように、
これらの手順(古い.jarファイルを/server/lib/から移動し、古い.dllファイルを/server/bin/win/lib64/から移動することを含む) を
やり直すことが不可欠です。
● Ver.25以降、アップグレード時にドライバ設定が上書きされなくなりました。
アップグレードの度にこれらの手順を再適用する必要を避けるため、Ver.25へのアップグレードをお勧めします。
1． サービス「PaperCut Application Server」を停止してください。
2． PaperCutインストールフォルダ「[app-path]/server/lib/」に移動してください。
3． 既存のmssql jdbc.jar ファイル(例: mssql*.jar) を
このディレクトリから必要に応じてロールバックできる一時フォルダへ移動してください。
このフォルダがデスクトップ上(例: C:\Users\[username]\Desktop\)にあることを確認してください。
PaperCutのインストールディレクトリ構造から完全に外れたロケーションに退避してください。
4． 新しい「jars/mssql-jdbc-12.x.x.jre11.jar」ファイルを
MS JDBCドライバのダウンロード・フォルダから「[app-path] /server/lib-ext/」に
コピーしてください。
5． 既存のmssqljdbc.jarファイル(例: mssql*.jar)をこのロケーションから一時フォルダへ移動してください。
必要に応じて変更をロールバックするために使用できます。
このフォルダがデスクトップ上にあることを確認してください。
例えば「C:\Users\[username]\Desktop\」または「PaperCut MF」の
インストールディレクトリ構造の外側にある他のロケーションです。
6． 下記のロケーションから「mssql-jdbc-12.x.x.jre11.jar」ファイルをコピーしてください。
コピー元ロケーション:
事前にダウンロードしたMS JDBCドライバ内のquth/x64フォルダから
コピー先ロケーション:
<app-path>/server/bin/win/lib64/
7． (Windowsのみ) PaperCutインストールフォルダ「[app-path /server/bin/win/lib64/]」へ移動してください。
8． (Windowsのみ) 既存のmssql auth.dll ファイル(例: sqljdbc_auth.dll もしくは mssql-jdbc_auth*.dll) を
このロケーションから一時フォルダへ移動し、必要に応じて変更をロールバックできるようにします。
このフォルダがデスクトップ上 (例: C:\Users\[username]\Desktop\ )
もしくはPaperCutインストールフォルダ以外のロケーションにあることを確認してください。
9． (Windowsのみ) 新しい「auth/x64/mssql-jdbc_auth-12.x.x.x64.dll」ファイルを
MS JDBC Driverのダウンロード・フォルダから「[app-path]/server/bin/win/lib64/」へ
コピーしてください。
4. PaperCut 接続文字列の変更
● 文字列の更新が必要な理由
Microsoft社のMS SQL JDBCドライバの更新により、特定のドライバ・バージョンを使用する際の「デフォルト」の動作が変更されました。
例えば、Microsoft社のVersion 10.2のリリースノートには、デフォルトでTLS暗号化を有効にするという変更点があります。
● 文字列のアップデート
注記
下記の推奨するデータベース接続文字列は、Ver.7のJDBCドライバの動作を模倣しています。
これは事実上、最新バージョンのドライバをVer.7のドライバと同じように動作させることであり、
現在の設定にできるだけ近づけることを意味します。
これにより、最も簡単な新しいドライバへの「同等の」以降が実現します。
しかし組織には異なる要件(暗号化要件やその他の接続設定など)がある可能性があり、
データベース管理者と話し合う必要があります。
1． PaperCutインストールフォルダ内の次のディレクトリへ移動してください: <app-path>/server/
2． 管理者権限でメモ帳を開き、「server」フォルダ内にある「server.properties」を開いてください。
3． 「database.url=」の後に記載する文字列を「;encrypt=false;trustServerCertificate=true;」を含むように更新してください。
例えば、現在の接続文字列が下記の場合、次のようになります。(あくまでも一例です。組織の要件に依存します。)
【現在の接続文字列例】 jdbc:sqlserver://sqlservername:1433;databaseName=databasename;integratedSecurity=true;sendStringParametersAsUnicode=false;socketTimeout=600000
【更新後の接続文字列例】 jdbc:sqlserver://sqlservername:1433;databaseName=databasename;integratedSecurity=true;sendStringParametersAsUnicode=false;socketTimeout=600000;encrypt=false;trustServerCertificate=true
注記
現在のデータベース接続文字列が「jdbc:jtds:sqlserver」で始まる場合、
さらに古い「jtds」ドライバを使用していることを示します。
ドライバを更新する際、接続文字列の余分な「jtds:」を削除し、
新しい文字列が上記の例のように「jdbc:sqlserver:」で始まるように編集してください。
注記
● 文字列オプションを変更する必要がない、もしくは変更したくない場合があります。
例えば、「encrypt」や「trustServerCertificate」パラメータがすでに文字列内に含まれている場合や、
SQL Server上でオーバーライド設定が構成されている場合などです。
● SQL Server側の変更とさらなる構成オプションが必要になる可能性があります。
データベース技術者と協力して詳細と構成を確認してください。
● Microsoft社は、接続プロパティの設定に関する記事で、接続文字列に関するドキュメントを提供しています。
【接続プロパティの設定】
https://learn.microsoft.com/ja-jp/sql/connect/jdbc/setting-the-connection-properties?view=sql-server-ver16
また、PaperCut社も参考記事(英語) を掲載しています。
【Using Windows Authentication with Microsoft SQL Server】
https://www.papercut.com/kb/Main/SQLServerWindowsAuthentication/
● データベース接続文字列パラメータの注意事項
・ encrypt=false
「encrypt」のデフォルト値は、ドライバのバージョン10.2以降では「true」、バージョン9.4以前は「false」です。
この記事では、同等の構成のバージョン7から12への移行について説明しています。
現在の(古い)動作を保持するためには「false」を設定する必要があります。
しかし、すでに暗号化を有効化するように設定している場合、
あるいは将来的に有効化する場合は変更することができます。
(注記) SQLサーバが暗号化するように構成されている場合、この設定に関係なく暗号化されます。
・ trustServerCertificate=true
デフォルト値「false」はTLS/SSL証明書の検証が強制されます。
これはSQL Serveで使用される既定の自己署名証明書では実行できないため選択されています。
これはデフォルト設定と同等の移行であるため、「true」は証明書を検証しないことを意味します。
組織が信頼された証明書を使用して暗号化を構成する場合、これを変更することができます。
(注記) 自己署名証明書を信頼したくない場合、データベース技術者と協力してCA署名証明書を設定してください。
・ integratedSecurity=true
Microsoft SQL ServerでWindows認証を使用している場合、古い文字列でも「true」に設定されているはずです。
・ その他のパラメータ
「sendStringParametersAsUnicode」の詳細は別紙「外部データベース設定ガイド (RDBMS)」を参照してください。
5． サービス「PaperCut Application Server」の再起動とテスト
1． サービス「PaperCut Application Server」を再起動してください。
2． 接続が動作するかを検証してください：
a． PaperCut管理者画面にログインし正常に画面が表示されるかどうか
b． 「server.log」(<app-path>\server\logs\server.log)にエラーが記録されていないかどうか
● 認証が失敗した場合
・ SQLドライバのバージョンが正しいかを確認してください。
例えば「mssql-jdbc-12.x.x.jre11.jar」ドライバが
PaperCutインストールフォルダ「<app-path>\server\lib-ext\」にあるかどうかを確認してください。
(注記) その他のmssql-jdbcドライバである.jarファイルは、このフォルダから移動する必要があります。
・ 「<app-path>\server\lib\」に「mssql*.jar」ファイルがないことを確認してください。
・ 認証DLLのバージョンが正しいかを確認してください。
例えば「mssql-jdbc_auth-12.x.x.x64.dll」は「<app-path>\server\bin\win\lib64\」にあるかどうかを確認してください。
・ 接続文字列にタイプミスがないかを再度確認してください。
・ トラブルシューティングの結果、何らかの変更を実施した場合、
必ずサービス「PaperCut Application Server」を再起動してください。
また、サービス再起動後、必ず動作検証を実施してください。
0 件のコメント :
コメントを投稿
注: コメントを投稿できるのは、このブログのメンバーだけです。