FreeBSD Manual Pages
FILESERV(8) User Commands FILESERV(8) 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 com- mand 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 re- quest has the value HOST. Depending on the configuration settings, directory listings can be pro- duced. 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 the privileges of this primary group. 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 the privileges of this user. USER must be either the name of a user listed in the system user database, or a numeric UID pre- fixed 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 sin- gle or double quote characters). Backslash character serves to escape the following character. Usual C escapes are understood. Empty lines are ig- nored. 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-un- readable, 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 usera- gent 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 re- main in effect for all subdirectories of the selected mapping, until over- ridden 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 ex- pected. If the first argument is + (a plus sign), all subsequent ar- guments 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 di- rectory will be served only if it is located in one of the config- ured mappings. Default is no. listing BOOL Enable directory listing mode. Directory listing will be returned in response to a request whose URL maps to a directory with no 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 di- rectories 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. Lines beginning with hash character are 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 the error description whose Content-language header matches 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 a built-in template (see the file src/de- fidx.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 the 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 im- age file to be displayed for matching files, and TEXT is the alter- native text. name-icon URL [alt=TEXT] SUFFIX [SUFFIX...] Defines the icon for to use file names that end in one of the SUF- FIXes. See mime-icon, for the description of URL and TYPE. type-icon URL [alt=TEXT] TYPE [TYPE...] Defines the 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 con- struct 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 substi- tuted. ${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 sub- stituted. ${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 sub- stituted, otherwise the expansion of word is substituted. ${variable:|word1|word2} Ternary operator. Unless variable is null or unset, substitutes the expansion of word1, otherwise the expansion of word2. If the |word2 part is omitted, the construct is equivalent to ${variable:+word1}. The above notation is consistent with the POSIX shell, except for the ${variable:|word1|word2} form, which is an extension. The following constructs expand to the modified value of the referenced variable: ${variable#word} Remove Shortest Prefix Pattern. The word is expanded to produce a pattern. If that pattern matches the beginning of the expanded value of variable, then this construct expands to the expanded value of variable with the shortest matching pattern removed. ${variable##word} Remove Longest Prefix Pattern. The word is expanded to produce a pattern. If that pattern matches the beginning of the expanded value of variable, then the result of the expansion is the expanded value of variable with the longest matching pattern removed. ${variable%word} Remove Shortest Suffix Pattern. The word is expanded to produce a pattern. If that pattern matches a trailing portion of the expanded value of variable, then the result of the expansion is the expanded value of variable with the shortest matching pattern removed. ${variable%%word} Remove Longest Suffix Pattern. The word is expanded to produce a pattern. If that pattern matches a trailing portion of the expanded value of variable, then the result of the expansion is the expanded value of variable with the longest matching pattern removed. ${variable/pattern/subst} Pattern Substitution. Both pattern and subst are expanded. The variable is expanded and the longest match of pattern against its value is replaced with the expansion of subst. By default only the first match is replaced. If pattern begins with /.fR, all matches of pattern are replaced with subst. If it begins with #, the match is replaced only if it occurs at the beginning of the expanded value of variable. Conversely, if it begins with %, the match is replaced only if it occurs at the end of the expanded value of variable. To match the special characters (/, #, or %) literally, precede them with a backslash. If the pattern does not match the expanded variable, the five constructs above result in the expanded value of the variable unchanged. In all expansion forms above, the word, pattern, and subst parts can con- tain variable expansions, command substitutions, single and double-quoted parts. 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 itera- tion 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 com- mand 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 an 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 alter- native 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> COPYRIGHT Copyright (C) 2017-2026 Sergey Poznyakoff License GPLv3+: GNU GPL version 3 or later <http://gnu.org/li- censes/gpl.html> This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. FILESERV April 14, 2026 FILESERV(8)
NAME | SYNOPSIS | DESCRIPTION | OPTIONS | CONFIGURATION FILE | LISTING TEMPLATE | COPYRIGHT
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=fileserv&sektion=8&manpath=FreeBSD+Ports+15.1.quarterly>