Zum Inhalt

Einstellbare Werte an Scripts

Kurz: Ein Script sagt selbst, welche Werte es von außen entgegennimmt. Diese Werte erscheinen dann als Felder am Check — Grenzwerte, Ausnahmelisten, Schalter. Wer den Check anpassen will, muss den Code nicht mehr anfassen.

Wozu das gut ist

Ohne einstellbare Werte steht die Einstellung im Script:

$processName = "sqlservr"     # ← wer einen zweiten Prozess will, KOPIERT das Script
$maxAgeHours = 26

Sobald jemand kopiert, driften die Kopien: eine Verbesserung am Original erreicht sie nie wieder. Mit einstellbaren Werten speist ein Script beliebig viele Checks, und jeder Check hat seine eigenen Zahlen.

Einen Wert deklarieren

Die Deklaration ist eine Kommentar-Zeile im Script selbst:

# @vesana-param MAX_AGE_HOURS number "Maximales Alter" unit="Stunden" default=24 required
Teil Bedeutung
MAX_AGE_HOURS Name. GROSSBUCHSTABEN, Ziffern, Unterstrich. Im Script heißt die Variable VESANA_MAX_AGE_HOURS.
number Die Art des Feldes (siehe unten). Weglassen ⇒ text.
"Maximales Alter" Was am Check über dem Feld steht. In Anführungszeichen.
default=24 Vorgabe, wenn das Feld leer bleibt.
unit="Stunden" Einheit hinter der Beschriftung — reine Anzeige.
required Pflicht. Fehlt der Wert, meldet der Check UNKNOWN statt zu raten.
help="…" Erklärung unter dem Feld.
show_if=METRIC:a\|b Das Feld erscheint nur, wenn der Wert METRIC gerade a oder b ist (siehe unten).

# ist in Bash, PowerShell und Python ein Kommentar — dieselbe Zeile funktioniert in allen drei.

Warum im Script und nicht daneben

