[BACK]Return to cvsweb.conf.5 CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / cvsweb

Annotation of cvsweb/cvsweb.conf.5, Revision 4.2

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: .\"
4.2     ! schwarze   30: .Dd $Mdocdate: November 29 2019 $
4.1       schwarze   31: .Dt CVSWEB.CONF 5
                     32: .Os
                     33: .Sh NAME
                     34: .Nm cvsweb.conf
                     35: .Nd CVSweb configuration file
                     36: .Sh DESCRIPTION
4.2     ! schwarze   37: The optional
4.1       schwarze   38: .Xr cvsweb 8
                     39: configuration file is a
                     40: .Xr perl 1
                     41: script executed via the Perl
                     42: .Fn do
4.2     ! schwarze   43: function near the beginning of the main program, if it exists.
4.1       schwarze   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.
4.2     ! schwarze   76: .It Va @annotate_options No = qw(-f -R) ; # array of strings
4.1       schwarze   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.
4.2     ! schwarze  105: .It Va @cvs_options No = qw(-f -R) ; # array of strings
4.1       schwarze  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