Poznámky k instalaci Calomu a WebCalomu

Calom server

Pro překlad spusťte: 

make
, příp. 
make [<parametr>=<hodnota>]
, kde hodnota je většinou 0 nebo 1 a parametry mohou být:
Název parametru Implicitní hodnota Popis
DEBUGGING 1 Vypne přidávání ladicích informací do programu, ztíží možnost ladění programu a zapne vyšší optimalizaci.
INCLUDE_DEBUG_INFO 0 Přidej ladicí informace i při volbě DEBUGGING=0. Pokud DEBUGGING=1, je tato volba ignorována.
FIREWALLS 1 Zapne podporu pro speciální kód předcházející chybám při alokaci paměti.
OPTIMIZE 1 pro DEBUGGING=0, 0 pro DEBUGGING=1 Zapíná, resp vypíná optimalizace v překladači.
FORCE_OPTIMIZE Kontroluje úroveň optimalizace - viz. manuálové stránky gcc.
LICENCES 1 Povoluje kontrolu licencí v Calom serveru.
STATIC 0 Zapíná, resp. vypíná kompilaci se statickými knihovnami.
DIETLIBC 0 Zapíná/vypíná podporu knihovny dietlibc. Ignoruje se, pokud STATIC=0.
INSTALL_PATH /opt/calom Instalační cesta (prefix).
FREETDS_INCLUDE_DIR autodetekce Cesta s hlavičkovými soubory knihovny FreeTDS.

K instalaci použijte instalační skript 

make install
Ten vytvoří uživatele calom a skupinu calom pod kterými později bude server běžet. Do domácích adresářů nainstaluje soubory:
calomd Calom server
calom Calom klient běžící pod UNIX terminálem
config Konfigurační soubor Calom serveru
tarifs Tarify pro Calom server
reports Šablony reportů využívaných Calom klientem
Dále instalační skript nastaví Calom server jako službu a nastaví automatické spouštění po startu systému.

Pokus budete využívat CCM gatherer Calom serveru nebo program SQLSync, budete potřebovat nainstalovanou knihovnu FreeTDS verze 0.62 nebo pozdější. Konkrétně Calom používá soubor libsybdb.so.4, který musí být přístupný dynamickému linkeru.
Pro překlad jsou také potřeba hlavičkové soubory knihovny FreeTDS, tedy freetds/sybdb.h.

WebCalom

WebCalom se může instalovat jako samostatný HTTP server nebo jako CGI-bin program. Nejprve spusťte instalaci příkazem: 

cd www; make install WEBCALOM_DIR="cesta"
kde cesta je to nějaký podadresář adresáře CGI-bin serveru Apache (pro případ druhého typu instalace) nebo (pro spouštění jako samostatný program) je to nějaký adresář, kam chcete WebCalom nainstalovat.
Pokud vynecháte specifikaci WEBCALOM_DIR="cesta", zkusí se automatická detekce - prohledávají se adresáře: Na distribucích, kde chybí program chkconfig pro přidávání a odstraňování spouštění služeb, bude nutné manuálně nastavit spouštění skriptu /etc/init.d/webcalom_scheduler. Jinak nebude fungovat plánovač reportů (resp. bude se muset spouštět ručně).

Pokud chcete WebCalom instalovat samostatně, stačí nastavit, aby se spouštěl program 

calom_www -p <port>
kde <port> je port, na kterém má WebCalom naslouchat. Pro vyzkoušení, zda server funguje, můžete v WWW prohlížeči zadat 
http://localhost:<port>/cgi-bin/calom/calom_www/
kde místo localhost doplňte jméno počítače, místo <port> dejte číslo portu, na kterém WebCalom přijímá požadavky.
Pokud jej spouštíte v rámci Apache serveru, bude to nejspíš port 80, a v tomto speciálním případě je možné část :<port> vynechat. Pokud jej spouštíte samostatně, je to parametr za -p. WebCalom by měl vypsat úvodní stránku s informací, že nejste přihlášen a příp. že požadovaná stránka není k dispozici.

Nastavení WebCalomu

Po nainstalování je třeba WebCalom nastavit. Většina konfigurace se provádí v adresáři config.
Některá nastavení je možné provádět ze systému WebCalom. Pro přihlášení by měl existovat ůčet webadmin s heslem webadmin, který má administrátorská práva. S tímto ůčtem můžete nastavit ostatní ůčty.
Nastavení je uloženo v různých konfiguračních souborech a adresářích. Formát souboru je následující - prázdné řádky a řádky začínající znakem '#' jsou ignorovány. Ostatní řádky začínají názvem nastavení, za kterým následuje dvojtečka a hodnota toho nastavení.
Hodnoty, které popisují cesty v souborovém systému mohou být relativní k hlavnímu adresáři WebCalomu.
Bližší popis jednotlivých souborů:

client_config Nastavení client-msgs specifikuje, kde se nachází lokalizační soubor s hlášeními Calom klienta. Je využíván pouze pro hlášení chyb v reportech. Hodnotou je cesta k souboru .mc s lokalizačními řetězci.
custom Speciální nastavení pro jednotlivé uživatele. V tomto adresáři může mít každý uživatel svůj podadresář a v něm nastavení platná jen pro něj. Tyto adresáře mají stejný obsah jako hlavní adresář config, ale nemusejí tam být všechny soubory (nebo adresář ani nemusí existovat). Nastavení specifikované v souborech v adresáři nastavení daného uživatele se použije pouze pro daného uživatele a má přednost před globálním nastavením.
defaults Implicitní nastavení WebCalomu. Nastavuje se jazyk (default-language) a vzhled WWW stránek (default-theme).
fast_reports Definice tzv.rychlých reportů, každý report je definován v samostatném souboru.
lang_ Adresář se soubory s jazykovými daty - např. chybová hlášení pro jednotlivé jazyky. Seznam jazyků je v souboru languages.
languages Seznam aktivních jazyků. Název nastavení je zkratka jazyka, hodnota pak jméno jazyka
licence Zakódovaná licence pro provoz WebCalomu. Dá se nastavit na stránce /config_licence.html.
mail.conf Konfigurace SMTP protokolu používaného pro posílání reportů mailem.
  • from a mail-from- odesílatel mailu
  • host-from - počítač, ze kterého se mail odesílá
  • smtp-server - jméno SMTP serveru
  • smtp-user - SMTP uživatel
  • smtp-passwd - SMTP heslo
  • auth-type - typ autorizace u SMTP serveru. Může být: 'none', 'plain', 'login' a 'cram-md5'
  • email-body-file - jméno souboru, který bude tvořit tělo mailu při zasílání reportu
  • email-body-encoding - kódování těla emailu
pdf_transformation.conf Konfigurace pro transformaci do PDF.
  • base-dir - domácí adresář pro transformaci (ostatní relativně k němu)
  • scratch-dir - adresář pro ukládání dočasných souborů (musí se mazat!)
  • xslt - XSLT šablona pro transformaci XML do FO
  • fop - cesta k programu Fop (transformace do PDF)
  • fop-config - cesta ke konfiguraci programu Fop
  • xslt-param - parametry XSLT transformace (popsány v konf. souboru)
server_params Různá nastavení parametrů a cest k využívaným programům. Obsahuje konfiguraci Calom serveru:
  • calom-host - jméno počítače s Calom serverem
  • calom-port - port, na kterém poslouchá Calom server
  • calom-user - uživatelské jméno pro Calom server
  • calom-passwd - heslo na Calom server
  • calom-home - domácí adresář systému Calom
  • calom-log-path - adresář s logy Calomu
  • calom-path - stejné jako calom-home
  • calom-exe - cesta k Calom serveru
  • sqlsync-path - cesta k programu SQLSync
  • sqlsync-config - konfigurace programu SQLSync
Dále různá nastavení
  • report-dir - Adresář s reporty
  • report-encoding - Kódování reportů (iso-8859-1, iso-8859-2, cp1250, utf-8)
  • scheduler-path - Cesta k WebCalom scheduleru
sql.conf Konfigurace programu SQLSync. Tento soubor má jinou syntaxi než ostatní První dva znaky řádku označují typ nastavení, zbytek řádku hodnotu.
  • SN - jméno/IP adresa Calom serveru
  • UN - uživatelské jméno na Calom server
  • PW - uživatelské heslo na Calom server
  • QS - jméno/IP adresa serveru s databází
  • QU - uživatelské jméno na server s databází
  • QP - uživatelské heslo na server s databází
  • QT - podstrom pro synchronizaci
tarif_names Jména tarifů. Aby se soubory s tarify mohy jmenovat jinak než tarify samy, mohou se zde nadefinovat záměny. Název nastavení je jméno souboru s tarifem a hodnota je název tarifu.
themes Soubor s definicemi témat. Témata jsou varianty HTML stránek. Viz níže.
users Soubor s definicemi uživatelů. Název je jméno uživatele, hodnota je jeho heslo. Více nastavení o uživatelích je v souboru custom/<jméno-uživatele>/defaults.

HTML stránky a témata