Weil das Script das ist, was Sie einer KI geben („erweitere es um einen Wert für X"). Kommt es mit einer neuen Variablen zurück, ist das Feld sofort da — Sie müssen nichts nachtragen. Es gibt genau eine Wahrheit.

Die Feldarten — und wie das Script sie liest

Jeder Wert kommt als Umgebungsvariable VESANA_<NAME> an. Nie als Textersetzung im Code: der Wert wird so nie zu Code, und der ausgelieferte Rumpf bleibt identisch zum Original.

Text

# @vesana-param DB_NAME text "Datenbank" default=master

DB="${VESANA_DB_NAME:-master}"

$db = if ($env:VESANA_DB_NAME) { $env:VESANA_DB_NAME } else { "master" }

db = os.environ.get("VESANA_DB_NAME", "master")

Zahl

# @vesana-param WARN_PCT number "Warnung ab" unit="%" default=80

WARN="${VESANA_WARN_PCT:-80}"
[ "$wert" -gt "$WARN" ] && exit 1

$warn = 80
if ($env:VESANA_WARN_PCT) { $warn = [double]$env:VESANA_WARN_PCT }

warn = float(os.environ.get("VESANA_WARN_PCT") or 80)

Grenzwerte lieber in die Schwellwert-Felder

Wenn Ihr Script eine reine Zahl ausgibt, gehören WARNING/CRITICAL in die Schwellwert-Felder des Checks — die wirken sofort und sind pro Gerät überschreibbar. Ein number-Wert ist für alles andere gedacht: Zeitfenster, Mindestanzahlen, Port.

Ja / Nein

# @vesana-param INCLUDE_DISABLED boolean "Auch deaktivierte Jobs prüfen" default=no

Kommt immer als 1 oder 0 an — nie als true/yes. Damit ist die Prüfung in jeder Sprache dieselbe:

if [ "$VESANA_INCLUDE_DISABLED" = "1" ]; then …; fi

$mit = $env:VESANA_INCLUDE_DISABLED -eq "1"

mit = os.environ.get("VESANA_INCLUDE_DISABLED") == "1"

Am Check hat das Feld drei Zustände: Ja, Nein und nicht gesetzt — im letzten Fall greift die Vorgabe aus der Deklaration.

Liste

# @vesana-param EXCLUDE_JOBS list "Ausgenommene Jobs" help="Groß-/Kleinschreibung egal"

Am Check tragen Sie Einträge einzeln ein (Enter nach jedem) — Leerzeichen sind erlaubt, „Daily Backup" ist ein Eintrag. Beim Script kommt eine Komma-Liste an: Daily Backup,Weekly.

# Komma-Liste durchgehen (POSIX, ohne Arrays):
alt=$IFS; IFS=','
for job in $VESANA_EXCLUDE_JOBS; do
  [ "$name" = "$job" ] && continue 2
done
IFS=$alt

$exclude = @()
if ($env:VESANA_EXCLUDE_JOBS) {
    $exclude = $env:VESANA_EXCLUDE_JOBS -split ',' | ForEach-Object { $_.Trim() }
}
if ($exclude -contains $name) { continue }

exclude = [t.strip() for t in os.environ.get("VESANA_EXCLUDE_JOBS", "").split(",") if t.strip()]

Ein leeres Feld setzt die Variable gar nicht — [ -z "$VESANA_EXCLUDE_JOBS" ] unterscheidet damit sauber „keine Ausnahmen".

Auswahl

# @vesana-param MODE choice "Berichtsart" options=summary|detailed default=summary

Die Optionen trennen Sie mit |. Am Check wird daraus ein Auswahlfeld — Tippfehler sind damit ausgeschlossen. Gelesen wird es wie ein Text.

Passwort / Token

# @vesana-param API_TOKEN password "API-Token" required

Verhält sich technisch genau wie Text. Der Unterschied ist die Behandlung in der Oberfläche: das Feld ist verdeckt, und in der Vorschau „Das Script bekommt damit" steht •••••• statt des Werts. Nehmen Sie diese Art für alles, was jemand über die Schulter mitlesen könnte — Tokens, Passwörter, Schlüssel.

Felder nur bei der passenden Messgröße zeigen

Ein Script speist oft viele Checks: dasselbe ESXi-Script liefert CPU, Datastores, VMs und Laufzeit — je nachdem, welche Messgröße am Check gewählt ist. Ohne weitere Angabe stünden bei jedem dieser Checks alle Felder, auch die, die zu seiner Messgröße nichts beitragen.

show_if bindet ein Feld an den Wert eines anderen:

# @vesana-param METRIC choice "Messgröße" options=cpu|datastores|vms default=cpu
# @vesana-param DATASTORE_MIN_GB number "Kleine Datastores überspringen ab (GB)" show_if=METRIC:datastores
# @vesana-param VM_EXCLUDE list "VMs ausnehmen" show_if=METRIC:vms
  • Das Feld erscheint, sobald der referenzierte Wert einen der genannten Werte hat; mehrere Werte trennst du mit |.
  • Maßgeblich ist der wirksame Wert: ist am Check nichts gesetzt, zählt die Vorgabe (default) des referenzierten Feldes.
  • Ein ausgeblendetes Feld wird dem Script nicht übergeben — und ein ausgeblendetes Pflichtfeld stellt den Check nicht auf UNKNOWN. Es gehört nicht zu dieser Messung.
  • Im Script-Editor lässt sich die Bedingung ohne Handarbeit setzen („Nur anzeigen, wenn …").

Werte am Check ausfüllen

Öffnen Sie den Check → Konfiguration. Unter dem gewählten Script stehen die Felder. Darunter zeigt Vesana, was das Script beim nächsten Lauf wirklich bekommt:

Das Script bekommt damit:
VESANA_MAX_AGE_HOURS=48
VESANA_EXCLUDE_JOBS=Daily Backup,Weekly
VESANA_INCLUDE_DISABLED=1
Wirkt ab dem nächsten Lauf des Checks.

Das ist die ehrliche Antwort auf „wirkt das, was ich eingetragen habe?". Einen Jetzt testen-Knopf gibt es bewusst nicht: Sofort-Prüfungen kann nur der Aktive Collector, und die meisten Checks laufen über einen Collector oder Agent.

Ein leeres Feld heißt nicht „leerer Wert", sondern „Vorgabe des Scripts". Ein leeres Pflichtfeld ohne Vorgabe lässt den Check ehrlich auf UNKNOWN laufen (Einstellbare Werte fehlen: …), statt gegen 0 zu messen und zuversichtlich OK zu melden.

Die Werte erben ganz normal: was am Profil steht, gilt für alle Geräte; was Sie am Gerät ändern, gilt nur dort.

Einen Wert nachrüsten lassen

Reichen die Felder nicht, ist der übliche Weg:

  1. Check → Konfiguration → Script → Bleistift öffnet den Inhalt.
  2. Script markieren, kopieren, einer KI geben: „Erweitere dieses Script um einen einstellbaren Wert für den Ordnerpfad. Halte dich an das # @vesana-param-Muster, das oben schon steht."
  3. Ergebnis zurück ins Fenster kleben, speichern — das neue Feld ist sofort da.

Weil die Deklaration im Script steht, sieht die KI das Muster und muss nichts erraten.

Ein Script speist viele Checks

Beim Speichern fragt Vesana, für wen die Änderung gilt: für alle Checks mit diesem Script (der Normalfall — nur so kommt eine Verbesserung überall an), als eigenes Script (sichtbare Kopie in der Bibliothek) oder nur für dieses Gerät. Der letzte Weg bekommt keine Verbesserungen am Original mehr.

Häufige Stolpersteine

Symptom Ursache
Feld erscheint nicht Der Name muss GROSSBUCHSTABEN sein und mit einem Buchstaben beginnen. Der Editor zeigt Meldungen zu fehlerhaften Zeilen direkt an.
Wert kommt nicht an Im Script VESANA_ vor dem Namen vergessen.
Ja/Nein wird nicht erkannt Gegen "1" vergleichen, nicht gegen "true" oder "yes".
Liste wird als ein Eintrag gelesen Am Komma trennen — die Werte kommen als eine Zeichenkette an.
Check meldet UNKNOWN „Einstellbare Werte fehlen" Ein Pflichtfeld ist leer und hat keine Vorgabe.
Ich suche die Grenze, ab der der Check gelb/rot wird Die ist kein einstellbarer Wert. Sie steht am Check im Block „Urteil über Schwellwerte" (Reiter Konfiguration, direkt unter dem Script) — pro Gerät überschreibbar, wirkt sofort. Das Script gibt nur den Messwert aus.
Warnung „deklariert, aber im Rumpf nie gelesen" Die Kopfzeile ist da, aber das Script verwendet VESANA_<NAME> nirgends — das Feld hätte keine Wirkung. Entweder im Script lesen oder die Zeile entfernen.

Siehe auch