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