.\" $OpenBSD$
.\" 
.\" Copyright (c) 2019 Ingo Schwarze <schwarze@openbsd.org>
.\" Copyright (c) 2002 Ville Skytta
.\" Copyright (c) 2000 Akinori MUSHA
.\" Copyright (c) 2000 Henner Zeller
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd $Mdocdate: November 29 2019 $
.Dt CVSWEB.CONF 5
.Os
.Sh NAME
.Nm cvsweb.conf
.Nd CVSweb configuration file
.Sh DESCRIPTION
The
.Xr cvsweb 8
configuration file is a
.Xr perl 1
script executed via the Perl
.Fn do
function near the beginning of the main program.
It can contain arbitrary Perl code, but it is only intended to
override or change the global variables documented below, which are
listed with their default value and their type.
.Bl -tag -width Ds
.It Va $address No = 'CVSweb' ; # string optionally including HTML markup
The address shown in the footer.
This will be put into an
.Pf < Ic address Ns >
element.
.It Va $allow_annotate No = 1 ; # boolean
Enable using the
.Xr cvs 1
.Cm annotate
command.
.It Va $allow_compress No = 0 ; # boolean
Enable
.Dq Content-Encoding: gzip
if the browser supports it.
.It Va $allow_dir_extra No = 1 ; # boolean
Enable generation of hyperlinks to manual pages in directory views.
.It Va $allow_log_extra No = 1 ; # boolean
Enable generation of hyperlinks to manual pages in logs.
.It Va $allow_mailtos No = 1 ; # boolean
Enable generation of mailto: links.
.It Va $allow_markup No = 1 ; # boolean
Enable display of files in HTML form.
.It Va $allow_source_extra No = 1 ; # boolean
Enable generation of hyperlinks to manual pages in source code and diffs.
.It Va $allow_tar No = 0 ; # boolean
Enable downloading of tarballs using the
.Cm tarball
query keyword and generate hyperlinks facilitating such downloads.
.It Va @annotate_options No = XXX ; # array of strings
Global options passed to the
.Xr cvs 1
program when invoking the
.Cm annotate
command.
Despite the name, these are
.Em not
options to
.Cm annotate ,
but to
.Xr cvs 1
itself.
The default is the same as for the configuration variable
.Va @cvs_options ,
but changing either of them in the configuration file leaves the
other variable unchanged.
.It Va %CMD No # hash of strings
Absolute paths inside the webserver
.Xr chroot 2
to the following commands:
.Bd -literal -compact -offset indent
$CMD{cvs}     = '/usr/bin/cvs';
$CMD{rcsdiff} = '/usr/bin/rcsdiff';
$CMD{rlog}    = '/usr/bin/rlog';
$CMD{tar}     = '/bin/tar';
.Ed
.It Va $cssurl No = '/css/cvsweb.css' ; # string
The URI of the cascading style sheet file.
.It Va @cvs_options No = XXX ; # array of strings
Global options passed to the
.Xr cvs 1
program when invoking a command other than
.Cm annotate .
In most cases,
.Xr cvsweb 8
passes additional global options which cannot be suppressed.
Also, the options passed to the individual CVS commands (as opposed
to the global options) are generally not configurable.
.It Va @CVSrepositories No = ('local', ['Local Repository', '/cvs']);
The list of repositories to serve in an extremely idiosyncratic format.
For each repository, the list requires two entries.
The first entry is a short string to identify the repository using the
.Cm cvsroot
query variable.
The second entry is an array reference containing two more strings.
The first one is the name of the CVS repository displayed in the user
interface, for example in navigation lines
and in dropdown selection lists.
The last on is the absolute path to the repository directory
inside the webserver
.Xr chroot 2 .
Each repository is required to contain a
.Pa CVSROOT
subdirectory with the usual content.
If possible, put all the modules you want to serve into the same
repository because that results in a simpler user interface on the web.
.It Va $DEBUG No = 0; # boolean
Let standard error output reach the web server error log.
By default, it is discarded.
.It Va $defaulttitle No = 'CVS Repository'; # string
The title of the main page.
This will be HTML escaped and put into the
.Pf < Ic title Ns >
and
.Pf < Ic h1 Ns >
elements.
.It Va %DEFAULTVALUE
A hash of defaults that can be overridden in individual CGI requests
by using query variables.
The keys are the names of the query variables listed below,
the values their respective default values.
.It Va $DEFAULTVALUE{f} No =  ' Ns Cm u Ns '; # one of the letters given below
Diff format:
.Bl -tag -width Ds -compact
.It Cm c
context diff
.It Cm u
unified diff (the default)
.It Cm h
side-by-side colored diff
.El
.It Va $DEFAULTVALUE{hideattic} No = 1 ; # boolean
By default, show deleted files in a separate
.Pa Attic
directory listing.
If set to 0, include them in the main directory listing.
Despite the name, completely hiding them is not possible.
.It Va $DEFAULTVALUE{hidecvsroot} No = 0 ; # boolean
Do not include the top-level
.Pa CVSROOT
directory in the top-level directory listing.
By default, it is shown like any other directory.
.It Va $DEFAULTVALUE{hidenonreadable} No = 1 ; # boolean
By default, files and directories that cannot be read do not appear
in directory listings.
If set to 0, show them like any other files and directories.
.It Va $DEFAULTVALUE{ignorecase} No = 0 ; # boolean
Ignore case when alphabetically sorting strings.
By default, all upper case letters precede all lower case letters.
.It Va $DEFAULTVALUE{ln} No = 0 ; # boolean
Show line numbers in HTML output of files, with HTML
.Cd id
attributes of the form
.Qq l%d
to support deep linking to specific lines.
.It Va $DEFAULTVALUE{logsort} No = ' Ns Cm date Ns ';\
 # one of the keywords given below
