Jak psát howto v DocBooku

DocBook je docela zajímavá věc pro psaní dokumentace k čemukoliv, umožňuje vám napsat jeden dokument v XML a z něj poté vygenerovat html variantu, pdf, ps, rtf a podobně. Pár lidí se mě už ptalo jak píšu své textíky, tak jsem si řekl, že udělám howto na to jak psát howto 🙂 Starší variantu tohoto dokumentu najdete na AbcLinuxu.cz v mém blogu. aktualizováno

Nemá cenu abych tu fušoval panu Koskovi do řemesla, proto u mě nehledejte návod na DocBook jako takový, ten je na jeho webu.

Kapitola 1. Instalace docbooku

Instalace DocBooku je docela dobře popsaná u pana Koska. Pokud máte nějakou slušnější distribuci Linuxu, tak si můžete celkem pohodlně nainstalovat DocBook z jejich balíčků, v Debianu jsou to balíčky

  • docbook

  • docbook-defguide

  • docbook-doc

  • docbook-dsssl

  • docbook-dsssl-doc

  • docbook-html-forms

  • docbook-mathml

  • docbook-simple

  • docbook-to-man

  • docbook-utils

  • docbook-website

  • docbook-xml

  • docbook-xml-simple

  • docbook-xsl

  • docbook-xsl-stylesheets-ko

  • docbook2x

  • xsltproc, openjade, jade, jadetex

Kapitola 2. Šablona pro psaní dokumentace

Pro každý dokument, který píšu si dělám samostatný adresář, ve kterém jsou potřebné soubory. V adresáři najdeme soubory Makefile, xhtml-chunk.xsl, xhtml-onechunk.xsl, xhtml-common.xsl a adresář html/, v něm je CSS styl (docbook.css) pro budoucí html variantu dokumentu. Samozřejmě je v adresáři i zdrojový dokument.xml případně další potřebné soubory (obrázky a podobně).

2.1. Makefile

Na make jsem zvyklý, je to jednodužší než si psát pokaždé shellový skriptík. Obsah mého Makefile je následující:

#$Id: docbook.xml,v 1.2 2006/01/30 00:25:11 tsunami Exp $
all: single

book: clean dokument.xml xhtml-chunk.xsl xhtml-common.xsl
        xsltproc -o html/ xhtml-chunk.xsl dokument.xml

single: clean dokument.xml xhtml-onechunk.xsl xhtml-common.xsl
        xsltproc -o html/ xhtml-onechunk.xsl dokument.xml

rtf: dokument.xml
        docbook2rtf dokument.xml

pdf: dokument.xml
        docbook2pdf dokument.xml

ps: dokument.xml
        docbook2ps dokument.xml

