# 機能設計書 210-Reset-DbaAdmin

## 概要

本ドキュメントは、dbatools PowerShellモジュールのReset-DbaAdmin関数の機能設計を定義する。この関数は、パスワードの紛失やアクセス不能時にSQL Serverインスタンスへの管理者アクセスを回復するための緊急復旧ツールを提供する。

### 本機能の処理概要

Reset-DbaAdminは、パスワード忘れ、アカウント無効化、認証問題などでSQL Serverインスタンスからロックアウトされた場合にアクセスを回復する。SQL Serverサービスを停止し、シングルユーザーモードで再起動して、資格情報のリセットと管理者権限の復元を行う。

**業務上の目的・背景**：SQL Server管理において、saパスワードの紛失やsysadminアカウントへのアクセス不能は深刻な問題である。この関数は、Windowsサーバー管理者権限を持つユーザーがSQL Server管理者アクセスを安全に回復するための緊急手段を提供する。

**機能の利用シーン**：
- saパスワードの紛失時の復旧
- sysadminアカウントが無効化された場合の復旧
- 認証問題によるアクセス不能時の対応
- 新しい管理者アカウントの緊急追加

**主要な処理内容**：
1. ログインタイプの検出（Windows/SQL認証）
2. SQL Serverサービスの停止
3. シングルユーザーモード(/mReset-DbaAdmin)での再起動
4. ログインの作成（存在しない場合）
5. 混合モード認証の有効化（SQLログインの場合）
6. ログインのロック解除と有効化
7. sysadminロールへの追加
8. サービスの通常再起動
9. ログイン情報の取得と出力

**関連システム・外部連携**：
- SQL Server Service：サービス停止/起動
- Windows Cluster Service：クラスター環境対応
- PSRemoting：リモートサーバーへのアクセス

**権限による制御**：Windows管理者権限が必要。SQL Server権限は不要（回復が目的）。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 111 | 管理者リセット | 主機能 | SQL Server管理者のリセット |

## 機能種別

管理操作（緊急復旧）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter | Yes | 対象のSQL Serverインスタンス | - |
| SqlCredential | PSCredential | No | 認証情報（LoginとSecurePasswordの代わりに使用可能） | - |
| Login | string | No | リセット/作成するログイン名。デフォルトは"sa" | - |
| SecurePassword | SecureString | No | SQLログイン用のパスワード | - |
| Force | switch | No | 確認プロンプトをスキップ | - |
| EnableException | switch | No | 例外を直接スローするかどうか | - |

### 入力データソース

- パラメータ入力：SqlInstance、Login、SecurePassword
- 対話入力：パスワード（SQLログインでSecurePassword未指定時）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverが稼働しているコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Name | string | ログイン名 |
| LoginType | string | ログインタイプ（SqlLogin/WindowsUser） |
| CreateDate | DateTime | ログイン作成日時 |
| LastLogin | DateTime | 最終ログイン日時 |
| IsDisabled | bool | 無効化状態 |
| IsLocked | bool | ロックアウト状態 |
| IsSysAdmin | bool | sysadmin権限（リセット後はtrue） |

### 出力先

- パイプライン：Dataplat.Dbatools.Loginオブジェクト
- SQL Server：ログイン設定の変更

## 処理フロー

### 処理シーケンス

