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

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