12.1. Technická dokumentace

12.1.1. Instalace

Zdrojový kód je kompilován pomocí Apache Maven: mvn clean package -DskipTests

Zkompilovaná aplikace je zabalena v spustitelném archival-storage.jar souboru.

Závislosti:

PostgreSQL (verze 15 a vyšší)

Java 17+ (OpenJDK)

ActiveMQ 6.x (volitelné)

ActviveMQ je použito pro distribuci operací z Archival Storage do logických úložišť - každé logické úložiště má svou persistentní frontu.

Defaultně je použit embedded ActiveMQ broker, v tomto případě není třeba nic instalovat ani konfigurovat. Data fronty jsou uložena v složce data/kahadb v pracovním adresáři aplikace Archival Storage. Pokud je to potřeba je možné tento adresář změnit v application.yml

Standalone služba

Pro podporu monitoringu a správy front je možné nainstalovat ActiveMQ jako standalone aplikaci. Pro stažení může být použit např. tento odkaz: https://activemq.apache.org/components/classic/download/

Při spuštění v standalone režimu jsou data defaultně uložena v složce data/kahadb v pracovním adresáři aplikace ActiveMQ. V konfiguračním souboru aplikace Archival Storage je v tomto případě nutno nastavit: spring.activemq.broker-url: tcp://localhost:61616 Defaultní port ActiveMq je 61616. Webové rozhraní je defaultně na adrese http://localhost:8161/admin, jméno:heslo je admin:admin .

V konfiguračním souboru activemq.xml je nutné zadefinovat podporu prioritizace pro fronty:

<broker>
 <destinationPolicy>
  <policyMap>
   <policyEntries>
    <policyEntry queue="archival-storage.*" prioritizedMessages="true" useCache="false" expireMessagesPeriod="0" queuePrefetch="1"/>

Při přechodu z jednoho režimu na druhý (Embedded <-> Standalone) je možné při vypnutém systému překopírovat datový obsah a neztratit tak data fronty.

Spuštění aplikace z příkazové řádky

Restartování aplikace spuštěné přímo z příkazové řádky:

pomocí ps xw nalézt PID JAVA procesu archival-storage.jar

kill <PID>

nohup java -jar -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005 archival-storage.jar $> arcstorage.log

agentlib:jdwp lze vypustit, slouží pro možnost remote debuggingu

pracovní adresář je automaticky adresář z nějž je aplikace spuštěna, lze změnit přepínačem -Duser.dir={cesta}

Spuštění aplikace jako služby

archival-storage.service - vzorový konfigurační soubor pro systemd službu

[Unit]
Description=Archival Storage
After=syslog.target

[Service]
Type=simple
User=ais
Group=ais
WorkingDirectory=/opt/ais/archival-storage
ExecStart=/opt/ais/archival-storage/archival-storage.jar
SuccessExitStatus=143

[Install]
WantedBy=multi-user.target

archival-storage.conf - konfigurační soubor systemd služby - vložit do pracovního adresáře aplikace

JAVA_OPTS="-XX:MaxMetaspaceSize=800M -Xmx4096M

12.1.2. Konfigurace

Logování

Logy se ukládají do složky {pracovní adresář}/../logs

Systém

Aplikace je konfigurovatelná skrze soubor application.yml který se nachází v pracovním adresáři. Konfigurační hodnoty v tomto souboru překrývají defaultní konfigurační hodnoty v souboru application.yml nacházejícím se ve složce src/main/resources. Po přepsání souboru je pro projevení změn nutné aplikaci restartovat. Při konfigurování atributů cest na souborovém systému lze zadat relativní cestu vzhledem k pracovnímu adresáři.

server:
  port: 8081
  tomcat:
# maximální počet aktivních vláken aplikačního serveru - počet HTTP požadavků které mohou být odbaveny paralelně
    max-threads: 70
# velikost fronty aplikačního serveru - při vyčerpání aktivních vláken jsou požadavky řazeny do fronty, po naplnění fronty je každý další požadavek zamítnut, velikost fronty je součtem následujících dvou hodnot
    accept-count: 1 # min 1
    max-connections: 99 # min 1
spring:
  activemq:
# URL ActiveMQ broker serveru, vm://localhost pro vnořené ActiveMQ, pro standalone službu např. tcp://localhost:61616
    broker-url: vm://localhost
# pracovní adresář aplikace do kterého jsou mimo jiné nahrávány objekty při cestě do úložiště a z úložiště
  servlet.multipart.location: tmp
# databáze
  datasource:
    url: jdbc:postgresql://localhost:5432/{DB name}
    username: {DB username}
    password: {DB password}
    tomcat:
# default = 100, hodnota musí být vhodně nastavena vzhledem k celkovému počtu vláken které v aplikaci mohou synchronně běžet a s ohledem na PostgreSQL max_conn
      max-active: 100
# default = 10, aplikace si již při startu rezervuje 10 PostgreSQL spojení
      initial-size: 10
# mail - konfigurace služby
 mail: 
    host: smtp.gmail.com
    port: 465
    username: {sender mail username}
    password: {sender mail password}
    protocol: smtp
    properties.mail.smtp:
      auth: true
      starttls.enable: false
      ssl.trust: smtp.gmail.com
      ssl.enable: true
# mail - konfigurace těla mailu
mail: 
  sender:
    name: Archival Storage
  app:
    name: Archival Storage
    logo: logo.png
    link: http://arclib.inqool.cz
    url: http://arclib.inqool.cz
arcstorage:
  embedded-queue:
# konfigurace datové složky ActiveMQ, pokud je použita vnořená ActiveMQ namísto standalone služby
    data-dir: data/kahadb
  consistencyCheck:
# cron dle kterého budou probíhat periodické kontroly stavu balíků na úložišti
    cron: "0 */30 * * * ?"
# počet AIP zkontrolovaných v rámci jedné periody kontroly, hodnotu je možné vynechat - v tom případě jsou v rámci periody zkontrolovány všechny dostupné AIPy
    count: 10
  storageStateCheck:
# cron dle kterého budou probíhat pravidelné reporty stavu logických úložišť
    cron: "0 0 8 ? * 2"
  threadPools:
# počet vláken rezervovaných pro periodické procesy, např. kontrolu dostupnosti úložišť
    scheduled: 2
# mez velikosti pracovního adresáře v MB, po jejímž dosažení přestane aplikace přijímat jakékoliv požadavky na uložení objektů
  tmpFolderUploadSizeLimit: 500000
# timeout pro navázání spojení s vzdálenými logickými úložišti, v milisekundách
  connectionTimeout: 5000
# timeout pro transakce při nichž se mění stav AIP, v sekundách
  stateChangeTransactionTimeout: 5
# v případě požadavku na přípojení nového logického úložiště musí do tohoto timeoutu (sekundy) všechny rozpracované objekty změnit svůj stav, pokud se tak nestane, synchronizace nezačne
  synchronizationInitTimeout: 15
# timeout operace uložení na sekundárním úložišti, -1 znamená bez timeoutu
  jmsMessageProcessTimeout: -1
# max. počet aktivních vláken pro zpracování požadavků jedné fronty
  jmsQueueConsumerThreads: 8
# při nastavení true jsou při startu aplikace promazány/vyčištěny všechny objekty které nejsou v finálním požadovaném stavu
  cleanUpAtApplicationStart: false
# cesta k adresáři do kterého jsou exportovány data pro zálohování
  backupDirPath: backup
# cesta k privátnímu klíči kterým se archival storage autentizuje skrze SSH v případě logického úložiště na vzdáleném serveru
  ssh:
    authKey: arcstorage.ppk
    userName: {username}
  optionalFeatures:
# true pro zapnutí volitelné funkcionality Forget
    forgetObject: false
# true pro zapnutí volitelné funkcionality Inkrementálního zálohování
    incrementalBackup: false

Cron používaný aplikací musí být ve formátu: second, minute, hour, day of month, month, day(s) of week.

12.1.3. Fronty a primární úložiště

Základní informace

Rozlišujeme primární úložiště (definované v DB konfiguraci systému) a sekundární úložiště. Každé logické úložiště má svou ActiveMQ frontu s podporou prioritizace. V rámci API požadavku je typicky operace poznačena do DB, zkontrolována dostupnost primárního úložiště, zpráva zaslána do fronty/front a následně vrácena odpověď klientovi.

Je-li úložiště připojené, jeho fronta má aktivní JMS Consumery - vlákna zpracovávající požadavky. Počet vláken je konfigurovatelný v application.yml.

Při selhání zprávy na primárním úložišti je poznačen chybový stav objektu v DB. Při selhání zprávy na sekundárním úložišti je úložiště odpojeno, tzn. jsou odebrány JMS consumery dané fronty. O takovémto odpojení je administrátor informován emailem a pro opětovné zapojení úložiště využívá k tomu určený endpoint. Mezitím však systém dále funguje - plní se fronta.

Dojde-li k odpojení úložiště (chybou či uživatelem) ve chvíli kdy vlákno či vlákna již zpracovávají požadavky, vlákna standardně nejsou ukončena a v případě že se požadavky úspěšně zpracují, jsou odebrány z fronty. Výjimkou je více požadavků nad stejným objektem sekundárního úložiště, kde selže-li jeden selžou automaticky i následující.

Při fatálním pádu systémů zůstávají nedokončené zprávy ve frontě a po startu jsou na aktivních úložištích odbaveny.

JMS Zprávy

Rozlišujeme následující typy zpráv a jejich prioritu (vyšší číslo značí vyšší prioritu):

CONFIGURATION(9)

ACTIVATE_DATASPACE

Volání endpointu pro aktivaci dataspace po přidání nového systémového účtu Archival Storage s jiným dataspace než mají dosavadní účty.

NEW_OBJECT(7)

SAVE_AIP
SAVE

Uložení nového AIP/objektu.

Při API požadavku na uložení objektu je:

záznam objektu uložen do DB
objekt uložen do workspace
operace zařazena do fronty primárního úložiště
vrácena odpověď klientovi

Následně JMS vlákno zpracovává zprávu primárního úložiště a na závěr je:

objekt odebrán z workspace
poznačen cílový stav
v případě úspěšného stavu operace zařazena do front sekundárních úložišť

Pokud sekundární úložiště balíček na primárním úložišti nenalezne požadavek je tiše přeskočen, předpokládá se že primární úložiště již balíček odebralo např. na základě ROLLBACK zprávy, která čeká i ve frontě sekundárního úložiště.

OLD_OBJECT(5)

COPY

Kopírování objektu v aktuálním stavu z primárního úložiště na nově zapojené úložiště. Pokud je časová značka vytvoření objektu na novém úložišti novější něž je časová značka v zprávě, je zpracování zprávy přeskočeno.

MODIFICATION(3)

DELETE
ROLLBACK
RENEW
REMOVE
FORGET

Propagace operace na objektu. Pokud je časová značka vytvoření objektu na úložišti novější něž je časová značka v zprávě, je zpracování zprávy přeskočeno.

Vybrané implementační detaily

Více požadavků nad stejnými objekty

Archival Storage si pro každou frontu drží v paměti seznam objektů které právě zpracovává některé vlákno z JMS poolu (zámek na objekt). Pokud vlákno z JMS poolu narazí na zamčený objekt, čeká na uvolnění zámku. Pokud vlákno držící zámek selže a jedná se o sekundární úložiště (které je tímto odpojeno) nastaví k danému zámku příznak a selžou automaticky i ostatní vlákna čekající na uvolnění zámku k danému objektu.

Timeout

Zpracování zpráv SAVE_AIP, SAVE a COPY na sekundárních úložištích může být omezeno timeoutem definovaným v application.yml. Nastane-li timeout úložiště je odpojeno. V rámci timeoutu je vyslán signál na přerušení vlákna, to však nezaručuje jeho okamžité přerušení. Nejpozději na konci procesu vlákno signál rozpozná a vyvolá chybu, což zaručí že zpráva zůstane ve frontě.

Přeskočení starého požadavku na uložení

V rámci (API) požadavku na rollback, smazání, zapomenutí a cleanup konkrétního objektu Archival Storage je do front přidána příslušná zpráva (ROLLBACK,DELETE,FORGET) a je-li v frontách historický požadavek na uložení tohoto objektu, je odebrán:

Projde se seznam právě ukládaných objektů na každém úložišti, a je-li zde nalezen onen objekt, je vyslán signál k zastavení uložení. Tento signál nezpůsobí chybu, zpráva je úspěšně zpracována a odebrána z fronty ale objekt ve skutečnosti kompletně uložen není.
Projde se i zbytek fronty (požadavky které teprv čekají na zpracování) a maže požadavky na uložení onoho objektu.

Chybové systémové přepnutí do read-only režimu

