# 画面設計書 141-ファイアウォールルール

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるSQL Serverファイアウォールルール管理機能の設計仕様を定義する。

### 本画面の処理概要

SQL ServerインスタンスへのネットワークアクセスをWindowsファイアウォールで管理するための機能群を提供する。SQL Serverのインストール後、クライアントからの接続を許可するためのファイアウォールルールを適切に構成することは、インフラストラクチャ管理における重要なタスクである。

**業務上の目的・背景**：SQL Serverをインストールした後、多くの場合Windowsファイアウォールによって外部からの接続がブロックされる。この機能を使用することで、SQL Serverエンジン（通常ポート1433）、SQL Server Browser（UDPポート1434）、専用管理者接続（DAC）、データベースミラーリング/可用性グループ（通常ポート5022）に対するファイアウォールルールを一元的に管理できる。手動でnetshコマンドやWindowsファイアウォールGUIを操作する代わりに、PowerShellスクリプトによる自動化が可能となり、複数サーバーへの一括適用やインフラストラクチャのコード化（IaC）を実現する。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから以下のコマンドを実行する。
- `Get-DbaFirewallRule` - 既存ルールの取得
- `New-DbaFirewallRule` - 新規ルールの作成
- `Remove-DbaFirewallRule` - 既存ルールの削除

**主要な操作・処理内容**：
1. ファイアウォールルールの取得（Get-DbaFirewallRule）：ターゲットコンピュータ上のSQL Server関連ファイアウォールルールを取得し、ポート番号、プロトコル、許可プログラムパスなどの詳細情報を返す
2. ファイアウォールルールの作成（New-DbaFirewallRule）：SQL Serverインスタンス用のファイアウォールルールを作成。プログラムベース（sqlservr.exe）またはポートベース（TCP/UDP）のルールタイプを選択可能
3. ファイアウォールルールの削除（Remove-DbaFirewallRule）：dbatools で作成されたSQL Server関連ファイアウォールルールを削除

**画面遷移**：CLIベースのため画面遷移は存在しない。パイプライン処理により Get-DbaFirewallRule の出力を Remove-DbaFirewallRule に渡すことが可能。

**権限による表示制御**：ファイアウォール操作にはターゲットコンピュータの管理者権限が必要。Credentialパラメータにより代替資格情報を指定可能。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 365 | Get-DbaFirewallRule | 主機能 | ファイアウォールルールの取得 |
| 370 | New-DbaFirewallRule | 主機能 | ファイアウォールルールの作成 |
| 371 | Remove-DbaFirewallRule | 主機能 | ファイアウォールルールの削除 |
| - | Get-DbaNetworkConfiguration | 補助機能 | ネットワーク設定情報の取得 |
| - | Get-DbaService | 補助機能 | SQL Serverサービス情報の取得 |

## 画面種別

コマンドラインインターフェース（CLI）/ PowerShell関数

## URL/ルーティング

```powershell
# ファイアウォールルールの取得
Get-DbaFirewallRule -SqlInstance <インスタンス名>

# ファイアウォールルールの作成
New-DbaFirewallRule -SqlInstance <インスタンス名>

# ファイアウォールルールの削除
Remove-DbaFirewallRule -SqlInstance <インスタンス名>
```

## 入出力項目

### Get-DbaFirewallRule パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス |
| Credential | PSCredential | No | 代替資格情報 |
| Type | string[] | No | Engine/Browser/DAC/DatabaseMirroring/AllInstance |
| EnableException | switch | No | 例外処理モードの有効化 |

### New-DbaFirewallRule パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス |
| Credential | PSCredential | No | 代替資格情報 |
| Type | string[] | No | Engine/Browser/DAC/DatabaseMirroring |
| RuleType | string | No | Program（デフォルト）またはPort |
| Configuration | hashtable | No | カスタムルール設定 |
| Force | switch | No | 既存ルールを強制的に再作成 |
| EnableException | switch | No | 例外処理モードの有効化 |

### Remove-DbaFirewallRule パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | Yes* | 対象SQL Serverインスタンス |
| Credential | PSCredential | No | 代替資格情報 |
| Type | string[] | No | Engine/Browser/DAC/DatabaseMirroring/AllInstance |
| InputObject | object[] | Yes* | Get-DbaFirewallRuleからのパイプライン入力 |
| EnableException | switch | No | 例外処理モードの有効化 |

## 表示項目

### Get-DbaFirewallRule 出力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | ホストコンピュータ名 |
| InstanceName | string | インスタンス名（Browserルールの場合はnull） |
| SqlInstance | string | 完全なインスタンス名 |
| DisplayName | string | ファイアウォールルールの表示名 |
| Type | string | ルールタイプ（Engine/Browser/DAC/DatabaseMirroring） |
| Protocol | string | プロトコル（TCP/UDP/Any） |
| LocalPort | string | ポート番号 |
| Program | string | 許可されているプログラムパス |

