Annotation of cvsweb/cvsweb.conf.5, Revision 4.1
4.1 ! schwarze 1: .\" $OpenBSD$
! 2: .\"
! 3: .\" Copyright (c) 2019 Ingo Schwarze <schwarze@openbsd.org>
! 4: .\" Copyright (c) 2002 Ville Skytta
! 5: .\" Copyright (c) 2000 Akinori MUSHA
! 6: .\" Copyright (c) 2000 Henner Zeller
! 7: .\" All rights reserved.
! 8: .\"
! 9: .\" Redistribution and use in source and binary forms, with or without
! 10: .\" modification, are permitted provided that the following conditions
! 11: .\" are met:
! 12: .\" 1. Redistributions of source code must retain the above copyright
! 13: .\" notice, this list of conditions and the following disclaimer.
! 14: .\" 2. Redistributions in binary form must reproduce the above copyright
! 15: .\" notice, this list of conditions and the following disclaimer in the
! 16: .\" documentation and/or other materials provided with the distribution.
! 17: .\"
! 18: .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
! 19: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
! 20: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
! 21: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
! 22: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
! 23: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
! 24: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
! 25: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
! 26: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
! 27: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
! 28: .\" SUCH DAMAGE.
! 29: .\"
! 30: .Dd $Mdocdate$
! 31: .Dt CVSWEB.CONF 5
! 32: .Os
! 33: .Sh NAME
! 34: .Nm cvsweb.conf
! 35: .Nd CVSweb configuration file
! 36: .Sh DESCRIPTION
! 37: The
! 38: .Xr cvsweb 8
! 39: configuration file is a
! 40: .Xr perl 1
! 41: script executed via the Perl
! 42: .Fn do
! 43: function near the beginning of the main program.
! 44: It can contain arbitrary Perl code, but it is only intended to
! 45: override or change the global variables documented below, which are
! 46: listed with their default value and their type.
! 47: .Bl -tag -width Ds
! 48: .It Va $address No = 'CVSweb' ; # string optionally including HTML markup
! 49: The address shown in the footer.
! 50: This will be put into an
! 51: .Pf < Ic address Ns >
! 52: element.
! 53: .It Va $allow_annotate No = 1 ; # boolean
! 54: Enable using the
! 55: .Xr cvs 1
! 56: .Cm annotate
! 57: command.
! 58: .It Va $allow_compress No = 0 ; # boolean
! 59: Enable
! 60: .Dq Content-Encoding: gzip
! 61: if the browser supports it.
! 62: .It Va $allow_dir_extra No = 1 ; # boolean
! 63: Enable generation of hyperlinks to manual pages in directory views.
! 64: .It Va $allow_log_extra No = 1 ; # boolean
! 65: Enable generation of hyperlinks to manual pages in logs.
! 66: .It Va $allow_mailtos No = 1 ; # boolean
! 67: Enable generation of mailto: links.
! 68: .It Va $allow_markup No = 1 ; # boolean
! 69: Enable display of files in HTML form.
! 70: .It Va $allow_source_extra No = 1 ; # boolean
! 71: Enable generation of hyperlinks to manual pages in source code and diffs.
! 72: .It Va $allow_tar No = 0 ; # boolean
! 73: Enable downloading of tarballs using the
! 74: .Cm tarball
! 75: query keyword and generate hyperlinks facilitating such downloads.
! 76: .It Va @annotate_options No = XXX ; # array of strings
! 77: Global options passed to the
! 78: .Xr cvs 1
! 79: program when invoking the
! 80: .Cm annotate
! 81: command.
! 82: Despite the name, these are
! 83: .Em not
! 84: options to
! 85: .Cm annotate ,
! 86: but to
! 87: .Xr cvs 1
! 88: itself.
! 89: The default is the same as for the configuration variable
! 90: .Va @cvs_options ,
! 91: but changing either of them in the configuration file leaves the
! 92: other variable unchanged.
! 93: .It Va %CMD No # hash of strings
! 94: Absolute paths inside the webserver
! 95: .Xr chroot 2
! 96: to the following commands:
! 97: .Bd -literal -compact -offset indent
! 98: $CMD{cvs} = '/usr/bin/cvs';
! 99: $CMD{rcsdiff} = '/usr/bin/rcsdiff';
! 100: $CMD{rlog} = '/usr/bin/rlog';
! 101: $CMD{tar} = '/bin/tar';
! 102: .Ed
! 103: .It Va $cssurl No = '/css/cvsweb.css' ; # string
! 104: The URI of the cascading style sheet file.
! 105: .It Va @cvs_options No = XXX ; # array of strings
! 106: Global options passed to the
! 107: .Xr cvs 1
! 108: program when invoking a command other than
! 109: .Cm annotate .
! 110: In most cases,
! 111: .Xr cvsweb 8
! 112: passes additional global options which cannot be suppressed.
! 113: Also, the options passed to the individual CVS commands (as opposed
! 114: to the global options) are generally not configurable.
! 115: .It Va @CVSrepositories No = ('local', ['Local Repository', '/cvs']);
! 116: The list of repositories to serve in an extremely idiosyncratic format.
! 117: For each repository, the list requires two entries.
! 118: The first entry is a short string to identify the repository using the
! 119: .Cm cvsroot
! 120: query variable.
! 121: The second entry is an array reference containing two more strings.
! 122: The first one is the name of the CVS repository displayed in the user
! 123: interface, for example in navigation lines
! 124: and in dropdown selection lists.
! 125: The last on is the absolute path to the repository directory
! 126: inside the webserver
! 127: .Xr chroot 2 .
! 128: Each repository is required to contain a
! 129: .Pa CVSROOT
! 130: subdirectory with the usual content.
! 131: If possible, put all the modules you want to serve into the same
! 132: repository because that results in a simpler user interface on the web.
! 133: .It Va $DEBUG No = 0; # boolean
! 134: Let standard error output reach the web server error log.
! 135: By default, it is discarded.
! 136: .It Va $defaulttitle No = 'CVS Repository'; # string
! 137: The title of the main page.
! 138: This will be HTML escaped and put into the
! 139: .Pf < Ic title Ns >
! 140: and
! 141: .Pf < Ic h1 Ns >
! 142: elements.
! 143: .It Va %DEFAULTVALUE
! 144: A hash of defaults that can be overridden in individual CGI requests
! 145: by using query variables.
! 146: The keys are the names of the query variables listed below,
! 147: the values their respective default values.
! 148: .It Va $DEFAULTVALUE{f} No = ' Ns Cm u Ns '; # one of the letters given below
! 149: Diff format:
! 150: .Bl -tag -width Ds -compact
! 151: .It Cm c
! 152: context diff
! 153: .It Cm u
! 154: unified diff (the default)
! 155: .It Cm h
! 156: side-by-side colored diff
! 157: .El
! 158: .It Va $DEFAULTVALUE{hideattic} No = 1 ; # boolean
! 159: By default, show deleted files in a separate
! 160: .Pa Attic
! 161: directory listing.
! 162: If set to 0, include them in the main directory listing.
! 163: Despite the name, completely hiding them is not possible.
! 164: .It Va $DEFAULTVALUE{hidecvsroot} No = 0 ; # boolean
! 165: Do not include the top-level
! 166: .Pa CVSROOT
! 167: directory in the top-level directory listing.
! 168: By default, it is shown like any other directory.
! 169: .It Va $DEFAULTVALUE{hidenonreadable} No = 1 ; # boolean
! 170: By default, files and directories that cannot be read do not appear
! 171: in directory listings.
! 172: If set to 0, show them like any other files and directories.
! 173: .It Va $DEFAULTVALUE{ignorecase} No = 0 ; # boolean
! 174: Ignore case when alphabetically sorting strings.
! 175: By default, all upper case letters precede all lower case letters.
! 176: .It Va $DEFAULTVALUE{ln} No = 0 ; # boolean
! 177: Show line numbers in HTML output of files, with HTML
! 178: .Cd id
! 179: attributes of the form
! 180: .Qq l%d
! 181: to support deep linking to specific lines.
! 182: .It Va $DEFAULTVALUE{logsort} No = ' Ns Cm date Ns ';\
! 183: # one of the keywords given below
! 184: Sort order for CVS logs:
! 185: .Bl -tag -width Ds -compact
! 186: .It Cm cvs
! 187: Do not sort; list revisions as
! 188: .Xr rlog 1
! 189: shows them.
! 190: .It Cm date
! 191: Sort revisions by date, most recent first.
! 192: .It Cm rev
! 193: Sort by revision number, highest first.
! 194: .El
! 195: .It Va $DEFAULTVALUE{sortby} No = ' Ns Cm file Ns ';\
! 196: # one of the keywords given below
! 197: File sort order in directory listings:
! 198: .Bl -tag -width Ds -compact
! 199: .It Cm author
! 200: by the login name of the most recent committer, alphabetically
! 201: .It Cm date
! 202: by the latest commit date, most recent first
! 203: .It Cm file
! 204: by the filename, alphabetically (the default)
! 205: .It Cm log
! 206: by the log message, alphabetically
! 207: .It Cm rev
! 208: by the highest revision number, highest first
! 209: .El
! 210: .It Va $edit_option_form No = 1 ; # boolean
! 211: In the directory view, show a form for setting options.
! 212: .It Va $file_list_len No = 0 ; # non-negative integer
! 213: The maximum number of filenames to pass to
! 214: .Xr rlog 1
! 215: in one command.
! 216: By default, the number of filenames in a single call is not limited.
! 217: .\" Two sentences written by Ville Skytta in 2002:
! 218: If you see "Failed to spawn rlog" errors with directories containing
! 219: lots of files, experiment by setting this to different values and see if
! 220: the error still occurs.
! 221: A good value to start from is 200.
! 222: .It Va @ForbiddenFiles No # array of compiled regular expressions
! 223: Matching files and directories are not displayed.
! 224: Path names are considered relative to the respective cvsroot,
! 225: and without the
! 226: .Pa ,v
! 227: suffix, if any.
! 228: By default, the array contains the following two entries:
! 229: .Bd -literal -offset indent
! 230: qr|^CVSROOT/+passwd$|o
! 231: qr|/\e.cvspass$|o
! 232: .Ed
! 233: .It Va $hr_breakable No = 1 ; # boolean
! 234: In side-by-side colored diffs and in
! 235: .Cm annotate
! 236: output, allow line breaking.
! 237: Otherwise, horizontal scrolling may be needed
! 238: to see all parts of long lines.
! 239: .It Va $hr_ignkeysubst No = 1 ; # boolean
! 240: Do not display changes resulting only from keyword substitution, using the
! 241: .Xr rcsdiff 1
! 242: .Fl kk
! 243: option.
! 244: .It Va $hr_ignwhite No = 0 ; # boolean
! 245: Ignore whitespace in side-by-side colored diffs, using the
! 246: .Xr diff 1
! 247: .Fl w
! 248: option.
! 249: .It Va $iconsdir No = '/icons' ; # string
! 250: Absolute path inside the webserver
! 251: .Xr chroot 2
! 252: to the directory containing the icons for the web UI.
! 253: .It Va $logo No = Cm undef ; No # string including HTML markup
! 254: Optional HTML code to include at the very beginning of the
! 255: .Pf < Ic body Ns >
! 256: element.
! 257: For example, it can include an
! 258: .Pf < Ic img Ns >
! 259: element.
! 260: .It Va $mancgi No = 'https://man.openbsd.org/%s.%s'; # URI template string
! 261: String to construct URIs of online manual pages from.
! 262: The first occurrence of the substring
! 263: .Sq %s
! 264: will be replaced by the name of the manual page to link to,
! 265: the second by the manual section.
! 266: For example:
! 267: .Bd -literal
! 268: https://www.freebsd.org/cgi/man.cgi?query=%s&sektion=%s
! 269: https://netbsd.gw.com/cgi-bin/man-cgi?%s+%s
! 270: .Ed
! 271: .It Va $mime_types No = '/conf/mime.types' ; # string
! 272: Absolute paths inside the webserver
! 273: .Xr chroot 2
! 274: to the traditional
! 275: .Pa mime.types
! 276: file.
! 277: That file is used as a fallback when neither
! 278: .Va %MTYPES
! 279: nor
! 280: .Xr MIME::Types 3p
! 281: yields a match.
! 282: .It Va %MTYPES No # hash of strings
! 283: The keys are file name extensions,
! 284: the values the corresponding MIME types.
! 285: This hash is used before any other lookup method,
! 286: providing fast lookup and allowing to override other sources.
! 287: If it contains a key
! 288: .Qq * ,
! 289: the associated MIME type is used when no match is found from any source.
! 290: .It Va $preformat_in_markup No = 0 ; # boolean
! 291: When displaying file contents, mark up URIs and manual page references
! 292: with HTML
! 293: .Pf < Ic a Ns >
! 294: elements.
! 295: .It Va @rcsdiff_options No = qw(-q) ; # array of strings
! 296: Command line options passed to the
! 297: .Xr rcsdiff 1
! 298: program.
! 299: .It Va $shortLogLen No = 80 ; # positive integer
! 300: The length to which the last log entry is truncated in the directory view.
! 301: .It Va $show_author No = 1 ; # boolean
! 302: In the directory view, show the committer of the latest change.
! 303: .It Va $show_log_in_markup No = 1 ; # boolean
! 304: Prepend the corresponding commit log entry
! 305: when displaying file content in HTML format.
! 306: .It Va $show_subdir_lastmod No = 0 ; # boolean
! 307: .\" Paragraph written by Henner Zeller in 2000
! 308: .\" and possibly edited by Akinori MUSHA in 2000:
! 309: For subdirectories, try to show the last changelog message.
! 310: The current implementation makes many assumptions
! 311: and may show the incorrect file at some times.
! 312: The main assumption is that the last modified file
! 313: has the newest filedate.
! 314: But some CVS operations touch the file even when a new version isn't
! 315: checked in, and TAG based browsing essentially puts this out of
! 316: order unless the last checkin was on the same tag as you are viewing.
! 317: Enable this if you like the feature, but don't rely on correct results.
! 318: .It Va $tabstop No = 8 ; # positive integer
! 319: Tab width used for expanding tabs to spaces in HTML output.
! 320: If an editor directive controlling the tab width is found near the
! 321: beginning of a file, this variable is ignored for that file.
! 322: .It Va @tar_options No = qw() # array of strings
! 323: Command line options passed to
! 324: .Xr tar 1
! 325: when creating an archive for download.
! 326: In addition to the configured options,
! 327: .Fl c
! 328: and
! 329: .Fl f
! 330: are always used.
! 331: .It Va $use_descriptions No = 0 ; # boolean
! 332: Use optional files
! 333: .Pa CVSROOT/descriptions
! 334: containing descriptions of directories.
! 335: The first word on each line is the name of the directory
! 336: relative to the cvsroot, terminated by whitespace.
! 337: The rest of the line is a description, optionally containing HTML markup.
! 338: .It Va $use_moddate No = 1 ; # boolean
! 339: Always calculate times that correspond to the content for the HTTP
! 340: Last-Modified header, even if this requires running an additional
! 341: .Xr rlog 1
! 342: command for a file being checked out.
! 343: Disabling this can slightly reduce server load, avoiding the additional
! 344: .Xr rlog 1
! 345: command when possible.
! 346: .El
! 347: .Sh FILES
! 348: This configuration file is located at
! 349: .Pa /conf/cvsweb/cvsweb.conf
! 350: inside the web server
! 351: .Xr chroot 2 .
! 352: The only way to read it from a different place is by editing the
! 353: .Va $config
! 354: variable in the
! 355: .Xr cvsweb 8
! 356: program itself, which is not recommended.
! 357: .Sh SEE ALSO
! 358: .Xr cvs 1 ,
! 359: .Xr cvsweb 8
CVSweb