V případě fatální chyby nedostupnosti primárního úložiště či selhání JMS healthchecku Archival Storage automaticky přepíná systém do read-only režimu a zasílá email. Do read-write režimu jej může přepnout administrátor skrze HTTP API.

JMS healthcheck je prováděn

v rámci vybraných API požadavků před zápisem do databáze
na konci procesu uložení do primárního úložiště, před distribucí požadavků na uložení do front sekundárních úložišť

12.1.4. Databáze

Všechny entity používají UUID.
Tabulky jsou generovány při prvním spuštění aplikace.
Aplikačnímu serveru musí být povolen přístup k DB s přihlašováním typu “md5”

Systémové účty

Archival Storage je systémová komponenta - neautentizují se vůči ní běžní uživatelé ale systémy. Archival Storage může sloužit více systémům, kde každý má svůj dataspace a v něm separátně uložená data. V případě logických úložišť realizovaných souborovým systémem je dataspace reprezentován složkou. Hodnota dataspace by měla obsahovat pouze malá písmena ASCII tabulky (a-z).

Pro každý dataspace může existovat několik účtů, typicky jsou však právě dva, jeden pouze pro čtení a druhý pro čtení i zápis. Jedná se o účty s rolemi ROLE_READ a ROLE_READ_WRITE. Pro jeden systém musí mít oba účty stejnou hodnotu dataspace. Email u tohoto účtu není prozatím využíván, není povinný.

Třetí rolí v systému je ROLE_ADMIN - tento typ účtu je používán výlučně administrátorem, autorizuje ho především ke konfiguraci logických úložišť ale neautorizuje ho pro běžné požadavky na práci s objekty. Tento typ účtu nemusí mít přidělen dataspace, naopak je vhodné aby měl přidělen email, na který jsou zasílány notifikace o neočekávaných chybách apod.

