QASIDA.API beží na Oracle Linux ako služba systemd. Obsahuje vlastný .NET runtime, .NET preto netreba inštalovať.
Pred inštaláciou overte, že prostredie spĺňa systémové požiadavky QASIDA.API a požiadavky na automatickú aktualizáciu.
| Oracle Linux | Unit API (Type=notify) |
Unit selfupdate (Type=oneshot) |
Pravidlo PolicyKit |
|---|---|---|---|
| OL8 (systemd 239) | ✅ | ✅ | ✅ |
| OL9 (systemd 252) | ✅ | ✅ | ✅ |
| OL10 (systemd 257) | ✅ | ✅ | ✅ |
Na OL8 (systemd 239) sa unit s
Type=execnenačíta. Unit API preto musí maťType=notify.
dnf install libicu libaio policycoreutils-python-utils unzip -y
Balík
libaiopotrebuje SQL*Plus z Oracle Instant Clientu (pozri Oracle Instant Client).
Štandardný inštalačný koreň je
/QASIDA. Upravte ho podľa prostredia zákazníka.
export TEMP=/xxx
export QASIDAAPI_USER=qasidaapi
export QASIDAAPI_BASE=/QASIDA/QasidaAPI
mkdir -p $QASIDAAPI_BASE
semanage fcontext -a -t bin_t "$QASIDAAPI_BASE(/.*)?"
restorecon -Rv $QASIDAAPI_BASE
Po prvom spustení skontrolujte zamietnutia SELinux:
ausearch -m AVC -ts recent
groupadd -r $QASIDAAPI_USER
useradd -r -g $QASIDAAPI_USER -s /bin/false $QASIDAAPI_USER
Inštalačný balík QASIDA.API (QasidaApi.zip) obsahuje podadresáre pre jednotlivé platformy. Rozbaľte len linuxovú časť API:
unzip -q $TEMP/QasidaApi.zip "Api/Linux/*" -d $TEMP/QasidaApi_extract
cp -r $TEMP/QasidaApi_extract/Api/Linux/. $QASIDAAPI_BASE/Api/
rm -rf $TEMP/QasidaApi_extract
Oracle Instant Client (vrátane SQL*Plus) sa dodáva ako samostatný balík InstantClient.zip (modul ORACLIENT v AsolHub) s rovnakými podadresármi pre jednotlivé platformy. SQL*Plus je potrebný pre aktualizácie databázových skriptov. Linuxovú časť rozbaľte do adresára InstantClient vedľa adresára Api:
unzip -q $TEMP/InstantClient.zip "Linux/*" -d $TEMP/InstantClient_extract
mkdir -p $QASIDAAPI_BASE/InstantClient
cp -r $TEMP/InstantClient_extract/Linux/. $QASIDAAPI_BASE/InstantClient/
rm -rf $TEMP/InstantClient_extract
restorecon -Rv $QASIDAAPI_BASE/InstantClient
Adresár
InstantClientnechajte vedľa adresáraApi($QASIDAAPI_BASE/InstantClient). Ak kľúčSystemMaintenance:SpinDatabaseUpdate:SqlPlusnie je nastavený alebo ukazuje na neexistujúci súbor, selfupdate hľadá SQL*Plus iba na tomto mieste (pozri appsettings.json).
chown $QASIDAAPI_USER:$QASIDAAPI_USER $QASIDAAPI_BASE -R
find $QASIDAAPI_BASE -type f -exec chmod 640 {} \;
find $QASIDAAPI_BASE -type d -exec chmod 750 {} \;
chmod 740 $QASIDAAPI_BASE/Api/Api
chmod 740 $QASIDAAPI_BASE/InstantClient/sqlplus
Počas selfupdate sa v
$QASIDAAPI_BASEautomaticky vytvoria pomocné adresáreApi_selfupdate_backupaApi_selfupdate_logs, ktoré sa po úspešnej aktualizácii zmažú. Súborappsettings.jsonsa po aktualizácii automaticky obnoví. AdresáreLogs,DataProtectionKeysaCertificatessa obnovia len vtedy, ak ležia v$QASIDAAPI_BASE/Api– ten aktualizácia zmaže a vytvorí znova. Pri štandardnom rozložení ležia vedľa adresáraApi(pozri Nastavenia selfupdate), takže sa ich aktualizácia vôbec nedotkne.
Po výmene súborov selfupdate znova nastaví štandardné oprávnenia (adresáre
0750, súbory0640/0740). AdresáreDataProtectionKeysaCertificatespotom sprísni na0700/0600– kľúče a privátny kľúč klientskeho certifikátu nesmie čítať skupina.
Pri aktualizácii sa zachová iba jeden adresár s certifikátmi: ten, ktorý je nastavený pre zbernicu
QasidaHub(RabbitMqCertificates:Path). Ak iný modul s RabbitMQ používa vlastný adresár s certifikátmi, ktorý tiež leží v$QASIDAAPI_BASE/Api, tento adresár sa nezachová a jeho obsah vrátane privátneho kľúča sa pri ďalšej aktualizácii stratí (do logu sa zapíše upozornenie). Všetky adresáre s certifikátmi preto nechajte mimo adresáraApi.
vi /etc/systemd/system/AssecoQasidaAPI.service
Dokumentácia systemd: https://www.freedesktop.org/software/systemd/man/latest
Cesty v WorkingDirectory, ExecStart, LD_LIBRARY_PATH a ReadWritePaths upravte iba vtedy, ak sa inštalácia odlišuje od štandardného rozloženia (
$QASIDAAPI_BASE). Uvedené hodnoty mu už zodpovedajú.
[Unit]
Description=Asseco Solutions - Qasida API Service
After=network-online.target
Wants=network-online.target
[Service]
Type=notify
Restart=on-failure
RestartSec=5
# Premenne prostredia
Environment="ASPNETCORE_ENVIRONMENT=Production"
# Kniznice Oracle Instant Clientu pre SQL*Plus
Environment="LD_LIBRARY_PATH=/QASIDA/QasidaAPI/InstantClient"
# Pouzivatel a skupina
User=qasidaapi
Group=qasidaapi
# Pracovny adresar
WorkingDirectory=/QASIDA/QasidaAPI/Api
# Spustenie aplikacie
ExecStart=/QASIDA/QasidaAPI/Api/Api
# Riadenie procesu
KillMode=mixed
TimeoutStopSec=30
# Systemove logovanie do /var/log/messages
# Log aplikacie je v adresari Logs
StandardOutput=null
StandardError=null
# Bezpecnost
# Spravu sluzieb povoluje PolicyKit (nie sudo), preto moze ostat NoNewPrivileges zapnute:
# zastavenie a spustenie unitov ide cez D-Bus API systemd a nepotrebuje SUID program.
ReadWritePaths=/QASIDA/QasidaAPI
NoNewPrivileges=yes
PrivateTmp=yes
ProtectSystem=strict
ProtectHome=yes
RestrictSUIDSGID=yes
LockPersonality=yes
UMask=0077
[Install]
WantedBy=multi-user.target
chmod 644 /etc/systemd/system/AssecoQasidaAPI.service
systemctl daemon-reload
systemctl enable AssecoQasidaAPI.service
systemctl start AssecoQasidaAPI.service
Overenie zabezpečenia:
systemd-analyze security AssecoQasidaAPI.service | grep -i newpriv
vi /etc/systemd/system/AssecoQasidaAPI-SelfUpdate.service
[Unit]
Description=Asseco Solutions - Qasida API Selfupdate Service
After=network-online.target
[Service]
Type=oneshot
# Pouzivatel a skupina
User=qasidaapi
Group=qasidaapi
# Pracovny adresar (pevne umiestnenie nastroja selfupdate)
WorkingDirectory=/QASIDA/QasidaAPI/SelfUpdate
# Spustenie nastroja selfupdate.
# Nastroj nema ziadne parametre: API sem skopiruje nastroj z nove stiahnuteho balika
# a parametre zapise do selfupdate.json vedla neho. Vdaka prikazu bez parametrov
# staci na povolenie spustenia jedno pevne pravidlo PolicyKit.
ExecStart=/QASIDA/QasidaAPI/SelfUpdate/SelfUpdate
# Bezpecnost
ReadWritePaths=/QASIDA/QasidaAPI
NoNewPrivileges=yes
PrivateTmp=yes
ProtectSystem=strict
ProtectHome=yes
RestrictSUIDSGID=yes
LockPersonality=yes
UMask=0077
Kľúč
QasidaUpdate:SelfUpdateInstallPathštandardne nie je nastavený a ukazuje na/QASIDA/QasidaAPI/SelfUpdate, čo zodpovedá WorkingDirectory a ExecStart vyššie. Nechajte ich tak. AkQasidaUpdate:SelfUpdateInstallPathvappsettings.jsonzmeníte, upravte podľa neho aj WorkingDirectory a ExecStart.
User=/Group=unitu selfupdate MUSÍ byť ten istý účet ako v unite API (qasidaapi).
Po každej aktualizácii selfupdate sprísni oprávnenia adresára API (adresáre0750, súbory0640/0740) a ostatným (others) odoberie všetok prístup. Nové súbory patria používateľovi, pod ktorým beží unit selfupdate. Ak sa líši od používateľa API (napr. unit beží akoroot), API nemôže čítať vlastné súbory a nenaštartuje. Overenie stavu potom zlyhá a ani návrat k pôvodnej verzii to nenapraví, lebo obnovené súbory majú rovnakého nesprávneho vlastníka. Výsledného vlastníka cieľového adresára selfupdate zapisuje dojournalctl -u AssecoQasidaAPI-SelfUpdate.service.
chmod 644 /etc/systemd/system/AssecoQasidaAPI-SelfUpdate.service
systemctl daemon-reload
Unit selfupdate sa zámerne nezapína (
systemctl enable), takže sa nespúšťa pri štarte systému a nenačíta ho žiadny target.systemctl enableunit len zaregistruje na automatické spustenie, nespúšťa ho. Unit má bežať iba vtedy, keď je pripravená aktualizácia: bežiaci procesAssecoQasidaAPIvtedy sám spustísystemctl start AssecoQasidaAPI-SelfUpdate.service(povolené pravidlom PolicyKit nižšie, bezsudo). Keďže má unitType=oneshot, prebehne raz a skončí.
Služba API musí vedieť spravovať svoje units bez sudo. Vytvorte súbor s pravidlom:
vi /etc/polkit-1/rules.d/50-qasidaapi-selfupdate.rules
// Pravidlo PolicyKit: neprivilegovanemu pouzivatelovi 'qasidaapi' povoli spustat, zastavovat
// a restartovat iba units Qasida API, bez sudo a bez hesla.
//
// Umiestnenie: /etc/polkit-1/rules.d/50-qasidaapi-selfupdate.rules (prava 0644, vlastnik root)
polkit.addRule(function(action, subject) {
if (action.id == "org.freedesktop.systemd1.manage-units" &&
subject.user == "qasidaapi") {
var unit = action.lookup("unit");
if (unit == "AssecoQasidaAPI.service" ||
unit == "AssecoQasidaAPI-SelfUpdate.service") {
return polkit.Result.YES;
}
}
return polkit.Result.NOT_HANDLED;
});
chmod 644 /etc/polkit-1/rules.d/50-qasidaapi-selfupdate.rules
polkitdnetreba reštartovať – pravidlá sa načítajú automaticky.
Overenie – spustenie aj zastavenie musí pod používateľom qasidaapi prejsť bez hesla:
sudo -u qasidaapi systemctl start AssecoQasidaAPI.service; echo "start=$?"
sudo -u qasidaapi systemctl stop AssecoQasidaAPI.service; echo "stop=$?"
sudo -u qasidaapi systemctl start AssecoQasidaAPI.service; echo "start=$?"
Konfigurácia závisí od integrácie a spôsobu použitia konkrétnej inštalácie.
Predpoklady:
appsettings.jsonso správnou konfiguráciou,- databázový používateľ aplikácie s potrebnými právami,
- heslo administrátora aplikačnej databázy – používateľa
DL.
Vzor všetkých nastavení je v súbore appsettings.sample v inštalačnom balíku. TCP port a povolené adresy pre jednotlivé prostredia uvádza stránka Minimálne systémové požiadavky.
Urls(kľúč na najvyššej úrovni, napr."Urls": "http://*:8888") – adresy, na ktorých API počúva. Viac adries sa oddeľuje bodkočiarkou bez medzier. Vappsettings.sampletento kľúč nie je – doplňte ho s portom tejto inštalácie.
AllowedHosts(kľúč na najvyššej úrovni) – sieťové adresy, pod ktorými je aplikácia dostupná.
Serilog:WriteTo, sink"Name": "File",Args.path– úplná cesta k log súboru. Nepovinné, predvolene/QASIDA/QasidaAPI/Logs/QasidaApi.txt. Nastavte ho len vtedy, ak sa inštalácia odlišuje od štandardného rozloženia, a vždy ako absolútnu cestu. Relatívna cesta sa vyhodnotí voči pracovnému adresáru procesu ($QASIDAAPI_BASE/ApipodľaWorkingDirectoryv unite), teda v adresári, ktorý selfupdate maže – nie v adresáriLogsvedľa neho.
SystemMaintenance:SpinDatabaseUpdate:SqlPlus– úplná cesta k SQL*Plus z Oracle Instant Clientu:"SqlPlus": "/QASIDA/QasidaAPI/InstantClient/sqlplus". Potrebná pre aktualizácie databázových skriptov. Bez tohto kľúča sasqlplushľadá vPATHpoužívateľa služby. Ak kľúč nie je nastavený alebo sa nedá použiť, selfupdate ho pri ďalšej aktualizácii nastaví na$QASIDAAPI_BASE/InstantClient/sqlplus– ak tento súbor existuje aappsettings.jsonneobsahuje komentáre.
Urls, AllowedHosts – povolené sú záznamy vo forme IP adresy alebo DNS mena.
Ak
SelfUpdateInstallPath,ClientInstallFilesPath,DownloadInstallFilesPath,DataProtectionPathaleboRabbitMqCertificates:Pathnastavíte explicitne, použite absolútnu cestu. Relatívna hodnota sa vyhodnotí voči samotnému adresáruApi, nie vedľa neho – napr.RabbitMqCertificates:Paths hodnotouCertificatesznamená$QASIDAAPI_BASE/Api/Certificates, teda adresár, ktorý selfupdate maže. Toto správanie existuje kvôli starším inštaláciám v IIS a pri inštalácii podľa tohto návodu sa nepoužíva.
AppManagement:DataProtectionPath – nepovinné, predvolene /QASIDA/QasidaAPI/DataProtectionKeys. Nechajte nenastavené, pokiaľ to nie je naozaj potrebné. Bez hodnoty API pri prvom štarte automaticky prenesie kľúče a súbor _secrets.xml zo starého umiestnenia v adresári Api. Po nastavení kľúča sa automatický prenos už nevykoná – existujúce súbory s kľúčmi a heslami presuňte ručne, inak sa vytvorí nová prázdna sada kľúčov a všetky uložené heslá a pripájacie reťazce budú nečitateľné.0700 a jeho súbory na 0600.Certifikáty pre šifrovanú komunikáciu (mTLS) s RabbitMQ sa čítajú zo súborov v adresári RabbitMqCertificates:Path (predvolene /QASIDA/QasidaAPI/Certificates), nikdy z úložiska certifikátov operačného systému.
RabbitMqCertificates:ClientCertificateFileName, predvolene client.pfx.RabbitMqCertificates:CaCertificateFileName, predvolene ca.pem, inak ca.crt. Serveru sa dôveruje iba na základe tohto certifikátu, úložiská certifikátov operačného systému sa nepoužívajú.RabbitMqCertificates:ClientCertificatePassword. Namiesto otvoreného textu ho radšej uložte šifrovane cez PUT /api/v1/Management/SaveSecret s kódom RabbitMqCertificates:ClientCertificatePassword. Uložené heslo má prednosť a použije sa pri ďalšom pokuse o pripojenie bez reštartu API.Certifikáty sa načítajú raz, pri prvom pokuse o pripojenie. Výmena súborov (napr. po obnove certifikátu) sa preto prejaví až po reštarte služby API.
Jednotlivé moduly môžu tieto spoločné nastavenia prepísať vlastnými kľúčmi (napr. AsolLicServerUpdateLicenseBackgroundService:RabbitMqCertificatesPath) – úplný zoznam je v appsettings.sample. Ako je uvedené v časti Oprávnenia, pri aktualizácii sa zachová iba adresár pre QasidaHub.
Databázový účet, pod ktorým sa API pripája k databáze, musí existovať a mať pridelené potrebné role.
Všetky adresáre nižšie sú predvolene adresáre s rovnakým názvom vedľa $QASIDAAPI_BASE/Api (teda $QASIDAAPI_BASE/Api/../<názov>). Pri štandardnom rozložení preto netreba nastavovať žiadny z týchto kľúčov – nastavte ho, len ak sa dané umiestnenie naozaj musí líšiť. Všetky pokrýva ReadWritePaths=/QASIDA/QasidaAPI v units vyššie.
| Kľúč | Predvolená hodnota | Význam |
|---|---|---|
QasidaUpdate:ApiServiceName |
AssecoQasidaAPI |
Názov unitu API. |
QasidaUpdate:SelfUpdateServiceName |
AssecoQasidaAPI-SelfUpdate |
Názov unitu selfupdate. |
QasidaUpdate:SelfUpdateInstallPath |
/QASIDA/QasidaAPI/SelfUpdate |
Musí zodpovedať WorkingDirectory/ExecStart unitu selfupdate. Nikdy nie adresár API ani koreň disku. |
QasidaUpdate:ClientInstallFilesPath |
/QASIDA/QasidaAPI/ClientInstallFiles |
Adresár, z ktorého API poskytuje súbory klienta (napr. sieťové zdieľanie). Musí byť zapisovateľný, nikdy nie adresár API ani koreň disku. Pred každým zverejnením sa celý jeho obsah zmaže. |
QasidaUpdate:DownloadInstallFilesPath |
/QASIDA/QasidaAPI/DownloadInstallFiles |
Adresár, do ktorého sa sťahujú inštalačné balíky z AsolHub. Musí byť zapisovateľný, nikdy nie adresár API ani koreň disku a nesmie ležať pod /tmp – oba units majú PrivateTmp=yes. |
User=/Group= unitu selfupdate |
qasidaapi |
Musí sa zhodovať s User=/Group= unitu API. Sprísnenie oprávnení po aktualizácii odoberie prístup ostatným; pri rozdielnom používateľovi API nemôže čítať vlastné súbory a ani návrat k pôvodnej verzii to nenapraví. |
Každá ďalšia inštancia QASIDA.API potrebuje vlastný inštalačný adresár, vlastné units a vlastné nastavenia. Selfupdate názov služby nezisťuje sám – bez nasledujúcich kľúčov by pracoval so službou primárnej inštancie.
Príklad pre inštanciu na porte 9999:
/QASIDA/QasidaAPI_9999 (postup inštalácie s QASIDAAPI_BASE=/QASIDA/QasidaAPI_9999),AssecoQasidaAPI_9999.service a AssecoQasidaAPI_9999-SelfUpdate.service – v oboch upravte cesty v WorkingDirectory, ExecStart, ReadWritePaths a v unite API aj LD_LIBRARY_PATH na adresár tejto inštancie,appsettings.json tejto inštancie:
"Urls": "http://*:9999",QasidaUpdate:ApiServiceName = AssecoQasidaAPI_9999,QasidaUpdate:SelfUpdateServiceName = AssecoQasidaAPI_9999-SelfUpdate, if (unit == "AssecoQasidaAPI.service" ||
unit == "AssecoQasidaAPI-SelfUpdate.service" ||
unit == "AssecoQasidaAPI_9999.service" ||
unit == "AssecoQasidaAPI_9999-SelfUpdate.service") {
systemctl restart AssecoQasidaAPI.service
Príklady používajú predvolený TCP port QASIDA.API. Podľa potreby ho upravte pre konkrétnu inštaláciu.
curl http://localhost:8888/health
curl http://localhost:8888/version
journalctl -u AssecoQasidaAPI-SelfUpdate.service
Príkaz musí vypísať verziu SQL*Plus. Chyba o chýbajúcej zdieľanej knižnici (napr. libaio.so.1) znamená chýbajúci systémový balík alebo nesprávne LD_LIBRARY_PATH:
sudo -u qasidaapi env LD_LIBRARY_PATH=/QASIDA/QasidaAPI/InstantClient /QASIDA/QasidaAPI/InstantClient/sqlplus -V
libicu, libaio, policycoreutils-python-utils (obsahuje semanage) a unzip (dnf install libicu libaio policycoreutils-python-utils unzip -y)qasidaapi$QASIDAAPI_BASE vytvorený so správnym vlastníkom a oprávneniamiausearch -m AVC -ts recent)$QASIDAAPI_BASE/Api/$QASIDAAPI_BASE/InstantClient/, sqlplus je spustiteľný (0740)AssecoQasidaAPI.service v /etc/systemd/system/, spustený systemctl daemon-reload, služba zapnutá a spustenáLD_LIBRARY_PATH na $QASIDAAPI_BASE/InstantClientType=notify a zapnuté zabezpečenie: systemd-analyze security AssecoQasidaAPI.service | grep -i newpriv → NoNewPrivileges=yesAssecoQasidaAPI-SelfUpdate.service v /etc/systemd/system/, spustený systemctl daemon-reload (unit nie je zapnutý)User=/Group= unitu selfupdate sa zhoduje s unitom API (qasidaapi); po skúšobnej aktualizácii overiť vlastníka cieľového adresára v journalctl -u AssecoQasidaAPI-SelfUpdate.service50-qasidaapi-selfupdate.rules v /etc/polkit-1/rules.d/ (práva 0644, vlastník root)sudo -u qasidaapi systemctl start/stop AssecoQasidaAPI.service vráti 0 bez heslaappsettings.json so správnou konfiguráciouSystemMaintenance:SpinDatabaseUpdate:SqlPlus nastavený na $QASIDAAPI_BASE/InstantClient/sqlplus; sqlplus -V prejde pod používateľom qasidaapi (pozri kontrolu SQL*Plus)QasidaUpdate:SelfUpdateInstallPath zodpovedá WorkingDirectory/ExecStart unitu selfupdate; ClientInstallFilesPath/DownloadInstallFilesPath na predvolených hodnotách, ak sa rozloženie neodlišuje od štandardu (a DownloadInstallFilesPath neleží pod /tmp)AppManagement:DataProtectionPath nenastavený (alebo ručne presunuté existujúce súbory s kľúčmi a heslami)client.pfx, ca.pem/ca.crt) v RabbitMqCertificates:Path (predvolene /QASIDA/QasidaAPI/Certificates), mimo adresára ApiQasidaUpdate:ApiServiceName a QasidaUpdate:SelfUpdateServiceName a units doplnené v pravidle PolicyKitcurl http://localhost:8888/health