clean:
        @rm -f html/*.html
        @rm -f dokument.aux dokument.dvi dokument.log dokument.out
        @rm -f dokument.rtf dokument.tex dokument.ps dokument.pdf

Pozor na odsazení v Makefile, je děláno pomocí tabulátorů a ne mezerama. Docela dobře to je vidět pokud Makefile děláte v mceditu, pak to odsazení bude červené (stačí dát dva tabulátory).

Jak vidíte, tento Makefile mi umožňuje vyrobit pomocí jednoduchého příkazu make CIL dokument v požadovaném formátu. Cíle jsou pdf, ps, rtf, single, book, clean, all. Cíle pdf, ps a rtf asi nemá cenu vysvětlovat. Cíl clean smaže všechny generované soubory, cíl all je výchozí cíl, uplatní se, když spustíte make bez parametrů. Book je html dokument dělený na jednotlivé stránky odpovídající kapitolám a single je html dokument ve formě jedné veliké stránky.

2.2. xhtml-*

2.2.1. xhtml-common.xsl

Tento soubor je společným pro book i single html, obsahuje základní definici parametrů pro generování html. Všechny své dokumenty píšu v ISO8859-2 kódování, ale samozřejmě si to můžete přehodit na UTF-8.

<?xml version="1.0" encoding="iso-8859-2"?>
<!-- $Id: docbook.xml,v 1.2 2006/01/30 00:25:11 tsunami Exp $ -->
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                version="1.0">

<!-- Úpravy parametru -->

<xsl:param name="chunker.output.encoding" select="'UTF-8'"/>

<!-- Mají se pouzívat rozsírení -->
<xsl:param name="use.extensions" select="1"/>
<!-- Vypneme podporu pro rozsireni tabulek -->
<xsl:param name="tablecolumns.extension" select="0"/>

<!-- Mají se sekce automaticky ??íslovat -->
<xsl:param name="section.autolabel" select="1"/>

<!-- Mají císla sekcí obsahovat i císla kapitol -->
<xsl:param name="section.label.includes.component.label" select="1"/>

<!-- Mají se císlovat kapitoly -->
<xsl:param name="chapter.autolabel" select="1"/>

<!-- Pouzijeme námi definovaný CSS-->
<xsl:param name="html.stylesheet">docbook.css</xsl:param>
<xsl:param name="html.stylesheet.type">text/css</xsl:param>

<xsl:param name="generate.id.attributes" select="1"></xsl:param>
<xsl:param name="make.valid.html" select="1"></xsl:param>
<xsl:param name="generate.meta.abstract" select="1"></xsl:param>
<xsl:param name="autotoc.label.separator" select="'. '"></xsl:param>

<xsl:param name="generate.toc">
book      toc,title
</xsl:param>
</xsl:stylesheet>

2.2.2. xhtml-chunk.xsl

Tento soubor dělá jen jednu věc, definuje výstup do html rozděleného na více stránek podle kapitol.

<?xml version="1.0" encoding="iso-8859-2"?>
<!-- $Id: docbook.xml,v 1.2 2006/01/30 00:25:11 tsunami Exp $ -->
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                version="1.0">

<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/chunk.xsl"/>
<xsl:include href="xhtml-common.xsl"/>
</xsl:stylesheet>

2.2.3. xhtml-onechunk.xsl

<?xml version="1.0" encoding="iso-8859-2"?>
<!-- $Id: docbook.xml,v 1.2 2006/01/30 00:25:11 tsunami Exp $ -->
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  version="1.0">

<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/onechunk.xsl"/>
<xsl:include href="xhtml-common.xsl"/>

</xsl:stylesheet>

2.3. html/docbook.css

Pro html je definice vlastního vzhledu relativně snadná, stačí nám k tomu jeden CSS soubor.

/* $Id: docbook.xml,v 1.2 2006/01/30 00:25:11 tsunami Exp $ */
body { font-family: Verdana, Helvetica CE, Arial CE, Arial, Helvetica, sans-serif;
       font-size: 12pt; 
       line-height: 1.3;
       background-color: #dddddd;
       color: black; 
       margin: 0px;}

table { font-size: 10pt
        border: solid black 1px;
        border-collapse: collapse; }


.title, .subtitle { color: navy }

.programlisting, 
.programlistingco, 
.screen { background-color: #f0f0fe;
          border: 1px solid #999999;
          margin: 0.3em; 
          padding: 0.3em; }

a:hover { color: red;
         text-decoration: underline; }

a { text-decoration: none;
    color: blue; }

.navfooter, .navheader { background-color: #bbbbbb; }

.section, .appendix,
.chapter, .refentry, 
.book, .reference, 
.preface, .colophon { margin-left: 10pt;
                      margin-right: 10pt; }

p { text-align: justify; }

li p { display: inline}

Kapitola 3. Tipy

3.1. Použitelný editor

Na psaní skoro všeho používám VIM. Pokud vám na XML nevyhovuje, tak zkuste pro DocBook třeba Emacs nebo spíš XMLmind. Emacs má narozdíl VIMu špičkovou podporu pro psaní XML, jako berličku pro rychlejší psaní xml a html ve vimu používám makro na zavírání tagů. Editor XMLmind je špičkový editor napsaný v javě, který vám umožní docela efektivně pracovat s čímkoliv v xml, takže i s DocBookem. Kolega ho používá a je s ním docela spokojen.

Pro kontrolu správnosti XML dokumentu používám xmllint:

$ alias xmlvalid='xmllint --noout --valid'
$ xmlvalid dokument.xml

3.2. Vložení obrázku

DocBook umožňuje vložit obrázek ve více formátech, při generování výsledného dokumentu použije ten vhodnější (pro html png, pro pdf eps).

<figure float="0" id="net">
  <title>Název obrázku</title>

  <mediaobject>
     <imageobject>
        <imagedata fileref="img/net.eps" format="EPS" scale="50" />
     </imageobject>
     <imageobject>
        <imagedata fileref="img/net.png" format="PNG" />
     </imageobject>
  </mediaobject>
</figure>

3.3. Rozdělení zdroje dokumentu do více souborů

U větších dokumentů se hodí rozdělit zdrohový soubor do více logických celků.

V hlavním souboru (dokument.xml) je třeba definovat kde se mají hledat další části (v mém případě to jsou rfc.xml, ldif.xml, slovnicek.xml a odkazy.xml), to se dělá na začátku dokumentu.

<?xml version="1.0" encoding="ISO-8859-2"?>
<!-- $Id: docbook.xml,v 1.2 2006/01/30 00:25:11 tsunami Exp $ -->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY rfc SYSTEM "rfc.xml">
<!ENTITY ldif SYSTEM "ldif.xml">
<!ENTITY slovnicek SYSTEM "slovnicek.xml">
<!ENTITY odkazy SYSTEM "odkazy.xml">
]>