Účty jsou uloženy v tabulce arcstorage_user. Systém se vůči Archival Storage autentizuje skrze Basic Auth. Heslo je v DB zašifrováno pomocí BCrypt (pro vygenerování za účely testu lze použít např. https://bcrypt-generator.com/).

Systém

Tabulka arcstorage_system_state obsahuje záznamy:

min_storage_count

hodnota je kontrolována při startu aplikace, v případě nedostatečného počtu logických úložišť jsou účty s rolí ADMIN notifikování emailem, aplikace však běží dál
hodnota je také kontrolována při odebírání úložiště skrze API

read_only

při nastavení systém zamítá operace na uložení nebo úpravu stavu objektů
systém nastavuje readOnly=true

na chvíli při začátku synchronizace nového úložiště

na stálo (resp. dokud admin manuálně nenastaví false) v případě fatálního selhání komunikace s ActiveMQ

reachability_checkInterval_in_minutes

automaticky aktualizuje hodnotu reachable logických úložišť v tabulce arcstorage_storage
změna skrze API je propagována bez nutnosti restartu aplikace

last_reachability_check, last_verified_object_creation

řídící atributy, spravovány systémem

primary_storage_id

ID primárního úložiště

V tabulce se musí vždy nacházet právě jeden záznam. Při prvním spuštění aplikace je vyplněn záznam defaultní konfigurace:

min_storage_count=2
read_only=false
reachability_checkInterval_in_minutes=60

Logické úložiště

K systému může být připojeno jedno či více logických úložišť, čímž je zajištěna redundance na úrovni Archival Storage. K jednotlivým úložištím je přistupováno skrze Java rozhraní StorageService, které zajišťuje abstrakci od konkrétní technologie. V současnosti existují implementace pro obyčejný filesystém (FS), ZFS a Ceph. V případě FS/ZFS je navíc podporováno jak lokální úložiště (případně mapované např. skrze NFS) tak přístup přes SSH ke vzdálenému serveru.

Tabulka arcstorage_storage obsahuje záznam pro každé připojené logické úložiště.

host

pokud je při FS/ZFS nastaveno localhost nebo 127.0.0.1 je automaticky použita implementace pro lokální/mapovaný FS, v ostatních případech je použito SSH

port v případě lokálního FS/ZFS ignorován

priority

pro čtení se používá úložiště s nejvyšší prioritou, pokud je takových více, je jedno z nich náhodně vybráno

type (FS/ZFS/CEPH)

reachable

Nastavován automaticky při každém požadavku na úložiště (všechny logické úložiště jsou kontrolovány na dostupnost). Úložiště které nejsou dostupné nejsou použitelné pro čtení. Pokud je v systému alespoň jedno nedostupné úložiště, systém se chová jako by byl read-only. Dostupnost je také kontrolována periodicky dle intervalu nastaveném v application.yml

config JSON s atributy specifickými dle typu úložiště

detached_by_admin časová značka uživatelsky vyvolaného odpojení úložiště

detached_by_error časová značka systémem vyvolaného odpojení úložiště z důvodu chyby

Další tabulky

arcstorage_aip_sip - entita reprezentující datovou část AIP (zip)
arcstorage_aip_xml - entita AIP XML
arcstorage_object

Archival Storage je navrhnuto s myšlenkou nevázat se pouze na případ užití AIP ale umožnit i práci s objekty obecně. Tato podpora však není zatím implementována, tabulka zůstává prázdná.

arcstorage_object_audit

operace REMOVAL, DELETION, RENEWAL, ROLLBACK, ARCHIVAL_RETRY, FORGET jsou zaznamenány do databáze před distribucí požadavku na logická úložiště

operace ARCHIVED je zaznamenána po úspěšném uložení na primární úložiště.

záznamy jsou použity při synchronizaci nového úložiště a exportu dat do úložiště pro zálohování

arcstorage_storage_sync_status

Informace o probíhající/proběhlé synchronizaci nově přidaného úložiště

12.1.5. Konfigurace logických úložišť

Pro připojení úložiště je z administrátorského účtu volán endpoint POST /api/administration/storage s JSON konfiguračním souborem v těle requestu.

JSON konfiguraci nelze po připojení úložiště zpětně zmenit skrze API.

Lokální FS

Příkladový JSON

{
    "id": "4fddaf00-43a9-485f-b81a-d3a4bcd6dd83",
    "name": "local storage",
    "host": "localhost",
    "port": 0,
    "priority": 10,
    "storageType": "FS",
    "note": null,
    "config": "{\"rootDirPath\":\"d:\\\\arcstorage\"}",
    "reachable": true
}

rootDirPath je cesta ke kořenovému adresáři pro ukládání souborů

v tomto adresáři je pro každý účet vytvořena složka pojmenovaná dle hodnoty dataspace
aplikace musí mít k této složce R/W přístup

Vzdálený FS

Příkladový JSON

{
    "id": "01f839b4-842a-4caf-b237-8f43ee01d0e9",
    "name": "remote storage",
    "host": "176.74.145.50",
    "port": 22,
    "priority": 10,
    "storageType": "FS",
    "note": null,
    "config": "{\"rootDirPath\":\"/opt/data/test\"}",
    "checksumCmd": "{\"MD5\":\"md5sum $filePath | awk '{print $1}'\",\"SHA512\":\"sha512sum $filePath | awk '{print $1}'\"}",
    "reachable": true
}

na vzdáleném serveru je třeba založit arcstorage uživatele a přidat jeho veřejný klíč
pokud se jedná o ZFS, arcstorage uživatel musí mít na serveru passwordless sudo oprávnění aby mohly být příkazy zfs list a zpool list volány skrze SSH
atribut port je nastaven na číslo SSH portu
checksumCmd je volitelný atribut pro optimalizaci výpočtu checksumu MD5 a SHA512

není-li vyplněn, Archival Storage při výpočtu checksumu čte soubor z vzdáleného úložiště

je-li vyplněn, Archival Storage spouští uvedený příkaz v terminálu na serveru vzdáleného úložiště a pouze přebírá výstup¨

výstup příkazu musí být textový řetězec obsahující checksum

Archival Storage nahradí $filePath cestou k objektu jehož checksum ověřuje

ZFS

Defaultně může ZFS příkazy volat pouze root, pro povolení ostatním sudo uživatelům (arcstorage user) lze vytvořit zfs soubor v /etc/sudeoers.d, s následujícím obsahem:

Cmnd_Alias C_ZFS = \
    /sbin/zfs "", /sbin/zfs help *, \
    /sbin/zfs get, /sbin/zfs get *, \
    /sbin/zfs list, /sbin/zfs list *, \
    /sbin/zpool "", /sbin/zpool help *, \
    /sbin/zpool iostat, /sbin/zpool iostat *, \
    /sbin/zpool list, /sbin/zpool list *, \
    /sbin/zpool status, /sbin/zpool status *, \
    /sbin/zpool upgrade, /sbin/zpool upgrade -v
ALL ALL = (root) NOPASSWD: C_ZFS

k ZFS lze přistupovat lokálně nebo přes SSH, JSON konfigurace je obdobná jako v případě Lokální FS resp. Vzdálený FS, musí však navíc obsahovat poolName, tedy např. pro vzdálený ZFS:

„config“: „{"rootDirPath":"/opt/data/test","poolName":"arcpool"}“

Ceph

je nutné nainstalovat Ceph a RGW http://docs.ceph.com/docs/master/start/
instalace může zabrat několik hodin, vyžaduje infrastrukturu uzlů a administrátorský uzel z něhož jsou řízeny
dle CEPH RGW manuálu je vytvořen uživatel
Pro získání stavu Cephu musí RGW server umožnit SSH připojení aplikace (uživatel arcstorage, použit je stejný klíč jako v případě vzdáleného FS). Navíc musí mít tento uživatel na RGW serveru passwordless sudo práva, aby mohla aplikace skrze SSH zavolat příkazy ceph df a ceph -s

Příkladový JSON

{
    "name": "ceph",
    "host": "192.168.10.61",
    "port": 7480,
    "priority": 1,
    "storageType": "CEPH",
    "note": null,
    "config": "{\"adapterType\":\"S3\", \"userKey\":\"SKGKKYQ50UU04XS4TA4O\",\"userSecret\":\"TrLjA3jdlzKcvyN1vWnGqiLGDwCB90bNF71rwA5D\",\"sshPort\":2226,\"https\":\"true\"}",
    "reachable": true,
    "virtualHost": false,
    "id": "8c3f62c0-398c-4605-8090-15eb4712a0e3"
}

port je Ceph RADOS gateway port
config obsahuje

povinné properties

adapterType - v současnosti podpora pouze pro S3

userKey a userSecret - údaje použité pro přístup k Ceph S3 clusteru

properties které překrývají defaultní properties

https true/false

virtualHost true pokud mají být buckety na RGW instanci adresované skrze doménu místo cesty, viz https://docs.ceph.com/docs/mimic/radosgw/s3/commons/

region region, pokud je v Ceph instanci definovaný.. v některých verzích Ceph je tento atribut v API vyžadován nehledě na to zda je konfigurován v Ceph instanci, v tom případě použijte us-east-1

properties použité pro zjištění stavu Ceph úložiště, tyto lze využít pouze má li Archival Storage SSH přístup k Ceph serveru (což typicky nemá, poskytuje-li Ceph třetí strana)

sshServer a sshPort na kterém RGW instance naslouchá

cluster pokud běží v clusteru

cephBinHome cesta k ceph binárce

12.1.6. Lazení výkonu

Aplikační server

Požadavek na uložení má synchronní a asynchronní část. V synchronní části jsou vstupní soubory nahrány do workspace Archival Storage, zkontrolovány jejich kontrolní součty po přenosu a je zaznačen začátek zpracování. Následně je vlákno aplikačního serveru vráceno do poolu a požadavek je dále zpracováván asynchronně. Vlákna aplikačního serveru jsou konfigurovány v sekci server.tomcat. V případě že je počet vláken AS vyčerpán a fronty zaplněny, každý další požadavek končí chybou „Connection refused“.

Archival Storage

Archival Storage zamítne požadavek na jakýkoliv datový i metadatový update pokud velikost jeho workspace přesáhne konfigurovaný limit (503). Cestu do workspace i limit je možné konfigurovat v souboru application.yml: spring.servlet.multipart.location, arcstorage.tmpFolderUploadSizeLimit Např. pokud je průměrná velikost balíku 0.5GB, parametr je nastaven na 5GB a zrovna jsou exportovány čtyři balíky (z čtyř dávek), zbývá 3 GB pro 6 nových zápisů (z 6 dávek) přičemž 7. už povolen není, i kdyby bylo dostupných X vláken.

Vhodným nastavením parametru lze počet právě probíhajících zápisů a tedy zátěž Archival Storage rozumně limitovat a takto lze zajistit dostatečný výpočetní výkon pro odbavování exportů a chodu systému. V případě že limit není nastaven vůbec, může se workspace zaplnit natolik že nebude fungovat např. při exportu. Pokud limit není nastaven, Archival Storage zamítne požadavek pouze v hraničním případě kdy dojde místo na disku workspace (500). Všechny požadavky na uložení které nejsou zamítnuty jsou frontovány a postupně zpracovány.

Poznámka: Hodnota volného místa ve workspace musí být minimálně dvojnásobek velikosti vkládaného objektu.

Postgres

Vzhledem k tomu že jeden databázový server může využívat více aplikací, může lehce dojít k tomu že defaultní počet connections které poskytuje PostgreSQL (100) nebude stačit.

Konfigurace by měla být taková že PGSQL max_conn musí být větší než součet hodnot spring.datasource.tomcat.max-active všech připojených aplikací, je vhodné navíc ponechat pár connections volných pro případné ostatní klienty. V opačném případě může tomcat JDBC pool vyhodit při pokusu o získání connection chybu FATAL: sorry, too many clients already

Dále by mělo platit že spring.datasource.tomcat.max-active je větší než definovaný počet paralelních vláken aplikace, tedy aby každé vlákno mělo zajištěno jedno spojení z poolu. Počet paralelních vláken aplikace není pouze součtem server.tomcat.max-threads (vlákna AS pro synchronní zpracování) se všemi programátorem definovanými pooly (arcstorage.threadPools), navíc si je totiž aplikace schopna tvořit vlákna pro asynchronní zpracování dle potřeby. Aplikace si takto tvoří vlákna v případech kdy není vhodné aby byla limitována, např. při synchronním uložením AIP XML skrze GUI, při automatické opravě v případě že je zjištěna chyba při namátkové kontrole, při exportu do adresáře pro zálohování nebo při synchronizaci nového úložiště, při čištění úložiště od nekompletních uploadů apod. Ve většině těchto případů se jedná o jednorázové operace, i přesto je však vhodné nechat pro tyto operace pár desítek connections v rezervě.

K stabilitě systému přispívá že transakční je pouze část operací vlákna, vlákno tedy nedrží spojení po celou dobu svého běhu, přesto je vhodné dodržet výše zmíněná opatření a snažit se udržet vztah počet dostupných spojení > maximální počet souběžně běžících vláken.

12.1.7. Zálohování a obnova

Postup pro zálohování

Pro zálohování úložiště je použit backup endpoint (GET /api/administration/backup) který provede export všech nových objektů a nových stavových souborů existujících objektů zaznamenaných v daném časovém intervalu do adresáře specifikovaném v application.yml (arcstorage.backupDirPath). Volání vyžaduje autorizační header účtu s rolí ROLE_ADMIN (basic auth). Odpověď je vrácena ihned po kontrole možnosti zápisu/čtení do backup adresáře, samotný export poté probíhá asynchronně, průběh je zaznamenáván v logu. Administrátor ve větších časových intervalech provádí plnou zálohu, v menších intervalech provádí zálohu inkrementální. Za tímto účelem vytvoří na úrovni OS skript který backup endpoint periodicky provolává. Časový interval je zadán jako query param (since,until) v formátu odpovídajícím ISO-8601 formátu (nelze však zadat jakýkoliv ISO-8601 formát, časová značka musí být v UTC formátu s přesností alespoň na sekundy, volitelně milisekundy). Příklad: /api/administration/backup?since=2019-10-27T:16:16:40.700Z&until=2019-10-27T17:16:40Z. Oba parametry jsou volitelné, v případě nevyplnění není výsledek časově zdola/shora omezen. Nevyplnění ani jednoho parametru zodpovídá plné záloze.

Zálohu databáze Archival Storage doporučujeme provádět společně s zálohováním databází ostatních modulů systému nativní PostgreSQL utilitou pg_dump, pro následnou obnovu do předem vytvořené databáze lze použít pg_restore, příklad:

pg_dump -U postgres -W -F t {dbname} > backup.tar
pg_restore -U postgres –dbname={dbname} backup.tar

Postup při obnově

AIS očekává že v složce z které čte data k obnově jsou soubory uloženy přesně tak jak je v průběhu času exportoval do exportní složky. Takováto data jsou téměř zrcadlovým obrazem reálných dat zálohovaného logického úložiště. Při obnově je vytvořen v DB záznam pro FS/ZFS logické úložiště a rootDirPath je nastaven na složku obsahující všechna data k obnově.

Při obnově je potřebné vypnout script provádějící zálohování. Některé operace vyžadují systém v read-only režimu. Systém lze do režimu přepnout přímo editací tabulky arcstorage_system_state nebo skrze endpoint POST /api/administration/config

Níže jsou detailněji popsány způsoby obnovy dle situací které mohou nastat.

K dispozici je pouze záloha úložiště

1.1 Je spuštěna aplikace, čímž se vytvoří defaultní záznam konfigurace systému.
1.2) Je vytvořen záznam pro FS/ZFS logické úložiště, rootDirPath je nastaven na složku obsahující všechna data k obnově.
1.3) Do DB je vložen nový záznam ADMIN účtu (tabulka arcstorage_user).
1.4) Do DB je vložen nový záznam R/W účtu. Atribut dataspace se musí shodovat s atributem dataspace původního AIS systémového R/W účtu, respektive musí se shodovat s názvem kořenové složky exportované do exportní složky.
1.5) Je volán endpoint POST /api/administration/recover_db?storageId={UUID logického úložiště} (ADMIN, při volání musí úložiště běžet v read-only režimu)

K dispozici je záloha DB i záloha úložiště

2.1) DB je obnovena ze zálohy
2.2) Je zajištěno že všechna exportovaná data jsou zkopírována do lokace rootDirPath dříve existujícího logického FS/ZFS úložiště.
2.3) Je spuštěna aplikace, konfigurační hodnota arcstorage.cleanUpAtApplicationStart=false (application.yml)
2.4) Pokud je záloha DB starší než záloha úložiště, je volán endpoint POST /api/administration/recover_db?storageId={UUID logického úložiště}&override=true (ADMIN, při volání musí úložiště běžet v read-only režimu)
2.5) Je volán endpoint POST /api/administration/cleanup?all=true
2.6) Pokud je záloha DB novější než záloha úložiště, je nastavena periodická kontrola systému tak aby proběhla nad všemi objekty. Tímto způsobem administrátor zjistí která data jsou na úložišti v nekonzistentním stavu a manuálně zasáhne buď do úložiště nebo databáze. Alternativně lze pro rychlejší detekci inkonzistence použít POST /api/administration/recover_db?storageId={UUID logického úložiště}&override=false - proces na konci loguje veškeré konfliktní objekty a objekty které jsou uloženy v DB ale nejsou na úložišti. Narozdíl od předchozího způsobu však nekontroluje kontrolní součty objektů jež konfliktní nejsou.

