-.\" $Id: man.cgi.8,v 1.2 2014/07/11 21:30:52 schwarze Exp $
+.\" $Id: man.cgi.8,v 1.11 2014/09/14 19:44:28 schwarze Exp $
.\"
.\" Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" 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 11 2014 $
+.Dd $Mdocdate: September 14 2014 $
.Dt MAN.CGI 8
.Os
.Sh NAME
displays a search form containing these elements:
.Bl -enum
.It
-A
-.Dq Search
-button to send a search request from the client to the server,
-to be clicked after filling in the following input box(es).
-.It
-An input box for search queries, expecting an
+An input box for search queries, expecting
+either a name of a manual page or an
.Ar expression
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
+button to send a search request from the client to the server.
+.It
+A
+.Dq Reset
+button to undo any changes to the input boxes and the dropdown menus
+and reset them to the values contained in the
+.Ev QUERY_STRING .
+.It
+Radio buttons to select pages either by name like in
+.Xr man 1
+or using
+.Xr apropos 1
+queries.
.It
-An input box for an optional section number.
+A dropdown menu to optionally select a manual section.
If one is provided, it has the same effect as the
+.Xr man 1
+and
.Xr apropos 1
.Fl s
option.
Otherwise, pages from all sections are shown.
.It
-An input box for an optional architecture name.
+A dropdown menu to optionally select an architecture.
If one is provided, it has the same effect as the
+.Xr man 1
+and
.Xr apropos 1
.Fl S
option.
.Pa /var/www/man/manpath.conf
contains only one manpath, the dropdown menu is not shown.
By default, the first manpath given in the file is used.
-.It
-A
-.Dq Reset
-button to undo any changes to the input boxes and the dropdown menu
-and reset them to the values contained in the
-.Ev QUERY_STRING .
.El
.Ss Program output
The
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,
The path to the program, normally
.Pa cgi-bin/man.cgi/ .
.It
-A page name, which can be
-.Cm index ,
-which is the default and can be omitted,
-.Cm search ,
-or
-.Cm show .
-.It
-For
-.Cm show
-only, a slash, the manpath, another slash,
+To show a single page, a slash, the manpath, another slash,
and the name of the requested file, for example
.Pa /OpenBSD-current/man1/mandoc.1 .
.It
-For
-.Cm search
-only, a query string starting with a question mark
+For searches, a query string starting with a question mark
and consisting of
.Ar key Ns = Ns Ar value
pairs, separated by ampersands, for example
-.Pa ?manpath=OpenBSD-current&expr=mandoc .
+.Pa ?manpath=OpenBSD-current&query=mandoc .
Supported keys are
.Cm manpath ,
-.Cm expr ,
+.Cm query ,
.Cm sec ,
-and
.Cm arch ,
corresponding to
.Xr apropos 1
.Fl M ,
.Ar expression ,
.Fl s ,
-and
.Fl S ,
-respectively.
+respectively, and
+.Cm apropos ,
+which is a boolean parameter to select or deselect the
+.Xr apropos 1
+query mode.
For backward compatibility with the traditional
.Nm ,
-.Cm query
-is supported as an alias for
-.Cm expr
-and
.Cm sektion
-as an alias for
+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 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 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 /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.
.It Ev PATH_INFO
The final part of the URI path passed from the client to the server,
starting after 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.
.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
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
CGI program is call-compatible with queries from the traditional
.Pa man.cgi
script by Wolfram Schneider.
-However, the results may not be quite the same.
+However, the output may not be quite the same.
.Sh SEE ALSO
.Xr apropos 1 ,
.Xr mandoc.db 5 ,
git.ckatri.com / mandoc.git / blobdiff