fileserv README.
See the end of file for copying conditions.

* Overview

This is a simple HTTP server for serving static files. It is suitable
as a lightweight replacement for full-fledged HTTP servers on sites
where only sporadic serving of static data is needed.

One of such use cases is deployment of LetsEncrypt certificates on a
server that runs only proxy software, such as pound[1] or haproxy[2]. In
this case using e.g. Apache or even lighttpd just to serve
LetsEncrypt challenge requests arriving once in 90 days is clearly an
overkill. Instead, fileserv can be used.

Starting the server can be as simple as:

 fileserv -u nobody -a 127.0.0.1:8080 /.well-known/acme-challenge:/var/www/acme
 
This instructs it to run in background with privileges of the user nobody
listening on localhost, port 8080. Requests with URL path beginning
with /.well-known/acme-challenge will be served from directory
/var/www/acme. Other requests will be rejected.

It is more convenient to keep all settings in the configuration file.
Its name is ${sysconfdir}/fileserv.conf, where ${sysconfdir} is
determined when compiling the package. Normally, it is /etc or
/usr/local/etc.

The above command line options are equivalent to the following
configuration:

 user nobody
 listen 127.0.0.1:8080
 mapping /.well-known/acme-challenge:/var/www/acme

If the proxy used is pound[1], define the following service in its
configuration file /etc/pound.conf:

 Service
     URL "^/.well-known/acme-challenge"
     BackEnd
         Address 127.0.0.1
         Port 8080
     End
 End

This will forward LetsEncrypt challenge requests to fileserv. Make
sure this service declaration is located before all other services, so
that it takes precedence over them.

If using haproxy[2], use the following fragment (supposing the default
backend is called dfl) in /etc/haproxy/haproxy.cfg:

 frontend http-in
    bind *:80
    default_backend dfl
    acl letsencrypt path_beg /.well-known/acme-challenge
    use_backend fileserv if letsencrypt

 backend fileserv
    server localhost 127.0.0.1:8080

* Building

To build fileserv you will need GNU Libmicrohttpd library[3]. It is
available for download from http://ftp.gnu.org/gnu/libmicrohttpd.

When building from source package, usual incantations apply:

 ./configure
 make
 make install

If you are building from a clone of the Git repository, you will need
GNU autotools to bootstrap the package first. Run

  ./bootstrap

in the top level source directory. This will create the configure
script and populate the directory with the missing files. Then proceed
as described above.

* Documentation

Manpage fileserv.8 included. After installing the package, run
man fileserv.
    
* Bug reporting.		

Send bug reports to <gray+fileserv@gnu.org.ua>. 

* References

[1] Pound - https://github.com/graygnuorg/pound
    As a matter of fact, pound now provides the built-in functionality
    for serving ACME challenges (see the ACME statement in
    https://www.gnu.org.ua/software/pound/pound.html#HTTP_Listener).
    It appeared long after fileserv had been released.
[2] Haproxy - https://www.haproxy.org
[3] GNU Libmicrohttpd - https://www.gnu.org/software/libmicrohttpd


* Copyright information:

Copyright (C) 2017-2023 Sergey Poznyakoff

   Permission is granted to anyone to make or distribute verbatim copies
   of this document as received, in any medium, provided that the
   copyright notice and this permission notice are preserved,
   thus giving the recipient permission to redistribute in turn.

   Permission is granted to distribute modified versions
   of this document, or of portions of it,
   under the above conditions, provided also that they
   carry prominent notices stating who last changed them.


Local Variables:
mode: outline
paragraph-separate: "[ 	]*$"
version-control: never
End: