# 機能設計書 370-New-DbaFirewallRule

## 概要

本ドキュメントは、SQL Server向けWindowsファイアウォールルールを作成するための dbatools コマンド `New-DbaFirewallRule` の機能設計を記述する。

### 本機能の処理概要

`New-DbaFirewallRule` は、SQL Serverインスタンス、Browserサービス、DAC（専用管理者接続）、データベースミラーリング/可用性グループ用のWindowsファイアウォールルールを自動作成するコマンドである。

**業務上の目的・背景**：SQL Serverインストール後のファイアウォール設定は手動で行う必要があり、ポート番号の特定やルール作成は煩雑な作業である。特に名前付きインスタンスや動的ポートを使用している場合、適切なファイアウォールルールの設定は困難である。本コマンドは、この設定作業を自動化し、ネットワーク接続性の迅速な確立を可能にする。

**機能の利用シーン**：
- 新規SQL Serverインストール後のファイアウォール設定
- 既存ファイアウォールルールの更新・再作成
- 複数インスタンスへの一括ファイアウォール設定
- データベースミラーリング/可用性グループのポート開放

**主要な処理内容**：
1. Engineルール作成:
   - Get-DbaNetworkConfigurationでTCP/IPアドレス設定取得
   - Program方式: sqlservr.exeパスを取得してプログラムベースルール作成
   - Port方式: TCPポート番号を取得してポートベースルール作成
2. Browserルール作成:
   - Program方式: sqlbrowser.exeパスでルール作成
   - Port方式: UDP 1434でルール作成
3. DACルール作成:
   - ERRORLOGからDACポート取得
   - TCPポートベースルール作成
4. DatabaseMirroringルール作成:
   - デフォルトポート5022でTCPルール作成
5. New-NetFirewallRuleでルール作成実行

**関連システム・外部連携**：NetSecurity PowerShellモジュール（New-NetFirewallRule）、Get-DbaNetworkConfiguration、Get-DbaService、Get-DbaStartupParameter

**権限による制御**：ターゲットコンピュータの管理者権限が必要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLIツール | 主機能 | PowerShellコンソールから実行 |

## 機能種別

構成管理 / ファイアウォール設定

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | ターゲットSQL Serverインスタンス | パイプライン対応 |
| Credential | PSCredential | No | 接続資格情報 | - |
| Type | string[] | No | ルール種別（Engine/Browser/DAC/DatabaseMirroring） | ValidateSet |
| RuleType | string | No | ルール方式（Program/Port、デフォルト: Program） | ValidateSet |
| Configuration | hashtable | No | 追加ルール設定 | Name/DisplayName/Group除外 |
| Force | switch | No | 既存ルールを再作成 | - |
| EnableException | switch | No | 例外を有効化 | - |

### 入力データソース

- Get-DbaNetworkConfiguration: TCP/IP設定
- Get-DbaService: サービス実行パス
- Get-DbaStartupParameter: ERRORLOGパス
- ERRORLOG: DACポート情報

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | String | コンピュータ名 |
| InstanceName | String | SQL Serverインスタンス名 |
| SqlInstance | String | 完全インスタンス名 |
| DisplayName | String | ファイアウォールルール表示名 |
| Name | String | ファイアウォールルール名 |
| Type | String | ルール種別（Engine/Browser/DAC/DatabaseMirroring） |
| Protocol | String | プロトコル（TCP/UDP/Any） |
| LocalPort | String | ポート番号（Portベース時） |
| Program | String | プログラムパス（Programベース時） |
| Successful | Boolean | ルール作成成功 |
| Status | String | 状態メッセージ |

### 出力先

PowerShellパイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. Begin ブロック
   └─ Configuration から禁止キー（Name/DisplayName/Group）を除去
   └─ リモート実行用ScriptBlockの定義

