.. _Admin_config:

================
Konfigurace Elza
================

Konfigurace aplikace Elza je standardně uložena v souboru 
:file:`elza.yaml` (případně :file:`elza-ui.yaml`) v závislosti
na distribuci aplikace. Soubor obsahuje definici databázového připojení,
nastavení pracovního adresáře a některá další nastavení.

Konfigurace je soubor ve formátu :token:`YAML`.

-------
Příklad
-------

Příklad konfigurace

.. literalinclude:: examples/elza.yaml
   :language: yaml

.. _Admin_config_web:

--------------------------
Nastavení webového serveru
--------------------------

Pokud je aplikace spuštěna samostatně, je možné nastavit
port pro příjem HTTP požadavků. Výchozí port je 8080.

Popis možností nastavení portů, adresy serveru a další 
možnosti týkající se HTTP komunikace jsou popsány v dokumentaci:
`Server properties <https://docs.spring.io/spring-boot/docs/current/reference/html/appendix-application-properties.html#server-properties>`_.

Ukázka nastavení pro spuštění serveru na portu 8088:

.. code-block:: yaml

  server:
    port: 8088


Pokročilé nastavení serveru
----------------------------

V rámci nastavení serveru je možné nastavit i pokročilé parametry, například:

 - pojmenování sessionn cookie (:token:`server.servlet.session.cookie.name`)
 - maximální délka session (:token:`server.servlet.session.timeout`)
 - požadavek na zabezpečené spojení (:token:`server.servlet.session.cookie.secure`)
 - maximální počet vláken pro zpracování požadavků (:token:`server.tomcat.threads.max`)


.. _Admin_config_accesslog:

Přístupové logy (access log)
----------------------------

Aplikace umí zaznamenávat příchozí HTTP požadavky do tzv. přístupového logu
(access log) vestavěného serveru Tomcat. Do logu se pro každý požadavek zapíše
jeden řádek – IP adresa klienta, čas, metoda a URL požadavku, návratový kód,
velikost odpovědi a doba zpracování. Přístupový log je ve výchozím stavu
**vypnutý**.

Zapnutí se provádí v sekci :token:`server.tomcat.accesslog`. Kromě vlastního
zapnutí je **nutné nastavit i cílový adresář** (:token:`directory`). Pokud
adresář neuvedete, Tomcat zapisuje logy do dočasného adresáře serveru
(:file:`/tmp/tomcat.<port>.<...>/logs`) a v pracovním adresáři aplikace se
tak žádný soubor neobjeví. Doporučujeme použít stejný adresář jako ostatní
logy aplikace, tj. :token:`${elza.workingDir}/log`.

Příklad kompletního nastavení:

.. code-block:: yaml

  server:
    tomcat:
      accesslog:
        enabled: true
        directory: ${elza.workingDir}/log
        prefix: access_log
        suffix: .log
        file-date-format: .yyyy-MM-dd
        pattern: "%h %{X-Forwarded-For}i %l %u %t \"%r\" %s %b %{ms}T"
        buffered: false
        rotate: true

Po úpravě konfigurace je nutné aplikaci restartovat. Výsledný soubor má název
ve tvaru :file:`access_log.RRRR-MM-DD.log` a je uložen v adresáři
:file:`work/log` vedle souborů :file:`elza.log` a :file:`siem.log`.

Význam jednotlivých parametrů:

 * :token:`enabled` - zapnutí/vypnutí přístupového logu (true/false)
 * :token:`directory` - adresář pro ukládání logů. Relativní cesta se vztahuje
   k dočasnému adresáři serveru, proto doporučujeme uvést absolutní cestu,
   resp. :token:`${elza.workingDir}/log`.
 * :token:`prefix`, :token:`suffix` - předpona a přípona jména souboru
 * :token:`file-date-format` - formát data v názvu souboru; zároveň určuje
   frekvenci rotace (denní rotace při hodnotě :token:`.yyyy-MM-dd`)
 * :token:`pattern` - formát řádku logu (viz níže)
 * :token:`buffered` - vyrovnávací paměť zápisu. Hodnota :token:`false` zapisuje
   záznamy okamžitě (vhodné pro sledování v reálném čase), :token:`true` je
   výkonnější při vysokém zatížení.
 * :token:`rotate` - povolení rotace souborů podle data

**Formát záznamu (pattern)**

Formát řádku se nastavuje pomocí zástupných znaků serveru Tomcat. Ve výše
uvedeném příkladu jsou použity:

 * :token:`%h` - IP adresa klienta (u požadavků přes reverzní proxy jde o adresu proxy)
 * :token:`%{X-Forwarded-For}i` - původní IP adresa klienta z hlavičky
   :token:`X-Forwarded-For` (vyplněna při přístupu přes reverzní proxy)
 * :token:`%l` - identita klienta (obvykle nevyplněno, "-")
 * :token:`%u` - uživatel ověřený na úrovni servletového kontejneru (viz poznámka)
 * :token:`%t` - datum a čas požadavku
 * :token:`%r` - první řádek požadavku (metoda, URL, verze protokolu)
 * :token:`%s` - stavový kód HTTP odpovědi
 * :token:`%b` - velikost odpovědi v bajtech
 * :token:`%{ms}T` - doba zpracování požadavku v milisekundách

Kompletní seznam zástupných znaků je v dokumentaci
`Tomcat Access Log Valve <https://tomcat.apache.org/tomcat-10.1-doc/config/valve.html#Access_Logging>`_,
popis parametrů :token:`server.tomcat.accesslog.*` v dokumentaci
`Spring Boot – Server properties <https://docs.spring.io/spring-boot/docs/current/reference/html/appendix-application-properties.html#server-properties>`_.

.. note::

   Zástupný znak :token:`%D` uvádí dobu zpracování v **mikrosekundách**
   (Tomcat 10.1), pro čitelnost je proto v příkladu použit :token:`%{ms}T`
   (milisekundy).

.. note::

   Do pole :token:`%u` se zapisuje pouze uživatel ověřený na úrovni
   servletového kontejneru. Při přihlašování přes Kerberos/SSO nebo při
   interním přihlášení Elza zůstává toto pole prázdné ("-"). Pro auditování
   činnosti konkrétních uživatelů slouží aplikační logy :file:`elza.log` a
   :file:`siem.log`.


------------------
Nastavení databáze
------------------

Konfigurace databáze se provádí v sekci :token:`elza.data`. 
Nastavení se skládá ze tří částí:

 * :token:`url` - připojení k databázi, formát je dle dokumentace 
   JDBC ovladače
 * :token:`user` - uživatelské jméno
 * :token:`pass` - heslo pro připojení k databázi

-------
Přílohy
-------

Konfigurace příloh se provádí v sekci :token:`elza.attachment`. 

Konfigurace slouží k definici typů příloh, určení,
které mohou uživatelé přímo v aplikaci editovat a případné nastavení 
generátorů pro převod do cílových formátů.

Sekce :token:`mimeDefs` definuje typy souborů. Každý typ se konfiguruje
pomocí těchto atributů:

 * :token:`mimeType` - mime-type přílohy
 * :token:`editable` - příznak, zda je typ editovatelný
 * :token:`generators` - seznam generátorů, které umožňují převod 
   daného formátu do jiného

Generátor a jeho konfigurace
----------------------------

Generátorem se rozumí konfigurace externí aplikace, která umožňuje
převod souboru do jiného formátu. Konfigurace generátoru se skládá 
ze tří částí:

 * :token:`outputMimeType` - výstupní formát generátoru (například: 
   :token:`application/pdf` )
 * :token:`command` - příkaz, který je spuštěn pro provedení transformace
 * :token:`outputFileName` - jméno souboru, který obsahuje výsledek transformace

Příkaz může být parametrizován. Parametry uvedené ve složených závorkách
jsou zaměněny za příslušné argumenty. Číslování argumentů je od nuly.

Dostupné argumenty:
 * :token:`{0}` - plná cesta do pracovního adresáře
 * :token:`{1}` - jméno vstupního souboru
 * :token:`{2}` - jméno vstupního souboru včetně úplné cesty
 * :token:`{3}` - jméno výstupního souboru
 * :token:`{4}` - jméno výstupního souboru včetně úplné cesty

------------------
Parametry aplikace
------------------

Další parametry aplikace.

Maximální velikosti upload požadavků
------------------------------------

Z bezpečnostních důvodů jsou v aplikaci nastaveny maximální velikosti pro velikost 
upload požadavků. Tyto limity je možné změnit.

 * :token:`elza.upload.max_file_size` - maximální velikost jednoho nahrávaného souboru, výchozí hodnota: 25MB
 * :token:`elza.upload.max_request_size` - maximální velikost jednoho požadavku, výchozí hodnota: 100MB

 Nastavením hodnoty -1 je možné omezení zcela vypnout.

.. _Admin_config_scope_del_ents: 

Maximální velikost dávky pro databázové operace
-----------------------------------------------