Pokud potom někam do dokumentu vložíte nově definovanou entitu (&rfc;, &ldif;, &slovnicek; nebo &odkazy;) tak se při překladu místo ní vloží zdrojový soubor, pro který je definována.

Formát tohot zdrojového souboru je trochu jednodužší, je třeba aby začínal jedním povinným řádkem a zbytek si už můžete psát co chcete (samozřejmě xml/DocBook a ne třeba xhtml).

<?xml version="1.0" encoding="ISO-8859-2"?>

3.4. Pěkně formátovaný html výstup

Určitě jste si všimli, že generovaný html kód není pro normálního smrtelníka moc čitelný. Pokud chcete pěkný čitelný kód, nainstalujte si program tidy.

Přeformátování html:

tidy -i -wrap 0 -c -q -utf8 -o vystupni.html vstupni.html

3.5. Prohlížení XML přímo ve webovém prohlížeči a jeho stylování

Snad každý moderní browser umí zobrazit XML soubor. Pro zobrazení, které se velmi podobá výslednému vygenerovanému html souboru, je potřeba přidat CCS styl.

Do hlavičky XML souboru přidáme odkaz na CSS.

<?xml version="1.0" encoding="ISO-8859-2"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
<?xml-stylesheet href="docbook-css-0.4/driver.css" type="text/css"?>
</article>
...

Do adresáře vedle našeho docbook souboru rozbalte balíček s CSS (v příloze u článku, trochu jsem ho upravoval pro češtinu a měnil jsem barvy).

Testování služeb mailserveru telnetem

Článek vyšel 9.1. na serveru abclinuxu.cz.

Při instalaci služeb zajišťujících běh (nejen) poštovního serveru se často setkáte s potřebou snadné kontroly funkčnosti služby pomocí jednoduchého programu. Možnost ručně si zadat příkazy a sledovat při tom odezvu systému je většinou neocenitelná. V článku vám ukážu jak snadno testovat služby POP3, IMAP, SMTP a jejich varianty zabalené do SSL.

Použité nástroje

Pro otestování použijeme běžné nástroje dostupné snad v každé "normální" distribuci linuxu a to programy telnet a openssl. Telnet nám poslouží pro připojení na POP3, IMAP a SMTP server. Openssl využijeme pro ověření funkčnosti POP3s, IMAPs a SMTPs.

Jako SMTP server používám postfix, o POP3 a IMAP se stará dovecot. Výpisy zde uvedené se můžou mírně lišit podle toho jaké programy použijete.

Telnet

Program telnet je dostupný v Linuxu (a UNIXech) i v MS Windows, umožňuje interaktivní TCP spojení na server. Spouští se z příkazového řádku:

$ telnet SERVER PORT

SERVER můžete zapsat pomocí doménového jména nebo IP adresy. PORT je číslo TCP portu a lze ho zapsat buď jako číslo nebo jako textový název, který je danému číslu portu přiřazen v souboru /etc/services.

Program telnet (a navázané spojení) ukončíte pomocí stisku kombinace kláves ^] a ^d.

[tsunami@vodik]$ telnet tsunami.locnet pop3
Trying 192.168.0.10...
Connected to tsunami.locnet.
Escape character is '^]'.
+OK Dovecot ready.
^]
telnet> Connection closed.

Pokud má někdo odpor k aplikacím spouštěným z příkazového řádku, může použít například grafický program PuTTY (Linux, Windows), ale dle mého názoru je to zbytečné.

SMTP

SMTP protokol je relativně jednoduchý protokol založený na textové komunikaci, používá TCP port 25. Původní popis protokolu najdete v RFC821 (z r. 1982), aktualizovaný popis najdete v RFC2821 (z r. 2001). Pro kompletní popis protokolu tu není místo proto zde uvedu praktickou ukázku toho jak se přes telnet pošle email. Všechny tučně zapsané řádky jsou zaslané klientem (mnou naťukané do klávesnice).

Připojíme se telnetem na server na port 25 a počkáme si na odpověď od serveru.

