FILESERV

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
CONFIGURATION FILE
LISTING TEMPLATE
DOWNLOADS
COPYRIGHT

NAME

fileserv - simple http server for static files

SYNOPSIS

fileserv [-fhsv] [-a [IP][:PORT]] [-c FILE] [-g GROUP] [-u USER] [HOST:]URL:DIR ...

DESCRIPTION

A simple and lightweight HTTP server. It serves static files from one or more directories on the file system. The directories to be used and the corresponding URLs are defined in the form of mappings, either in the command line or in the configuration file. The mapping

PATH:DIR

instructs the server to map all URLs that begin with the path prefix PATH to the directory DIR on the file system. The mapping

HOST:PATH:DIR

has the same effect, but only if the Host: header of the incoming HTTP request has the value HOST.

Depending on the configuration settings, the directory listing can be produced.

OPTIONS

-a [IP][:PORT]

Listen on the given IP address and port. Either IP or PORT (but not both) can be omitted. If IP is omitted, the colon must be retained.

This option overrides the listenv configuration setting.

-c FILE

Read configuration from FILE, instead of /etc/fileserv.conf.

-f

Run in foreground.

-g GROUP

Run with this primary group privileges. GROUP must be either the name of a group listed in the user database, or a numeric GID prefixed with a plus sign.

This option overrides the group configuration setting.

	-h		Display a terse command line summary and exit.
	-s		Run in single-process mode. In this mode, fileserv does not start a sentinel process.

-u USER

Run with this user privileges. USER must be either the name of a user listed in the system user database, or a numeric UID prefixed with a plus sign.

This option overrides the user configuration setting.

	-v		Increase verbosity level. Multiple options accumulate.
	-V		Show program version, license and copyright information.

CONFIGURATION FILE

The server reads most of its settings from the configuration file /etc/fileserv.conf (the default location can be overridden using the -c command line option). The file has a traditional UNIX configuration file syntax. Each statement occupies a single line and consists of configuration keyword followed by one or more values, separated by whitespace characters. Values containing whitespace characters should be quoted (with either single or double quote characters). Backslash character serves to escape the following character. Usual C escapes are understood. Empty lines are ignored. Comments are introduced by # symbol.
user NAME

Run as the user NAME. Argument must be either login name of a user listed in the user database, or a numeric UID prefixed with a plus sign.

Notice, that in single-process mode (see the -s option) switching to user privileges is performed before writing the PID file, so make sure that the directory it is located in is writable for this user (see the pidfile statement).

group NAME

Run with primary group NAME. Argument must be either the name of a group listed in the user database, or a numeric GID prefixed with a plus sign. By default, the primary group of the user supplied with the user statement will be used.

Note, that supplementary groups are always honored.

pidfile FILE

Save PID of the running process to FILE. See the notice to the user statement, above.

For compatibility with earlier versions, the keyword can also be spelled as pid-file.

mime-types-file FILE

Name of the MIME magic file. This file is used to determine the types of the files being served or listed. The file syntax is the same as for cups. See mime.types(5), for a detailed discussion. The apache’s mime types file, which is a simplification of this format, can also be used.

listen IPADDR:PORT

Listen on the given IP address and port. Either IPADDR or PORT (but not both) can be omitted. If IPADDR is omitted, the colon must be retained.

Notice, that multiple listen addresses are not supported.

Default address is 0.0.0.0:8080.

access-file-name NAME

Name of the per-directory access file. The file has the same syntax as the main configuration file, except that only the following statements are allowed: directory-index, follow, listing, list-unreadable, and hidden-files.

Default access file name is .fileserv.

forwarded-header NAME

Treat the value of the HTTP header NAME as a comma-delimited list of intermediate useragent IP addresses. To determine the actual useragent IP, the list is traversed from right to left, until an IP is found that is not listed as trusted-proxy address (see below).

Default header name is X-Forwarded-For.

trusted-proxy IP [IP...]

List of IP addresses of trusted proxies. One or more IP addresses can be given. Multiple statements accumulate. The initial list is empty.

temp-dir DIR

Store temporary files in DIR. Default is /tmp.

syslog NAME

Syslog facility name to use for reporting. Valid values for NAME are: auth, authpriv, cron, daemon(default), ftp, kern, lpr, mail, news, security, syslog, user, uucp, and local0 through local7.

