Browse Source

[doc] update README and INSTALL

also add tests/README with some testing notes
master
Glenn Strauss 4 months ago
parent
commit
140c0fb8f4
3 changed files with 229 additions and 15 deletions
  1. +140
    -9
      INSTALL
  2. +7
    -6
      README
  3. +82
    -0
      tests/README

+ 140
- 9
INSTALL View File

@ -3,25 +3,22 @@
Installation
============
:author: Jan Kneschke
:Date: $Date: $
:Revision: $Revision: $
Installation
------------
Quick Installation
------------------
Get the source from
Get lighttpd source from
https://www.lighttpd.net/download/
unpack it by ::
$ gzip -cd lighttpd-1.x.x.tar.gz | tar xf -
$ tar xvJf lighttpd-1.4.xx.tar.xz
compile and install it with ::
$ cd lighttpd-1.x.x
$ ./configure
$ cd lighttpd-1.4.xx
$ ./configure -C
$ make
$ su -
# make install
@ -31,6 +28,140 @@ take look at the configfile in ./doc/lighttpd.conf,
make your own copy of that file and modify it for your needs.
Online documentation
--------------------
https://redmine.lighttpd.net/projects/lighttpd/wiki/Devel
https://redmine.lighttpd.net/projects/lighttpd/wiki/DevelSubversion
https://redmine.lighttpd.net/projects/lighttpd/wiki/InstallFromSource
Custom Installation
-------------------
required packages ::
autoconf
automake
libtool
m4
pcre
pcre-devel
pkg-config
optional packages for optional features ::
bzip2-devel # bzip2 ./configure --with-bzip2
bzip2-libs
cyrus-sasl # SASL ./configure --with-sasl
cyrus-sasl-devel
gamin # FAM ./configure --with-fam
gamin-devel
gdbm # GDBM ./configure --with-gdbm
gdbm-devel
GeoIP-devel # GeoIP ./configure --with-geoip
GeoIP
gnutls # GnuTLS ./configure --with-gnutls
gnutls-devel
krb5-devel # Kerberos5 ./configure --with-krb5
krb5-libs
libattr # xattr ./configure --with-attr
libattr-devel
libbrotli # brotli ./configure --with-brotli
brotli-devel
libdbi # DBI ./configure --with-dbi
libdbi-devel
libdbi-dbd-mysql
libdbi-dbd-pgsql
libdbi-dbd-sqlite
libmaxminddb # MaxMindDB ./configure --with-maxminddb
libmaxminddb-devel
libmemcached-devel # Memcached ./configure --with-memcache
libmemcached-libs
libpq # Postgresql ./configure --with-pgsql
libpq-devel
libunwind # libunwind ./configure --with-libunwind
libuuid # libuuid ./configure --with-webdav-locks
libuuid-devel
libxml2 # libxml2 ./configure --with-webdav-props
libxml2-devel
libxml2-static
lua # Lua ./configure --with-lua
lua-devel
mariadb-devel # MariaDB ./configure --with-mysql
mariadb-libs
mbedtls # mbedTLS ./configure --with-mbedtls
mbedtls-devel
nettle # Nettle ./configure --with-nettle
nettle-devel
nss # NSS ./configure --with-nss
nss-devel
openldap # OpenLDAP ./configure --with-ldap
openldap-devel
openssl-devel # OpenSSL ./configure --with-openssl
openssl-libs
pam # PAM ./configure --with-pam
pam-devel
pcre # PCRE ./configure --with-pcre # (default)
pcre-devel
sqlite # SQLite ./configure --with-webdav-props
sqlite-devel
valgrind # valgrind ./configure --with-valgrind
valgrind-devel
zlib # zlib ./configure --with-zlib
zlib-devel
more options: ./configure --help
re-run ./configure after installing packages
compile and install it with ::
$ cd lighttpd-1.4.xx
$ ./autogen.sh # detect/use newer versions of autotools (if present)
$ ./configure -C # add --with-xxxxx custom flags
$ make
# sudo make install
Running Tests
-------------
required packages to run test harness ::
(e.g. on Fedora 22, sudo dnf install ...)
(e.g. on Arch Linux, sudo pacman ... (with lowercased package names))
perl-CGI
perl-Digest
perl-Digest-MD5
perl-Encode-Locale
perl-HTML-Entities-Interpolate
perl-HTML-Parser
perl-HTML-Tagset
perl-HTTP-Date
perl-HTTP-Message
perl-IO-HTML
perl-LWP-MediaTypes
perl-Tie-Function
perl-TimeDate
php
php-cgi
optional packages to run test harness ::
fcgi-devel
$ cd tests/ && make fcgi-auth fcgi-responder
run test harness
$ make check
run test harness with additional FastCGI tests (requires fcgi-devel package)
$ cd tests/ && make check-am
static build using SCons
------------------------


+ 7
- 6
README View File

@ -37,21 +37,22 @@ Network
Protocols
`````````
- HTTP/1.0 (http://www.ietf.org/rfc/rfc1945.txt)
- HTTP/1.1 (http://www.ietf.org/rfc/rfc2616.txt)
- HTTPS (provided by openssl)
- CGI/1.1 (http://CGI-Spec.Golux.Com/)
- HTTP/2 (https://tools.ietf.org/rfc/rfc7540.txt)
- HTTP/1.1 (https://tools.ietf.org/rfc/rfc2616.txt)
- HTTP/1.0 (https://tools.ietf.org/rfc/rfc1945.txt)
- HTTPS (via one of openssl, BoringSSL, LibreSSL, mbedTLS, wolfSSL, GnuTLS, NSS)
- CGI/1.1 (https://tools.ietf.org/html/rfc3875.txt)
- FastCGI (http://www.fastcgi.com/devkit/doc/fcgi-spec.html)
Advanced Features
`````````````````
- load-balanced FastCGI
- load-balanced FastCGI, SCGI, reverse-proxy, socket proxy, websocket tunnel
(one webserver distributes requests to multiple PHP-servers via FastCGI)
- streaming FastCGI, SCGI, reverse-proxy, socket proxy, websocket tunnel
- custom error pages (for Response-Code 400-599)
- virtual hosts
- directory listings
- streaming CGI and FastCGI
- URL-Rewriting
- HTTP-Redirection
- output-compression with transparent caching


+ 82
- 0
tests/README View File

@ -0,0 +1,82 @@
Running tests
-------------
$ make check
If run from tests/ dir, tests will fail to run tests if lighttpd not built.
If run from top level, 'make' will build lighttpd exectuable if not yet built,
and then will run tests.
Running individual tests programs
---------------------------------
prep
$ cd tests/
$ ./prepare.sh
then, for any particular *.t such as request.t,
$ ./request.t
or
$ VERBOSE=1 RUNTESTS=request ./run-tests.pl
More information is output by tests with additional environment settings:
$ TRACE_HTTP=1 ./request.t
See LightyTest.pm before trying TRACEME
$ less LightyTest.pm
$ TRACEME=strace ./request.t # output to file 'strace'
$ TRACEME=truss ./request.t # output to file 'strace'
$ TRACEME=gdb ./request.t # not for interactive debugging (see below)
$ TRACEME=valgrind ./request.t
To reduce noise from valgrind --show-leak-kinds=all (or =reachable), avoid FAM.
Use server.stat-cache-engine = "simple" (not server.stat-cache-engine = "fam")
in lighttpd.conf. (FAM creates /usr/libexec/gam_server as child process.)
Running lighttpd server with a config from tests/*.conf
-------------------------------------------------------
Each *.t loads the lighttpd server with one or more config files.
See each *.t for which config file is used, e.g. tests/lighttpd.conf
To run a specific config
repo=$PWD # from root of src repository
cd tests/
./prepare.sh
PERL=/usr/bin/perl PHP=/usr/bin/php-cgi SRCDIR=$repo/tests \
$repo/src/lighttpd -D -f lighttpd.conf -m $repo/src/.libs
The PERL, PHP, and SRCDIR environment variables are set by LightyTest.pm
when 'make check' is run. PERL and PHP can be set to paths to perl and php,
e.g. export PERL=/usr/bin/perl PHP=/usr/bin/php-cgi
To run a specific config under gdb
repo=$PWD # from root of src repository
cd tests/
./prepare.sh
PERL=/usr/bin/perl PHP=/usr/bin/php-cgi SRCDIR=$repo/tests repo=$repo \
gdb $repo/src/lighttpd
(gdb) set args -D -f lighttpd.conf -m $repo/src/.libs
(gdb) start
(gdb) ...
Hints and tips
--------------
Q: What do I do if tests fail with:
bind: Address already in use at LightyTest.pm line 429.
A: It is likely that something else on the machine is already using the port
that tests are trying to use to run a backend. Try exiting out of your web
browser and then run the tests again. (root can use 'netstat' or 'ss' to
find out which process is using the port.)
Additional documentation
------------------------
https://redmine.lighttpd.net/projects/lighttpd/wiki/RunningUnitTests
https://redmine.lighttpd.net/projects/lighttpd/wiki/HowToReportABug
https://redmine.lighttpd.net/projects/lighttpd/wiki/DebugVariables

Loading…
Cancel
Save