Sort order for CVS logs:
.Bl -tag -width Ds -compact
.It Cm cvs
Do not sort; list revisions as
.Xr rlog 1
shows them.
.It Cm date
Sort revisions by date, most recent first.
.It Cm rev
Sort by revision number, highest first.
.El
.It Va $DEFAULTVALUE{sortby} No = ' Ns Cm file Ns ';\
 # one of the keywords given below
File sort order in directory listings:
.Bl -tag -width Ds -compact
.It Cm author
by the login name of the most recent committer, alphabetically
.It Cm date
by the latest commit date, most recent first
.It Cm file
by the filename, alphabetically (the default)
.It Cm log
by the log message, alphabetically
.It Cm rev
by the highest revision number, highest first
.El
.It Va $edit_option_form No = 1 ; # boolean
In the directory view, show a form for setting options.
.It Va $file_list_len No = 0 ; # non-negative integer
The maximum number of filenames to pass to
.Xr rlog 1
in one command.
By default, the number of filenames in a single call is not limited.
.\" Two sentences written by Ville Skytta in 2002:
If you see "Failed to spawn rlog" errors with directories containing
lots of files, experiment by setting this to different values and see if
the error still occurs.
A good value to start from is 200.
.It Va @ForbiddenFiles No # array of compiled regular expressions
Matching files and directories are not displayed.
Path names are considered relative to the respective cvsroot,
and without the
.Pa ,v
suffix, if any.
By default, the array contains the following two entries:
.Bd -literal -offset indent
qr|^CVSROOT/+passwd$|o
qr|/\e.cvspass$|o
.Ed
.It Va $hr_breakable No = 1 ; # boolean
In side-by-side colored diffs and in
.Cm annotate
output, allow line breaking.
Otherwise, horizontal scrolling may be needed
to see all parts of long lines.
.It Va $hr_ignkeysubst No = 1 ; # boolean
Do not display changes resulting only from keyword substitution, using the
.Xr rcsdiff 1
.Fl kk
option.
.It Va $hr_ignwhite No = 0 ; # boolean
Ignore whitespace in side-by-side colored diffs, using the
.Xr diff 1
.Fl w
option.
.It Va $iconsdir No = '/icons' ; # string
Absolute path inside the webserver
.Xr chroot 2
to the directory containing the icons for the web UI.
.It Va $logo No = Cm undef ; No # string including HTML markup
Optional HTML code to include at the very beginning of the
.Pf < Ic body Ns >
element.
For example, it can include an
.Pf < Ic img Ns >
element.
.It Va $mancgi No = 'https://man.openbsd.org/%s.%s'; # URI template string
String to construct URIs of online manual pages from.
The first occurrence of the substring
.Sq %s
will be replaced by the name of the manual page to link to,
the second by the manual section.
For example:
.Bd -literal
https://www.freebsd.org/cgi/man.cgi?query=%s&sektion=%s
https://netbsd.gw.com/cgi-bin/man-cgi?%s+%s
.Ed
.It Va $mime_types No = '/conf/mime.types' ; # string
Absolute paths inside the webserver
.Xr chroot 2
to the traditional
.Pa mime.types
file.
That file is used as a fallback when neither
.Va %MTYPES
nor
.Xr MIME::Types 3p
yields a match.
.It Va %MTYPES No # hash of strings
The keys are file name extensions,
the values the corresponding MIME types.
This hash is used before any other lookup method,
providing fast lookup and allowing to override other sources.
If it contains a key
.Qq * ,
the associated MIME type is used when no match is found from any source.
.It Va $preformat_in_markup No = 0 ; # boolean
When displaying file contents, mark up URIs and manual page references
with HTML
.Pf < Ic a Ns >
elements.
.It Va @rcsdiff_options No = qw(-q) ; # array of strings
Command line options passed to the
.Xr rcsdiff 1
program.
.It Va $shortLogLen No = 80 ; # positive integer
The length to which the last log entry is truncated in the directory view.
.It Va $show_author No = 1 ; # boolean
In the directory view, show the committer of the latest change.
.It Va $show_log_in_markup No = 1 ; # boolean
Prepend the corresponding commit log entry
when displaying file content in HTML format.
.It Va $show_subdir_lastmod No = 0 ; # boolean
.\" Paragraph written by Henner Zeller in 2000
.\" and possibly edited by Akinori MUSHA in 2000:
For subdirectories, try to show the last changelog message.
The current implementation makes many assumptions
and may show the incorrect file at some times.
The main assumption is that the last modified file
has the newest filedate.
But some CVS operations touch the file even when a new version isn't
checked in, and TAG based browsing essentially puts this out of
order unless the last checkin was on the same tag as you are viewing.
Enable this if you like the feature, but don't rely on correct results.
.It Va $tabstop No = 8 ; # positive integer
Tab width used for expanding tabs to spaces in HTML output.
If an editor directive controlling the tab width is found near the
beginning of a file, this variable is ignored for that file.
.It Va @tar_options No = qw() # array of strings
Command line options passed to
.Xr tar 1
when creating an archive for download.
In addition to the configured options,
.Fl c
and
.Fl f
are always used.
.It Va $use_descriptions No = 0 ; # boolean
Use optional files
.Pa CVSROOT/descriptions
containing descriptions of directories.
The first word on each line is the name of the directory
relative to the cvsroot, terminated by whitespace.
The rest of the line is a description, optionally containing HTML markup.
.It Va $use_moddate No = 1 ; # boolean
Always calculate times that correspond to the content for the HTTP
Last-Modified header, even if this requires running an additional
.Xr rlog 1
command for a file being checked out.
Disabling this can slightly reduce server load, avoiding the additional
.Xr rlog 1
command when possible.
.El
.Sh FILES
This configuration file is located at
.Pa /conf/cvsweb/cvsweb.conf
inside the web server
.Xr chroot 2 .
The only way to read it from a different place is by editing the
.Va $config
variable in the
.Xr cvsweb 8
program itself, which is not recommended.
.Sh SEE ALSO
.Xr cvs 1 ,
.Xr cvsweb 8