Access control settings
The statements discussed below configure access control settings. These remain in effect for all subdirectories of the selected mapping, until overridden by the corresponding statements in the per-directory access files (see access-file-name, above).

Some of these statements take a boolean value (denoted as BOOL) as their arguments. Valid boolean values are (case-insensitive): 1, yes, true, or on, indicating true value, and 0, no, false, or off, indicating false value.
directory-index FILE [FILE...]

Directory index file names. One or more filename arguments are expected. If the first argument is + (a plus sign), all subsequent arguments are appended to the current list, instead of overwriting it. This is for use in per-directory access files.

follow BOOL

Follow symbolic links. If set to yes, symbolic links appearing in the request will be resolved. Notice, that the resulting file or directory will be served only if it is located in one of the configured mappings.

Default is no.

listing BOOL

Enable directory listing mode. Directory listing will be returned as a response for a request with URL mapping to a directory without valid index file. The format of the listing file is configurable. See the section LISTING TEMPLATE, for a detailed discussion.

Default is no.

list-unreadable BOOL

Whether to include in the listing the names of files that cannot be read.

Default is no.

hidden-files REGEX [REGEX...]

When producing a directory listing, omit any files whose names match one of the POSIX extended regular expressions from this list.

Mapping
Mappings declare correspondence between URLs of incoming requests and directories on the local filesystem. At least one mapping must be defined.
mapping [HOST:]URL:DIR

HTTP requests with path beginning with URL will be mapped to local file paths beginning with DIR. Optional HOST part limits the mapping to requests that have this value in the HTTP "Host:" header. This is similar to Apache’s Alias directive.

Error documents
error-dir DIR

Look for customized versions of error pages in the directory DIR. specified by the error-dir statement.

When reporting a HTTP error, fileserv will search in that directory for the first existing file from the following list: CODE.html, CODE.html.var, ERR.html,, ERR.html.var, where CODE is the HTTP error code, and ERR is its internal name. Allowed CODEs and the corresponding ERR names are: 403 (HTTP_FORBIDDEN), 404 (HTTP_NOT_FOUND), 405 (HTTP_METHOD_NOT_ALLOWED), 500 (HTTP_INTERNAL_SERVER_ERROR), 501 (HTTP_NOT_IMPLEMENTED), and 503 (HTTP_SERVICE_UNAVAILABLE).

If the file with .html suffix is found, it will be served as the body of the error response. If the file with .html.var suffix is found, it will be treated as a type map in Apache’s mod_negotiation. A type map has a format similar to RFC822 mail headers. It contains error document descriptions separated by blank lines, with lines beginning with a hash character treated as comments. A document description consists of several header records; records may be continued on multiple lines if the continuation lines start with spaces. The leading space will be deleted and the lines concatenated. A header record consists of a keyword name, which always ends in a colon, followed by a value. Whitespace is allowed between the header name and value, and between the tokens of value. The headers allowed are:
Content-Language:

The language(s) of the variant, as an Internet standard language tag (RFC 1766), e.g. en, meaning English. If the variant contains more than one language, they are separated by a comma.

This header is a look-up key.

Content-Type:

The MIME media type of the document, with optional parameters.

Body:

The actual content of the error document is included in the type-map file using the Body header. This header must contain a string that designates a delimiter for the body content. Then all following lines in the type map file will be considered part of the document body until the delimiter string is found.

The server will select this error description whose Content-language header matches the language definitions from the Accept-Language request header.

Listing template
The following statements control generation of directory index listings (see the listing statement, above).
index-template FILE

By default, fileserv uses the built-in template (see the file src/defidx.html). This statement instructs it to use FILE instead. See the section LISTING TEMPLATE FILE, for a discussion of its syntax. FILE must be an absolute file name.

index-css FILE

Name of the CSS file to use in listings. It will be available in the $INDEXCSS template variable. FILE must be an absolute file name.

mime-icon URL [alt=TEXT] TYPE [TYPE...]

Defines icon to use for files of given MIME types. Each TYPE is treated as globbing pattern (see glob(7)). URL is the URL of the image file to be displayed for matching files, and TEXT is the alternative text.

