Yapılandırma başvurusu

helmsight tek bir TOML dosyası okur. Aşağıdakilerden ilk bulunan kullanılır:

1. --config <yol>
2. $HELMSIGHT_CONFIG
3. /etc/helmsight/helmsight.toml
4. ./helmsight.toml

English version

examples/helmsight.toml her seçeneği yorumlarıyla gösteren bir örnektir. Bir dosyayı helmsight config check ile doğrulayın; hatalar dosyayı, satırı, sütunu ve anahtarı gösterir:

error: helmsight.toml:23:1: `hosts[1].name`: duplicate host name `web-1`
error: helmsight.toml:41:8: `alerts.rules[0].expr`: unknown operator `=>` (use > >= < <= == !=)

Bilinmeyen anahtarlar hatadır; böylece yazım yanlışları sessizce geçmez.

Süreler "500ms", "30s", "5m", "1h30m", "7d", "2w" gibi metinlerdir (ms milisaniye, s saniye, m dakika, h saat, d gün, w hafta).

Gizli değerler düz metin olarak yazılabilir, ancak başvuru kullanmak tercih edilir:

env: systemd’nin EnvironmentFile= veya konteynerin ortam değişkenleriyle, file: ise Docker/Kubernetes gizli dosyalarıyla (/run/secrets/...) iyi çalışır.

Yapılandırma değişiklikleri yeniden başlatmadan sonra geçerli olur.

Tam bir örnek

# En üst düzey anahtarlar herhangi bir [bölüm] başlığından önce gelmelidir.
hosts_file = "hosts.toml"

[server]
listen = "127.0.0.1:8080"
data_dir = "/var/lib/helmsight"
public_url = "https://monitor.example.com"
trusted_proxies = ["127.0.0.1"]

[auth]
require_totp_for_admins = true

[ssh]
user = "monitor"
identity_files = ["/etc/helmsight/id_ed25519"]

[[alerts.rules]]
id = "disk-full"
expr = "disk_used_pct > 90 for 10m"
severity = "critical"

[[notify]]
id = "ops"
type = "slack"
url = "secret:slack-webhook"

[[certs]]
endpoint = "www.example.com:443"

TOML kuralları gereği bir [bölüm] başlığından sonra yazılan her anahtar o bölüme ait sayılır. hosts_file gibi en üst düzey anahtarları bu yüzden dosyanın en başına yazın; yanlış yere yazılırsa config check bunu bilinmeyen anahtar olarak bildirir.

[server]

trusted_proxies istemci adresinin doğru belirlenmesi için önemlidir: oturum açma hız sınırlaması istemci adresine göre çalışır. Vekil sunucu arkasında bu ayar yapılmazsa bütün kullanıcılar vekil sunucunun adresinden geliyormuş gibi görünür.

[server.tls]

Let’s Encrypt sertifikası kullanıyorsanız cert için fullchain.pem, key için privkey.pem dosyasını gösterin ve sertifika yenilendikten sonra helmsight’ı yeniden başlatın (ör. certbot’un --deploy-hook seçeneğiyle).

[auth]

[auth.oidc]

Kimlik sağlayıcıda yönlendirme adresi (redirect URI) olarak <public_url>/api/v1/auth/oidc/callback kaydedin. Roller her oturum açılışında alandan yeniden okunur; yani kimlik sağlayıcıda bir kullanıcının grubunu değiştirmek bir sonraki girişte rolünü de değiştirir.

Örnek (Keycloak):

[auth.oidc]
issuer = "https://sso.example.com/realms/ops"
client_id = "helmsight"
client_secret = "secret:oidc"
role_claim = "realm_access.roles"
role_map = { "helmsight-admin" = "admin", "sre" = "operator", "dev" = "viewer" }
label = "Şirket hesabıyla giriş"

Yerel yönetici hesabını acil durum girişi olarak tutmanız önerilir; SSO çalışmadığında arayüze erişimi kaybetmemek için disable_local_login ayarını dikkatle kullanın.

[ssh]

[collect]

Başarısız sunucular artan aralıklarla yeniden denenir: ulaşılamadığında 5 dakikaya kadar üstel olarak, kimlik doğrulama hatalarından sonra (saldırı önleme sistemlerini tetiklememek için) 1 ila 5 dakika arasında ve sunucu anahtarı sorunlarında dakikada bir.

interval değerini düşürmek grafiklerin çözünürlüğünü artırır ama hem sunuculardaki hem de veritabanındaki yükü orantılı olarak artırır. Çok sayıda sunucuda 10–15 saniye makul bir başlangıçtır.

[retention]

Grafikler istenen aralığı kapsayan en ince çözünürlüğü seçer. Süreleri uzatmak veritabanını orantılı olarak büyütür. Süresi dolan veriler saatte bir kendiliğinden silinir; özetler dakikada bir hesaplanır.