2. Process ブロック - 各SqlInstanceに対して
   └─ Engineルール処理:
       └─ Get-DbaNetworkConfigurationでTCP/IP取得
       └─ RuleType判定:
           ├─ Program: Get-DbaServiceでsqlservr.exeパス取得
           └─ Port: TcpIpAddresses.TcpPort取得
       └─ ルール設定構築（DisplayName, Group, Protocol等）
   └─ Browserルール処理（名前付きインスタンスまたはType指定時）:
       └─ RuleType判定:
           ├─ Program: Get-DbaServiceでsqlbrowser.exeパス取得
           └─ Port: UDP 1434
   └─ DACルール処理（Type指定またはデフォルト）:
       └─ ERRORLOGからDACポート検出
       └─ リモートリスニング確認
       └─ TCPポートルール設定
   └─ DatabaseMirroringルール処理（Type指定時）:
       └─ デフォルトポート5022でTCPルール設定
   └─ 各ルールについて:
       └─ Configurationオプション適用
       └─ ShouldProcess確認
       └─ Invoke-Command2でNew-NetFirewallRule実行
       └─ 結果出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[各SqlInstanceループ]
    B --> C{Engine作成?}
    C -->|Yes| D[NetworkConfig取得]
    D --> E{RuleType?}
    E -->|Program| F[sqlservr.exeパス取得]
    E -->|Port| G[TCPポート取得]
    F --> H[Engineルール追加]
    G --> H
    C -->|No| I{Browser作成?}
    H --> I
    I -->|Yes| J{RuleType?}
    J -->|Program| K[sqlbrowser.exeパス取得]
    J -->|Port| L[UDP 1434設定]
    K --> M[Browserルール追加]
    L --> M
    I -->|No| N{DAC作成?}
    M --> N
    N -->|Yes| O[ERRORLOG読取]
    O --> P{リモートDAC?}
    P -->|Yes| Q[DACルール追加]
    P -->|No| R[スキップ]
    N -->|No| S{Mirroring作成?}
    Q --> S
    R --> S
    S -->|Yes| T[ポート5022ルール追加]
    S -->|No| U[各ルール処理]
    T --> U
    U --> V[New-NetFirewallRule実行]
    V --> W[結果出力]
    W --> B
    B --> X{次のInstance?}
    X -->|Yes| B
    X -->|No| Y[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | SQLServerグループ | 全ルールは'SQL Server'グループに属する | 常に |
| BR-02 | 命名規則 | 'SQL Server default instance'または'SQL Server instance XXX' | ルール作成時 |
| BR-03 | Program優先 | RuleType未指定時はProgramベースルールを使用 | デフォルト |
| BR-04 | Browser条件 | 名前付きインスタンスまたは非1433ポート時にBrowser作成 | Engine作成時 |
| BR-05 | DAC条件 | リモートDACが有効な場合のみルール作成 | DAC処理時 |
| BR-06 | Force上書き | 既存ルールをRemove-NetFirewallRuleで削除後に再作成 | -Force時 |

### 計算ロジック

ルール名の決定:
- デフォルトインスタンス: `'SQL Server default instance'`
- 名前付きインスタンス: `'SQL Server instance ' + $instance.InstanceName`
- DAC: 上記 + ` (DAC)`
- DatabaseMirroring: 上記 + ` (DatabaseMirroring)`

## データベース操作仕様

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | SQLデータベースへの操作なし |

### テーブル別操作詳細

SQLデータベースへの操作なし（Windowsファイアウォール設定のみ）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 設定エラー | NetworkConfig取得失敗 | インスタンス名・資格情報確認 |
| - | 実行エラー | New-NetFirewallRule失敗 | 管理者権限確認 |
| - | 重複エラー | ルール既存（-Forceなし） | -Force指定で再作成 |
| - | 複数IP非対応 | 複数IPリスニング | 現バージョンでは非対応 |

### リトライ仕様

リトライ処理は実装されていない

## トランザクション仕様

ファイアウォールルール操作のため、SQLトランザクションは不要。各ルールは独立して作成される。

## パフォーマンス要件

特に定義なし。リモートPowerShell実行のためネットワーク遅延に依存。

## セキュリティ考慮事項

- 管理者権限が必要
- 資格情報はPSCredentialオブジェクトで安全に取り扱う
- ファイアウォールルール作成はセキュリティに影響
- -WhatIfで事前確認推奨

## 備考

- 現在の機能は限定的で拡張予定あり
- 将来のバージョンでbreaking changesの可能性あり
- Configurationパラメータで詳細なルール設定が可能（Profile制限等）
- DAC/DatabaseMirroringは常にPort方式

---

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

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

### 推奨読解順序

#### Step 1: パラメータ定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | New-DbaFirewallRule.ps1 | `public/New-DbaFirewallRule.ps1` | paramブロック（197-209行目）でパラメータ構造を確認 |

**主要処理フロー**:
- **202行目**: Type ValidateSet（Engine/Browser/DAC/DatabaseMirroring）
- **204行目**: RuleType ValidateSet（Program/Port）、デフォルトProgram

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | New-DbaFirewallRule.ps1 | `public/New-DbaFirewallRule.ps1` | beginブロック（221-263行目）でリモート実行スクリプトを確認 |

**主要処理フロー**:
- **227行目**: New-NetFirewallRuleコマンドの存在確認
- **231行目**: -Force時のRemove-NetFirewallRule
- **234行目**: New-NetFirewallRule実行

#### Step 3: Engineルール処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbaFirewallRule.ps1 | `public/New-DbaFirewallRule.ps1` | processブロック（278-359行目）でEngineルール処理を確認 |

**主要処理フロー**:
- **304-306行目**: Get-DbaNetworkConfiguration呼び出し
- **317-332行目**: Programベースルール処理（sqlservr.exeパス取得）
- **343-351行目**: Portベースルール処理

#### Step 4: Browser/DAC/Mirroringルール処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | New-DbaFirewallRule.ps1 | `public/New-DbaFirewallRule.ps1` | processブロック（361-486行目）で各ルール処理を確認 |

**主要処理フロー**:
- **362-403行目**: Browserルール処理
- **405-457行目**: DACルール処理（ERRORLOG読取含む）
- **459-486行目**: DatabaseMirroringルール処理

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

```
New-DbaFirewallRule
    │
    ├─ Get-DbaNetworkConfiguration -OutputType TcpIpAddresses
    │
    ├─ Get-DbaService -Type Engine/Browser
    │
    ├─ Get-DbaStartupParameter (DAC用)
    │
    ├─ Invoke-Command2 (ERRORLOG読取)
    │
    └─ Invoke-Command2 (リモート実行)
           │
           ├─ Remove-NetFirewallRule (-Force時)
           │
           └─ New-NetFirewallRule
```

### データフロー図

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

SqlInstance ────────────▶ ルール種別判定
                                │
                    ┌───────────┼───────────┐
                    │           │           │
                    ▼           ▼           ▼
              Engine       Browser      DAC/Mirroring
                │           │               │
                ▼           ▼               ▼
         RuleType判定  RuleType判定    ポート取得
                │           │               │
                └───────────┼───────────────┘
                            │
                            ▼
                   New-NetFirewallRule ───────▶ PSCustomObject
                                                (Successful, Status)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| New-DbaFirewallRule.ps1 | `public/New-DbaFirewallRule.ps1` | ソース | メインコマンド実装 |
| Get-DbaFirewallRule.ps1 | `public/Get-DbaFirewallRule.ps1` | ソース | ファイアウォールルール取得（関連コマンド） |
| Remove-DbaFirewallRule.ps1 | `public/Remove-DbaFirewallRule.ps1` | ソース | ファイアウォールルール削除（関連コマンド） |
| Get-DbaNetworkConfiguration.ps1 | `public/Get-DbaNetworkConfiguration.ps1` | ソース | ネットワーク構成取得 |
| Get-DbaService.ps1 | `public/Get-DbaService.ps1` | ソース | サービス情報取得 |
