Konfiguracija prehoda

Vsak konfiguracijski ključ prehoda pod Gateway s privzeto vrednostjo in učinkom. Vrednosti prihajajo iz appsettings.json, appsettings.<okolje>.json, okoljskih spremenljivk, zagonskih parametrov in appsettings.Local.json; pri istem ključu velja poznejši vir, appsettings.Local.json ima torej prednost pred vsemi drugimi. S skrbniško shrambo so obratovalni podatki (viri podatkov, pravila, dodelitve) shranjeni v njej namesto v datoteki. Konfiguracija, ki ne opravi preverjanja ob zagonu, prepreči zagon; dnevnik navede vsako napako.

{
  "Gateway": {
    "Databases": [ { "Name": "fachdaten", "Provider": "sqlserver", "ConnectionString": "…" } ],
    "MetadataCacheSeconds": 300,
    "ResponseCompression": true,
    "Security": { "AuthMode": "ApiKey, Windows", "ApiKeys": [], "Clients": [] },
    "Limits": { "DefaultTop": 1000, "MaxTop": 10000 },
    "Store": { "Path": "store/gateway.db", "MasterKey": "env:WKL_GW_MASTER_KEY" },
    "Certificate": { "Subject": "daten.example.com" },
    "Downloads": { "Path": "downloads" }
  },
  "Kestrel": { "Endpoints": { } }
}

Kot okoljska spremenljivka z dvojnim podčrtajem: Gateway__Databases__0__ConnectionString.

Datoteke appsettings*.json in vsaka relativna pot na tej strani se nanašajo na koren vsebine prehoda: kot storitev Windows je to programska mapa, sicer delovna mapa ob zagonu (pod systemd WorkingDirectory). Zagonski parameter --contentRoot <mapa> ga nastavi izrecno.

appsettings.json opisuje obliko in privzete nastavitve ter ne vsebuje niza povezave in ne ključa. Oboje pripada delujočemu primerku prehoda:

• appsettings.Local.json v korenu vsebine: prehod jo prebere v vsakem okolju; pri razvoju je izključena iz gita, pri obratovanju pa vsebuje na primer zamenjavo glavnega ključa;
• okoljske spremenljivke (Gateway__Databases__0__ConnectionString) pri delovanju prehoda.

Ključi se nastavljajo izključno kot sklic:

Sklic, ki ga ni mogoče razrešiti, prepreči zagon. To je namerno: nenastavljena okoljska spremenljivka bi se sicer pokazala šele kot klicatelj, ki se brez pojasnila ne more prijaviti.

Stisnjeni odgovori (Gateway:ResponseCompression, privzeto true): če klicatelj navede Accept-Encoding, prehod vsak odgovor stisne z Brotli ali gzip na najhitrejši stopnji, tudi prek HTTPS. JSON v vsaki vrstici ponavlja imena stolpcev, zato se dobro stisne; prek počasne povezave to občutno skrajša nalaganje velikih tabel. Gonilnik in Power Query odgovore razširita sama. Napad BREACH, ki izkorišča stisnjene odgovore HTTPS (RFC 7457, razdelek 2.6), potrebuje zaupno vrednost (geslo ali ključ) v istem odgovoru kot besedilo, ki ga izbere napadalec, in brskalnik s samodejno prijavo. Podatkovni odgovori vsebujejo le zahtevane podatke; odgovori na izmenjavo in nastavitev 2FA ter na izdajo ključa pa vsebujejo ključe ali podatke za izračun kod in so prav tako stisnjeni. Če z istega izvora ponujate spletno aplikacijo s prijavo Windows in želite to tveganje izključiti, stikalo izklopite.

En vnos na alias. S skrbniško shrambo so viri podatkov tam (množica DataSources).

Alias (Name) postane del vsakega naslova (/odata/v4/<alias>/…, /api/v1/cf/<alias>/…) in se primerja s pravili klicateljev. Zato zanj velja isto pravilo kot za navaden identifikator SQL Serverja, brez dela s shemo:

Kršitev prepreči zagon s sporočilom „'<Name>' ist kein zulaessiger Aliasname“ ('<Name>' ni dovoljeno ime aliasa). Prek skrbniškega vmesnika (množica DataSources) vnos ni sprejet: odgovor je 422 z istim sporočilom, shramba pa ostane nespremenjena.

Vir pravila v kodi: GatewayIdentifier.IsValidPart v paketu specifikacije vmesnika Wkl.Data.Gateway.Contracts; aplikacija, ki uporablja paket, lahko pred shranjevanjem pokliče prav to metodo.

Omejitve virov nastavite v Gateway:Limits in jih lahko prilagodite za posamezne objekte. Vzorec se primerja z <alias>/<vrsta>/<objekt>; velja prvi ustrezni vnos v nastavljenem vrstnem redu.