[tsunami@vodik]$ telnet tsunami.locnet 25
Trying 192.168.0.10...
Connected to tsunami.locnet.
Escape character is '^]'.
220 tsunami ESMTP Postfix (Debian/GNU)

Nejprve se identifikujeme

EHLO vodik.locnet
250-tsunami
250-PIPELINING
250-SIZE 10240000
250-VRFY
250-ETRN
250 8BITMIME

Uvedeme od koho email pochází

MAIL FROM: od.koho.ten@email.je
250 Ok

a komu ho zasíláme

RCPT TO: tsunami@tsunami.locnet
250 Ok

no a potom můžeme začít psát vlastní zprávu, psaní ukončíme pomocí tečky na samostatném řádku a „odentrování“.

DATA
354 End data with <CR><LF>.<CR><LF>
Subject: pozdrav od anonyma

Ahoj, jak se mas?
.
250 Ok: queued as 0AA3929FAA

Email byl zařazen do fronty a my můžeme ukončit svou práci:

QUIT
221 Bye

Jak vidíte, docela jednoduše můžete zasílat emaily i když nemáte vhodného emailovéh klienta jako je mozilla nebo outlook 🙂

POP3

Protokol pop3 slouží ke stažení pošty ze serveru ke klientovi. POP3 přístup k poště je vhodný pokud potřebujete rozumný přístup k poště přes pomalou linku případně nemůžete/nechcete uchovávat všechnu poštu na serveru. Pop3 je většinou dostupný na portu 110/tcp, je popsán v RFC1939, RFC2449 a RFC1734.

Připojíme se k serveru

[tsunami@vodik]$ telnet tsunami.locnet 110
Trying 192.168.0.10...
Connected to tsunami.locnet.
Escape character is '^]'.
+OK Dovecot ready.

Přihlásíme se jako uživatel k serveru

USER tsunami
+OK
PASS heslo
+OK Logged in.

Příkazem STAT můžeme zjisit počet zpráv a jejich velikost případně si je příkazem LIST vypíšeme.

STAT
+OK 3 1619
LIST
+OK 3 messages:
1 433
2 486
3 700
.

Rozhodl jsem se stáhnout zprávu číslo 2

RETR 2
+OK 486 octets
Return-Path: <od.koho.ten@email.je>
X-Original-To: tsunami@tsunami.locnet
Delivered-To: tsunami@tsunami.locnet
Received: from vodik.locnet (vodik [192.168.0.13])
        by tsunami (Postfix) with ESMTP id 0AA3929FAA
        for <tsunami@tsunami.locnet>; Sat,  7 Jan 2006 23:36:40 +0100 (CET)
Subject: pozdrav od anonyma
Message-Id: <20060107223653.0AA3929FAA@tsunami>
Date: Sat,  7 Jan 2006 23:36:40 +0100 (CET)
From: od.koho.ten@email.je
To: undisclosed-recipients:;

Ahoj, jak se mas?
.

Stažený email označím ke smazání

DELE 2
+OK Marked to be deleted.

Ukončení spojení zároveň znamená i smazání označených zpráv

QUIT
+OK Logging out, messages deleted.

IMAP

Další protokol, kterým se dostaneme ke své poště na serveru se jmenuje IMAP (Internet Message Access Protocol, aktuálně ve verzi 4v1). Protokol je složitější než POP3 a umožňuje o mnoho víc funkcí. První rozdíl, kterého si všimnete je, že pošta se nechává na serveru. Protokol je také navržen pro současné připojení více klientů k jednomu mailboxu. IMAP funguje přes TCP port 143. Protokol IMAP je popsán v RFC3501, zajímavé informace k IMAPu najdete také na webu www.imap.org

Připojíme se na server a přihlásíme se jako uživatel

[tsunami@vodik]$ telnet tsunami.locnet 143
Trying 192.168.0.10...
Connected to tsunami.locnet.
Escape character is '^]'.
* OK Dovecot ready.
. LOGIN tsunami heslo
. OK Logged in.

Každý příkaz musí být uveden unikátním idenitfikátorem v rámci daného sezení. Vypíšeme si co nám server nabízí za funkce s tím.

IDENT01 CAPABILITY
* CAPABILITY IMAP4rev1 SORT THREAD=REFERENCES MULTIAPPEND
UNSELECT LITERAL+ IDLE CHILDREN NAMESPACE LOGIN-REFERRALS
IDENT01 OK Capability completed.

Pro další ukázky raději použiju kratší identifikátory. Zkusíme si vypsat dostupné složky.

