EOL Docker NGINX-またはEnvoy-basedイメージの更新

[waf-mode-instr]:                   ../../admin-en/configure-wallarm-mode.md
[blocking-page-instr]:              ../../admin-en/configuration-guides/configure-block-page-and-code.md
[logging-instr]:                    ../../admin-en/configure-logging.md
[proxy-balancer-instr]:             ../../admin-en/using-proxy-or-balancer-en.md
[process-time-limit-instr]:         ../../admin-en/configure-parameters-en.md#wallarm_process_time_limit
[allocating-memory-guide]:          ../../admin-en/configuration-guides/allocate-resources-for-node.md
[ptrav-attack-docs]:                ../../attacks-vulns-list.md#path-traversal
[attacks-in-ui-image]:           ../../images/admin-guides/test-attacks-quickstart.png
[nginx-process-time-limit-docs]:    ../../admin-en/configure-parameters-en.md#wallarm_process_time_limit
[nginx-process-time-limit-block-docs]:  ../../admin-en/configure-parameters-en.md#wallarm_process_time_limit_block
[overlimit-res-rule-docs]:           ../../user-guides/rules/configure-overlimit-res-detection.md
[graylist-docs]:                     ../../user-guides/ip-lists/overview.md
[waf-mode-instr]:                   ../../admin-en/configure-wallarm-mode.md
[envoy-process-time-limit-docs]:    ../../admin-en/configuration-guides/envoy/fine-tuning.md#process_time_limit
[envoy-process-time-limit-block-docs]: ../../admin-en/configuration-guides/envoy/fine-tuning.md#process_time_limit_block
[ip-lists-docs]:                    ../../user-guides/ip-lists/overview.md
[api-policy-enf-docs]:              ../../api-specification-enforcement/overview.md

# 終了サポートのDocker NGINXベースイメージのアップグレード

本手順では、稼働中の終了サポートとなったDocker NGINXベースイメージ（バージョン3.6以下）をバージョン5.0にアップグレードするための手順を説明します。

