Merge branch 'master' of vc.linet-services.de:public/lx-office-erp

[mfinanz.git] / doc / INSTALL.texi

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename INSTALL.info
@documentencoding UTF-8
@afourpaper
@settitle Lx-Office Installationsanleitung
@c %**end of header

@c @copying
@c Die Lx-Office Installationsanleitung kann beliebig weiter verwendet
@c werden.
@c @end copying

@titlepage
@title Lx-Office Installationsanleitung
@end titlepage

@contents

@ifnottex
@node Top
@top Inhalt der Anleitung
@end ifnottex

@menu
* Aktuelle Hinweise:: Andere Informationsquellen als diese Anleitung
* Benötigte Software und Pakete:: Vorraussetzungen zum Betrieb von Lx-Office
* Manuelle Installation des Programmpaketes:: Installationsort, Berechtigungen
* Anpassung der PostgreSQL-Konfiguration:: Verschiedene Aspekte der Datenbankkonfiguration
* Apache-Konfiguration:: Einrichtung eines Aliases und Optionen für das Ausführen von CGI-Scripten
* Der Task-Server:: Konfiguration und Einrichtung des Task-Server-Dämonen
* Benutzerauthentifizierung und Administratorpasswort:: Einrichtung der Authentifizierungsdatenbank und der Passwortüberprüfung
* Benutzer- und Gruppenverwaltung:: Einrichten von Benutzern, Gruppen und Datenbanken
* Drucken mit Lx-Office:: Voraussetzungen, Einrichtung und Fehlerdiagnose
* OpenDocument-Vorlagen:: Wichtige Hinweise zum Erstellen und zur Verwendung von Dokumentenvorlagen
* Lx-Office ERP verwenden:: Die URLs zur Anmeldung und Administration
@end menu

@c ---------------------------------------------------------------

@node Aktuelle Hinweise
@chapter Aktuelle Hinweise

Aktuelle Installations- und Konfigurationshinweise gibt es:

@itemize
@item
auf der Lx-Office Homepage unter @uref{http://lx-office.org/index.php?id=dokumentation}

@item
im Lx-Office-Wiki unter Dokumentation (@uref{http://wiki.lx-office.org/index.php/Lx-Office_ERP})

@item
im Lx-Office-Forum: @uref{http://www.lx-office.org/forum/}
@end itemize

@c ---------------------------------------------------------------

@node Benötigte Software und Pakete
@chapter Benötigte Software und Pakete

@menu
* Betriebssystem:: Unterstützte Betriebsysteme und Hinweise für ältere Systeme
* Pakete:: Benötigte Software und Perlpakete sowie deren Quellen
@end menu

@node Betriebssystem
@section Betriebssystem

Lx-Office ist für Linux konzipiert, und sollte auf jedem unixoiden
Betriebssystem zum Laufen zu kriegen sein. Getestet ist diese Version im
speziellen auf Debian und Ubuntu, grundsätzlich wurde bei der Auswahl der
Pakete aber darauf Rücksicht genommen, dass es ohne große Probleme auf den
derzeit aktuellen verbreiteten Distributionen läuft.

Anfang 2011 sind das folgende Systeme:

@itemize
@item
Ubuntu 8.04 LTS Hardy Heron
@item
Ubuntu 9.10 Karmic Koala
@item
Ubuntu 10.04 Lucid Lynx
@item
Ubuntu 10.10 Maverick Meerkat
@item
Debian 5.0 Lenny
@item
Debian 6.0 Squeeze
@item
openSUSE 11.2
@item
openSUSE 11.3
@item
SuSE Linux Enterprice Server 11
@item
Fedora 13
@item
Fedora 14
@end itemize

Für die debianoiden Betriebssysteme existiert ein .deb, das deutlich einfacher
zu installieren ist.

Ubuntu 8.04 LTS hat zusätzlich die Schwierigkeit, dass die Module im Archiv
recht alt sind, und das viele der benötigten Module nicht einfach zu
installieren sind. Dafür sollte es kurz nach dem Release ein eigenes .deb
geben.

Alternativ dazu kann die normale Installation durchgeführt werden
(@pxref{Manuelle Installation des Programmpaketes}), wenn vorher ein
Kompatibilitätspaket installiert wird, das die fehlenden Pakete bereitstellt.
Das Paket ist auf @uref{https://sourceforge.net/projects/lx-office/files/Lx-Office%20ERP/2.6.2/, Sourceforge} unter dem Namen @code{lx-erp-perl-libs-compat-v2.tar.gz} hinterlegt.

Zur Installation das Paket in das entpackte Lx-Office Verzeichnis entpacken:

@code{tar xzf lx-erp-perl-libs-compat-v2.tar.gz /path/to/lx-office/}

Zusätzlich müssen dann noch die folgenden Pakete installiert weerden

@code{libbit-vector-perl libsub-exporter-perl libclone-perl libclass-factory-util-perl}

Danach sollte der Installationscheck (@pxref{Pakete}) die enthaltenen Pakete erkennen.

@node Pakete
@section Pakete

Zum Betrieb von Lx-Office werden zwingend ein Webserver (meist Apache)
und ein Datenbankserver (PostgreSQL, mindestens v8.2) benötigt.

Zusätzlich benötigt Lx-Office die folgenden Perl-Pakete, die nicht Bestandteil
einer Standard-Perl-Installation sind:

@itemize
@item
parent
@item
Archive::Zip
@item
Config::Std
@item
DateTime
@item
DBI
@item
DBD::Pg
@item
Email::Address
@item
JSON
@item
List::MoreUtils
@item
Params::Validate
@item
PDF::API2
@item
Rose::Object
@item
Rose::DB
@item
Rose::DB::Object
@item
Template
@item
Text::CSV_XS
@item
Text::Iconv
@item
URI
@item
XML::Writer
@item
YAML
@end itemize

Gegenüber Version 2.6.0 sind zu dieser Liste 2 Pakete hinzugekommen, @code{URI}
und @code{XML::Writer} sind notwendig. Ohne startet Lx-Office nicht.

Gegenüber Version 2.6.1 sind @code{parent}, @code{DateTime},
@code{Rose::Object}, @code{Rose::DB} und @code{Rose::DB::Object} neu
hinzugekommen. @code{IO::Wrap} wurde entfernt.

Gegenüber Version 2.6.3 ist @code{JSON} neu hinzugekommen.

@code{Email::Address} und @code{List::MoreUtils} sind schon länger feste
Abhängigkeiten, wurden aber bisher mit Lx-Office mitgeliefert.  Beide sind auch
in 2.6.1 weiterhin mit ausgeliefert, wurden in einer zukünftigen Version aber
aus dem Paket entfernt werden. Es wird empfohlen diese Module zusammen mit den
anderen als Bibliotheken zu installieren.

Die zu installierenden Pakete können in den verschiedenen Distributionen unterschiedlich heißen.

Für Debian oder Ubuntu benötigen Sie diese Pakete:

@code{apache2 postgresql libparent-perl libarchive-zip-perl libdatetime-perl libdbi-perl libdbd-pg-perl libpg-perl libemail-address-perl liblist-moreutils-perl libpdf-api2-perl librose-object-perl librose-db-perl librose-db-object-perl libtemplate-perl libtext-csv-xs-perl libtext-iconv-perl liburi-perl libxml-writer-perl libyaml-perl libconfig-std-perl libparams-validate-perl libjson-perl}

Für Fedora Core benötigen Sie diese Pakete:

@code{httpd postgresql-server perl-parent perl-DateTime perl-DBI perl-DBD-Pg perl-Email-Address perl-List-MoreUtils perl-PDF-API2 perl-Rose-Object perl-Rose-DB perl-Rose-DB-Object perl-Template-Toolkit perl-Text-CSV_XS perl-Text-Iconv perl-URI perl-XML-Writer perl-YAML}

Für OpenSuSE benötigen Sie diese Pakete:

@code{apache2 postgresql-server perl-Archive-Zip perl-DateTime perl-DBI perl-DBD-Pg perl-MailTools perl-List-MoreUtils perl-PDF-API2 perl-Template-Toolkit perl-Text-CSV_XS perl-Text-Iconv perl-URI perl-XML-Writer perl-YAML}

Bei openSuSE 11 ist @code{parent} bereits enthalten, und braucht nicht nachinstalliert werden. Die @code{Rose::*} Pakete sind derzeit nicht für SuSE gepackt, und müssen anderweitig nachinstalliert werden.

Lx-Office enthält ein Script, mit dem überprüft werden kann, ob alle
benötigten Perl-Module installiert sind. Der Aufruf lautet wie folgt:

@code{./scripts/installation_check.pl}

@c ---------------------------------------------------------------

@node Manuelle Installation des Programmpaketes
@chapter Manuelle Installation des Programmpaketes

Die Lx-Office ERP Installationsdatei (lxoffice-erp-2.6.2.tgz) wird im
Dokumentenverzeichnis des Webservers (z.B. @code{/var/www/html/},
@code{/srv/www/htdocs} oder @code{/var/www/}) entpackt:

@code{cd /var/www
@*
tar xvzf lxoffice-erp-2.6.2.tgz}

Verändern Sie evtl. noch den Namen des Verzeichnisses mit

@code{mv lxoffice-erp/ lx-erp/}

Alternativ können Sie auch einen Alias in der Webserverkonfiguration
benutzen, um auf das tatsächliche Installationsverzeichnis zu
verweisen.

Die Verzeichnisse @code{users}, @code{spool} und @code{webdav} müssen
für den Benutzer beschreibbar sein, unter dem der Webserver läuft. Die
restlichen Dateien müssen für diesen Benutzer lesbar sein. Der
Benutzername ist bei verschiedenen Distributionen unterschiedlich
(z.B. bei Debian/Ubuntu @code{www-data}, bei Fedora core @code{apache}
oder bei OpenSuSE @code{wwwrun}).

Der folgende Befehl ändert den Besitzer für die oben genannten
Verzeichnisse auf einem Debian/Ubuntu-System:

@code{chown -R www-data lx-office-erp/users lx-office-erp/spool lx-office-erp/webdav}

Weiterhin muss der Webserver-Benutzer im Verzeichnis @code{templates} Verzeichnisse für
jeden neuen Benutzer, der in lx-office angelegt wird, anlegen dürfen:

@code{chgrp www-data lx-office-erp/templates; chmod g+w lx-office-erp/templates}


@c ---------------------------------------------------------------

@node Anpassung der PostgreSQL-Konfiguration
@chapter Anpassung der PostgreSQL-Konfiguration

PostgreSQL muss auf verschiedene Weisen angepasst werden.

@menu
* Zeichensätze/die Verwendung von UTF-8:: Was bei der Verwendung von UTF-8 zu beachten ist
* Änderungen an Konfigurationsdateien:: Anpassungen für Anmeldung am Server und Featureunterstützung
* Erweiterung für servergespeicherte Prozeduren:: Lx-Office benutzt servergespeicherte Prozeduren
* Datenbankbenutzer anlegen:: Um den Zugriff besser zu reglementieren
@end menu

@node Zeichensätze/die Verwendung von UTF-8
@section Zeichensätze/die Verwendung von UTF-8

Lx-Office kann komplett mit UTF-8 als Zeichensatz verwendet
werden. Dabei gibt es zwei Punkte zu beachten: PostgreSQL muss in
Version 8.0 oder neuer benutzt werden, und der
PostgreSQL-Datenbankcluster muss ebenfalls mit UTF-8 als Locale
angelegt worden sein.

Dieses ist kann überprüft werden: ist das Encoding der Datenbank
``template1'' ``UTF8'', so kann auch Lx-Office mit UTF-8 betrieben
werden. Andernfalls ist es notwendig, einen neuen Datenbankcluster mit
UTF-8-Encoding anzulegen und diesen zu verwenden. Unter Debian und
Ubuntu kann dies z.B. mit dem folgenden Befehl getan werden:

@code{pg_createcluster --locale=de_DE.UTF-8 --encoding=UTF-8 8.2 clustername}

Die Datenbankversionsnummer muss an die tatsächlich verwendete
Versionsnummer angepasst werden.

Unter anderen Distributionen gibt es ähnliche Methoden.

Wurde PostgreSQL nicht mit UTF-8 als Encoding initialisiert und ist
ein Neuanlegen eines weiteren Clusters nicht möglich, so kann
Lx-Office mit ISO-8859-15 als Encoding betrieben werden.

Das Encoding einer Datenbank kann in @code{psql} mit @code{\l} geprüft werden.

@node Änderungen an Konfigurationsdateien
@section Änderungen an Konfigurationsdateien

In der Datei @code{postgresql.conf}, die je nach Distribution in
verschiedenen Verzeichnissen liegen kann
(z.B. @code{/var/lib/pgsql/data/} oder @code{/etc/postgresql/}, muss
sichergestellt werden, dass TCP/IP-Verbindungen aktiviert sind. Das
Verhalten wird über den Parameter @code{listen_address}
gesteuert. Laufen PostgreSQL und Lx-Office auf demselben Rechner, so
kann dort der Wert @code{localhost} verwendet werden. Andernfalls
müssen Datenbankverbindungen auch von anderen Rechnern aus zugelassen
werden, was mit dem Wert \@code{*} geschieht.

In der Datei @code{pg_hba.conf}, die im gleichen Verzeichnis wie die
@code{postgresql.conf} zu finden sein sollte, müssen die
Berichtigungen für den Zugriff geändert werden. Hier gibt es mehrere
Möglichkeiten. Eine besteht darin, lokale Verbindungen immer
zuzulassen

@code{local all all trust
@*
host all all 127.0.0.1 255.0.0.0 trust}

Besser ist es, für eine bestimmte Datenbank Zugriff nur per Passwort
zuzulassen. Beispielsweise:

@code{local   all         lxoffice                                           password
@*
host    all         lxoffice      127.0.0.1         255.255.255.255    password}

@c ---------------------------------------------------------------

@node Erweiterung für servergespeicherte Prozeduren
@section Erweiterung für servergespeicherte Prozeduren

In der Datenbank @code{template1} muss die Unterstützung für servergespeicherte
Prozeduren eingerichet werden. Melden Sie sich dafür als Benutzer ``postgres''
an der Datenbank an, und führen Sie die folgenden Kommandos aus:

@code{create language 'plpgsql';}

Achtung: In älteren Postgresversionen (vor 8.0) muss der Handler für die
Sprache manuell anlelegt werden, diese Versionen werden aber nicht mehr
offiziell von Lx-Office unterstützt. Dafür dann die folgenden Kommandos:

@code{create function plpgsql_call_handler () returns opaque as '/usr/lib/pgsql/plpgsql.so' language 'c';
@*
create language 'plpgsql' handler plpgsql_call_handler lancompiler 'pl/pgsql';}

Bitte beachten Sie, dass der Pfad zur Datei @code{plpgsql.so} von Distribution
zu Distribution verschiedlich sein kann. Bei Debian/Ubuntu befindet sie sich
unter @code{/usr/lib/postgresql/lib/plpgsql.so}.

@c ---------------------------------------------------------------

@node Datenbankbenutzer anlegen
@section Datenbankbenutzer anlegen

Wenn Sie nicht den Datenbanksuperuser ``postgres'' zum Zugriff
benutzen wollen, so sollten Sie bei PostgreSQL einen neuen Benutzer
anlegen. Ein Beispiel, wie Sie einen neuen Benutzer anlegen können:

@code{su - postgres
@*
createuser -d -P lxoffice}

Wenn Sie später einen Datenbankzugriff konfigurieren, verändern Sie
den evtl. voreingestellten Benutzer ``postgres'' auf ``lxoffice''
bzw. den hier gewählten Benutzernamen.

@c ---------------------------------------------------------------

@node Apache-Konfiguration
@chapter Apache-Konfiguration

Hinweis: Für einen deutlichen Performanceschub sorgt die Ausführung
mittels FCGI. Die Einrichtung wird ausführlich in der Datei
@code{INSTALL.fcgi} beschrieben.

Der Zugriff auf das Programmverzeichnis muss in der Apache
Webserverkonfigurationsdatei @code{httpd.conf} eingestellt
werden. Fügen Sie den folgenden Abschnitt dieser Datei oder einer
anderen Datei hinzu, die beim Starten des Webservers eingelesen wird:

@code{@*
AddHandler cgi-script .pl
@*
Alias /lx-erp/ /var/www/lx-erp/
@*
<Directory /var/www/lx-erp>
@*
  Options ExecCGI Includes FollowSymlinks
@*
</Directory>
@*
@*
<Directory /var/www/lx-erp/users>
@*
  Order Deny,Allow
@*
  Deny from All
@*
</Directory>
@*
}

Ersetzen Sie dabei die Pfade durch diejenigen, in die Sie vorher das
Lx-Office-Archiv entpacket haben.

Achtung: Vor den einzelnen Optionen muss bei einigen Distributionen ein
Plus @samp{+} gesetzt werden.

Auf einigen Webservern werden manchmal die Grafiken und Style-Sheets
nicht ausgeliefert. In solchen Fällen hat es oft geholfen, die
folgende Option in die Konfiguration aufzunehmen:

@code{EnableSendfile Off}

@c ---------------------------------------------------------------

@node Der Task-Server
@chapter Der Task-Server

Der Task-Server ist ein Prozess, der im Hintergrund läuft, in
regelmäßigen Abständen nach abzuarbeitenden Aufgaben sucht und diese
zu festgelegten Zeitpunkten abarbeitet (ähnlich wie Cron). Dieser
Prozess wird bisher nur für die Erzeugung der wiederkehrenden
Rechnungen benutzt, wird aber in Zukunft deutlich mehr Aufgaben
übertragen bekommen.

@menu
* Konfiguration des Task-Servers:: Verfügbare und notwendige Konfigurationsoptionen
* Prozesskontrolle:: Wie der Task-Server gestartet und beendet wird
* Einbinden in den Boot-Prozess:: Automatisches Starten des Task-Servers beim Booten
@end menu

@node Konfiguration des Task-Servers
@section Verfügbare und notwendige Konfigurationsoptionen

Die Konfiguration erfolgt über den Abschnitt @code{[task_server]} in
der Datei @file{config/lx_office.conf}. Die dort verfügbaren Optionen
sind:

@itemize
@item @code{login}: gültiger Lx-Office-Benutzername, der benutzt wird, um die zu verwendende Datenbankverbindung auszulesen. Der Benutzer muss in der Administration angelegt werden. Diese Option muss angegeben werden.
@item @code{run_as}: Wird der Server vom Systembenutzer @code{root} gestartet, so wechselt er auf den mit @code{run_as} angegebenen Systembenutzer. Der Systembenutzer muss dieselben Lese- und Schreibrechte haben, wie auch der Webserverbenutzer (siehe @pxref{Manuelle Installation des Programmpaketes}). Daher ist es sinnvoll, hier denselben Systembenutzer einzutragen, unter dem auch der Webserver läuft.
@item @code{debug}: Schaltet Debug-Informationen an und aus.
@end itemize

@node Einbinden in den Boot-Prozess
@section Automatisches Starten des Task-Servers beim Booten

Der Task-Server verhält sich von seinen Optionen her wie ein reguläres
SystemV-kompatibles Boot-Script. Außerdem wechselt er beim Starten
automatisch in das Lx-Office-Installationsverzeichnis.

Deshalb ist es möglich, ihn durch Setzen eines symbolischen Links aus
einem der Runlevel-Verzeichnisse heraus in den Boot-Prozess
einzubinden. Da das bei neueren Linux-Distributionen aber nicht
zwangsläufig funktioniert, werden auch Start-Scripte mitgeliefert, die
anstelle eines symbolischen Links verwendet werden können.

@subsection SystemV-basierende Systeme (z.B. Debian, OpenSuSE, Fedora Core)

Kopieren Sie die Datei
@file{scripts/boot/system-v/lx-office-task-server} nach
@file{/etc/init.d/lx-office-task-server}. Passen Sie in der kopierten
Datei den Pfad zum Task-Server an (Zeile @code{DAEMON=....}). Binden
Sie das Script in den Boot-Prozess ein. Dies ist distributionsabhängig:

@itemize
@item Debian-basierende Systeme:
@*
@code{update-rc.d lx-office-task-server defaults
@*
# Nur bei Debian Squeeze und neuer:
@*
insserv lx-office-task-server}
@item OpenSuSE und Fedora Core:
@*
@code{chkconfig --add lx-office-task-server}
@end itemize

Danach kann der Task-Server mit dem folgenden Befehl gestartet werden:
@code{/etc/init.d/lx-office-task-server start}

@subsection Upstart-basierende Systeme (z.B. Ubuntu)

Kopieren Sie die Datei
@file{scripts/boot/upstart/lx-office-task-server.conf} nach
@file{/etc/init/lx-office-task-server.conf}. Passen Sie in der kopierten
Datei den Pfad zum Task-Server an (Zeile @code{exec ....}).

Danach kann der Task-Server mit dem folgenden Befehl gestartet werden:
@code{service lx-office-task-server start}

@node Prozesskontrolle
@section Wie der Task-Server gestartet und beendet wird

Der Task-Server wird wie folgt kontrolliert:

@code{./scripts/task_server.pl Befehl}

@code{Befehl} ist dabei eine der folgenden Optionen:

@itemize
@item @code{start} startet eine neue Instanz des Task-Servers. Die Prozess-ID wird innerhalb des @file{users}-Verzeichnisses abgelegt.
@item @code{stop} beendet einen laufenden Task-Server.
@item @code{restart} beendet und startet ihn neu.
@item @code{status} berichtet, ob der Task-Server läuft.
@end itemize

Der Task-Server wechselt beim Starten automatisch in das Lx-Office-Installationsverzeichnis.

Dieselben Optionen können auch für die SystemV-basierenden
Runlevel-Scripte benutzt werden (siehe oben).

@c ---------------------------------------------------------------

@node Benutzerauthentifizierung und Administratorpasswort
@chapter Benutzerauthentifizierung und Administratorpasswort

Informationen über die Einrichtung der Benutzerauthentifizierung, über
die Verwaltung von Gruppen und weitere Einstellungen

@menu
* Grundlagen zur Benutzerauthentifizierung:: Verfügbare Methoden, Name der Konfigurationsdatei
* Administratorpasswort:: Wo das Administratorpasswort gesetzt werden kann
* Authentifizierungsdatenbank:: Verbindungseinstellungen zur Authentifizierungsdatenbank
* Passwortüberprüfung:: Einstellungen zur Überprüfung der Benutzerpasswörter
* Name des Session-Cookies:: Ändern des Cookie-Namens bei Verwendung mehrerer Lx-Office-Installationen auf einem Server
* Anlegen der Authentifizierungsdatenbank:: Wie die Authentifizierungsdatenbank angelegt wird
@end menu

@c ---------------------------------------------------------------

@node Grundlagen zur Benutzerauthentifizierung
@section Grundlagen zur Benutzerauthentifizierung

Lx-Office verwaltet die Benutzerinformationen in einer Datenbank, die
im folgenden ``Authentifizierungsdatenbank'' genannt wird. Für jeden
Benutzer kann dort eine eigene Datenbank für die eigentlichen
Finanzdaten hinterlegt sein. Diese beiden Datenbanken können, müssen
aber nicht unterschiedlich sein.

Im einfachsten Fall gibt es für Lx-Office nur eine einzige Datenbank,
in der sowohl die Benutzerinformationen als auch die Daten abgelegt
werden.

Zusätzlich ermöglicht es Lx-Office, dass die Benutzerpasswörter
entweder gegen die Authentifizierungsdatenbank oder gegen einen
LDAP-Server überprüft werden.

Welche Art der Passwortüberprüfung Lx-Office benutzt und wie Lx-Office
die Authentifizierungsdatenbank erreichen kann, wird in der
Konfigurationsdatei @file{config/lx_office.conf} festgelegt. Diese
muss bei der Installation und bei einem Upgrade von einer Version vor
v2.6.0 angelegt werden. Eine Beispielkonfigurationsdatei
@file{config/lx_office.conf.default} existiert, die als Vorlage
benutzt werden kann.

@node Administratorpasswort
@section Administratorpasswort

Das Passwort, das zum Zugriff auf das Aministrationsinterface benutzt wird,
wird ebenfalls in dieser Datei gespeichert. Es kann auch nur dort und nicht
mehr im Administrationsinterface selber geändert werden. Der Parameter dazu
heißt @code{$self->@{admin_password@}}.

@node Authentifizierungsdatenbank
@section Authentifizierungsdatenbank

Die Verbindung zur Authentifizierungsdatenbank wird mit den Parametern
in @code{$self->@{DB_config@}} konfiguriert. Hier sind die folgenden
Parameter anzugeben:

@itemize
@item
@samp{host} -- Der Rechnername oder die IP-Adresse des Datenbankservers
@item
@samp{port} -- Die Portnummer des Datenbankservers, meist 5432
@item
@samp{db} -- Der Name der Authentifizierungsdatenbank
@item
@samp{user} -- Der Benutzername, mit dem sich Lx-Office beim Datenbankserver anmeldet (z.B. ``postgres'')
@item
@samp{password} -- Das Passwort für den Datenbankbenutzer
@end itemize

Die Datenbank muss noch nicht existieren. Lx-Office kann sie
automatisch anlegen (mehr dazu siehe unten).

@node Passwortüberprüfung
@section Passwortüberprüfung

Lx-Office unterstützt Passwortüberprüfung auf zwei Arten: gegen die
Authentifizierungsdatenbank und gegen einen externen LDAP- oder
Active-Directory-Server. Welche davon benutzt wird, regelt der
Parameter @code{$self->@{module@}}.

Sollen die Benutzerpasswörter in der Authentifizierungsdatenbank
gespeichert werden, so muss der Parameter @code{$self->@{module@}} den
Wert @samp{DB} enthalten. In diesem Fall können sowohl der
Administrator als auch die Benutzer selber ihre Psaswörter in
Lx-Office ändern.

Soll hingegen ein externer LDAP- oder Active-Directory-Server benutzt
werden, so muss der Parameter @code{$self->@{module@}} auf @samp{LDAP}
gesetzt werden. In diesem Fall müssen zusätzliche Informationen über
den LDAP-Server in @code{$self->@{LDAP_config@}} angegeben werden:

@itemize
@item
@samp{host} -- Der Rechnername oder die IP-Adresse des LDAP- oder Active-Directory-Servers. Diese Angabe ist zwingend erforderlich.
@item
@samp{port} -- Die Portnummer des LDAP-Servers; meist 389.
@item
@samp{tls} -- Wenn Verbindungsverschlüsselung gewünscht ist, so diesen Wert auf @samp{1} setzen, andernfalls auf @samp{0} belassen
@item
@samp{attribute} -- Das LDAP-Attribut, in dem der Benutzername steht, den der Benutzer eingegeben hat. Für Active-Directory-Server
  ist dies meist @samp{sAMAccountName}, für andere LDAP-Server hingegen @samp{uid}. Diese Angabe ist zwingend erforderlich.
@item
@samp{base_dn} -- Der Abschnitt des LDAP-Baumes, der durchsucht werden soll. Diese Angabe ist zwingend erforderlich.
@item
@samp{filter} -- Ein optionaler LDAP-Filter. Enthält dieser Filter das Wort @code{<%login%>}, so wird dieses durch den vom Benutzer
  eingegebenen Benutzernamen ersetzt. Andernfalls wird der LDAP-Baum nach einem Element durchsucht, bei dem das oben angegebene Attribut
  mit dem Benutzernamen identisch ist.
@item
@samp{bind_dn} und @samp{bind_password} -- Wenn der LDAP-Server eine Anmeldung erfordert, bevor er durchsucht werden kann (z.B. ist dies bei
  Active-Directory-Servern der Fall), so kann diese hier angegeben werden. Für Active-Directory-Server kann als @samp{bind_dn} entweder eine
  komplette LDAP-DN wie z.B. @samp{cn=Martin Mustermann,cn=Users,dc=firmendomain} auch nur der volle Name des Benutzers
  eingegeben werden; in diesem Beispiel also @samp{Martin Mustermann}.
@end itemize

@node Name des Session-Cookies
@section Name des Session-Cookies

Sollen auf einem Server mehrere Lx-Office-Installationen aufgesetzt
werden, so müssen die Namen der Session-Cookies für alle
Installationen unterschiedlich sein. Der Name des Cookies wird mit dem
Parameter @code{$self->@{cookie_name@}} gesetzt.

Diese Angabe ist optional, wenn nur eine Installation auf dem Server
existiert.

@node Anlegen der Authentifizierungsdatenbank
@section Anlegen der Authentifizierungsdatenbank

Nachdem alle Einstellungen in @file{config/lx_office.conf}
vorgenommen wurden, muss Lx-Office die Authentifizierungsdatenbank
anlegen. Dieses geschieht automatisch, wenn Sie sich im
Administrationsmodul anmelden, das unter der folgenden URL erreichbar
sein sollte:

@uref{http://localhost/lx-erp/admin.pl}


@c ---------------------------------------------------------------

@node Benutzer- und Gruppenverwaltung
@chapter Benutzer- und Gruppenverwaltung

Nach der Installation müssen Benutzer, Gruppen und Datenbanken
angelegt werden.  Dieses geschieht im Administrationsmenü, das Sie
unter folgender URL finden:

@uref{http://localhost/lx-erp/admin.pl}

Verwenden Sie zur Anmeldung das Password, dass Sie in der Datei
@file{config/lx_office.conf} eingetragen haben.

@menu
* Zusammenhänge:: Übersicht über Benutzer, Gruppen, Berechtigungen und Datenbanken
* Datenbanken anlegen:: Hinweise zum Anlegen von Datenbanken
* Gruppen anlegen:: Hinweise zum Anlegen von Gruppen
* Benutzer anlegen:: Hinweise zum Anlegen von Benutzern
* Gruppenmitgliedschaften verwalten:: Wie man Gruppen Benutzer zuordnet
* Migration alter Installationen:: Automatische Übernahme bei Update von einer älteren Version
@end menu

@node Zusammenhänge
@section Zusammenhänge

Lx-Office verwendet eine Datenbank zum Speichern all seiner
Informationen wie Kundendaten, Artikel, Angebote, Rechnungen etc. Um
mit Lx-Office arbeiten zu können, muss eine Person einen
Benutzeraccount haben. Jedem Benutzeraccount wiederum wird genau eine
Datenbank zugewiesen, mit der dieser Benutzer arbeiten kann. Es ist
möglich und normal, dass mehreren Benutzern die selbe Datenbank
zugewiesen wird, sodass sie alle mit den selben Daten arbeiten können.

Die Basisdaten der Benutzer, die in der Administration eingegeben
werden können, werden in einer zweiten Datenbank gespeichert, der
bereits erwähnten Authentifizierungsdatenbank. Diese ist also den
Produktivdaten enthaltenden Datenbanken vorgeschaltet. Pro
Lx-Office-Installation gibt es nur eine Authentifizierungsdatenbank,
aber beliebig viele Datenbanken mit Firmendaten.

Lx-Office kann seinen Benutzern Zugriff auf bestimmte
Funktionsbereiche erlauben oder verbieten. Wird der Zugriff nicht
gestattet, so werden der entsprechenden Menüpunkte auch nicht
angezeigt. Diese Rechte werden ebenfalls in der
Authentifizierungsdatenbank gespeichert.

Um Rechte verteilen zu können, verwendet Lx-Office ein
Gruppen-Prinzip. Einer Gruppe kann der Zugriff auf bestimmte Bereiche
erlaubt werden. Ein Benutzer wiederum kann Mitglied in einer oder
mehrerer Gruppen sein. Der Benutzer hat Zugriff auf alle diejenigen
Funktionen, die mindestens einer Gruppe erlaubt sind, in der der
Benutzer Mitglied ist.

Die allgemeine Reihenfolge, in der Datenbanken, Gruppen und Benutzer
angelegt werden sollten, lautet:

@enumerate
@item
Datenbank anlegen
@item
Gruppen anlegen
@item
Benutzer anlegen
@item
Benutzer den Gruppen zuordnen
@end enumerate

@node Datenbanken anlegen
@section Datenbanken anlegen

Zuerst muss eine Datenbank angelegt werden. Verwenden Sie für den
Datenbankzugriff den vorhin angelegten Benutzer (in unseren Beispielen
ist dies @samp{lxoffice}).

Wenn Sie für die Lx-Office-Installation nicht den europäischen
Schriftsatz ISO-8859-15 sondern UTF-8 (Unicode) benutzen wollen, so
müssen Sie vor dem Anlegen der Datenbank in der Datei
@file{config/lx_office.conf} die Variable @code{dbcharset} im
Abschnitt @code{system} auf den Wert @samp{UTF-8} setzen. Zusätzlich
muss beim Anlegen der Datenbank @samp{UTF-8 Unicode} als Schriftsatz
ausgewählt werden.

Bitte beachten Sie, dass alle Datenbanken den selben Zeichensatz
verwenden müssen, da diese Einstellungen momentan global in Lx-Office
vorgenommen wird und nicht nach Datenbank unterschieden werden
kann. Auch die Authentifizierungsdatenbank muss mit diesem Zeichensatz
angelegt worden sein.

@node Gruppen anlegen
@section Gruppen anlegen

Eine Gruppe wird in der Gruppenverwaltung angelegt. Ihr muss ein Name
gegeben werden, eine Beschreibung ist hingegen optional. Nach dem
Anlegen können Sie die verschiedenen Bereiche wählen, auf die
Mitglieder dieser Gruppe Zugriff haben sollen.

Benutzergruppen sind unabhängig von Datenbanken, da sie in der
Authentifizierungsdatenbank gespeichert werden. Sie gelten für alle
Datenbanken, die in dieser Installation verwaltet werden.

@node Benutzer anlegen
@section Benutzer anlegen

Beim Anlegen von Benutzern werden für viele Parameter
Standardeinstellungen vorgenommen, die den Gepflogenheiten des
deutschen Raumes entsprechen.

Zwingend anzugeben sind der Loginname sowie die komplette
Datenbankkonfiguration. Wenn die Passwortauthentifizierung über die
Datenbank eingestellt ist, so kann hier auch das Benutzerpasswort
gesetzt bzw. geändert werden. Ist hingegen die LDAP-Authentifizierung
aktiv, so ist das Passwort-Feld deaktiviert.

In der Datenbankkonfiguration müssen die Zugriffsdaten einer der eben
angelegten Datenbanken eingetragen werden.

@node Gruppenmitgliedschaften verwalten
@section Gruppenmitgliedschaften verwalten

Nach dem Anlegen von Benutzern und Gruppen müssen Benutzer den Gruppen
zugewiesen werden. Dazu gibt es zwei Möglichkeiten:

@enumerate
@item
In der Gruppenverwaltung wählt man eine Gruppe aus. Im folgenden
Dialog kann man dann einzeln die Benutzer der Gruppe hinzufügen.
@item
In der Gruppenverwaltung wählt man das Tool zur Verwaltung der
Gruppenmitgliedschaft. Hier wird eine Matrix angezeigt, die alle im
System angelegten Gruppen und Benutzer enthält. Durch Setzen der
Häkchen wird der Benutzer in der ausgewählten Zeile der Gruppe in der
ausgewählten Spalte hinzugefügt.
@end enumerate

@node Migration alter Installationen
@section Migration alter Installationen

Wenn Lx-Office 2.6.2 über eine ältere Version installiert wird, in der
die Benutzerdaten noch im Dateisystem im Verzeichnis @code{users}
verwaltet wurden, so bietet Lx-Office die Möglichkeit, diese
Benutzerdaten automatisch in die Authentifizierungsdatenbank zu
übernehmen. Dies geschieht, wenn man sich nach dem Update der
Installation das erste Mal im Administrationsbereich anmeldet. Findet
Lx-Office die Datei @code{users/members}, so wird der
Migrationsprozess gestartet.

Der Migrationsprozess ist nahezu vollautomatisch. Alle Benutzerdaten
können übernommen werden. Nach den Benutzerdaten bietet Lx-Office noch
die Möglichkeit an, dass automatisch eine Benutzergruppe angelegt
wird. Dieser Gruppe wird Zugriff auf alle Funktionen von Lx-Office
gewährt. Alle migrierten Benutzern werden Mitglied in dieser
Gruppe. Damit wird das Verhalten von Lx-Office bis Version 2.4.3
inklusive wiederhergestellt, und die Benutzer können sich sofort
wieder anmelden und mit dem System arbeiten.

@c ---------------------------------------------------------------

@node Drucken mit Lx-Office
@chapter Drucken mit Lx-Office

Das Drucksystem von Lx-Office benutzt von Haus aus LaTeX Vorlagen. Um drucken
zu können, braucht der Server ein geeignetes LaTeX System. Am einfachsten ist
dazu eine @code{texlive} Installation. Unter Debianoiden Betriebssystemen sind
das die Pakete:

@code{texlive-latex-base texlive-latex-extra texlive-fonts-recommended}

Diese hinteren beiden enthalten Bibliotheken und Schriftarten die von den
Standardvorlagen verwendet werden.

TODO: rpm Pakete.

In den allermeisten Installationen sollte drucken jetzt schon funktionieren.
Sollte ein Fehler auftreten wirft TeX sehr lange Fehlerbeschreibungen, der
eigentliche Fehler ist immer die erste Zeite die mit einem Ausrufezeichen
anfängt. Häufig auftretende Fehler sind zum Beispiel:

@itemize
@item ! LaTeX Error: File `eurosym.sty' not found.
Die entsprechende LaTeX-Bibliothek wurde nicht gefunden. Das tritt vor allem
bei Vorlagen aus der Community auf. Installieren Sie die entsprechenden Pakete.
@item ! Package inputenc Error: Unicode char \u8:æ¡\9c not set up for use with LaTeX.
Dieser Fehler tritt auf, wenn sie versuchen mit einer Standardinstallation
exotische utf8 Zeichen zu drucken. TeXLive unterstützt von Haus nur romanische
Schriften und muss mit diversen Tricks dazu gebracht werden andere Zeichen zu
akzeptieren. Adere TeX Systeme wie XeTeX schaffen hier Abhilfe.
@end itemize

Wird garkein Fehler angezeigt sondern nur der Name des Templates, heißt das
normalerweise, dass das LaTeX Binary nicht gefunden wurde. Prüfen Sie den Namen
in der Konfiguration (Standard: @code{pdflatex}), und stellen Sie sicher, dass
pdflatex (oder das von Ihnen verwendete System) vom Webserver ausgeführt werden
darf.

@c ---------------------------------------------------------------

@node OpenDocument-Vorlagen
@chapter OpenDocument-Vorlagen

Lx-Office unterstützt die Verwendung von Vorlagen im
OpenDocument-Format, wie es OpenOffice.org ab Version 2
erzeugt. Lx-Office kann dabei sowohl neue OpenDocument-Dokumente als
auch aus diesen direkt PDF-Dateien erzeugen.  Um die Unterstützung von
OpenDocument-Vorlagen zu aktivieren muss in der Datei
@file{config/lx_office.conf} die Variable @code{opendocument} im
Abschnitt @code{print_templates} auf @samp{1} stehen.  Dieses ist die
Standardeinstellung.

Weiterhin muss in der Datei @file{config/lx_office.conf} die Variable
@code{dbcharset} im Abschnitt @code{system} auf die Zeichenkodierung
gesetzt werden, die auch bei der Speicherung der Daten in der
Datenbank verwendet wird. Diese ist in den meisten Fällen "UTF-8".

Während die Erzeugung von reinen OpenDocument-Dateien keinerlei
weitere Software benötigt, wird zur Umwandlung dieser Dateien in PDF
OpenOffice.org benötigt. Soll dieses Feature genutzt werden, so muss
neben OpenOffice.org ab Version 2 auch der ``X virtual frame buffer''
(xvfb) installiert werden.  Bei Debian ist er im Paket ``xvfb''
enthalten. Andere Distributionen enthalten ihn in anderen Paketen.

Nach der Installation müssen in der Datei @file{config/lx_config.conf}
zwei weitere Variablen angepasst werden: @code{openofficeorg_writer}
muss den vollständigen Pfad zur OpenOffice.org Writer-Anwendung
enthalten. @code{xvfb} muss den Pfad zum ``X virtual frame buffer''
enthalten. Beide stehen im Abschnitt @code{applications}.

Zusätzlich gibt es zwei verschiedene Arten, wie Lx-Office mit
OpenOffice kommuniziert. Die erste Variante, die benutzt wird, wenn
die Variable @code{$openofficeorg_daemon} gesetzt ist, startet ein
OpenOffice, das auch nach der Umwandlung des Dokumentes gestartet
bleibt. Bei weiteren Umwandlungen wird dann diese laufende Instanz
benutzt. Der Vorteil ist, dass die Zeit zur Umwandlung deutlich
reduziert wird, weil nicht für jedes Dokument ein OpenOffice gestartet
werden muss. Der Nachteil ist, dass diese Methode Python und die
Python-UNO-Bindings benötigt, die Bestandteil von OpenOffice 2 sind.

Ist @code{$openofficeorg_daemon} nicht gesetzt, so wird für jedes
Dokument OpenOffice neu gestartet und die Konvertierung mit Hilfe
eines Makros durchgeführt. Dieses Makro muss in der Dokumentenvorlage
enthalten sein und ``Standard.Conversion.ConvertSelfToPDF()''
heißen. Die Beispielvorlage @samp{templates/mastertemplates/German/invoice.odt}
enthält ein solches Makro, das in jeder anderen Dokumentenvorlage
ebenfalls enthalten sein muss.

Als letztes muss herausgefunden werden, welchen Namen OpenOffice.org
Writer dem Verzeichnis mit den Benutzereinstellungen gibt. Unter
Debian ist dies momentan @code{~/.openoffice.org2}. Sollte der Name
bei Ihrer OpenOffice.org-Installation anders sein, so muss das
Verzeichnis @code{users/.openoffice.org2} entsprechend umbenannt
werden. Ist der Name z.B. einfach nur @code{.openoffice}, so wäre
folgender Befehl auszuführen:

@code{mv users/.openoffice.org2 users/.openoffice}

Dieses Verzeichnis, wie auch das komplette @code{users}-Verzeichnis, muss vom
Webserver beschreibbar sein. Dieses wurde bereits erledigt
(@pxref{Manuelle Installation des Programmpaketes}), kann aber erneut überprüft
werden, wenn die Konvertierung nach PDF fehlschlägt.

@c ---------------------------------------------------------------

@node Lx-Office ERP verwenden
@chapter Lx-Office ERP verwenden

Nach erfolgreicher Installation ist der Loginbildschirm unter
folgender URL erreichbar:

@uref{http://localhost/lx-office-erp/login.pl}

Die Administrationsseite erreichen Sie unter:

@uref{http://localhost/lx-office-erp/admin.pl}

@bye