```
1. ログインタイプ検出
   └─ 1.1 "\"を含む場合はWindowsログイン
   └─ 1.2 Windowsログインの場合はアカウント存在確認
   └─ 1.3 SQLログインの場合はパスワード入力待機
2. サービス情報取得
   └─ 2.1 インスタンス名からサービス名を特定
   └─ 2.2 クラスター環境かどうかを確認
3. SQL Serverサービス停止
   └─ 3.1 クラスター：TakeOffline()
   └─ 3.2 スタンドアロン：Stop-Service
4. シングルユーザーモードで起動
   └─ 4.1 net start "サービス名" /mReset-DbaAdmin
5. ログイン作成/更新
   └─ 5.1 Windowsログイン：CREATE LOGIN FROM WINDOWS
   └─ 5.2 SQLログイン：CREATE LOGIN WITH PASSWORD（sa以外）
6. 認証モード設定
   └─ 6.1 SQLログインの場合、混合モード認証を有効化
   └─ 6.2 パスワードポリシーOFFでパスワード設定
7. ログイン有効化
   └─ 7.1 ALTER LOGIN ... ENABLE
8. sysadminロール追加
   └─ 8.1 sp_addsrvrolemember（sa以外）
9. サービス再起動
   └─ 9.1 サービス停止
   └─ 9.2 通常モードで起動
10. 結果取得
    └─ 10.1 Get-DbaLoginでログイン情報取得
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{ログインタイプ判定}
    B -->|Windows| C[アカウント存在確認]
    B -->|SQL| D[パスワード入力]
    C --> E[サービス情報取得]
    D --> E
    E --> F{クラスター?}
    F -->|Yes| G[TakeOffline]
    F -->|No| H[Stop-Service]
    G --> I[/mReset-DbaAdmin起動]
    H --> I
    I --> J[接続テスト]
    J --> K{ログイン存在?}
    K -->|No| L[ログイン作成]
    K -->|Yes| M{SQLログイン?}
    L --> M
    M -->|Yes| N[混合モード有効化]
    M -->|No| O[ログイン有効化]
    N --> P[パスワード設定/解除]
    P --> O
    O --> Q{sa以外?}
    Q -->|Yes| R[sysadmin追加]
    Q -->|No| S[サービス再起動]
    R --> S
    S --> T[Get-DbaLogin]
    T --> U[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-210-01 | Windows管理者権限必須 | サーバーへのWindows管理者権限が必要 | 常時 |
| BR-210-02 | シングルユーザーモード | /mReset-DbaAdminでこのスクリプトのみ接続可能 | 常時 |
| BR-210-03 | 混合モード自動有効化 | SQLログインの場合は自動的に混合モード認証を有効化 | SQLログイン時 |
| BR-210-04 | パスワードポリシーOFF | SQLログイン作成時はパスワードポリシーをOFFに設定 | SQLログイン作成時 |
| BR-210-05 | クラスター対応 | クラスター環境ではリソースグループの操作を使用 | クラスター環境時 |
| BR-210-06 | リモートアクセス | リモートサーバーの場合はPSRemotingが必要 | リモート実行時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象 | 操作種別 | 概要 |
|-----|-----|---------|------|
| ログイン作成 | master.sys.server_principals | DDL (CREATE LOGIN) | 新規ログイン作成 |
| 認証モード変更 | レジストリ | UPDATE | xp_instance_regwrite |
| パスワード変更 | master.sys.sql_logins | DDL (ALTER LOGIN) | パスワード設定 |
| ログイン有効化 | master.sys.server_principals | DDL (ALTER LOGIN) | ENABLE |
| ロール追加 | master.sys.server_role_members | INSERT | sp_addsrvrolemember |

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

#### master.sys.server_principals

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| CREATE LOGIN | - | Windowsログイン/SQLログイン | 存在しない場合のみ |
| ALTER LOGIN | is_disabled | 0 (ENABLE) | ログイン有効化 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| PSRemotingError | 接続エラー | リモートアクセス不可 | ファイアウォール/リモーティング設定確認 |
| ServiceError | サービスエラー | サービス停止/起動失敗 | 権限/サービス状態確認 |
| AccountError | アカウントエラー | Windowsアカウント解決失敗 | アカウント存在確認 |
| RestartError | 再起動エラー | シングルユーザーモード起動失敗 | 手動でサービス再起動 |

### リトライ仕様

接続テストは1回リトライ（3秒待機）。

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

各SQL操作は独立して実行。失敗時はサービスの再起動を試行。

## パフォーマンス要件

- サービス停止/起動に時間がかかる場合あり
- 対話的なパスワード入力待機

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

- Windows管理者権限が必要（SQL Server権限は不要）
- ConfirmImpact=Highで確認プロンプト
- シングルユーザーモードで他の接続を防止
- パスワードはSecureStringで取り扱い

## 備考

- Chrissy LeMaire (@cl) により作成
- SQL Server 2005以上をサポート
- クラスター/スタンドアロン両方に対応
- リモートアクセス不可の場合はローカル実行を推奨

---

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

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

### 推奨読解順序

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

SQL Serverのサービス管理と認証の構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | SQL Server認証モード | SQL Server | LoginMode (1=Windows, 2=Mixed) |
| 1-2 | シングルユーザーモード | SQL Server | /m パラメータ |

**読解のコツ**: /mReset-DbaAdminは特定のアプリケーション名のみ接続を許可するシングルユーザーモード。これによりスクリプト以外の接続を防止。

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

Reset-DbaAdmin.ps1の構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Reset-DbaAdmin.ps1 | `public/Reset-DbaAdmin.ps1` | 関数全体の処理フロー |

**主要処理フロー**:
1. **124-179行目**: begin ブロック（ヘルパー関数、パラメータ処理）
2. **180-214行目**: リモートセッション設定
3. **216-236行目**: ログインタイプ検出
4. **257-312行目**: サービス停止処理
5. **314-343行目**: シングルユーザーモード起動
6. **345-384行目**: 接続テスト
7. **366-419行目**: ログイン作成/認証モード設定
8. **421-434行目**: サービス再起動
9. **436-450行目**: 結果取得

#### Step 3: 関連機能を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaService.ps1 | `public/Get-DbaService.ps1` | サービス取得 |
| 3-2 | Get-DbaLogin.ps1 | `public/Get-DbaLogin.ps1` | ログイン取得 |

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

```
Reset-DbaAdmin
    │
    ├─ Invoke-ResetSqlCmd (内部関数)
    │      └─ Microsoft.Data.SqlClient接続
    │
    ├─ Resolve-DbaNetworkName
    │      └─ ホスト名解決
    │
    ├─ New-PSSession
    │      └─ リモートセッション確立
    │
    ├─ Get-Service
    │      └─ SQL Serverサービス取得
    │
    ├─ Stop-Service / Start-Service
    │      └─ サービス停止/起動
    │
    ├─ Get-DbaCmObject (クラスター)
    │      └─ クラスターリソース取得
    │
    ├─ net start "サービス名" /mReset-DbaAdmin
    │      └─ シングルユーザーモード起動
    │
    ├─ SQL文実行（CREATE LOGIN, ALTER LOGIN, sp_addsrvrolemember等）
    │      └─ Invoke-ResetSqlCmd経由
    │
    └─ Get-DbaLogin
           └─ ログイン情報取得
