EOL Wallarm NGINXモジュールの更新

[wallarm-status-instr]:             ../../admin-en/configure-statistics-service.md
[ptrav-attack-docs]:                ../../attacks-vulns-list.md#path-traversal
[attacks-in-ui-image]:              ../../images/admin-guides/test-attacks-quickstart.png
[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
[configure-selinux-instr]:          ../../admin-en/configure-selinux.md
[configure-proxy-balancer-instr]:   ../../admin-en/configuration-guides/access-to-wallarm-api-via-proxy.md
[install-postanalytics-instr]:      ../../admin-en/installation-postanalytics-en.md
[dynamic-dns-resolution-nginx]:     ../../admin-en/configure-dynamic-dns-resolution-nginx.md
[img-wl-console-users]:             ../../images/check-users.png 
[img-create-wallarm-node]:      ../../images/user-guides/nodes/create-cloud-node.png
[nginx-custom]:                 ../../installation/custom/custom-nginx-version.md
[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
[wallarm-token-types]:              ../../user-guides/nodes/nodes.md#api-and-node-tokens-for-node-creation
[sqli-attack-docs]:                 ../../attacks-vulns-list.md#sql-injection
[xss-attack-docs]:                  ../../attacks-vulns-list.md#crosssite-scripting-xss
[web-server-mirroring-examples]:    ../../installation/oob/web-server-mirroring/overview.md#configuration-examples-for-traffic-mirroring
[ip-lists-docs]:                     ../../user-guides/ip-lists/overview.md

# EOL Wallarm NGINXモジュールのアップグレード

本書の手順は、廃止されたWallarm NGINXモジュール（バージョン3.6以下）をバージョン5.0にアップグレードする方法を説明します。Wallarm NGINXモジュールは、以下のいずれかの手順に従ってインストールしたモジュールです：

* NGINX stable向けの個別パッケージ
* NGINX Plus向けの個別パッケージ
* ディストリビューション提供のNGINX向けの個別パッケージ

!!! 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.

!!! info "all-in-oneインストーラを使用したアップグレード"
    個別のLinuxパッケージは廃止されたため、Wallarmの[all-in-oneインストーラ](../../installation/nginx/all-in-one.md)を使用してアップグレードを実施します。この方法は、以前の方法と比較してアップグレード作業および継続的な展開メンテナンスを簡素化します。

    インストーラは自動的に以下の処理を実行します：

    1. OSとNGINXバージョンの確認。
    1. 検出されたOSとNGINXバージョンに対してWallarmリポジトリを追加。
    1. これらのリポジトリからWallarmパッケージのインストール。
    1. インストールされたWallarmモジュールをNGINXに接続。
    1. 提供されたトークンを使用してフィルタリングノードをWallarm Cloudに接続。

        個別のLinuxパッケージによる手動アップグレードはこれ以上サポートされません。

    ![All-in-one compared to manual](../../images/installation-nginx-overview/manual-vs-all-in-one.png)

## EOLノードをアップグレードする旨をWallarmテクニカルサポートへ連絡

もし廃止されたWallarm NGINXモジュール（バージョン3.6以下）をバージョン5.0にアップグレードする場合は、その旨を[Wallarmテクニカルサポート](mailto:support@wallarm.com)に連絡し、支援を依頼してください。

その他の支援と合わせて、Wallarmアカウントに対して新しいIPリストロジックの有効化も依頼してください。新しいIPリストロジックが有効化された場合、Wallarm Consoleを開き、[**IP lists**](../../user-guides/ip-lists/overview.md)セクションが表示されることを確認してください。

## 必要要件

* Access to the account with the **Administrator** role in Wallarm Console for the [US Cloud](https://us1.my.wallarm.com/) or [EU Cloud](https://my.wallarm.com/).
* Access to `https://meganode.wallarm.com` to download all-in-one Wallarm installer. Ensure the access is not blocked by a firewall.
* Access to `https://us1.api.wallarm.com` for working with US Wallarm Cloud or to `https://api.wallarm.com` for working with EU Wallarm Cloud. If access can be configured only via the proxy server, then use the [instructions][configure-proxy-balancer-instr].
* Executing all commands as a superuser (e.g. `root`).
* Access to the IP addresses below for downloading updates to attack detection rules and API specifications, as well as retrieving precise IPs for your allowlisted, denylisted, or graylisted 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
        ```

## アップグレード手順

* フィルタリングノードとpostanalyticsモジュールが同一サーバーにインストールされている場合は、以下の手順に従って全てをアップグレードしてください。

    クリーンなマシンでall-in-oneインストーラを使用して新しいバージョンのノードを実行し、正常に動作することを確認後、以前のノードを停止し、トラフィックを以前のノードの代わりに新しいマシンへ流れるように設定する必要があります。

* フィルタリングノードとpostanalyticsモジュールが別々のサーバーにインストールされている場合は、**最初**にpostanalyticsモジュールをアップグレードし、**次に**これら[手順](separate-postanalytics.md)に従ってフィルタリングモジュールをアップグレードしてください。

## ステップ1：Threat Replay Testingモジュールの無効化（ノード2.16以下のアップグレードの場合）

Wallarmノード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)が発生する可能性があるため、モジュールを無効化することでリスクを最小限に抑えます。

## ステップ2：クリーンなマシンの準備

When upgrading modules with all-in-one installer, you cannot upgrade an old package installation - instead you need to use a clean machine. Thus, as step 1, prepare a machine with one of the supported OS:

* Debian 10, 11 and 12.x
* Ubuntu LTS 18.04, 20.04, 22.04
* CentOS 7, 8 Stream, 9 Stream
* Alma/Rocky Linux 9
* RHEL 8.x
* RHEL 9.x
* Oracle Linux 8.x
* Oracle Linux 9.x
* Redox
* SuSe Linux
* Others (the list is constantly widening, contact [Wallarm support team](mailto:support@wallarm.com) to check if your OS is in the list)

Using new clean machine will lead to that at some moment you will have both old and new node, which is good: you can test the new one working properly without stopping the old one.

## ステップ3：NGINXと依存関係のインストール

Install the latest NGINX version of:

* **NGINX `stable`** (the latest supported version is v1.28.0) - see how to install it in the NGINX [documentation](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-open-source/).
* **NGINX Mainline** (the latest supported version is v1.27.5) - see how to install it in the NGINX [documentation](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-open-source/).
* **NGINX Plus** (the latest supported version is NGINX Plus R33) - see how to install it in the NGINX [documentation](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/).
* **Distribution-Provided NGINX** - to install, use the following commands:

    === "Debian"
        ```bash
        sudo apt update 
        sudo apt -y install --no-install-recommends nginx
        ```
    === "Ubuntu"
        ```bash
        sudo apt-get update
        sudo apt-get install nginx
        ```
    === "CentOS"
        ```bash
        sudo yum -y update 
        sudo yum install -y nginx
        ```
    === "AlmaLinux, Rocky Linux or Oracle Linux 8.x"
        ```bash
        sudo yum -y update 
        sudo yum install -y nginx
        ```
    === "RHEL 8.x"
        ```bash
        sudo yum -y update 
        sudo yum install -y nginx
        ```

## ステップ4：Wallarmトークンの準備

To install node, you will need a Wallarm token of the [appropriate type][wallarm-token-types]. To prepare a token:

=== "API token"

    1. Open Wallarm Console → **Settings** → **API tokens** in the [US Cloud](https://us1.my.wallarm.com/settings/api-tokens) or [EU Cloud](https://my.wallarm.com/settings/api-tokens).
    1. Find or create API token with the `Node deployment/Deployment` usage type.
    1. Copy this token.

=== "Node token"

    1. Open Wallarm Console → **Nodes** in the [US Cloud](https://us1.my.wallarm.com/nodes) or [EU Cloud](https://my.wallarm.com/nodes).
    1. Do one of the following: 
        * Create the node of the **Wallarm node** type and copy the generated token.
        * Use existing node group - copy token using node's menu → **Copy token**.

## ステップ5：all-in-one Wallarmインストーラのダウンロード

Wallarm suggests all-in-one installations for the following processors:

* x86_64
* ARM64 (beta)

To download all-in-one Wallarm installation script, execute the command:

=== "x86_64 version"
    ```bash
    curl -O https://meganode.wallarm.com/6.1/wallarm-6.1.0.x86_64-glibc.sh
    ```
=== "ARM64 version (beta)"
    ```bash
    curl -O https://meganode.wallarm.com/6.1/wallarm-6.1.0.aarch64-glibc.sh
    ```

## ステップ6：all-in-one Wallarmインストーラの実行

### フィルタリングノードとpostanalyticsが同一サーバーの場合

1. Run downloaded script:

    === "API token"
        ```bash
        # If using the x86_64 version:
        sudo env WALLARM_LABELS='group=<GROUP>' sh wallarm-6.1.0.x86_64-glibc.sh

        # If using the ARM64 version:
        sudo env WALLARM_LABELS='group=<GROUP>' sh wallarm-6.1.0.aarch64-glibc.sh
        ```        

        The `WALLARM_LABELS` variable sets group into which the node will be added (used for logical grouping of nodes in the Wallarm Console UI).

    === "Node token"
        ```bash
        # If using the x86_64 version:
        sudo sh wallarm-6.1.0.x86_64-glibc.sh

        # If using the ARM64 version:
        sudo sh wallarm-6.1.0.aarch64-glibc.sh
        ```

1. Select [US Cloud](https://us1.my.wallarm.com/) or [EU Cloud](https://my.wallarm.com/).
1. Enter Wallarm token.

### フィルタリングノードとpostanalyticsが別々のサーバーの場合

!!! warning "フィルタリングノードとpostanalyticsモジュールのアップグレード手順の順序"
    フィルタリングノードとpostanalyticsモジュールが別々のサーバーにインストールされている場合、フィルタリングノードパッケージを更新する前にpostanalyticsパッケージをアップグレードする必要があります。

1. これら[手順](separate-postanalytics.md)に従ってpostanalyticsモジュールをアップグレードしてください。
1. フィルタリングノードをアップグレードしてください：

    === "APIトークン"
        ```bash
        # x86_64版を使用している場合:
        sudo env WALLARM_LABELS='group=<GROUP>' sh wallarm-5.3.0.x86_64-glibc.sh filtering

        # ARM64版を使用している場合:
        sudo env WALLARM_LABELS='group=<GROUP>' sh wallarm-5.3.0.aarch64-glibc.sh filtering
        ```        

        `WALLARM_LABELS`変数は、ノードを追加するグループを設定します（Wallarm Console上でのノードの論理グループ化に使用されます）。

    === "ノードトークン"
        ```bash
        # x86_64版を使用している場合:
        sudo sh wallarm-5.3.0.x86_64-glibc.sh filtering

        # ARM64版を使用している場合:
        sudo sh wallarm-5.3.0.aarch64-glibc.sh filtering
        ```

## ステップ7：以前のWallarmノードバージョンから5.0へのallowlistおよびdenylistの移行（ノード2.18以下のアップグレードのみ）

ノード2.18以下をアップグレードする場合、[migrate](../migrate-ip-lists-to-node-3.md)を参照して以前のWallarmノードバージョンから新しいバージョンへのallowlistおよびdenylistの設定を移行してください。

## ステップ8：古いノードマシンから新しいノードマシンへNGINXおよびpostanalyticsの設定を転送

古いマシン上の設定ファイルからノード関連のNGINX設定およびpostanalytics設定を新しいマシンのファイルへ転送してください。必要なディレクティブをコピーすることで実施できます。

**ソースファイル**

古いマシンでは、OSおよびNGINXバージョンに応じてNGINX設定ファイルの配置ディレクトリや名称が異なる場合があります。主に以下のものです：

* `/etc/nginx/conf.d/default.conf`：NGINXの設定
* `/etc/nginx/conf.d/wallarm-status.conf`：Wallarmノードの監視設定。詳細は[こちら][wallarm-status-instr]を参照してください。

また、postanalyticsモジュール（Tarantoolデータベース設定）の設定は通常以下に配置されています：

* `/etc/default/wallarm-tarantool`または
* `/etc/sysconfig/wallarm-tarantool`

**ターゲットファイル**

all-in-oneインストーラはOSとNGINXバージョンの組み合わせにより動作するため、新しいマシンの[ターゲットファイル](https://docs.nginx.com/nginx/admin-guide/basic-functionality/managing-configuration-files/)は名称や配置ディレクトリが異なる場合があります。

設定を転送する際、以下の手順を実施してください。

### 非推奨のNGINXディレクティブの名称変更

設定ファイルに明示的に指定されている場合、以下のNGINXディレクティブの名称を変更してください：

* `wallarm_instance` → [`wallarm_application`](../../admin-en/configure-parameters-en.md#wallarm_application)
* `wallarm_local_trainingset_path` → [`wallarm_custom_ruleset_path`](../../admin-en/configure-parameters-en.md#wallarm_custom_ruleset_path)
* `wallarm_global_trainingset_path` → [`wallarm_protondb_path`](../../admin-en/configure-parameters-en.md#wallarm_protondb_path)
* `wallarm_ts_request_memory_limit` → [`wallarm_general_ruleset_memory_limit`](../../admin-en/configure-parameters-en.md#wallarm_general_ruleset_memory_limit)

ディレクティブの名称のみを変更しており、ロジックは同一です。旧名称のディレクティブは近く非推奨となるため、事前に名称変更を推奨します。

### ノードのログ変数の更新

新しいノードバージョンでは、以下の[ノードログ変数](../../admin-en/configure-logging.md#filter-node-variables)の変更が実装されています：

* `wallarm_request_time`変数が`wallarm_request_cpu_time`に名称変更されました。

    変数名のみを変更しており、ロジックは同一です。旧名称も一時的にサポートされていますが、名称変更を推奨します。
* `wallarm_request_mono_time`変数が追加されました – 以下の合計値（
    * キュー内の時間
    * リクエスト処理においてCPUが費やした秒数
  ）のログ情報が必要な場合、ログ形式の設定に追加してください。

### 最新バージョンで変更されたWallarmノードのフィルトレーションモード設定の調整

1. 以下に記載される設定の期待動作が[フィルトレーションモード `off` と `monitoring` の変更されたロジック](what-is-new.md#filtration-modes)に対応していることを確認してください：
      * [ディレクティブ `wallarm_mode`](../../admin-en/configure-parameters-en.md#wallarm_mode)
      * [Wallarm Consoleで設定される全般的なフィルトレーションルール](../../admin-en/configure-wallarm-mode.md#general-filtration-rule-in-wallarm-console)
      * [Wallarm Consoleで設定されるエンドポイント対象のフィルトレーションルール](../../admin-en/configure-wallarm-mode.md#endpoint-targeted-filtration-rules-in-wallarm-console)
2. 期待される動作が変更後のフィルトレーションモードのロジックと一致しない場合は、[手順](../../admin-en/configure-wallarm-mode.md)に従ってフィルトレーションモードの設定を調整してください。

### `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 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 directives, it is recommended to transfer them to the rule as follows:

1. Open Wallarm Console → **Rules** and proceed to the [**Limit request processing time**][overlimit-res-rule-docs] rule setup.
1. Configure the rule as done via the NGINX directives:

    * The rule condition should match the NGINX configuration block with the `wallarm_process_time_limit` and `wallarm_process_time_limit_block` directives specified.
    * The time limit for the node to process a single request (milliseconds): the value of `wallarm_process_time_limit`.

        !!! warning "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.
1. Delete the `wallarm_process_time_limit` and `wallarm_process_time_limit_block` NGINX directives from the NGINX configuration file.

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

### `wallarm-status.conf`ファイルの内容の更新

`/etc/nginx/conf.d/wallarm-status.conf`の内容を以下の通り更新してください：