Document NTFS naming convention placeholders

README.md

@@ -1,5 +1,185 @@
 # LIAM
 
+## Naming Conventions fuer NTFS-Gruppen
+
+NTFS-Namenskonventionen bestehen aus `NamingTemplate`, `DescriptionTemplate` und `Wildcard`. Die Templates werden beim Erzeugen oder Sicherstellen von AD-Gruppen materialisiert. Der `Wildcard` ist eine regulaere Expression und wird beim Auslesen der ACLs verwendet, um vorhandene Gruppen wieder einer Rolle zuzuordnen.
+
+Die wichtigsten Eingaben fuer die Ersetzung sind:
+
+| Quelle | Beispiel |
+| --- | --- |
+| `RootPath` | `\\SRVWSM001.imagoverum.com\file_shares\share2` |
+| Aktuelle DataArea | `\\SRVWSM001.imagoverum.com\file_shares\share2\test33` |
+| `CustomTags` | `Filesystem_GroupGlobalTag=UG`, `Filesystem_GroupDomainLocalTag=FS`, `Filesystem_GroupOwnerTag=_OW` |
+| Rolle / Scope | z. B. `Owner` und `DomainLocal` |
+
+### Standard-Platzhalter
+
+| Platzhalter | Wirkung | Beispielwert bei Root `\\server\file_shares\share2` und DataArea `...\share2\test33` |
+| --- | --- | --- |
+| `{{NAME}}` | Name des aktuellen Ordners oder Shares. | `test33` |
+| `{{RELATIVEPATH}}` | Relativer Pfad der DataArea unterhalb des `RootPath`, mit Sanitizing und konfiguriertem Segmenttrenner. | `test33` |
+| `{{RELATIVEPATH(0)}}` | Letztes relatives Pfadsegment. | `test33` |
+| `{{RELATIVEPATH(1)}}` | Die letzten zwei relativen Pfadsegmente. Bei weniger Segmenten werden alle vorhandenen verwendet. | z. B. `team1_test33` |
+| `{{ROOT_SERVER}}` | Server-/Namespace-Teil des UNC-RootPath. | `server` |
+| `{{ROOT_NAME}}` | Letztes Segment des RootPath. | `share2` |
+| `{{ROOT_PATH}}` | Alle RootPath-Segmente ohne Server, mit Segmenttrenner verbunden. | `file_shares_share2` |
+| `{{ROOT_PATH(1)}}` | Letztes RootPath-Segment. | `share2` |
+| `{{ROOT_PATH(2)}}` | Letzte zwei RootPath-Segmente. | `file_shares_share2` |
+| `{{ROOT_SEGMENT(0)}}` | RootPath-Segment per 0-basierter Position, ohne Server. | `file_shares` |
+| `{{ROOT_SEGMENT(1)}}` | Zweites RootPath-Segment. | `share2` |
+
+`{{RELATIVEPATH(n)}}` zaehlt von hinten: `0` ist das letzte Segment, `1` sind die letzten zwei Segmente, `2` die letzten drei Segmente usw. `{{ROOT_PATH(n)}}` verwendet dagegen die letzten `n` Segmente des RootPath.
+
+Wenn die aktuelle DataArea dem `RootPath` selbst entspricht, ist `{{RELATIVEPATH}}` leer. `{{NAME}}` ist dann der Name des RootPath, also z. B. `share2` oder `LEI.01.test`.
+
+### Rollen- und Scope-Platzhalter
+
+Diese Platzhalter werden aus Rolle, Scope und `CustomTags` aufgebaut:
+
+| Platzhalter | Wirkung | Typische Werte |
+| --- | --- | --- |
+| `{{PREFIX}}` | Gruppenprefix aus `Filesystem_GroupPrefixTag`, fallback auf `ADGroupPrefix`. | `ACL`, `FS` |
+| `{{SCOPETAG}}` | Scope-Tag. Bei `Global` aus `Filesystem_GroupGlobalTag`, bei `DomainLocal` aus `Filesystem_GroupDomainLocalTag`. | `UG`, `FS`, `G`, `DL` |
+| `{{GROUPTYPEPOSTFIX}}` | Rollen-Postfix. Owner/Write/Read/Traverse verwenden die jeweiligen `Filesystem_Group*Tag` Werte. | `_OW`, `_RW`, `_R`, `_T` |
+| `{{_LOOP}}` | Optionaler Eindeutigkeitszaehler. Beim ersten Versuch leer, danach `_1`, `_2`, usw. | leer, `_1`, `_2` |
+| `{{LOOP}}` | Variante ohne Trennzeichen. Beim ersten Versuch leer, danach `1`, `2`, usw. | leer, `1`, `2` |
+
+Der Loop-Platzhalter ist flexibel: Alles innerhalb der geschweiften Klammern, das `LOOP` enthaelt, wird als Loop-Tag behandelt. `{{-LOOP}}` wird beim ersten Versuch leer und danach z. B. `-1`.
+
+### CustomTags
+
+Alle Eintraege aus `CustomTags` koennen ebenfalls direkt verwendet werden. Die Schreibweise muss exakt zum Key passen.
+
+Beispiele:
+
+```text
+{{ADGroupPrefix}}_{{RELATIVEPATH}}{{GROUPTYPEPOSTFIX}}
+{{Filesystem_GroupGlobalTag}}_{{ROOT_NAME}}_{{NAME}}{{GROUPTYPEPOSTFIX}}
+{{Filesystem_GroupDomainLocalTag}}_{{ROOT_PATH(1)}}_{{RELATIVEPATH}}{{GROUPTYPEPOSTFIX}}
+```
+
+### Beispiele fuer NamingTemplate
+
+Share-basierte Gruppen nur mit Share-Name:
+
+```text
+{{SCOPETAG}}_{{NAME}}{{_LOOP}}{{GROUPTYPEPOSTFIX}}
+```
+
+Bei `RootPath=\\intra.brkr.corp\File_Shares\LEI.01.test`, Scope `DomainLocal`, `Filesystem_GroupDomainLocalTag=FS` und Rolle `Owner` entsteht:
+
+```text
+FS_LEI.01.TEST_OW
+```
+
+Gruppen fuer Unterordner relativ zum Root:
+
+```text
+{{SCOPETAG}}_{{RELATIVEPATH}}{{_LOOP}}{{GROUPTYPEPOSTFIX}}
+```
+
+Bei `RootPath=\\SRVWSM001.imagoverum.com\file_shares\share2` und DataArea `...\share2\test33` entsteht fuer Owner:
+
+```text
+FS_TEST33_OW
+```
+
+Root-Share und Unterordner kombinieren:
+
+```text
+{{SCOPETAG}}_{{ROOT_NAME}}.{{RELATIVEPATH}}{{_LOOP}}{{GROUPTYPEPOSTFIX}}
+```
+
+Bei Root `share2` und Ordner `test33` entsteht:
+
+```text
+FS_SHARE2.TEST33_OW
+```
+
+Nur die letzten zwei relativen Pfadsegmente verwenden:
+
+```text
+{{SCOPETAG}}_{{RELATIVEPATH(1)}}{{_LOOP}}{{GROUPTYPEPOSTFIX}}
+```
+
+Bei `...\share2\team1\test33` entsteht:
+
+```text
+FS_TEAM1_TEST33_OW
+```
+
+Namespace-/Share-Bestandteile aus dem RootPath verwenden:
+
+```text
+{{SCOPETAG}}_{{ROOT_SEGMENT(0)}}_{{ROOT_SEGMENT(1)}}_{{NAME}}{{GROUPTYPEPOSTFIX}}
+```
+
+Bei Root `\\SRVWSM001.imagoverum.com\file_shares\share2` und Name `test33` entsteht:
+
+```text
+FS_FILE_SHARES_SHARE2_TEST33_OW
+```
+
+### Beispiele fuer AGP und AGDLP
+
+Bei AGP liegen die Global-Gruppen direkt auf der ACL. Eine typische Konvention ist:
+
+```text
+NamingTemplate: {{SCOPETAG}}_{{NAME}}{{_LOOP}}{{GROUPTYPEPOSTFIX}}
+Scope: Global
+```
+
+Bei AGDLP liegen die DomainLocal-Gruppen auf der ACL, die Global-Gruppen werden darin verschachtelt. Typisch ist:
+
+```text
+Global NamingTemplate:      {{SCOPETAG}}_{{NAME}}{{_LOOP}}{{GROUPTYPEPOSTFIX}}
+DomainLocal NamingTemplate: {{SCOPETAG}}_{{NAME}}{{_LOOP}}{{GROUPTYPEPOSTFIX}}
+```
+
+Mit `Filesystem_GroupGlobalTag=UG` und `Filesystem_GroupDomainLocalTag=FS` entstehen z. B.:
+
+```text
+UG_LEI.01.TEST_OW
+FS_LEI.01.TEST_OW
+```
+
+In diesem Fall gehoert bei AGDLP die `FS_...` DomainLocal-Gruppe auf die NTFS-ACL; `UG_...` wird Mitglied der `FS_...` Gruppe.
+
+### Wildcard-Regeln
+
+`Wildcard` ist eine regulaere Expression. Sie muss nach Platzhalterersetzung zum erzeugten oder vorhandenen `sAMAccountName` passen.
+
+Passendes Beispiel:
+
+```text
+^{{SCOPETAG}}_[a-zA-ZoeaeueOeAeUess0-9_\-\.]*{{GROUPTYPEPOSTFIX}}$
+```
+
+Mit `SCOPETAG=FS` und `GROUPTYPEPOSTFIX=_OW` matcht das:
+
+```text
+FS_LEI.01.TEST_OW
+```
+
+Nicht passend ist ein fuehrendes Leerzeichen:
+
+```text
+^ {{SCOPETAG}}_[a-zA-ZoeaeueOeAeUess0-9_\-\.]*{{GROUPTYPEPOSTFIX}}$
+```
+
+Dieser Regex erwartet nach `^` ein Leerzeichen und matcht deshalb nicht auf `FS_LEI.01.TEST_OW`.
+
+Wenn eine Traverse-Naming-Convention keine Gruppe erzeugen soll, kann das `NamingTemplate` leer bleiben. Fuer Owner/Write/Read sollte der `Wildcard` nicht leer sein. Ein leerer Regex ist keine sinnvolle Matching-Regel, weil er technisch sehr breit matchen kann.
+
+### Sanitizing, Laenge und Grossschreibung
+
+Pfadbasierte Platzhalter wie `{{NAME}}`, `{{RELATIVEPATH}}`, `{{ROOT_PATH}}` und `{{ROOT_SEGMENT(n)}}` werden fuer AD-Gruppennamen bereinigt. Standardmaessig werden ungueltige Zeichen mit `_` ersetzt. Das Ersatzzeichen kann ueber `NtfsGroupNameSanitizeReplacement` geaendert oder entfernt werden.
+
+Generierte AD-Gruppennamen werden standardmaessig in Grossbuchstaben geschrieben. Mit `PreserveNtfsAdGroupNameCase=1` bleibt die Schreibweise erhalten.
+
+AD-Gruppennamen werden auf die maximale Laenge von 64 Zeichen begrenzt. Wenn ein Template mit `{{RELATIVEPATH}}` oder `{{NAME}}` zu lang wird, werden Pfadbestandteile gekuerzt. Fuer Loop-Platzhalter werden bis zu drei Ziffern reserviert.
+
 ## AdditionalParameters / AdditionalConfiguration
 
 Provider-spezifische Zusatzparameter werden in Matrix42 am DataArea-Collector ueber das Fragment `C4IT_GCC_DataArea_Collector_AdditionalAttributes` gepflegt. Pro Parameter wird ein Eintrag mit `Name` und `Value` angelegt.