id01 LIST "" "*"
* LIST (\NoInferiors \UnMarked) "/" "Trash"
* LIST (\NoInferiors) "/" "Pracovni"
* LIST (\NoInferiors \UnMarked) "/" "Soukrome"
* LIST (\NoInferiors) "/" "Linux"
* LIST (\NoInferiors) "/" "Solaris"
* LIST (\NoInferiors) "/" "INBOX"
id01 OK List completed.

Z předchozího výpisu jsme zjistili, že na serveru existuje několik složek. „Přepneme“ se do složky Linux.

id02 SELECT "Linux"
* FLAGS (\Answered \Flagged \Deleted \Seen \Draft)
* OK [PERMANENTFLAGS (\Answered \Flagged \Deleted \Seen \Draft \*)] Flags permitted.
* 2 EXISTS
* 0 RECENT
* OK [UIDVALIDITY 1136680099] UIDs valid
* OK [UIDNEXT 4] Predicted next UID
id02 OK [READ-WRITE] Select completed.

Vypíšeme si seznam všech emailů ve složce

id03 FETCH 1:* FLAGS
* 1 FETCH (FLAGS (\Seen))
* 2 FETCH (FLAGS (\Seen))
id03 OK Fetch completed.

Stáhneme si email č. 2:

id04 FETCH 2 body[text]
* 2 FETCH (BODY[TEXT] {75}
mkdir: cannot create directory `/var/run/sendmail/msp': Permission denied
)
id04 OK Fetch completed.

Myslím, že to na ukázání stačilo, takže se odhlásíme

id05 logout
* BYE Logging out
id05 OK Logout completed.

SSL

Dnes je téměř samozřejmostí, že admin přehodí většinu veřejně dostupných služeb na jejich zabezpečenou variantu (zabalenou do SSL). Klasickým telnetem v tomto případě nic nevyzkoušíte, protože telnet neumí SSL. Pro připojení na server proto použijeme program openssl.

O programu openssl si spousta lidí myslí, že to je ta divná věc na generování certifikátů, ale on umí být i klientskou aplikací pro SSL spojení. Stačí ho spustit s parametrem s_client:

$ openssl s_client -host SERVER -port PORT

Openssl s_client umožňuje zadat spoustu dalších parametrů, například umožní využít certifikát certifikační autority případně zaslat serveru klientský certifikát. Seznam všech parametrů dostanete pokud zadáte jakýkoliv neznámí parametr:

[tsunami@vodik]$ openssl s_client -h
unknown option -h
usage: s_client args

 -host host     - use -connect instead
 ...

Když se připojíte k serveru pomocí openssl, na obrazovce se zobrazí informace o navazovaném SSL spojení:

[tsunami@vodik]$ openssl s_client -host tsunami.locnet -port 995
CONNECTED(00000003)
depth=1 /C=CZ/ST=-/L=Prag/O=Zdenek Burda/CN=Zdenek Burda/emailAddress=zdenda@
zdenda.com
verify error:num=19:self signed certificate in certificate chain
verify return:0
---
Certificate chain
 0 s:/C=CZ/ST=-/L=Prag/O=Zdenek Burda/CN=tsunami.locnet/emailAddress=zdenda@zdenda.com
   i:/C=CZ/ST=-/L=Prag/O=Zdenek Burda/CN=Zdenek Burda/emailAddress=zdenda@zdenda.com
 1 s:/C=CZ/ST=-/L=Prag/O=Zdenek Burda/CN=Zdenek Burda/emailAddress=zdenda@zdenda.com
   i:/C=CZ/ST=-/L=Prag/O=Zdenek Burda/CN=Zdenek Burda/emailAddress=zdenda@zdenda.com
---
Server certificate
-----BEGIN CERTIFICATE-----
MIIC4jCCAcoCAQIwDQYJKoZIhvcNAQEFBQAweDELMAkGA1UEBhMCQ1oxCjAIBgNV
...
gBRJXBktFFaRCI+4pUiUi02o+pfkkgeGoVBRtycauOXZ7TVT97aihjk8Qxj98Bys
lDt47imjTMwwh8LSOz0M6OsmIupVTw==
-----END CERTIFICATE-----
subject=/C=CZ/ST=-/L=Prag/O=Zdenek Burda/CN=tsunami.locnet/emailAddress=zdenda@zdenda.com
issuer=/C=CZ/ST=-/L=Prag/O=Zdenek Burda/CN=Zdenek Burda/emailAddress=zdenda@zdenda.com
---
No client certificate CA names sent
---
SSL handshake has read 2016 bytes and written 340 bytes
---
New, TLSv1/SSLv3, Cipher is AES256-SHA
Server public key is 1024 bit
Compression: NONE
Expansion: NONE
SSL-Session:
    Protocol  : TLSv1
    Cipher    : AES256-SHA
    Session-ID: EACB77B795913F22DC65CD867301E84913CDBEAA1FE89E5A90A32E2891297E58
    Session-ID-ctx: 
    Master-Key: F1480F1397A2A1DB995B4FB8AC720FEF6CFE77F02FBB95407576B3C023620
6736ABDE4FE2108AA936EC115B365CF70BA
    Key-Arg   : None
    Start Time: 1136712490
    Timeout   : 300 (sec)
    Verify return code: 19 (self signed certificate in certificate chain)
---
+OK Dovecot ready.

Po připojení pomocí openssl můžete zadávat příkazy stejně jako při připojení telnetem. Openssl ukončíte pomocí ^d nebo ^c.

V případě mého spojení pomocí openssl se na ukázalo hlášení o self signed certifikátu. Bylo to způsobené tím, že openssl nezná certifikát certifikační autority, která podepsala certifikát serveru. Pokud openssl vnutíme certifikát CA (CA.crt), bude vše v pořádku.

[tsunami@vodik]$ openssl s_client -host tsunami.locnet \
 -port 995 -CAfile CA.crt
  

Docela zajímavou funkcí je, pokud server vyžaduje aby mu klient zaslal svůj certifikát jinak mu nedovolí připojení/přihlášení. OpenSSL tento certifikát předáme volbami -cert a -key.

[tsunami@vodik]$ openssl s_client -host tsunami.locnet \
 -port 995 -CAfile CA.crt -cert burda.crt -key burda.key

Nejčastěji používané porty pro SSL varianty běžných služeb:

  • imaps: 993
  • pop3s: 995
  • smtps: 465
  • https: 443

A to je vše přátelé…

Jednotlivé protokoly jsem zde nepopisoval, protože je vše pěkně vysvětlené v odkazovaných RFC. Uvedený způsob ovládání emailu se nehodí jen pro testování, ale někdy se dá využít i v normálním životě. Pokud máte ve schránce velký email, který nechcete/nemůžete stáhnout, tak jeho smazání přes pop3 telnetem je záležitost na chvilku. Telnet na SMTP server se hodí pokud zkoušíte jestli můžete přijímat poštu z venku a přitom ještě není správně nastavený DNS server (pokud byste si zkusili poslat email klasickým způsobem z nějakého freemailu, nepřijšel by protože neví kam má jít).

Kalendář dostupný odkudkoliv?

Update: Webdav jsme opustili a přešli na DAViCAL: Kalendář pro každého: DAViCAL – opensource implementace CalDAV serveru.

Článek vyšel 2.1.2006 na serveru abclinuxu.cz.

Během posledních několika let jsem zkusil různé webové kalendáře, ale většinou jsem u nich moc dlouho nezůstal. Velké množství webových kalendářů používá vlastní formát pro uchovávání dat a případná změna aplikace znamená ztrátu všech údajů. Při poslední změně programu jsem se naštval a rozhodl se pro definitivní řešení – přechod na program s přenositelným formátem dat.

Zadal jsem si následující podmínky pro výběr vhodného kalendáře.

  • Dostupnost odkudkoliv
  • Možnost využít klasickou desktopovou grafickou aplikaci
  • Webový přístup ke kalendáři, stačí pouze pro čtení
  • Standardní formát pro uchovávání dat abych v budoucnosti neměl problámy s převodem do jiného programu
  • Bezpečný přístup ke kalendáři
  • Možnost zpřístupnit kalendář někomu dalšímu

Nakonec jsem si vybral následující řešení:

  • Formát dat: iCalendar
  • Způsob uložení: WebDAV přes HTTPS
  • Aplikace na desktop: Mozilla Calendar
  • Webový přístup: PHP iCalendar

Formát dat iCalendar je standard (RFC 2445) pro výměnu kalendářových dat. iCalendar je podporován většinou běžně používaných programů jako jsou Mozilla Calendar ( Mozilla SunBird), Microsoft Outlook, KOrganizer, Apple iCal, Ximian Evolution nebo třeba Lotus Notes.

p

WebDAV protokol nám umožní ukládat kalendář na web přímo z aplikace SunBird. Nelíbí se mi představa, že by se heslo ke kalendáři a vlastně celý můj kalendář potuloval po internetu v čistém textu, proto používám WebDAV přes HTTPS. WebDAV mám spuštěný na vlastním serveru. Pokud vlastní server nemáte a váš webhosting WebDAV nepodporuje, můžete využít například služby icalx, která slouží ke sdílení kalendářů.

Pro práci s kalendářem na desktopu si můžete vybrat z více apliakcí, já sem si zvolil program Mozilla Sunbird případně Mozilla Calendar. Samozřejmě můžete použít třeba KOrganizer, Evolution nebo třeba Outlook.

Pro webový přístup ke kalendáři použijeme program PHP iCalendar, je relativně jednoduchý na nastavení a rychle se v něm zorientujete.

Zapnutí podpory WebDAV v apache

Nebudu zde popisovat kompletní nastavení apache webserveru, od toho je oficiální dokumentace na httpd.apache.org. Ukázka konfigurace (jde o umístění a názvy souborů), kterou uvedu je z distribuce Debiana a platí pro webserver Apache 2.

Podpora WebDAV je v standardní součástí Apache. Aktivujeme ji přidáním modulu do konfigurace webserveru, to samé provedeme pro modul mod_userdir. Modul userdir nám umožní jednoduše nastavit pro každého uživatele adresář pro web, v našem případě pro kalendář.

cd /etc/apache2
ln -s mods-available/dav.load mods-enabled/
ln -s mods-available/dav_fs.load mods-enabled/
ln -s mods-available/dav_fs.conf mods-enabled/
ln -s mods-available/userdir.load mods-enabled/
ln -s mods-available/userdir.conf mods-enabled/

Nyní povolíme pro uživatelské adresáře WebDAV. Soubor /etc/apache2/mods-enabled/userdir.conf upravíme

<IfModule mod_userdir.c>
        UserDir public_html
        UserDir disabled root

        <Directory /home/*/public_html>
                <IfModule mod_dav.c>
                        Dav On
                </IfModule>
                AllowOverride FileInfo AuthConfig Limit
                Options MultiViews Indexes SymLinksIfOwnerMatch IncludesNoExec
        </Directory>
</IfModule>

A na závěr restartujeme webserver

/etc/init.d/apache2 restart

Pokud vyrobíte v domácím adresáři uživatele (v mém případě uživatel tsunami) adresář public_html/ a nastavíte mu práva tak aby do něj mohl webserver přistupovat a číst, budete mít jeho obsah dostupný na http://server/~tsunami/.

 

Pro umístění kalendářů a povolení zápisu přes WebDAV si jako uživatel vyrobíme adresář ~tsunami/public_html/kalendar a nastavíme mu práva na 777. Pokud se vám nechce práva takhle blbě nastavovat, tak je nastavte na 770 a změňte skupinu toho adresáře na www-data nebo pod čím vám běží apache. Zápis přes webdav totiž probíhá pod uživatelem pod kterým běží webserver.

Aby nám nemohl každý kolemjdoucí lézt do kalendáře, je vhodné ho schovat za heslo.

order allow,deny
allow from all

AuthName "Kalendar"
AuthType Basic
AuthUserFile ~tsunami/public_html/kalendar/.htpasswd
AuthGroupFile /dev/null
require valid-user

Soubor s heslem pro uživatele tsunami vyvoříme utilitou htpasswd

vodik:/$ htpasswd -c ~tsunami/public_html/kalendar/.htpasswd tsunami
New password:
Re-type new password:
Adding password for user tsunami

Nastavení webserveru, které jsem zde ukázal jako příklad, je to nejjednodužší co může být, kdy uživatelé mají plná práva. Pokud chcete uživatele omezit, tak se zaměřte na volby <Limit> případně <LimitExcept>. Samozřejmě nemusíte mít nastavení v soubrou .htaccess, ale můžete vše napsat přímo do konfiguračních souborů apache.

Když už vám bude vše fungovat přes HTTP protokol, tak zkuste i HTTPS. Přece nechcete aby vaše kalendáře poletovaly po síti v plaintextu :-).

Zkouška WebDAV

Pro vyzkoušení přístupu na webdav použijeme program litmus.

[tsunami@vodik]$ litmus https://server/~tsunami/kalendar/ login heslo
-> running `basic':
 0. init.................. pass
 1. begin................. pass
 2. options............... pass
 .
 .
 .
 38. finish................ pass
<- summary for `locks': of 39 tests run: 36 passed, 3 failed. 92.3%
-> 1 warning was issued.
See debug.log for network/debug traces.

Test proběhl, ale nahlásil 3 chyby. Vzhledem k tomu, že to jsou chyby, které i nevadí, prohlásím webdav za správně nastavený :-). Pro přístup na webdav je možné použít řádkového klienta cadaver nebo namountovat vzdálený webdav jako filesystem. Pro přimountování je třeba nainstalovat davfs.

vodik:~# mount -t davfs https://server/~/tsunami/kalendar/ /mnt
Please enter the username for authentication with server
https://server/~tsunami/kalendar/ or hit enter for none.
Username: tsunami
Please enter the password to authenticate tsunami with server
https://server/~tsunami/kalendar/ or hit enter for none.
Password:
Server cerifticate could not be verified.
  presented for `server':
  Issuer:  server, Zdenek Burda, Prag, Czech Republic, CZ
  Subject: server, Zdenek Burda, Prag, Czech Republic, CZ
  Fingerprint: 8c:98:55:32:84:f1:5b:74:b2:cf:7f:d0:26:b8:23:6f:e7:d5:9e:f4
If you can't verify the fingerprint the server may be faked
or there may be a man-in-the-middle-attack!
I am not a coward and accept the certificate anyway [y,N]? y

Mozilla SunBird

 

Program Mozilla Calendar je dostupný jako rozšíření pro Mozilla Suite, případně Firefox a Thunderbird.
Pokud raději chcete úplně samostatnou aplikaci, můžete zkusit Mozilla SunBird. Další nastavení bude odpovídat SunBirdu, ale na Mozilla Calendar půjde určitě taky aplikovat.

Vytvoření kalendáře

Vzdálený kalendář se vytvoří pomocí „průvodce“. Začněte v menu File->New Calendar File, otevře se dialog, kde zvolíme vzdálený kalendář (Remote).

Dialog pro vytvoření nového kalendáře

Po potvrzení můžeme vybrat způsob jakým budeme ke kalendáři přistupovat a kde bude uložen. Zvolíme protokol WebDAV a jako místo kde bude kalendář napíšeme kompletní adresu https://server/~tsunami/kalendar/kalendar.ics. Kalendářů si samozřejmě můžete vyrobit víc, takže je vhodné zvolit dobré jméno.

Výběr protokolu a umístění pro nový kalendář

Poslední dialog umožní pojmenovat kalendář a zvolit barvu jakou se bude zobrazovat.

Pojmenování nového kalendáře

Po potvrzení se vás kalendář pravděpodobně zeptá na to zda se vám líbí SSL certifikát serveru na kterém je webdav a poté na login a heslo.

Po odklepnutí se mi ukázalo varování, že je kalendář pouze pro čtení (Read-only).

Chybova hlaska o read-only kalendari

Náprava je jednoduchá, prostě zrušíme Read-only ve vlastnostech daného kalendáře. Pravým tlačítkem myši klikněte v seznamu kalendářů na náš kalendář, zvolte Edit Calendar a v dialogu, který se otevře zrušte zatržení u Read-only.

Nyní můžete začít ládovat do kalendáře data. Pokud se rozhlédnete po internetu, najde zajímavé kalendáře. Jeden z nich (seznam státních svátků) najdete na stránce Filipa Molčana.

SunBird

Co s tím, když něco nefunguje?

Pokud vám něco nefunguje, zeptejte se ve fóru věnovanému kalendáři.

Webový přístup

Přístup přes web se hodí pokud nejste zrovna u svého počítače a nechte/nemůžete nastavit SunBird tak aby zobrazoval vaše kalendáře. Pro zobrazení kalendáře na webu použijeme zmiňovaný PHP iCalendar (aktuálně ve verzi 2.1).

PHP iCalendar rozbalte například do adresáře ~tsunami/public_html/kalendar/web/. Přesuňte se do adresáře s kalendářem, smažte adresář calendars a místo něj si vytvořte symlink na adresář ~tsunami/public_html/kalendar/.

$ cd ~tsunami/public_html/kalendar/web
rm -rf calendars
ln -s ../ calendars

Tím dosáhneme zveřejnění všech kalendářů, které si vyrobíme, na webu. Pokud potřebujete zveřejňovat pouze nějaké kalendáře, nemusíte mazat adresář calendars, ale můžete si do něj požadované kalendáře nalinkovat. Konfiguraci webového kalendáře můžete ovlivnit v souboru config.inc.php.

Webové rozhraní pro kalendář

Něco na závěr

Popsané řešení zřejmě nebude pro spoustu lidí dostačující, ale mě vyhovuje. Zlepšení vidím ve hodnějším nastavení práv pro WebDAV přístup ke kalendářům tak aby se daly sdílet jednotlivé kalendáře s různým oprávněním pro různé uživatele. Možná by se hodila i editace kalendáře přes web, třeba existuje vhodná webová aplikace, pokud o ní někdo víte, napište do diskuze.