Parametr zajišťuje bezpečnou a efektivní práci se seznamy v databázových dotazech s tím,
že rozděluje příliš velké seznamy na dávky. Výchozí velikost dávky je 1000. Pomocí parametru je možné nastavit
velikost dávky (maximální počet záznamů v klauzuli IN):

 * :token:`elza.data.batchSize` - maximální velikost dávky

Vymazání oblastí archivních entit
---------------------------------

Archivní entity jsou členěny do oblastí. Oblast nelze odstranit
pokud jsou k ní připojeny archivní entity. Aktivací zvláštní
volby je možné vynutit odstranění oblasti.

 * :token:`elza.scope.deleteWithEntities` - hodnota true nebo false

Volba je standardně vypnuta (false). Pokud je volba aktivní 
(po restartu aplikace). Je možné odstranění již nepoužívaných oblastí.


.. _Admin_config_upload_reindex:

Automatická reindexace
---------------------------------

Ve výchozí konfiguraci je nastaveno provádění automatické reindexace dat každou sobotu 
ve 4:00 ráno. Spouštění reindexace je možné deaktivovat nebo nastavit 
vlastní frekvenci jejího provádění. Popis nastavení je ve vzorové konfiguraci
v části :token:`elza.reindex.cron`.


.. _Admin_config_upload_fa: 

Předávání pomůcek a výstupů pomocí WS
-------------------------------------

Pomocí webové služby je možné výslednou archivní 
pomůcku automatizovaně předat po vygenerování do návazného informačního systému.
Pomůcka je odeslána pomocí WSDL služby - FileTransfer.

Z hlediska konfigurace je pro předávání nutné nastavit:
 * :token:`elza.findingAid.upload.url` - cílové URL 
 * :token:`elza.findingAid.upload.username`, :token:`elza.findingAid.upload.password` - volitelné jméno a heslo pro BASIC autorizaci.
 * :token:`elza.findingAid.upload.soapLogging` - podrobné logování komunikace (true/false)

Pro povolení nahrávání pomůcek z uživatelského rozhraní je nutné nastavit:
 * :token:`elza.output.allowSend: true` - povolení odesílání
 * :token:`elza.output.senderName: FtOutputSender` - určení způsobu odesílání

Kompletní příklad nastavení:

.. code:: yaml

  elza:
    findingAid:
      upload:
        url: http://10.1.25.34:8080/esm/cxf/ft
        soapLogging: false
        username: xxxxx
        password: xxxxx
    output:
      allowSend: true
      senderName: FtOutputSender


.. _Admin_config_ws_fonds_admin:

Aktualizace správců fondu přes webovou službu
---------------------------------------------

Při zakládání nebo aktualizaci archivního souboru (fondu) přes webovou službu
je možné určit, jak se mají aktualizovat oprávnění správců fondu (uživatelů
a skupin):

 * :token:`elza.webservice.fonds.adminPermissionMode` - režim aktualizace správců

Možné hodnoty:

 * :token:`FULL_SYNC` (výchozí) - zaslaní správci se přidají a stávající
   správci, kteří nejsou v požadavku, se odeberou. Výsledek přesně odpovídá
   zaslanému seznamu.
 * :token:`ADD_ONLY` - zaslaní správci se pouze přidají, stávající oprávnění
   zůstanou zachována. Oprávnění přidaná administrátorem nejsou aktualizací
   přes webovou službu odebrána.

Příklad nastavení:

.. code:: yaml

  elza:
    webservice:
      fonds:
        adminPermissionMode: ADD_ONLY


-------------------
Zabezpečení
-------------------

V aplikaci Elza je možné nastavit několik parametrů týkajících se zabezpečení a metod 
autentizace uživatelů. Pro nastavení je určena sekce :token:`elza.security`.

Dostupné metody autentizace uživatelů:

 - autentizace pomocí databáze Elza, tj. uživatelských účtů uložených v Elza v kombinaci s heslem (výchozí metoda)
 - autentizace pomocí LDAP serveru (Active Directory apod.)
 - autentizace na základě hlaviček HTTP požadavků
 - autentizace na základě JWT tokenů
 - autentizace pomocí Kerberos (SPNEGO), umožňuje jednotné přihlášení (SSO) v rámci Windows domény

Jednotlivé metody autentizace je možné kombinovat. Dokumentace pro nastavení jednotlivých metod
je v rámci zdrojového kódu Elza, případně je vhodné kontaktovat dodavatele aplikace a 
požádat o konzultaci.

Url pro adresu po odhlášení
-----------------------------------

V nastavení je možné definovat adresu pro přechod při odhlášení uživatele. Při odhlášení uživatele
dojde k přesměrování na určenou adresu.

 * :token:`elza.security.logoutUrl` - url adresa přechodu

 