HTML stránky, které se servírují, jsou uloženy jako XML soubory pod stromem s kořenem v podadresáři HTML.
Tyto soubory server WebCalom transformuje na HTML stránky a při tom dodává různé informace (např. z Calom serveru).
Při požadavku na stánku se prohledávají adresáře tak, že se vezme cesta za jménem cgi-bin programu (calom_www) a soubor se zkouší najít v následujících adresářích v tomto pořadí (když se někde najde, ostatní varianty se už neprohledávají a použije se první nalezený adresář).

HTML/custom/<jméno uživatele> Toto umístění má prioritu. Obsahuje stránky specifické pro jednotlivé uživatele.
HTML/<aktuální téma>/<aktuální jazyk> Toto je nejčastější umístění HTML stránek, obsahuje soubory závislé jak na tématu, tak na jazyku.
HTML/<aktuální téma> Obsahuje soubory závislé na tématu, ale ne na jazyku. Sem patří např. CSS soubory nebo loga (obrázky bez textu).
HTML/common/<aktuální jazyk> Společné soubory pro všechna témata, ale specifická pro jazyky.
HTML/common Společné soubory pro všechna témata a jazyky.
HTML/<implicitní téma>/<implicitní jazyk> Pokud ve zvoleném tématu daný soubor chybí, hledá se v implicitním tématu.
HTML/<implicitní téma> Pokud ve zvoleném tématu daný soubor chybí, hledá se v implicitním tématu.
HTML/common/<implicitní téma> Pokud ve zvoleném tématu daný soubor chybí, hledá se v implicitním tématu.
Poznámky:

Plánování reportů

Pro plánování reportů je nutné mít spuštěný tzv. plánovač reportů, webcalom_scheduler a mít k němu správně nastavenou cestu v konfiguračních souborech. Dále je potřeba se ujistit, že má právo na zápis do adresáře, kam má reporty ukládat.
Také musí běžet pod stejným uživatelem, jako běží proces, který k němu přistupuje (tedy nejčastěji uživatel calom, na kterého se pomocí setuid bitu přepne WebCalom při spouštění z umístění, kam byl nainstalován. Pokud by webcalom_scheduler nechtěl startovat, je potřeba zkontrolovat, zda někde neběží stará kopie tohoto programu, příp. zda neběží pod jiným uživatelem. Také může být třeba pomocí utility ipcrm odstranit používaný sdílený segment paměti (pozná se podle práv 644, velikosti 220 bytů a nenulového klíče, při startu také vypíše ID sdílené paměti).
Poznámky:

Fop a PDF transformace

Pro PDF výstup reportu je třeba aktuální verze procesoru Fop. V současnosti je používána verze 20050203173628, kterou je možné stáhnout z http://cvs.apache.org/snapshots/xml-fop/xml-fop_20050203173628.tar.gz. Novější verze lze najít na: stránce "snapshotů" programu Fop.
Aby program Fop fungoval, musí být správně nastavena proměnná JAVA_HOME na adresář, kde se nachází instalace Javy, dále je potřeba změnit soubor fop.sh z instalace programu Fop, aby obsahoval na začátku souboru řádku: 

EXTRAARGS="-Xmx256m"
dále pak na konci místo 
$JAVACMD $LOGCHOICE $LOGLEVEL -classpath "$LOCALCLASSPATH" $FOP_OPTS org.apache.fop.apps.Fop "$@"
uveďte 
$JAVACMD $LOGCHOICE $LOGLEVEL $EXTRAARGS -classpath "$LOCALCLASSPATH" $FOP_OPTS org.apache.fop.apps.Fop "$@"
Také je potřeba správně nastavit soubor pdf_transformation.conf (viz. výše).

Kontrola a mazání log-souborů

Calom, WebCalom, plánovač i konvertor do PDF reportů zapisují do tzv. log-souborů informace o provozu a chybách, které nastaly. Calom server používá stejnou adresářovou strukturu jako pro data, log-soubory se jmenují log.n, kde n je číslo dne.
WebCalom zapisuje hlášení do souboru scratch/messages, který je možné čistit i zobrazovat přes rozhraní WebCalomu.
Plánovač reportů zapisuje hlášení do souboru helpers/scheduler.log - uchovává se pouze log poslední spuštěné instance.
Konvertor PDF reportů zapisuje hlášení do souboru webcalom-pdf-fo-<n>.log v adresáři nastaveném jako scratch-dir, <n> je PID číslo daného procesu. Pokud konverze proběhne bez chyby, všechny mezivýsledky a log soubor se smažou, pokud ne, zůstane log soubor a poslední správně vygenerovaný mezivýsledek. Konvertor při spuštění smaže log soubory i mezivýsledky předchozích instancí.

Popisovaná verze Calom serveru: 2.3.0

Potřebné knihovny

Společné:

Calom server:

Calom client:

Různé:

WebCalom: