1.\" $OpenBSD: man.cgi.8,v 1.21 2017/03/18 16:48:07 schwarze Exp $ 2.\" 3.\" Copyright (c) 2014, 2015, 2016 Ingo Schwarze <schwarze@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: March 18 2017 $ 18.Dt MAN.CGI 8 19.Os 20.Sh NAME 21.Nm man.cgi 22.Nd CGI program to search and display manual pages 23.Sh DESCRIPTION 24The 25.Nm 26CGI program searches for manual pages on a WWW server 27and displays them to HTTP clients, 28providing functionality equivalent to the 29.Xr man 1 30and 31.Xr apropos 1 32utilities. 33It can use multiple manual trees in parallel. 34.Ss HTML search interface 35At the top of each generated HTML page, 36.Nm 37displays a search form containing these elements: 38.Bl -enum 39.It 40An input box for search queries, expecting 41either a name of a manual page or an 42.Ar expression 43using the syntax described in the 44.Xr apropos 1 45manual; filling this in is required for each search. 46.Pp 47The expression is broken into words at whitespace. 48Whitespace characters and backslashes can be escaped 49by prepending a backslash. 50The effect of prepending a backslash to another character is undefined; 51in the current implementation, it has no effect. 52.It 53A 54.Xr man 1 55submit button. 56The string in the input box is interpreted as the name of a manual page. 57.It 58An 59.Xr apropos 1 60submit button. 61The string in the input box is interpreted as a search 62.Ar expression . 63.It 64A dropdown menu to optionally select a manual section. 65If one is provided, it has the same effect as the 66.Xr man 1 67and 68.Xr apropos 1 69.Fl s 70option. 71Otherwise, pages from all sections are shown. 72.It 73A dropdown menu to optionally select an architecture. 74If one is provided, it has the same effect as the 75.Xr man 1 76and 77.Xr apropos 1 78.Fl S 79option. 80By default, pages for all architectures are shown. 81.It 82A dropdown menu to select a manual tree. 83If the configuration file 84.Pa /var/www/man/manpath.conf 85contains only one manpath, the dropdown menu is not shown. 86By default, the first manpath given in the file is used. 87.El 88.Ss Program output 89The 90.Nm 91program generates five kinds of output pages: 92.Bl -tag -width Ds 93.It The index page. 94This is returned when calling 95.Nm 96without 97.Ev PATH_INFO 98and without a 99.Ev QUERY_STRING . 100It serves as a starting point for using the program 101and shows the search form only. 102.It A list page. 103Lists are returned when searches match more than one manual page. 104The first column shows the names and section numbers of manuals 105as clickable links. 106The second column shows the one-line descriptions of the manuals. 107.It A manual page. 108This output format is used when a search matches exactly one 109manual page, or when a link on a list page or an 110.Ic \&Xr 111link on another manual page is followed. 112.It A no-result page. 113This is shown when a search request returns no results - 114eiher because it violates the query syntax, or because 115the search does not match any manual pages. 116.It \&An error page. 117This cannot happen by merely clicking the 118.Dq Search 119button, but only by manually entering an invalid URI. 120It does not show the search form, but only an error message 121and a link back to the index page. 122.El 123.Ss Setup 124For each manual tree, create one first-level subdirectory below 125.Pa /var/www/man . 126The name of one of these directories is called a 127.Dq manpath 128in the context of 129.Nm . 130Create a single ASCII text file 131.Pa /var/www/man/manpath.conf 132containing the names of these directories, one per line. 133The directory given first is used as the default manpath. 134.Pp 135Inside each of these directories, use the same directory and file 136structure as found below 137.Pa /usr/share/man , 138that is, second-level subdirectories 139.Pa /var/www/man/*/man1 , /var/www/man/*/man2 140etc. containing source 141.Xr mdoc 7 142and 143.Xr man 7 144manuals with file name extensions matching the section numbers, 145second-level subdirectories 146.Pa /var/www/man/*/cat1 , /var/www/man/*/cat2 147etc. containing preformatted manuals with the file name extension 148.Sq 0 , 149and optional third-level subdirectories for architectures. 150Use 151.Xr makewhatis 8 152to create a 153.Xr mandoc.db 5 154database inside each manpath. 155.Pp 156Configure your web server to execute CGI programs located in 157.Pa /cgi-bin . 158When using 159.Ox 160.Xr httpd 8 , 161the 162.Xr slowcgi 8 163proxy daemon is needed to translate FastCGI requests to plain old CGI. 164.Pp 165To compile 166.Nm , 167first copy 168.Pa cgi.h.example 169to 170.Pa cgi.h 171and edit it according to your needs. 172It contains the following compile-time definitions: 173.Bl -tag -width Ds 174.It Ev COMPAT_OLDURI 175Only useful for running on www.openbsd.org to deal with old URIs containing 176.Qq "manpath=OpenBSD " 177where the blank character has to be translated to a hyphen. 178When compiling for other sites, this definition can be deleted. 179.It Dv CSS_DIR 180An optional file system path to the directory containing the file 181.Pa mandoc.css , 182to be specified relative to the server's document root, 183and to be specified without a trailing slash. 184When empty, the CSS file is assumed to be in the document root. 185Otherwise, a leading slash is needed. 186This is used in generated HTML code. 187.It Dv CUSTOMIZE_TITLE 188An ASCII string to be used for the HTML <TITLE> element. 189.It Dv MAN_DIR 190A file system path to the 191.Nm 192data directory relative to the web server 193.Xr chroot 2 194directory, to be specified with a leading slash and without a trailing slash. 195It needs to have at least one component; the root directory cannot be used 196for this purpose. 197The files 198.Pa manpath.conf , 199.Pa header.html , 200and 201.Pa footer.html 202are looked up in this directory. 203It is also prepended to the manpath when opening 204.Xr mandoc.db 5 205and manual page files. 206.It Dv SCRIPT_NAME 207The initial component of URIs, to be specified without leading 208and trailing slashes. 209It can be empty. 210.El 211.Pp 212After editing 213.Pa cgi.h , 214run 215.Pp 216.Dl make man.cgi 217.Pp 218and copy the resulting binary to the proper location, 219for example using the command: 220.Pp 221.Dl make installcgi 222.Pp 223In addition to that, make sure the default manpath contains the files 224.Pa man1/apropos.1 225and 226.Pa man8/man.cgi.8 , 227or the documentation links at the bottom of the index page will not work. 228.Ss URI interface 229.Nm 230uniform resource identifiers are not needed for interactive use, 231but can be useful for deep linking. 232They consist of: 233.Bl -enum 234.It 235The 236.Cm http:// 237protocol specifier. 238.It 239The host name. 240.It 241The 242.Dv SCRIPT_NAME , 243preceded by a slash unless empty. 244.It 245To show a single page, a slash, the manpath, another slash, 246and the name of the requested file, for example 247.Pa /OpenBSD-current/man1/mandoc.1 . 248This can be abbreviated according to the following syntax: 249.Sm off 250.Op / Ar manpath 251.Op / Cm man Ar sec 252.Op / Ar arch 253.Pf / Ar name Op \&. Ar sec 254.Sm on 255.It 256For searches, a query string starting with a question mark 257and consisting of 258.Ar key Ns = Ns Ar value 259pairs, separated by ampersands, for example 260.Pa ?manpath=OpenBSD-current&query=mandoc . 261Supported keys are 262.Cm manpath , 263.Cm query , 264.Cm sec , 265.Cm arch , 266corresponding to 267.Xr apropos 1 268.Fl M , 269.Ar expression , 270.Fl s , 271.Fl S , 272respectively, and 273.Cm apropos , 274which is a boolean parameter to select or deselect the 275.Xr apropos 1 276query mode. 277For backward compatibility with the traditional 278.Nm , 279.Cm sektion 280is supported as an alias for 281.Cm sec . 282.El 283.Ss Restricted character set 284For security reasons, in particular to prevent cross site scripting 285attacks, some strings used by 286.Nm 287can only contain the following characters: 288.Pp 289.Bl -dash -compact -offset indent 290.It 291lower case and upper case ASCII letters 292.It 293the ten decimal digits 294.It 295the dash 296.Pq Sq - 297.It 298the dot 299.Pq Sq \&. 300.It 301the slash 302.Pq Sq / 303.It 304the underscore 305.Pq Sq _ 306.El 307.Pp 308In particular, this applies to all manpaths and architecture names. 309.Sh ENVIRONMENT 310The web server may pass the following CGI variables to 311.Nm : 312.Bl -tag -width Ds 313.It Ev SCRIPT_NAME 314The initial part of the URI passed from the client to the server, 315starting after the server's host name and ending before 316.Ev PATH_INFO . 317This is ignored by 318.Nm . 319When constructing URIs for links and redirections, the 320.Dv SCRIPT_NAME 321preprocessor constant is used instead. 322.It Ev PATH_INFO 323The final part of the URI path passed from the client to the server, 324starting after the 325.Ev SCRIPT_NAME 326and ending before the 327.Ev QUERY_STRING . 328It is used by the 329.Cm show 330page to acquire the manpath and filename it needs. 331.It Ev QUERY_STRING 332The HTTP query string passed from the client to the server. 333It is the final part of the URI, after the question mark. 334It is used by the 335.Cm search 336page to acquire the named parameters it needs. 337.El 338.Sh FILES 339.Bl -tag -width Ds 340.It Pa /var/www 341Default web server 342.Xr chroot 2 343directory. 344All the following paths are specified relative to this directory. 345.It Pa /cgi-bin/man.cgi 346The usual file system path to the 347.Nm 348program inside the web server 349.Xr chroot 2 350directory. 351A different name can be chosen, but in any case, it needs to be configured in 352.Xr httpd.conf 5 . 353.It Pa /htdocs 354The file system path to the server document root directory 355relative to the server 356.Xr chroot 2 357directory. 358This is part of the web server configuration and not specific to 359.Nm . 360.It Pa /htdocs/mandoc.css 361A style sheet for 362.Xr mandoc 1 363HTML styling, referenced from each generated HTML page. 364.It Pa /man 365Default 366.Nm 367data directory containing all the manual trees. 368Can be overridden by 369.Dv MAN_DIR . 370.It Pa /man/manpath.conf 371The list of available manpaths, one per line. 372If any of the lines in this file contains a slash 373.Pq Sq / 374or any character not contained in the 375.Sx Restricted character set , 376.Nm 377reports an internal server error and exits without doing anything. 378.It Pa /man/header.html 379An optional file containing static HTML code to be inserted right 380after opening the <BODY> element. 381.It Pa /man/footer.html 382An optional file containing static HTML code to be inserted right 383before closing the <BODY> element. 384.It Pa /man/OpenBSD-current/man1/mandoc.1 385An example 386.Xr mdoc 7 387source file located below the 388.Dq OpenBSD-current 389manpath. 390.El 391.Sh COMPATIBILITY 392The 393.Nm 394CGI program is call-compatible with queries from the traditional 395.Pa man.cgi 396script by Wolfram Schneider. 397However, the output may not be quite the same. 398.Sh SEE ALSO 399.Xr apropos 1 , 400.Xr mandoc.db 5 , 401.Xr makewhatis 8 , 402.Xr slowcgi 8 403.Sh HISTORY 404A version of 405.Nm 406based on 407.Xr mandoc 1 408first appeared in mdocml-1.12.1 (March 2012). 409The current 410.Xr mandoc.db 5 411database format first appeared in 412.Ox 6.1 . 413.Sh AUTHORS 414.An -nosplit 415The 416.Nm 417program was written by 418.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv 419and is maintained by 420.An Ingo Schwarze Aq Mt schwarze@openbsd.org , 421who also designed and implemented the database format. 422