=================================================================== RCS file: /cvs/mandoc/man.cgi.8,v retrieving revision 1.4 retrieving revision 1.12 diff -u -p -r1.4 -r1.12 --- mandoc/man.cgi.8 2014/07/13 00:19:51 1.4 +++ mandoc/man.cgi.8 2015/11/05 17:47:51 1.12 @@ -1,4 +1,4 @@ -.\" $Id: man.cgi.8,v 1.4 2014/07/13 00:19:51 schwarze Exp $ +.\" $Id: man.cgi.8,v 1.12 2015/11/05 17:47:51 schwarze Exp $ .\" .\" Copyright (c) 2014 Ingo Schwarze .\" @@ -14,7 +14,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: July 13 2014 $ +.Dd $Mdocdate: November 5 2015 $ .Dt MAN.CGI 8 .Os .Sh NAME @@ -43,6 +43,12 @@ either a name of a manual page or an using the syntax described in the .Xr apropos 1 manual; filling this in is required for each search. +.Pp +The expression is broken into words at whitespace. +Whitespace characters and backslashes can be escaped +by prepending a backslash. +The effect of prepending a backslash to another character is undefined; +in the current implementation, it has no effect. .It A .Dq Submit @@ -155,10 +161,74 @@ database inside each manpath. Configure your web server to execute CGI programs located in .Pa /cgi-bin . When using +.Ox +.Xr httpd 8 +or .Xr nginx 8 , the .Xr slowcgi 8 proxy daemon is needed to translate FastCGI requests to plain old CGI. +.Pp +To compile +.Nm , +first copy +.Pa cgi.h.example +to +.Pa cgi.h +and edit it according to your needs. +It contains the following compile-time definitions: +.Bl -tag -width Ds +.It Ev COMPAT_OLDURI +Only useful for running on www.openbsd.org to deal with old URIs containing +.Qq "manpath=OpenBSD " +where the blank character has to be translated to a hyphen. +When compiling for other sites, this definition can be deleted. +.It Ev CSS_DIR +An optional path to the directory containing the CSS files, +to be specified relative to the server's document root, +and to be specified without a trailing slash. +When not specified, the CSS files +are assumed to be in the document root. +This is used in generated HTML code. +.It Ev CUSTOMIZE_BEGIN +A HTML string to be inserted right after opening the +.Aq BODY +element. +.It Ev CUSTOMIZE_TITLE +An ASCII string to be used for the HTML +.Aq TITLE +element. +.It Ev HTTP_HOST +The FQDN of the (possibly virtual) host the HTTP server is running on. +This is used for +.Ic Location: +headers in HTTP 303 responses. +.It Ev MAN_DIR +A path to the +.Nm +data directory to be used instead of +.Pa /var/www/man , +relative to the web server +.Xr chroot 2 +directory, to be specified without a trailing slash. +This is prepended to the manpath when opening +.Xr mandoc.db 5 +and manual page files. +.El +.Pp +After editing +.Pa cgi.h , +run +.Pp +.Dl make man.cgi +.Pp +and copy the files to the proper locations. +Reading the +.Cm installcgi +target in the +.Pa Makefile +can help with that, but do not run it without carefully checking it +because the directory layouts of web servers vary greatly. .Ss URI interface .Nm uniform resource identifiers are not needed for interactive use, @@ -206,15 +276,38 @@ For backward compatibility with the traditional is supported as an alias for .Cm sec . .El +.Ss Restricted character set +For security reasons, in particular to prevent cross site scripting +attacks, some strings used by +.Nm +can only contain the following characters: +.Pp +.Bl -dash -compact -offset indent +.It +lower case and upper case ASCII letters +.It +the ten decimal digits +.It +the dash +.Pq Sq - +.It +the dot +.Pq Sq \&. +.It +the slash +.Pq Sq / +.It +the underscore +.Pq Sq _ +.El +.Pp +In particular, this applies to the +.Ev SCRIPT_NAME , +to all manpaths, and to all architecture names. .Sh ENVIRONMENT The web server may pass the following CGI variables to .Nm : .Bl -tag -width Ds -.It Ev HTTP_HOST -The FQDN of the (possibly virtual) host the HTTP server is running on. -This is used for -.Ic Location: -headers in HTTP 303 responses. .It Ev PATH_INFO The final part of the URI path passed from the client to the server, starting after the @@ -223,7 +316,7 @@ and ending before the .Ev QUERY_STRING . It is used by the .Cm show -page to aquire the manpath and filename it needs. +page to acquire the manpath and filename it needs. .It Ev QUERY_STRING The HTTP query string passed from the client to the server. It is the final part of the URI, after the question mark. @@ -237,6 +330,10 @@ binary relative to the server root, usually .Pa /cgi-bin/man.cgi . This is used for generating URIs to be embedded in generated HTML code and HTTP headers. +If this contains any character not contained in the +.Sx Restricted character set , +.Nm +reports an internal server error and exits without doing anything. .El .Sh FILES .Bl -tag -width Ds @@ -255,50 +352,34 @@ Can be overridden by The path to the server document root relative to the server root. This is part of the web server configuration and not specific to .Nm . -.It Pa /htdocs/man-cgi.css -A style sheet for general -.Nm -styling, referenced from each generated HTML page. -.It Pa /htdocs/man.css +.It Pa /htdocs/mandoc.css A style sheet for .Xr mandoc 1 -HTML styling, referenced from each generated HTML page after -.Pa man-cgi.css . +HTML styling, referenced from each generated HTML page. .It Pa /man Default .Nm data directory containing all the manual trees. Can be overridden by .Ev MAN_DIR . +.It Pa /man/mandoc/man1/apropos.1 , /man/mandoc/man8/man.cgi.8 +Manual pages documenting +.Nm +itself, linked from the index page. .It Pa /man/manpath.conf The list of available manpaths, one per line. +If any of the lines in this file contains a slash +.Pq Sq / +or any character not contained in the +.Sx Restricted character set , +.Nm +reports an internal server error and exits without doing anything. .It Pa /man/OpenBSD-current/man1/mandoc.1 An example .Xr mdoc 7 source file located below the .Dq OpenBSD-current manpath. -.El -.Sh COMPILE-TIME DEFINES -.Bl -tag -width Ds -.It Ev CSS_DIR -An optional path to the directory containing the CSS files, -to be specified relative to the server's document root, -and to be specified without a trailing slash. -When not specified, the CSS files -are assumed to be in the document root. -This is used in generated HTML code. -.It Ev MAN_DIR -A path to the -.Nm -data directory to be used instead of -.Pa /var/www/man , -relative to the web server -.Xr chroot 2 -directory, to be specified without a trailing slash. -This is prepended to the manpath when opening -.Xr mandoc.db 5 -and manual page files. .El .Sh COMPATIBILITY The