### New-DbaFirewallRule 出力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | ホストコンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全なインスタンス名 |
| DisplayName | string | ファイアウォールルールの表示名 |
| Type | string | ルールタイプ |
| Successful | boolean | 作成成功フラグ |
| Status | string | 操作結果のステータス |
| Protocol | string | プロトコル |
| LocalPort | string | ポート番号 |
| Program | string | 許可プログラムパス |

### Remove-DbaFirewallRule 出力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | ホストコンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全なインスタンス名 |
| DisplayName | string | ファイアウォールルールの表示名 |
| Type | string | ルールタイプ |
| IsRemoved | boolean | 削除成功フラグ |
| Status | string | 操作結果のステータス |

## イベント仕様

### 1-ファイアウォールルール取得

**Get-DbaFirewallRule 実行時**

1. SqlInstance パラメータからコンピュータ名を抽出
2. Invoke-Command2 を使用してリモートコンピュータで Get-NetFirewallRule を実行
3. グループ名 'SQL Server' のルールをフィルタリング
4. 各ルールに対してポートフィルター・アプリケーションフィルター情報を取得
5. ルール種別（Engine/Browser/DAC/DatabaseMirroring）を判別
6. PSCustomObject として結果を出力

### 2-ファイアウォールルール作成

**New-DbaFirewallRule 実行時**

1. SQL Serverインスタンスのネットワーク設定を Get-DbaNetworkConfiguration で取得
2. RuleType に基づき、Program または Port ベースのルール設定を構成
3. Get-DbaService でサービスのバイナリパスを取得（Programベースの場合）
4. DAC ルールの場合、エラーログからDACポート情報を取得
5. Invoke-Command2 を使用して New-NetFirewallRule を実行
6. 結果をPSCustomObjectとして出力

### 3-ファイアウォールルール削除

**Remove-DbaFirewallRule 実行時**

1. SqlInstance パラメータまたは InputObject からルール情報を取得
2. Get-DbaFirewallRule で削除対象ルールを特定
3. Invoke-Command2 を使用して Remove-NetFirewallRule を実行
4. 結果をPSCustomObjectとして出力

## データベース更新仕様

### 操作別データベース影響一覧

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| ファイアウォールルール取得 | なし | N/A | データベース操作なし |
| ファイアウォールルール作成 | なし | N/A | データベース操作なし |
| ファイアウォールルール削除 | なし | N/A | データベース操作なし |

本機能はWindowsファイアウォール（NetSecurity モジュール）に対する操作であり、SQL Serverデータベースへの直接的な更新は行わない。

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|---------|
| MSG001 | 成功 | "The rule was successfully created." | ルール作成成功時 |
| MSG002 | 警告 | "The desired rule already exists. Use -Force to remove and recreate the rule." | 既存ルールが存在する場合 |
| MSG003 | 成功 | "The rule was successfully removed." | ルール削除成功時 |
| MSG004 | エラー | "The module NetSecurity with the command Get-NetFirewallRule is missing..." | NetSecurityモジュールが存在しない場合 |
| MSG005 | 警告 | "Dynamic port is enabled" | 動的ポートが使用されている場合 |
| MSG006 | 情報 | "No information about the dedicated admin connection (DAC) found in ERRORLOG" | DAC情報がエラーログにない場合 |

## 例外処理

| 例外条件 | 対応処理 |
|---------|---------|
| NetSecurityモジュールが存在しない | エラーメッセージを返し処理を中断 |
| リモート接続失敗 | Stop-Function でエラーを記録し次のインスタンスへ継続 |
| ファイアウォールルール作成失敗 | Status プロパティにエラー情報を格納して返却 |
| 管理者権限不足 | 例外をキャッチし、適切なエラーメッセージを返却 |
| SQL Serverサービス情報取得失敗 | ポートベースルールへフォールバック |

## 備考

- 本機能はdbatools で作成された特定の命名規則に従うファイアウォールルールのみを管理対象とする
- 将来のバージョンで破壊的変更が発生する可能性がある（ソースコード内の注記による）
- RuleType: Program はSQL Server実行ファイルをターゲットとし、ポート変更時もルール更新不要
- RuleType: Port は従来のポートベースルールで、ポート変更時はルール更新が必要

---

## コードリーディングガイド

本画面を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

各コマンドが返すPSCustomObjectの構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaFirewallRule.ps1 | `public/Get-DbaFirewallRule.ps1` | 235-247行目: 出力オブジェクトの構造定義 |
| 1-2 | New-DbaFirewallRule.ps1 | `public/New-DbaFirewallRule.ps1` | 530-544行目: 出力オブジェクトの構造定義 |
| 1-3 | Remove-DbaFirewallRule.ps1 | `public/Remove-DbaFirewallRule.ps1` | 178-186行目: 出力オブジェクトの構造定義 |

