From 140c0fb8f452b154cc8f24ff412a4d7c2bbdbfdc Mon Sep 17 00:00:00 2001 From: Glenn Strauss Date: Sat, 5 Sep 2020 23:54:02 -0400 Subject: [PATCH] [doc] update README and INSTALL also add tests/README with some testing notes --- INSTALL | 149 +++++++++++++++++++++++++++++++++++++++++++++++---- README | 13 ++--- tests/README | 82 ++++++++++++++++++++++++++++ 3 files changed, 229 insertions(+), 15 deletions(-) create mode 100644 tests/README diff --git a/INSTALL b/INSTALL index 883bfd4b..b09d4172 100644 --- a/INSTALL +++ b/INSTALL @@ -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 ------------------------ diff --git a/README b/README index e3dd31c0..aa8d78e3 100644 --- a/README +++ b/README @@ -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 diff --git a/tests/README b/tests/README new file mode 100644 index 00000000..bbecd0c7 --- /dev/null +++ b/tests/README @@ -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