name-icon URL [alt=TEXT] SUFFIX [SUFFIX...]

Defines icon for to use file names that end in one of the SUFFIXes. See mime-icon, for the description of URL and TYPE.

type-icon URL [alt=TEXT] TYPE [TYPE...]

Defines icon to use for file of the given type. Available TYPEs are: DIRECTORY, for a directory, FILE, for a regular file, and BLANK, for a blank line.

LISTING TEMPLATE

Listing template file is used to produce directory listings. It is a normal HTML file, except for the following special constructs:
{% STRING %}

Replaced with the expansion of STRSING

{% if STRING %}

Starts conditional construct. The syntax is:
{% if STRING %}
TEXT-IF-TRUE
{% else %}
TEXT-IF-FALSE
{% endif %}
If the expansion if STRING is not empty, the construct is replaced with TEXT-IF-TRUE, otherwise it is replaced with TEXT-IF-FALSE. The else branch is optional.

{% loop %}

Starts main loop. The syntax is:

{% loop %}
TEXT
{% endloop %}

For each file found in the directory being listed, the loop construct produces expansion of TEXT.

The expansions performed on strings in template constructs are:

Variable expansion
Variable expansion replaces each occurrence of $NAME or ${NAME} with the value of the templave variable NAME.

The forms below test for a variable that is unset or null. Omitting the colon results in a test only for a variable that is unset.
${variable:-word}

Use Default Values. If variable is unset or null, the expansion of word is substituted. Otherwise, the value of variable is substituted.

${variable:=word}

Assign Default Values. If variable is unset or null, the expansion of word is assigned to variable. The value of variable is then substituted.

${variable:?word}

Display Error if Null or Unset. If variable is null or unset, the expansion of word (or a message to that effect if word is not present) is sent to the program error output stream. Otherwise, the value of variable is substituted.

${variable:+word}

Use Alternate Value. If variable is null or unset, nothing is substituted, otherwise the expansion of word is substituted.

The following template variables are defined:

URI

URL of the object being listed.

INDEXCSS

The value of index-css configuration statement.

The following variables are available only within the loop construct:
ROWCLASS

Expands to the string odd or even, depending on the number of iteration within loop.

FILENAME

Current file name.

FILESIZE

Current file size.

FILETIME

Last modification time of the current file, in format "%Y-%m-%d %H:%M".

FILETYPE

Type of the current file: either DIRECTORY or FILE.

MIMETYPE

MIME type of the current file, as determined using the mime-types-file.

Command substitution
During command substitution, each word is scanned for commands. Each command found is executed and replaced with the output it creates.

The syntax is:

$(command)

Command substitutions may be nested.

Available template commands are:
iconlookup NAME MIME TYPE

Look up the icon to use for file NAME, using the list of name-icon statements. If no icon is found and the MIME type MIME is given, look up the icon for that MIME type, using the mime-icon statements. If the icon file is not found after that step, and the file type TYPE is given, then look up the icon for that type, using the type-icon configuration statements. On success, return the URL of the icon. If no matching icon was found, return empty string.

iconsrc

If the previous call to $(iconlookup) succeeded, returns the URL of the icon.

iconalt

If the previous call to $(iconlookup) succeeded, returns the alternative text for the icon, i.e. the TEXT part of the alt= parameter to the matching name-icon, mime-icon, or type-icon statement.

updir URL

Returns the URL obtained by removing the last firectory component from the URL argument, or empty string if the latter is /.

sortorder COL

Reverts the current sort order for the sorting column COL. Possible values for the argument are:

N File name

		M
		File modification date
		S
		File size
		D
		Description

Return value is A for ascending, and D for descending order.

This function is useful to create listing ordering menu, e.g.:

<th>
<a href="?C=N&O={% $(sortorder N) %}">Name</a>
</th>
<th>
<a href="?C=M&O={% $(sortorder M) %}">Last modified</a>
</th>
<th>
<a href="?C=S&O={% $(sortorder S) %}">Size</a>
</th>

DOWNLOADS

Fileserv is available for download from this location.

The latest version is fileserv-0.4.

Recent news, changes and bugfixes can be tracked from the project's development page.

COPYRIGHT

Copyright © 2017--2019 Sergey Poznyakoff
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

Manpage server at man.gnu.org.ua.