**読解のコツ**: PowerShellの[PSCustomObject]@{}構文でオブジェクトを構築している。Select-DefaultViewで表示プロパティを制御。

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaFirewallRule.ps1 | `public/Get-DbaFirewallRule.ps1` | 177-202行目: process ブロック - メイン処理ループ |
| 2-2 | New-DbaFirewallRule.ps1 | `public/New-DbaFirewallRule.ps1` | 266-547行目: process ブロック - ルール作成ロジック |
| 2-3 | Remove-DbaFirewallRule.ps1 | `public/Remove-DbaFirewallRule.ps1` | 140-189行目: process ブロック - ルール削除ロジック |

**主要処理フロー（Get-DbaFirewallRule）**:
1. **177行目**: foreach ($instance in $SqlInstance) でインスタンスをループ
2. **182行目**: Invoke-Command2 でリモートスクリプトブロックを実行
3. **205-248行目**: 取得したルール情報に型情報を追加
4. **250-285行目**: Type パラメータに基づきフィルタリング

#### Step 3: リモート実行スクリプトブロックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaFirewallRule.ps1 | `public/Get-DbaFirewallRule.ps1` | 116-174行目: cmdScriptBlock - リモート実行コード |
| 3-2 | New-DbaFirewallRule.ps1 | `public/New-DbaFirewallRule.ps1` | 221-263行目: cmdScriptBlock - ルール作成実行コード |

**主要処理フロー（リモートスクリプトブロック）**:
- **119-121行目**: NetSecurityモジュールの存在確認
- **124行目**: Get-NetFirewallRule でグループ 'SQL Server' のルールを取得
- **145-154行目**: 各ルールの詳細情報を取得

#### Step 4: ルールタイプ判別ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaFirewallRule.ps1 | `public/Get-DbaFirewallRule.ps1` | 206-234行目: ルール名からタイプ・インスタンス名を判別 |
| 4-2 | New-DbaFirewallRule.ps1 | `public/New-DbaFirewallRule.ps1` | 277-358行目: Engine ルール構成 |
| 4-3 | New-DbaFirewallRule.ps1 | `public/New-DbaFirewallRule.ps1` | 361-403行目: Browser ルール構成 |
| 4-4 | New-DbaFirewallRule.ps1 | `public/New-DbaFirewallRule.ps1` | 405-457行目: DAC ルール構成 |
| 4-5 | New-DbaFirewallRule.ps1 | `public/New-DbaFirewallRule.ps1` | 459-486行目: DatabaseMirroring ルール構成 |

### プログラム呼び出し階層図

```
Get-DbaFirewallRule
    │
    ├─ Invoke-Command2 (リモート実行)
    │      └─ Get-NetFirewallRule -Group 'SQL Server'
    │              ├─ Get-NetFirewallPortFilter
    │              └─ Get-NetFirewallApplicationFilter
    │
    └─ Select-DefaultView (出力フォーマット)

New-DbaFirewallRule
    │
    ├─ Get-DbaNetworkConfiguration (TCP/IP設定取得)
    ├─ Get-DbaService (サービスパス取得)
    ├─ Get-DbaStartupParameter (DAC情報取得)
    │
    └─ Invoke-Command2 (リモート実行)
           └─ New-NetFirewallRule

Remove-DbaFirewallRule
    │
    ├─ Get-DbaFirewallRule (削除対象特定)
    │
    └─ Invoke-Command2 (リモート実行)
           └─ Remove-NetFirewallRule
```

### データフロー図

```
[入力]                      [処理]                         [出力]

SqlInstance ───────▶ Invoke-Command2 ───────▶ PSCustomObject
                         │                        │
                         ▼                        ├─ ComputerName
              Get-NetFirewallRule                 ├─ InstanceName
                         │                        ├─ SqlInstance
                         ▼                        ├─ DisplayName
              PortFilter / AppFilter              ├─ Type
                         │                        ├─ Protocol
                         ▼                        ├─ LocalPort
               ルールタイプ判別                   └─ Program
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaFirewallRule.ps1 | `public/Get-DbaFirewallRule.ps1` | ソース | ファイアウォールルール取得 |
| New-DbaFirewallRule.ps1 | `public/New-DbaFirewallRule.ps1` | ソース | ファイアウォールルール作成 |
| Remove-DbaFirewallRule.ps1 | `public/Remove-DbaFirewallRule.ps1` | ソース | ファイアウォールルール削除 |
| Invoke-Command2.ps1 | `internal/functions/Invoke-Command2.ps1` | ソース | リモート実行ヘルパー関数 |
| Get-DbaNetworkConfiguration.ps1 | `public/Get-DbaNetworkConfiguration.ps1` | ソース | ネットワーク設定取得 |
| Get-DbaService.ps1 | `public/Get-DbaService.ps1` | ソース | SQL Serverサービス情報取得 |
| Get-DbaStartupParameter.ps1 | `public/Get-DbaStartupParameter.ps1` | ソース | 起動パラメータ取得 |