!!! warning "Wallarm nodes 3.6 and lower are not supported"
    You are recommended to upgrade the Wallarm nodes 3.6 and lower since these versions are [not supported, they are end-of-life](../versioning-policy.md#version-list).

    Node configuration and traffic filtration have been significantly simplified in the Wallarm node of the latest versions. Before upgrading the modules, please carefully review the [list of changes](what-is-new.md) and [general recommendations](../general-recommendations.md). Please note that some settings of the latest node are **incompatible** with the nodes 3.6 and lower.

## 要件

* [Docker](https://docs.docker.com/engine/install/) installed on your host system
* Access to `https://hub.docker.com/r/wallarm/node` to download the Docker image. Please ensure the access is not blocked by a firewall
* Access to the account with the **Administrator** role in Wallarm Console in the [US Cloud](https://us1.my.wallarm.com/) or [EU Cloud](https://my.wallarm.com/) 
* Access to `https://us1.api.wallarm.com` if working with US Wallarm Cloud or to `https://api.wallarm.com` if working with EU Wallarm Cloud. Please ensure the access is not blocked by a firewall
* Access to the IP addresses below for downloading updates to attack detection rules and [API specifications][api-policy-enf-docs], as well as retrieving precise IPs for your [allowlisted, denylisted, or graylisted][ip-lists-docs] countries, regions, or data centers

    === "US Cloud"
        ```
        34.96.64.17
        34.110.183.149
        35.235.66.155
        34.102.90.100
        34.94.156.115
        35.235.115.105
        ```
    === "EU Cloud"
        ```
        34.160.38.183
        34.144.227.90
        34.90.110.226
        ```

## ステップ1: フィルタリングノードモジュールのアップグレードについてWallarm技術サポートに連絡する（ノード2.18以下の場合のみ）

ノード2.18以下をアップグレードする場合、[Wallarm技術サポート](mailto:support@wallarm.com)に対して、フィルタリングノードモジュールをバージョン5.0までアップグレードする旨と、Wallarmアカウントに新しいIPリストロジックを有効にするよう依頼してください。新しいIPリストロジックが有効になった場合、Wallarm Consoleの[**IP lists**](../../user-guides/ip-lists/overview.md)セクションが利用可能であることを確認してください。

## ステップ2: Threat Replay Testingモジュールの無効化（ノード2.16以下の場合のみ）

ノード2.16以下をアップグレードする場合、Wallarm Console → **Vulnerabilities** → **Configure**にて[Threat Replay Testing](../../about-wallarm/detecting-vulnerabilities.md#threat-replay-testing)モジュールを無効化してください。

モジュールの動作により、アップグレードプロセス中に[false positives](../../about-wallarm/protecting-against-attacks.md#false-positives)が発生する可能性があります。モジュールを無効化することで、このリスクを最小限に抑えます。

## ステップ3: APIポートの更新

Starting with version 4.0, the filtering node uploads data to the Cloud using the `us1.api.wallarm.com:443` (US Cloud) and `api.wallarm.com:443` (EU Cloud) API endpoints instead of `us1.api.wallarm.com:444` and `api.wallarm.com:444`.

If you upgrade the node from the version 3.x or lower and your server with the deployed node has a limited access to the external resources and the access is granted to each resource separately, then after upgrade the synchronization between the filtering node and the Cloud will stop.

To restore the synchronization, in your configuration, change port `444` to `443` for API endpoint for each resource.

## ステップ4: 更新されたフィルタリングノードイメージのダウンロード

``` bash
docker pull wallarm/node:5.3.0

ステップ5: Wallarm Cloudへのトークンベース接続へ切り替える¶

コンテナをWallarm Cloudに接続する手法が以下のようにアップグレードされました。

「email and password」ベースの手法は廃止されました。従来、この手法では、DEPLOY_USERおよびDEPLOY_PASSWORD変数に正しい認証情報を渡すことでコンテナ起動時に自動的にWallarm Cloudへノードが登録されました。
トークンベースの手法が導入されました。コンテナをCloudに接続するには、Wallarm Console UIからコピーしたWallarm APIトークンを含むWALLARM_API_TOKEN変数を使用してコンテナを起動してください。

イメージ5.0の実行には新しい手法の使用を推奨します。「email and password」ベースの手法は今後のリリースで削除されるため、早めに移行してください。

新しいWallarmノードの作成とトークンの取得方法:

Wallarm Console → Settings → API Tokensを開き、Deployロールを持つトークンを生成します。
生成されたトークンをコピーします。

ステップ6: 以前のWallarmノードバージョンからのallowlistおよびdenylistの移行（ノード2.18以下の場合のみ）¶

ノード2.18以下をアップグレードする場合、以前のWallarmノードバージョンからのallowlistおよびdenylistの設定をバージョン5.0へ移行してください。

ステップ7: 非推奨の設定オプションからの切り替え¶

以下の非推奨の設定オプションがあります:

WALLARM_ACL_ENABLE環境変数は非推奨です。IPリストが新しいノードバージョンに移行された場合、この変数をdocker runコマンドから削除してください。
以下のNGINXディレクティブが名称変更されました:
- wallarm_instance → wallarm_application
- wallarm_local_trainingset_path → wallarm_custom_ruleset_path
- wallarm_global_trainingset_path → wallarm_protondb_path
- wallarm_ts_request_memory_limit → wallarm_general_ruleset_memory_limit
ディレクティブの名称のみ変更され、ロジックは同一です。旧名称のディレクティブはまもなく非推奨となりますので、早めに名称を変更することを推奨します。

マウントされた設定ファイルに旧名称のディレクティブが明示的に指定されている場合、名称を変更してください。
wallarm_request_timeというログ変数がwallarm_request_cpu_timeに変更されました。

変数名のみ変更され、ロジックは同一です。旧名称は一時的にサポートされていますが、名称変更を推奨します。

ステップ8: Wallarmブロッキングページの更新（NGINXベースイメージの場合）¶

新しいノードバージョンでは、Wallarmのサンプルブロッキングページが変更されました。ページ上のロゴおよびサポートメールアドレスはデフォルトで空になっています。

Dockerコンテナがブロックされたリクエストに対して&/usr/share/nginx/html/wallarm_blocked.htmlページを返すように設定されている場合、以下の手順で設定を変更してください:

新しいサンプルページのコピーとカスタマイズを行います。
カスタマイズしたページおよびNGINX設定ファイルを、新しいDockerコンテナにマウントしてください。

ステップ9: 最近のアーキテクチャ変更の確認（NGINXベースのDockerイメージの場合）¶

最新のアップデートにより、特定のファイルのパス変更に起因して、特にコンテナ起動時にカスタム設定ファイルをマウントしているユーザーに影響を及ぼすアーキテクチャの変更が導入されました。新しいイメージの正しい設定および使用方法を確保するため、これらの変更点に精通してください。

ステップ10: `overlimit_res`攻撃検出設定をディレクティブからルールへ移行する¶

Starting from the version 3.6, you can fine-tune the overlimit_res attack detection using the rule in Wallarm Console.

Earlier, the [wallarm_process_time_limit][nginx-process-time-limit-docs] and [wallarm_process_time_limit_block][nginx-process-time-limit-block-docs] NGINX directives have been used.

The listed directives and parameters are considered to be deprecated with the new rule release and will be deleted in future releases.

If the overlimit_res attack detection settings are customized via the listed parameters, it is recommended to transfer them to the rule as follows:

Open Wallarm Console → Rules and proceed to the [Limit request processing time][overlimit-res-rule-docs] rule setup.
Configure the rule as done in the mounted configuration files:
- The time limit for the node to process a single request (milliseconds): the value of wallarm_process_time_limit or process_time_limit.
  
  Risk of running out of system memory
  
  The high time limit and/or continuation of request processing after the limit is exceeded can trigger memory exhaustion or out-of-time request processing.
- The node will either block or pass the overlimit_res attack depending on the [node filtration mode][waf-mode-instr]:
  - In the monitoring mode, the node forwards the original request to the application address. The application has the risk to be exploited by the attacks included in both processed and unprocessed request parts.
  - In the safe blocking mode, the node blocks the request if it is originated from the [graylisted][graylist-docs] IP address. Otherwise, the node forwards the original request to the application address. The application has the risk to be exploited by the attacks included in both processed and unprocessed request parts.
  - In the block mode, the node blocks the request.
Delete the wallarm_process_time_limit, wallarm_process_time_limit_block NGINX directives from the mounted configuration file.

If the overlimit_res attack detection is fine-tuned using both the parameters and the rule, the node will process requests as the rule sets.

ステップ11: 稼働中のコンテナを停止する¶

docker stop <RUNNING_CONTAINER_NAME>

ステップ12: 更新されたイメージを使用してコンテナを起動する¶

必要に応じてマウントファイルのパスの調整を行い、更新されたイメージを使用してコンテナを起動してください。これは最新のイメージに関する変更に基づくものです。

更新されたイメージを使用してコンテナを起動する方法は2通りあります:

ステップ13: 最新バージョンでリリースされた変更に合わせてWallarmノードのフィルトレーションモード設定を調整する（ノード2.18以下の場合のみ）¶

以下の設定項目について、期待される動作がoffおよびmonitoringフィルトレーションモードの変更されたロジックに対応していることを確認してください:
- Dockerコンテナの環境変数WALLARM_MODEまたはNGINXベースコンテナのディレクティブwallarm_mode
- Wallarm Consoleにて設定された一般的なフィルトレーションルール
- Wallarm Consoleにて設定されたエンドポイント対象フィルトレーションルール
期待される動作と変更後のフィルトレーションモードのロジックが一致しない場合、手順に従いフィルトレーションモード設定を調整してください。

ステップ14: フィルタリングノードの動作をテストする¶

Send the request with the test [Path Traversal][ptrav-attack-docs] attack to the application address:
```
curl http://localhost/etc/passwd
```
If traffic is configured to be proxied to example.com, include the -H "Host: example.com" header in the request.
Make sure the node of the new type processes the request in the same way as the regular node did, e.g.:
- Blocks the request if the appropriate [filtration mode][waf-mode-instr] is configured.
- Returns the [custom blocking page][blocking-page-instr] if it is configured.
Open Wallarm Console → Attacks in the EU Cloud or US Cloud and make sure that:
- The attack is displayed in the list.
- Hit details display the Wallarm node UUID.
![Attacks in the interface][attacks-in-ui-image]

ステップ15: 以前バージョンのフィルタリングノードを削除する¶

イメージ5.0が正しく動作していることを確認したら、Wallarm Console → Nodesセクションにて以前のフィルタリングノードを削除してください。

ステップ16: Threat Replay Testingモジュールの再有効化（ノード2.16以下の場合のみ）¶

Threat Replay Testingモジュールの設定に関する推奨事項を確認し、必要に応じて再度有効化してください。

しばらく運用し、モジュールの動作がfalse positivesを引き起こさないことを確認してください。false positivesが発生した場合は、Wallarm技術サポートへご連絡ください。
```