X-Git-Url: http://wagnertech.de/git?a=blobdiff_plain;f=doc%2Fdokumentation.xml;h=5d01c462bc3132c8b98dbd340ab07ca127ea0861;hb=caa629de1287f86231fa7a468b53372b38edc131;hp=2f96804d3042ca352354562667706a023dd4885c;hpb=fd6eee82b34349036d3dd097f05c10a47f730e2b;p=kivitendo-erp.git diff --git a/doc/dokumentation.xml b/doc/dokumentation.xml index 2f96804d3..5d01c462b 100644 --- a/doc/dokumentation.xml +++ b/doc/dokumentation.xml @@ -2,7 +2,8 @@ - kivitendo 3.5.0: Installation, Konfiguration, Entwicklung + kivitendo 3.5.3: Installation, Konfiguration, + Entwicklung Aktuelle Hinweise @@ -105,7 +106,7 @@ ohne große Probleme auf den derzeit aktuellen verbreiteten Distributionen läuft. - Anfang 2016 sind das folgende Systeme, von denen bekannt ist, + Anfang 2019 sind das folgende Systeme, von denen bekannt ist, dass kivitendo auf ihnen läuft: @@ -114,27 +115,28 @@ - 7.0 "Wheezy" + 8.0 "Jessie" - - 8.0 "Jessie" + 9.0 "Stretch" + + + 10.0 "Buster" - Ubuntu 12.04 LTS "Precise Pangolin", 14.04 "Trusty Tahr" - LTS, 15.10 "Wily Werewolf" und 16.04 "Xenial Xerus" LTS - Alpha + 16.04 "Xenial Xerus" LTS und 18.04 "Bionic Beaver" LTS + - openSUSE LEAP 42.1 + openSUSE 15.0 - Fedora 22 + Fedora 29 @@ -158,17 +160,13 @@ - parent (nur bei Perl vor 5.10.1) + Algorithm::CheckDigits Archive::Zip - - Algorithm::CheckDigits - - CGI @@ -181,14 +179,26 @@ Config::Std + + Daemon::Generic + + DateTime + + DateTime::Event::Cron + + DateTime::Format::Strptime + + DateTime::Set + + DBI @@ -205,6 +215,10 @@ Email::MIME + + Exception::Class + + FCGI (nicht Versionen 0.68 bis 0.71 inklusive; siehe File::Copy::Recursive + + File::Flock + + File::MimeInfo + + File::Slurp + + GD @@ -279,6 +301,10 @@ PDF::API2 + + Regexp::IPv6 + + Rose::Object @@ -292,6 +318,10 @@ neuer + + Set::Infinite + + String::ShellQuote @@ -325,16 +355,25 @@ - YAML + YAML::XS oder YAML + Seit Version größer v3.5.3 sind die folgenden Pakete hinzugekommen: Exception::Class + + Seit Version größer v3.5.1 sind die folgenden Pakete hinzugekommen: Set::Infinite, + List::UtilsBy, DateTime::Set, DateTime::Event::Cron + Daemon::Generic, DateTime::Event::Cron, File::Flock, + File::Slurp + Seit Version größer v3.5.0 sind die folgenden Pakete - hinzugekommen: Text::Unidecode, LWP::Authen::Digest, - LWP::UserAgent + hinzugekommen: Text::Unidecode, + LWP::Authen::Digest, + LWP::UserAgent Seit Version v3.4.0 sind die folgenden Pakete hinzugekommen: - Algorithm::CheckDigitsPBKDF2::Tiny + Algorithm::CheckDigits, + PBKDF2::Tiny Seit Version v3.2.0 sind die folgenden Pakete hinzugekommen: GD, HTML::Restrict, @@ -370,9 +409,8 @@ Debian und Ubuntu - Für Debian und Ubuntu stehen die meisten der benötigten - Perl-Pakete als Debian-Pakete zur Verfügung. Sie können mit + Pakete als Debian-Pakete zur Verfügung. Sie können mit folgendem Befehl installiert werden: apt install apache2 libarchive-zip-perl libclone-perl \ @@ -385,15 +423,24 @@ libtext-iconv-perl liburi-perl libxml-writer-perl libyaml-perl \ libimage-info-perl libgd-gd2-perl libapache2-mod-fcgid \ libfile-copy-recursive-perl postgresql libalgorithm-checkdigits-perl \ - libcrypt-pbkdf2-perl git libcgi-pm-perl libtext-unidecode-perl libwww-perl + libcrypt-pbkdf2-perl git libcgi-pm-perl libtext-unidecode-perl libwww-perl\ + postgresql-contrib aqbanking-tools poppler-utils libhtml-restrict-perl\ + libdatetime-set-perl libset-infinite-perl liblist-utilsby-perl\ + libdaemon-generic-perl libfile-flock-perl libfile-slurp-perl\ + libfile-mimeinfo-perl libpbkdf2-tiny-perl libregexp-ipv6-perl \ + libdatetime-event-cron-perl libexception-class-perl - - Für das Paket HTML::Restrict gibt es kein Debian-Paket, dies - muß per CPAN installiert werden. Unter Ubuntu funktioniert das - mit: - +Sollten Pakete nicht zu Verfügung stehen, so können diese auch mittels CPAN installiert werden. Ferner muss für Ubuntu das Repository "Universe" aktiv sein (s.a. Anmerkungen). + + Die Perl Pakete für Ubuntu befinden sich im "Universe" Repository. Falls dies nicht aktiv ist, kann dies mit folgendem Aufruf aktiviert werden: +add-apt-repository universe + + + Für ältere Ubuntu/Debians müßen einige Pakete per CPAN installiert werden. + Das geht bspw. für das benötige Paket HTML::Restrict mit: apt-get install build-essential cpan HTML::Restrict + @@ -403,19 +450,17 @@ cpan HTML::Restrict RPM-Pakete zur Verfügung. Sie können mit folgendem Befehl installiert werden: - dnf install httpd mod_fcgid perl-Archive-Zip perl-Clone perl-DBD-Pg \ - perl-DBI perl-DateTime perl-Email-Address perl-Email-MIME perl-FCGI \ - perl-File-Copy-Recursive perl-JSON perl-List-MoreUtils perl-Net-SMTP-SSL perl-Net-SSLGlue \ - perl-PDF-API2 perl-Params-Validate perl-Rose-DB perl-Rose-DB-Object \ + dnf install httpd mod_fcgid postgresql-server postgresql-contrib\ + perl-Algorithm-CheckDigits perl-Archive-Zip perl-CPAN perl-Class-XSAccessor \ + perl-Clone perl-Config-Std perl-DBD-Pg perl-DBI perl-Daemon-Generic \ + perl-DateTime perl-DateTime-Set perl-Email-Address perl-Email-MIME perl-FCGI \ + perl-File-Copy-Recursive perl-File-Flock perl-File-MimeInfo perl-File-Slurp \ + perl-GD perl-HTML-Restrict perl-JSON perl-List-MoreUtils perl-List-UtilsBy \ + perl-Net-SMTP-SSL perl-Net-SSLGlue perl-PBKDF2-Tiny perl-PDF-API2 \ + perl-Params-Validate perl-Regexp-IPv6 perl-Rose-DB perl-Rose-DB-Object \ perl-Rose-Object perl-Sort-Naturally perl-String-ShellQuote \ - perl-Template-Toolkit perl-Text-CSV_XS perl-Text-Iconv perl-URI \ - perl-XML-Writer perl-YAML perl-parent postgresql-server perl-CPAN \ - perl-Algorithm-CheckDigits perl-GD perl-Class-XSAccessor perl-Text-Balanced perl-libwww-perl - - Zusätzlich müssen einige Pakete aus dem CPAN installiert - werden. Dazu können Sie die folgenden Befehle nutzen: - - cpan Config::Std HTML::Restrict + perl-Template-Toolkit perl-Text-CSV_XS perl-Text-Iconv perl-URI perl-XML-Writer \ + perl-YAML perl-libwww-perl @@ -425,18 +470,24 @@ cpan HTML::Restrict RPM-Pakete zur Verfügung. Sie können mit folgendem Befehl installiert werden: - zypper install apache2 apache2-mod_fcgid perl-Archive-Zip perl-Clone \ - perl-Config-Std perl-DBD-Pg perl-DBI perl-DateTime perl-Email-Address \ - perl-Email-MIME perl-FastCGI perl-File-Copy-Recursive perl-JSON perl-List-MoreUtils \ - perl-Net-SMTP-SSL perl-Net-SSLGlue perl-PDF-API2 perl-Params-Validate \ - perl-Sort-Naturally perl-Template-Toolkit perl-Text-CSV_XS perl-Text-Iconv \ - perl-URI perl-XML-Writer perl-YAML perl-CPAN \ - perl-Algorithm-CheckDigits perl-GD perl-Class-XSAccessor postgresql-server perl-libwwww-perl + zypper install apache2 apache2-mod_fcgid postgresql-server postgresql-contrib\ + perl-Algorithm-CheckDigits perl-Archive-Zip perl-CGI perl-Class-XSAccessor \ + perl-Clone perl-Config-Std perl-DBD-Pg perl-DBI perl-Daemon-Generic \ + perl-DateTime perl-DateTime-Format-Strptime perl-Email-Address \ + perl-Email-MIME perl-FastCGI perl-File-Copy-Recursive perl-File-Flock \ + perl-File-MimeInfo perl-File-Slurp perl-GD perl-Image-Info perl-JSON \ + perl-List-MoreUtils perl-List-UtilsBy perl-Net-SMTP-SSL perl-Net-SSLGlue \ + perl-PDF-API2 perl-Params-Validate perl-Regexp-IPv6 \ + perl-Sort-Naturally perl-String-ShellQuote perl-Template-Toolkit \ + perl-Text-CSV_XS perl-Text-Iconv perl-Text-Unidecode perl-URI \ + perl-XML-Writer perl-YAML perl-libwww-perl + Zusätzlich müssen einige Pakete aus dem CPAN installiert werden. Dazu können Sie die folgenden Befehle nutzen: - cpan Rose::Db::Object + cpan DateTime::event::Cron DateTime::Set FCGI \ + HTML::Restrict PBKDF2::Tiny Rose::Db::Object Set::Infinite @@ -449,7 +500,9 @@ cpan HTML::Restrict Debian und Ubuntu: apt install aqbanking-tools - OpenSuSE: zypper install aqbanking-tools + Fedora: dnf install aqbanking + + openSUSE: zypper install aqbanking-tools Seit Version v3.4.1 wird generell zum Feststellen der Seitenanzahl von PDF_Dokumenten 'pdfinfo' benötigt was im Paket @@ -458,7 +511,9 @@ cpan HTML::Restrict Debian und Ubuntu: apt install poppler-utils - OpenSuSE: zypper install poppler-tools + Fedora: dnf install poppler-utils + + openSUSE: zypper install poppler-tools @@ -471,15 +526,15 @@ cpan HTML::Restrict url="https://github.com/kivitendo/kivitendo-erp/releases">hier heruntergeladen werden. - Die kivitendo ERP Installationsdatei - (kivitendo-erp-3.4.1.tgz) wird im + Diese aktuelleste kivitendo ERP-Archiv + (kivitendo-erp-*.tgz) wird dann im Dokumentenverzeichnis des Webservers (z.B. /var/www/html/, /srv/www/htdocs oder /var/www/) entpackt: cd /var/www -tar xvzf kivitendo-erp-3.4.1.tgz +tar xvzf kivitendo-erp-*.tgz Wechseln Sie in das entpackte Verzeichnis: @@ -500,7 +555,7 @@ tar xvzf kivitendo-erp-3.4.1.tgz restlichen Dateien müssen für diesen Benutzer lesbar sein. Die Benutzer- und Gruppennamen sind bei verschiedenen Distributionen unterschiedlich (z.B. bei Debian/Ubuntu www-data, bei Fedora - apache oder bei OpenSUSE + apache oder bei openSUSE wwwrun). Der folgende Befehl ändert den Besitzer für die oben genannten @@ -524,11 +579,11 @@ git clone https://github.com/kivitendo/kivitendo-erp.git cd kivitendo-erp/ git checkout `git tag -l | egrep -ve "(alpha|beta|rc)" | tail -1` Erläuterung: Der Befehl wechselt zur letzten Stable-Version (git tag - -l listet alle Tags auf, das egrep schmeisst alle Einträge mit alpha, beta - oder rc raus und das tail gibt davon den obersten Treffer zurück). - Sehr sinnvoll ist es, direkt im Anschluss einen eigenen Branch zu - erzeugen, um bspw. seine eigenen Druckvorlagen-Anpassungen damit zu - verwalten. Hierfür reicht ein simples git checkout -b meine_eigenen_änderungen + -l listet alle Tags auf, das egrep schmeisst alle Einträge mit alpha, + beta oder rc raus und das tail gibt davon den obersten Treffer + zurück). Sehr sinnvoll ist es, direkt im Anschluss einen eigenen + Branch zu erzeugen, um bspw. seine eigenen Druckvorlagen-Anpassungen + damit zu verwalten. Hierfür reicht ein simples git checkout -b meine_eigenen_änderungen nach dem letzten Kommando (weiterführende Informationen Git Magic). @@ -768,7 +823,19 @@ default_manager = german Anpassung der PostgreSQL-Konfiguration PostgreSQL muss auf verschiedene Weisen angepasst werden. - + Dies variert je nach eingesetzter Distribution, da distributionsabhängig unterschiedliche Strategien beim Upgrade der Postgres Version eingesetzt werden. + Als Hinweis einige Links zu den drei Distribution (Stand Dezember 2018): + + + Fedora (Postgres-Installation unter Fedora) + + + Ubuntu (Infos für Postgres für die aktuelle LTS Version) + + + OpenSuSE (aktuell nur bis Version OpenSuSE 13 verifiziert) + + Zeichensätze/die Verwendung von Unicode/UTF-8 @@ -849,6 +916,35 @@ psql template1 führen Sie die folgenden Kommandos aus: + + Erweiterung für Trigram Prozeduren + + Ab Version 3.5.1 wird die Trigram-Index-Erweiterung benötigt. + Diese wird mit dem SQL-Updatescript + sql/Pg-upgrade2/trigram_extension.sql und Datenbank-Super-Benutzer + Rechten automatisch installiert. Dazu braucht der + DatenbankSuperbenutzer "postgres" ein Passwort. + + su - postgres +psql +\password postgres + +Eingabe Passwort +\q + + Benutzername Postgres und Passwort können jetzt beim Anlegen + einer Datenbank bzw. bei Updatescripten, die SuperuserRechte + benötigen, eingegeben werden. + + + pg_trgm ist je nach Distribution nicht im + Standard-Paket von Postgres enthalten. Ein select * from pg_available_extensions where name ='pg_trgm'; + in template1 sollte entsprechend erfolgreich sein. Andernfalls muss + das Paket nachinstalliert werden, bspw. bei debian/ubuntu + apt install postgresql-contrib + + + Datenbankbenutzer anlegen @@ -965,22 +1061,16 @@ Alias /kivitendo-erp/ /var/www/kivitendo-erp/ - Apache 2.2.11 (Ubuntu) und mod_fcgid. + Apache 2.4.7 (Ubuntu 14.04.2 LTS) und mod_fcgid. - - Apache 2.2.11 / 2.2.22 (Ubuntu) und mod_fastcgi. + Apache 2.4.18 (Ubuntu 16.04 LTS) und mod_fcgid - - Apache 2.4.7 (Ubuntu 14.04.2 LTS) und mod_fcgid. + Apache 2.4.29 (Ubuntu 18.04 LTS) und mod_fcgid - Dabei wird mod_fcgid empfohlen, weil mod_fastcgi seit geraumer - Zeit nicht mehr weiter entwickelt wird. Im Folgenden wird auf - mod_fastcgi nicht mehr explizit eingegangen. - Als Perl Backend wird das Modul FCGI.pm verwendet. @@ -1076,13 +1166,11 @@ FcgidMaxRequestLen 10485760 <Directory /path/to/kivitendo-erp> AllowOverride All Options ExecCGI Includes FollowSymlinks - Order Allow,Deny - Allow from All + Require all granted </Directory> <DirectoryMatch /path/to/kivitendo-erp/users> - Order Deny,Allow - Deny from All +Require all denied </DirectoryMatch> Hierdurch wird nur ein zentraler Dispatcher gestartet. Alle @@ -1108,6 +1196,20 @@ Alias /url/for/kivitendo-erp-fcgid/ /path/to/kivitendo-erp/ + + Authentifizierung mittels HTTP Basic Authentication + + + Kivitendo unterstützt, dass Benutzerauthentifizierung über den Webserver mittels des »Basic«-HTTP-Authentifizierungs-Schema erfolgt + (siehe RFC 7617). Dazu ist es aber nötig, dass der dabei vom Client + mitgeschickte Header Authorization vom Webserver an Kivitendo über die Umgebungsvariable + HTTP_AUTHORIZATION weitergegeben wird, was standardmäßig nicht der Fall ist. Für Apache kann dies über die + folgende Konfigurationsoption aktiviert werden: + + + SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1 + + Weitergehende Konfiguration @@ -1211,7 +1313,7 @@ Alias /url/for/kivitendo-erp-fcgid/ /path/to/kivitendo-erp/ SystemV-basierende Systeme (z.B. ältere Debian, ältere - OpenSUSE, ältere Fedora) + openSUSE, ältere Fedora) Kopieren Sie die Datei scripts/boot/system-v/kivitendo-task-server @@ -1229,7 +1331,7 @@ insserv kivitendo-task-server - Ältere OpenSUSE und ältere Fedora: + Ältere openSUSE und ältere Fedora: chkconfig --add kivitendo-task-server @@ -1880,8 +1982,8 @@ systemctl enable kivitendo-task-server.service einfachsten ist dazu eine texlive Installation. Unter debianoiden Betriebssystemen installiert man die Pakete mit: - apt-get install texlive-base-bin texlive-latex-recommended texlive-fonts-recommended \ - texlive-latex-extra texlive-lang-german texlive-generic-extra + apt install texlive-base-bin texlive-latex-recommended texlive-fonts-recommended \ + texlive-latex-extra texlive-lang-german texlive-generic-extra texlive-xetex ghostscript Für Fedora benötigen Sie die folgenden Pakete: @@ -7727,6 +7829,89 @@ file_name = /tmp/kivitendo-debug.log + + Programmatische API-Aufrufe + + + Einführung + + + Es ist möglich, Funktionen in kivitendo programmatisch aus anderen Programmen aufzurufen. Dazu ist nötig, dass + Authentifizierungsinformationen in jedem Aufruf mitgegeben werden. Dafür gibt es zwei Methoden: die HTTP-»Basic«-Authentifizierung + oder die Übergabe als spziell benannte GET-Parameter. Neben den Authentifizierungsinformationen muss auch der zu verwendende Mandant + übergeben werden. + + + + + Wahl des Mandanten + + + Der zu verwendende Mandant kann als Parameter {AUTH}client_id mit jedem Request mitgeschickt werden. Der Wert + muss dabei die Datenbank-ID des Mandanten sein. kivitendo prüft, ob der Account, der über die Authentifizierungsinformationen + übergeben wurde, Zugriff auf den angegebenen Mandanten hat. + + + + Wird in einem Request kein Mandant mitgegeben, so wird derjenige Mandant genommen, wer als Standardmandant markiert wurde. Gibt es + keinen solchen, kommt es zu einer Fehlermeldung. + + + + + HTTP-»Basic«-Authentifizierung + + + Für diese Methode muss jedem Request der bekannte HTTP-Header Authorization mitgeschickt werden (siehe RFC 7617). Unterstützt wird ausschließlich die »Basic«-Methode. Loginname und + Passwort werden bei dieser Methode durch einen Doppelpunkt getrennt und Base64-encodiert im genannten HTTP-Header übertragen. + + + + Diese Informationen müssen einen vorhandenen Account benennen. kivitendo prüft genau wie bei Benutzung über den Webbrowser, ob + dieser Account Zugriff auf den Mandanten sowie auf die angeforderte Funktion hat. + + + + Da die Logininformationen im Klartext im Request stehen, sollte der Zugriff auf kivitendo ausschließlich über HTTPS verschlüsselt + erfolgen. + + + + + Authentifizierung mit Parametern + + + Für diese Methode müssen jedem Request zwei Parameter mitgegeben werden: {AUTH}login und + {AUTH}password. Diese Informationen müssen einen vorhandenen Account benennen. kivitendo prüft genau wie bei + Benutzung über den Webbrowser, ob dieser Account Zugriff auf den Mandanten sowie auf die angeforderte Funktion hat. + + + + Da die Logininformationen im Klartext im Request stehen, sollte der Zugriff auf kivitendo ausschließlich über HTTPS verschlüsselt + erfolgen. + + + + + Die Verwendung dieser Methode ist veraltet. Statt dessen sollte die oben erwähnte HTTP-»Basic«-Authentifizierung verwendet werden. + + + + + + Beispiele + + + Das folgende Beispiel nutzt das Kommandozeilenprogramm »curl« und ruft die Funktion auf, die eine vorhandene Telefonnummer in den + Ansprechpersonen sucht und dazu Informationen zurückliefert. Dabei wird die HTTP-»Basic«-Authentifizierung genutzt. + + + $ curl --silent --user 'jdoe:SecretPassword!' \ + 'https://…/controller.pl?action=PhoneNumber/look_up&number=053147110815' + + + SQL-Upgradedateien @@ -8341,11 +8526,14 @@ $self->{more_texts} = { angegeben werden. Der hier angegebene Benutzer muss weiterhin das Recht haben, Datenbanken anzulegen und zu löschen. - Der so angegebene Benutzer muss nicht zwingend über Super-User-Rechte verfügen. Allerdings gibt es einige Datenbank-Upgrades, - die genau diese Rechte benötigen. Für den Fall kann man in diesem Konfigurationsabschnitt einen weiteren Benutzeraccount angeben, - der dann über Super-User-Rechte verfügt, und mit dem die betroffenen Upgrades durchgeführt werden. In der - Beispiel-Konfigurationsdatei finden Sie die benötigten Parameter. - + Der so angegebene Benutzer muss nicht zwingend über + Super-User-Rechte verfügen. Allerdings gibt es einige + Datenbank-Upgrades, die genau diese Rechte benötigen. Für den Fall + kann man in diesem Konfigurationsabschnitt einen weiteren + Benutzeraccount angeben, der dann über Super-User-Rechte verfügt, und + mit dem die betroffenen Upgrades durchgeführt werden. In der + Beispiel-Konfigurationsdatei finden Sie die benötigten + Parameter.