Prehod ob zagonu išče v dveh mapah, vsakič z zgradbo <mapa>/<oznaka>/<različica>/ in datoteko provider.json v njej: v mapi providers poleg programa (priloženi ponudniki; posodobitev jo nadomesti) in pod Path (v vaši pristojnosti, ob posodobitvi ostane). Paket se naloži le, če se ime mape in identifikator ujemata, se ujema različica specifikacije vmesnika ponudnika, se ujema platforma in vsaka datoteka ustreza svoji kontrolni vsoti (SHA-256). Paket, ki ga namestite sami, ne sme uporabiti niti identifikatorja niti drugega imena priloženega ponudnika.

Ponudnik teče v prehodu z njegovimi pravicami. Pisati v obe mapi smejo le računi, ki smejo spreminjati tudi sam prehod; prek omrežja paketa ni mogoče odložiti.

{
  "Gateway": {
    "Store": {
      "Path": "store/gateway.db",
      "MasterKey": "env:WKL_GW_MASTER_KEY",
      "PollSeconds": 5
    }
  }
}

SetupKey in EmergencyAccess ne obstajata več. Nastavitveni ključ je prek HTTPS veljal z vsakega računalnika in je samodejno znova postal veljaven, ko se noben skrbnik ni več mogel prijaviti, in to brez 2FA. Prvega skrbnika zdaj ustvarite z ukazom init-admin na strežniku. Konfiguracija, ki ti vrednosti še navaja, se še vedno zažene; prehod ob zagonu sporoči, da ju ne upošteva.

Dnevnik prijav v datoteki dnevnikov poleg skrbniške shrambe, pravila prijave in sporočanje njihovih ugotovitev; brez shrambe prehod ne beleži ničesar.

"Gateway": {
  "SignInLog": {
    "TimeZone": "Europe/Ljubljana",
    "Networks": [ { "Name": "Obrat 3", "Network": "10.3.0.0/16" } ],
    "GeoIp": { "StaleDays": 60 },
    "Alerts": { "Recipients": [ "varnost@example.com" ], "DigestHour": 7 }
  }
}

Vir geolokacijske zbirke ni nastavljen tukaj, temveč v shrambi (set-geoip-source), ker k njemu lahko spada licenčni ključ in ga mora spreminjati skrbništvo.

Sporočanje ugotovitev. Vsaka ugotovitev je zapisana v dnevniku prehoda (act kot opozorilo, ask kot informacija) s pravilom, časom in osebo. Z Alerts:Recipients prehod vsako ugotovitev stopnje act dodatno takoj pošlje po pošti, ugotovitve stopnje ask pa enkrat na dan v zbirnem sporočilu. Sporočilo navede pravilo, čas, osebo in številko ugotovitve, nikoli naslova, države ali ključa; ti so na voljo le upravičenim osebam v skrbniškem vmesniku. Zbirno sporočilo, ki ga poštni strežnik ni sprejel, prehod pošlje znova naslednji dan.

Pošiljanje pošte za sporočanje ugotovitev. Brez vnosa prehod ne pošilja pošte.

"Gateway": {
  "Mail": {
    "Transport": "smtp",
    "Host": "mail.example.com",
    "Port": 587,
    "Encryption": "starttls",
    "Username": "gateway@example.com",
    "FromAddress": "gateway@example.com",
    "FromName": "Podatkovni prehod",
    "PublicBaseUrl": "https://gateway.example.com"
  }
}

Nastavitev, s katero pošiljanje ni mogoče, prepreči zagon in navede razlog; enako velja za Alerts:Recipients brez Transport. none brez prejemnikov je običajno stanje.

Dnevnik obremenitve v datoteki dnevnikov poleg skrbniške shrambe; brez shrambe prehod ne beleži ničesar.

"Gateway": {
  "LoadLog": { "PersonDays": 3, "SlowMilliseconds": 2000 }
}

Zahtev na /health prehod ne beleži. V eni minuti hrani največ 5.000 različnih oblik in 2.000 počasnih zahtev; preostalih ne šteje in to sporoči v svojem dnevniku.

"Gateway": {
  "Certificate": { "Subject": "daten.example.local", "StoreLocation": "LocalMachine", "StoreName": "My" }
}

"Gateway": {
  "Certificate": { "File": "zertifikat/gateway.pfx", "Password": "env:WKL_GW_CERT_PASSWORD" }
}

Učinek in zamenjavo brez ponovnega zagona opisuje Nastavitev protokola HTTPS in potrdila.

Modul za posodobitve namešča posodobitve v podatkovne zbirke, za katere ima ta mapa zaščiteno konfiguracijo.

Konfiguracija velja samo, če datoteko in mapo lahko spreminjajo le skrbniki in SYSTEM (račun storitve ju bere) in se ime datoteke ujema z id; sicer modul podatkovno zbirko izpusti in razlog navede v update-databases. Modul se poveže z lastno prijavo SQL Server, nikoli z računom storitve; geslo ni v datoteki, temveč v spremenljivki okolja ali v datoteki, ki jo lahko berejo le skrbniki, SYSTEM in račun storitve:

{
  "format": 1, "id": "demo-prod", "gatewayAlias": "demo", "product": "Demo", "dialect": "sqlserver",
  "connection": { "string": "Server=sql01;Database=Demo;User ID=wkl_update;Encrypt=True",
                  "secret": "file:C:\\ProgramData\\Wkl.Data.Gateway\\secrets\\demo-update.txt" },
  "keys": [ "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE…" ],
  "inbox": "D:\\Updates\\Demo", "archive": "D:\\Updates\\Demo-Archiv",
  "backup": { "mode": "native", "target": "D:\\Sicherung" }
}

keys so javni ključi izdajateljev, ki jim podatkovna zbirka zaupa. Pri backup.mode native modul pred vsakim paketom naredi varnostno kopijo v mapo backup.target na strežniku podatkovne zbirke; pri external za varnostne kopije poskrbi IT sam in vsak paket čaka na potrditev. starterSource (neobvezno) je mapa, v katero modul zapiše stanje sheme za WKL Bootstrapper. Če v mapi ni datoteke, modul ne naredi ničesar.

Hramba varnostnih kopij. Po vsaki novi varnostni kopiji modul izbriše starejše kopije iste podatkovne zbirke, vendar samo kopijo, ki ima vsaj BackupKeepCount novejših (privzeto 10) in je starejša od BackupKeepDays dni (privzeto 30; 0: šteje samo število). Najnovejših BackupKeepCount torej vedno ostane. Obe vrednosti nastavite v množici `UpdateSettings`. Upoštevane so samo datoteke, ki jih je ustvaril modul sam (<zbirka>-<llllMMdd-uummss>-<paket>.bak, čas v UTC); druge datoteke v mapi ostanejo nedotaknjene. Modul briše prek datotečnega sistema in samo, če pod backup.target vidi pravkar zapisano kopijo: na istem računalniku kot SQL Server ali v mapi v skupni rabi, ki jo dosežeta oba (\\strežnik\mapa\...). Če je mapa samo na drugem strežniku podatkovne zbirke, modul to enkrat zapiše v dnevnik storitve in vse kopije pusti; počisti jih IT.

Sporočila. Kaj se zgodi s paketom, modul sporoči po poteh, ki so za podatkovno zbirko vklopljene v množici `UpdateSettings`:

• Dnevnik dogodkov (privzeto): dnevnik aplikacij, vir Wkl.Data.Gateway. Vir registrira namestitev (setup-host); če ga ni, je to enkrat zapisano v dnevniku storitve.
• Datoteka: za vsak dan (UTC) datoteka %ProgramData%\Wkl.Data.Gateway\logs\updates\<LLLL-MM-DD>.jsonl z enim objektom JSON v vsaki vrstici (utc, database, product, event, file, schema, code, message). Mapa je nespremenljiva; modul datotek nikoli ne izbriše.
• Pošta: prejemnikom podatkovne zbirke prek poštnih nastavitev storitve (`Gateway:Mail`), z enakim besedilom kot v dnevniku dogodkov. Pošta se pošlje zunaj prehoda; počasen ali nedosegljiv poštni strežnik ne zadrži nobenega paketa.

Čakanje modul sporoči samo, ko se spremeni njegov razlog, ne ob vsakem prehodu.

Naslovi poslušanja in fiksno potrdilo po pravilih ASP.NET Core (Kestrel:Endpoints); glejte Nastavitev protokola HTTPS in potrdila. Brez tega razdelka velja --urls.

• Preverjanje ob zagonu zavrne protislovne nastavitve, namesto da bi izbralo eno od njih: podvojene ključe, dve pravili enega klicatelja za isti alias, sql na pravilu samo za branje, omrežje z nastavljenimi biti gostitelja, RequireTotp za ključe storitve, neznane račune Windows.
• SqlLogin v AuthMode zahteva vsaj en vir podatkov z AllowSqlLogins in vsaj en vnos pod SqlLogins. Brez skrbniške shrambe manjkajoči podatek prepreči zagon. S skrbniško shrambo se prehod zažene in manjkajočo nastavitev zapiše v dnevnik, ker je stikalo in preslikave tam mogoče nastaviti šele po vklopu postopka; do tedaj se prijava SQL Server konča z 401. Obratno preverjanje ob zagonu in skrbništvo zavrneta AllowSqlLogins in preslikave brez vklopljenega postopka. Vrstni red korakov: Nastavitev prijave z računom SQL Server.
• Spremenjena konfiguracijska datoteka začne veljati šele po ponovnem zagonu; spremembe v skrbniški shrambi veljajo takoj.

Alias z lastnimi stavki in klicatelj, ki jih sme uporabljati:

{
  "Gateway": {
    "Databases": [
      { "Name": "fachdaten", "Provider": "sqlserver", "ConnectionString": "…",
        "AllowPassThrough": true }
    ],
    "Security": {
      "Clients": [
        { "Id": "auswertung", "Databases": [ "fachdaten" ],
          "Resources": [ "views", "sql" ], "Verbs": [ "GET", "POST" ], "ReadOnly": false }
      ]
    }
  }
}

• Skrbniška shramba in glavni ključ
• Ukazi na strežniku