aboutsummaryrefslogtreecommitdiffstats
path: root/README.md
blob: ad1ed98d36d6d6887f12696a73e42ee562d189c5 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
# Trace

Remote debugger voor PowerShell-scripts op een vloot servers. Trace vindt draaiende
`pwsh`-scripts via SSH, volgt ze op en legt bij een crash de volledige toestand vast:
regel, variabelen, callstack en `$Error`. Op de servers wordt niets geïnstalleerd.

> **Status:** in ontwikkeling. Alleen de proof of concept in `poc/attach` werkt:
> attachen aan een al draaiend script op een andere machine, met tracepoints.

## Vereisten

- **Beheermachine:** PowerShell 7.4 of hoger, de module `powershell-yaml`.
- **Servers:** PowerShell 7.4 of hoger, en in `sshd_config`:
  ```
  Subsystem powershell /usr/bin/pwsh -sshs -NoLogo
  ```
- Om te attachen: dezelfde SSH-gebruiker als het script, of root.

## Snel aan de slag

1. Kopieer `fleet.example.yml` naar `fleet.yml` en vul je servers in.
   Een bestaande Ansible-inventaris in YAML werkt ook.
2. Zet `trace_debug: true` alleen op servers waar debuggen mag.

Gepland gebruik:

```powershell
Import-Module ./Trace
Import-TraceServer ./fleet.yml | Test-TraceServer      # is elke server klaar?
Import-TraceServer ./fleet.yml | Find-TraceScript      # welke scripts draaien er?
Get-Help about_Trace                                   # de niveaus van licht tot diep
```

## Cmdlets (gepland)

| Cmdlet | Wat het doet | Niveau |
|---|---|---|
| `Import-TraceServer` | Serverlijst inlezen en valideren | |
| `Test-TraceServer` | Controleren of elke server klaar is (pwsh, subsystem, rechten) | |
| `Find-TraceScript` | Draaiende `pwsh`-scripts vinden | |
| `Get-TraceLog` | Logs ophalen die het script zelf schrijft | 0 |
| `Start-TraceScript` | Script starten via de wrapper | 1 |
| `Set-TraceTracepoint` / `Remove-TraceTracepoint` | Tracepoints zetten en weghalen | 2 |
| `Connect-TraceScript` / `Disconnect-TraceScript` | Aanhaken aan een draaiend script en loskoppelen | 3 |
| `Get-TraceCrashReport` | Crashrapporten opvragen en tonen | |

## Mappen

```
fleet.example.yml        voorbeeldserverlijst
docs/architectuur.md     hoe het werkt, met de bevindingen uit de PoC
docs/about_Trace.help.txt  helptopic (komt in de module onder en-US/)
poc/attach/              proof of concept: VM opstarten en een draaiend script debuggen
```

## Proof of concept

```sh
cd poc/attach
./up.sh              # Debian-VM met pwsh en een draaiend hello.ps1
pwsh ./debug.ps1     # attachen, tracepoints, resultaat op de beheermachine
./down.sh            # VM stoppen
```

Zie `poc/attach/README.md` voor de uitvoer en de beperkingen.