Sunucular

[[hosts]]

hosts_file

En üst düzeydeki hosts_file = "hosts.toml" başka bir dosyadan (yapılandırma dosyasına göre göreli) ek [[hosts]] kayıtları yükler.

[ssh_config_import]

HostName, User, Port ve IdentityFile dikkate alınır; eşleşen Host blokları arasında OpenSSH’nin “ilk değer kazanır” kuralı geçerlidir. Aynı adla açıkça yazılmış [[hosts]] kayıtları önceliklidir. ProxyJump olan sunucular uyarıyla atlanır; Match ve Include değerlendirilmez.

Alarmlar

[alerts]

Yerleşik kurallar: host_unreachable (critical; kimlik doğrulama hataları için de), host_key_changed (critical), host_key_unknown (warning), failed_units (warning, birim başına bir alarm), cert_expiry (kalan güne göre warning veya critical; denetim başarısız olursa warning).

[[alerts.rules]]

İşleçler: >, >=, <, <=, ==, !=. Eşikler K, M, G, T (1000’in kuvvetleri) ve Ki, Mi, Gi, Ti (1024’ün kuvvetleri) soneklerini kabul eder. Örnek başına metrikler her örnek için (ör. her bağlama noktası için) ayrı alarm üretir. Bir sunucuya ulaşılamadığı sürece onun metrik alarmları çözülmez, durumlarını korur.

Kurallarda kullanılabilen metrikler

[[notify]]

Bildirimler bir alarm tetiklendiğinde, çözüldüğünde (tetiklenme bildirimi gönderilmişse) ve hatırlatma olarak gönderilir. Susturulmuş alarmlar kaydedilir ama bildirilmez. Başarısız teslimatlar üç kez yeniden denenir ve alarmla birlikte listelenir. API’den deneme gönderin: POST /api/v1/notify/<id>/test.

Webhook gövdesi:

{
  "version": 1,
  "source": "helmsight",
  "status": "firing",
  "alert": {
    "id": 42,
    "rule": "disk-full",
    "host": "web-1",
    "instance": "/var",
    "severity": "critical",
    "summary": "disk_used_pct on /var is 93.1% (> 90.0%)",
    "value": 93.1,
    "started_at": "2026-09-30T16:56:12Z",
    "resolved_at": null,
    "acknowledged_by": null
  },
  "url": "https://monitor.example.com/alerts?id=42"
}

status değeri firing, resolved, reminder veya test olur.

[[certs]]

Sertifika doğrulanmasa bile okunur; güven sorunları bağlantı hatalarından ayrı gösterilir. Denetim helmsight sunucusundan yapılır; yani yalnızca helmsight’ın erişebildiği uç noktalar denetlenebilir.

[[actions]]

[prometheus]

scrape_configs:
  - job_name: helmsight
    scheme: https
    authorization:
      credentials_file: /etc/prometheus/helmsight.token
    static_configs:
      - targets: ["monitor.example.com"]

Sunulan metrikler helmsight_ önekini taşır: host_up, host_alerts_firing, cpu_percent{mode}, memory_*_bytes, load1/5/15, filesystem_{size,used,avail}_bytes{mount}, disk_{read,written}_bytes_per_second{device}, network_{receive,transmit}_bytes_per_second{interface}, tcp_connections{state}, pending_updates, pending_security_updates, reboot_required ve daha fazlası; hepsi host etiketiyle.

Komut satırı

Genel seçenekler: --config <yol>, --data-dir <dizin> (server.data_dir değerini geçersiz kılar; yapılandırma dosyası olmadan komutlar yerel kipin varsayılanı olan ~/.local/share/helmsight dizinini, root için /var/lib/helmsight dizinini kullanır), --log-format text|json.

Hiç kullanıcı yokken serve, ilk yöneticiyi tarayıcıda oluşturmak için tek kullanımlık bir kurulum bağlantısı (/setup#token=...) yazdırır.

Ortam değişkenleri

HTTP API

Web arayüzü, /api/v1 altındaki sürümlü JSON API’nin aynısını kullanır. OpenAPI belgesi /api/v1/openapi.json adresinde sunulur. Kimlik doğrulama için POST /api/v1/auth/login ile alınan oturum çerezini kullanın; durum değiştiren istekler GET /api/v1/auth/me yanıtında dönen X-CSRF-Token başlığını gerektirir. Canlı güncellemeler /api/v1/events adresinde sunucu gönderimli olaylar olarak sunulur. Duvar ekranları /api/v1/display/state adresini Authorization: Bearer <belirteç> başlığıyla çağırır. /healthz kimlik doğrulama olmadan ok döndürür.