```

### データフロー図

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

SqlInstance ─────────────▶ ホスト名解決
    │                              │
    │                              ▼
    │                    リモートセッション確立
    │                              │
Login ───────────────────▶ ログインタイプ判定
    │                              │
SecurePassword ──────────▶ パスワード取得
    │                              │
    │                              ▼
    │                    SQL Serverサービス停止
    │                              │
    │                              ▼
    │                    シングルユーザーモード起動
    │                              │
    │                              ▼
    │                    ┌─────────────────────┐
    │                    │ SQL操作             │
    │                    │ - ログイン作成      │
    │                    │ - 認証モード変更    │
    │                    │ - パスワード設定    │
    │                    │ - sysadmin追加      │
    │                    └─────────────────────┘
    │                              │
    │                              ▼
    │                    サービス通常再起動
    │                              │
    │                              ▼
    └────────────────────▶ Get-DbaLogin ─────────▶ Loginオブジェクト
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Reset-DbaAdmin.ps1 | `public/Reset-DbaAdmin.ps1` | ソース | メイン関数実装 |
| Get-DbaService.ps1 | `public/Get-DbaService.ps1` | ソース | サービス取得 |
| Get-DbaLogin.ps1 | `public/Get-DbaLogin.ps1` | ソース | ログイン取得 |
| Resolve-DbaNetworkName.ps1 | `public/Resolve-DbaNetworkName.ps1` | ソース | ホスト名解決 |
| Get-DbaCmObject.ps1 | `functions/Get-DbaCmObject.ps1` | ソース | WMI/CIMオブジェクト取得 |