K dispozici je záloha úložiště, DB je aktuální

DB je aktuální (není obnovena ze zálohy, nebyla ztracena). Provedou se akce 2.2, 2.3, 2.5, 2.6 z předchozího scénáře.

12.1.8. Instalace v kontextu AIS

Pro instalaci v AIS je pro Archival Storage dodán samostatný instalační balíček.

Databáze je iniciována z DB dumpu arcstorageDump.bin který obsahuje:

záznamy AIP migrovaných archiválií (v tabulkách arcstorage_aip_sip a arcstorage_aip_xml)
defaultní hodnoty v tabulce arcstorage_system_state
jedno logické úložiště typu FS v tabulce arcstorage_storage (záznam v DB administrátor upraví aby odpovídal požadované lokaci migrovaných AIP, viz níže)
3 systémové účty s rolemi ROLE_READ, ROLE_READ_WRITE, ROLE_ADMIN (opět se předpokládá úprava v DB administrátorem)

Kromě DB dumpu je dodán také soubor local-storage-folder.zip obsahující kompletní obsah úložiště po již provedené migraci (obsahuje AIP zaznamenané v arcstorageDump.bin) - extrahovat do složky úložiště nakonfigurované v DB (v dodaném dumpu se jedná o složku local-storage-folder v pracovním adresáři aplikace).

Dále jsou dodány tyto přílohy:

archival-storage.jar - zkompilovaná aplikace
application.yml - konfigurační soubor překrývající defaultní konfiguraci - vložit do pracovního adresáře aplikace. Jedná se o vzorový soubor, jednotlivé konfigurační hodnoty může být nutné upravit dle konkrétního prostředí.
arcstorageInitDump.bin - iniciální Archival Storage DB dump s předkonfigurovaným úložištěm a účty který je možné použít v rámci procesu migrace mezivýstupu z DB PEVA II do DB AIS