summaryrefslogtreecommitdiffstats
path: root/Bugzilla/Install/Localconfig.pm
blob: f01be8bf9f1fbd9e83a19f1538ca246ba839de8a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
# -*- Mode: perl; indent-tabs-mode: nil -*-
#
# The contents of this file are subject to the Mozilla Public
# License Version 1.1 (the "License"); you may not use this file
# except in compliance with the License. You may obtain a copy of
# the License at http://www.mozilla.org/MPL/
#
# Software distributed under the License is distributed on an "AS
# IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
# implied. See the License for the specific language governing
# rights and limitations under the License.
#
# The Original Code is the Bugzilla Bug Tracking System.
#
# Contributor(s): Max Kanat-Alexander <mkanat@bugzilla.org>

package Bugzilla::Install::Localconfig;

# NOTE: This package may "use" any modules that it likes. However,
# all functions in this package should assume that:
#
# * The data/ directory does not exist.
# * Templates are not available.
# * Files do not have the correct permissions
# * The database is not up to date

use strict;

use Bugzilla::Constants;

use Data::Dumper;
use IO::File;
use Safe;

use base qw(Exporter);

our @EXPORT_OK = qw(
    read_localconfig
    update_localconfig
);

# We write this constant as a sub because it has to call other
# subroutines.
sub LOCALCONFIG_VARS {
    return (
    {
        name    => 'create_htaccess',
        default => 1,
        desc    => <<EOT
# If you are using Apache as your web server, Bugzilla can create .htaccess
# files for you that will instruct Apache not to serve files that shouldn't
# be accessed from the web (like your local configuration data and non-cgi
# executable files).  For this to work, the directory your Bugzilla
# installation is in must be within the jurisdiction of a <Directory> block
# in the httpd.conf file that has 'AllowOverride Limit' in it.  If it has
# 'AllowOverride All' or other options with Limit, that's fine.
# (Older Apache installations may use an access.conf file to store these
# <Directory> blocks.)
# If this is set to 1, Bugzilla will create these files if they don't exist.
# If this is set to 0, Bugzilla will not create these files.
EOT
    },
    {
        name    => 'webservergroup',
        default => ON_WINDOWS ? '' : 'apache',
        desc    => q{# This is the group your web server runs as.
# If you have a Windows box, ignore this setting.
# If you do not have access to the group your web server runs under,
# set this to "". If you do set this to "", then your Bugzilla installation
# will be _VERY_ insecure, because some files will be world readable/writable,
# and so anyone who can get local access to your machine can do whatever they
# want. You should only have this set to "" if this is a testing installation
# and you cannot set this up any other way. YOU HAVE BEEN WARNED!
# If you set this to anything other than "", you will need to run checksetup.pl
# as} . ROOT_USER . qq{, or as a user who is a member of the specified group.\n}
    },
    {
        name    => 'db_driver',
        default => 'mysql',
        desc    => <<EOT
# What SQL database to use. Default is mysql. List of supported databases
# can be obtained by listing Bugzilla/DB directory - every module corresponds
# to one supported database and the name corresponds to a driver name.
EOT
    },
    {
        name    => 'db_host',
        default => 'localhost',
        desc    => 
            "# The DNS name of the host that the database server runs on.\n"
    },
    {
        name    => 'db_name',
        default => 'bugs',
        desc    => "# The name of the database\n"
    },
    {
        name    => 'db_user',
        default => 'bugs',
        desc    => "# Who we connect to the database as.\n"
    },
    {
        name    => 'db_pass',
        default => '',
        desc    => <<EOT
# Enter your database password here. It's normally advisable to specify
# a password for your bugzilla database user.
# If you use apostrophe (') or a backslash (\\) in your password, you'll
# need to escape it by preceding it with a '\\' character. (\\') or (\\)
# (Far simpler just not to use those characters.)
EOT
    },
    {
        name    => 'db_port',
        default => 0,
        desc    => <<EOT
# Sometimes the database server is running on a non-standard port. If that's
# the case for your database server, set this to the port number that your
# database server is running on. Setting this to 0 means "use the default
# port for my database server."
EOT
    },
    {
        name    => 'db_sock',
        default => '',
        desc    => <<EOT
# MySQL Only: Enter a path to the unix socket for MySQL. If this is
# blank, then MySQL's compiled-in default will be used. You probably
# want that.
EOT
    },
    {
        name    => 'db_check',
        default => 1,
        desc    => <<EOT
# Should checksetup.pl try to verify that your database setup is correct?
# (with some combinations of database servers/Perl modules/moonphase this
# doesn't work)
EOT
    },
    {
        name    => 'index_html',
        default => 0,
        desc    => <<EOT
# With the introduction of a configurable index page using the
# template toolkit, Bugzilla's main index page is now index.cgi.
# Most web servers will allow you to use index.cgi as a directory
# index, and many come preconfigured that way, but if yours doesn't
# then you'll need an index.html file that provides redirection
# to index.cgi. Setting \$index_html to 1 below will allow
# checksetup.pl to create one for you if it doesn't exist.
# NOTE: checksetup.pl will not replace an existing file, so if you
#       wish to have checksetup.pl create one for you, you must
#       make sure that index.html doesn't already exist
EOT
    },
    {
        name    => 'cvsbin',
        default => &_get_default_cvsbin,
        desc    => <<EOT
# For some optional functions of Bugzilla (such as the pretty-print patch
# viewer), we need the cvs binary to access files and revisions.
# Because it's possible that this program is not in your path, you can specify
# its location here.  Please specify the full path to the executable.
EOT
    },
    {
        name    => 'interdiffbin',
        default => &_get_default_interdiffbin,
        desc    => <<EOT
# For some optional functions of Bugzilla (such as the pretty-print patch
# viewer), we need the interdiff binary to make diffs between two patches.
# Because it's possible that this program is not in your path, you can specify
# its location here.  Please specify the full path to the executable.
EOT
    },
    {
        name    => 'diffpath',
        default => &_get_default_diffpath,
        desc    => <<EOT
# The interdiff feature needs diff, so we have to have that path.
# Please specify the directory name only; do not use trailing slash.
EOT
    },
    );
}

use constant OLD_LOCALCONFIG_VARS => qw(
    mysqlpath
    contenttypes
    pages
    severities platforms opsys priorities
);

sub read_localconfig {
    my ($include_deprecated) = @_;
    my $filename = bz_locations()->{'localconfig'};

    my %localconfig;
    if (-e $filename) {
        my $s = new Safe;
        $s->rdo($filename);
        if ($@ || $!) {
            my $err_msg = $@ ? $@ : $!;
            die <<EOT;
An error has occurred while reading your 'localconfig' file.  The text of 
the error message is:

$err_msg

Please fix the error in your 'localconfig' file. Alternately, rename your
'localconfig' file, rerun checksetup.pl, and re-enter your answers.

  \$ mv -f localconfig localconfig.old
  \$ ./checksetup.pl
EOT
        }

        my @vars = map($_->{name}, LOCALCONFIG_VARS);
        push(@vars, OLD_LOCALCONFIG_VARS) if $include_deprecated;
        foreach my $var (@vars) {
            my $glob = $s->varglob($var);
            # We can't get the type of a variable out of a Safe automatically.
            # We can only get the glob itself. So we figure out its type this
            # way, by trying first a scalar, then an array, then a hash.
            #
            # The interesting thing is that this converts all deprecated 
            # array or hash vars into hashrefs or arrayrefs, but that's 
            # fine since as I write this all modern localconfig vars are 
            # actually scalars.
            if (defined $$glob) {
                $localconfig{$var} = $$glob;
            }
            elsif (defined @$glob) {
                $localconfig{$var} = \@$glob;
            }
            elsif (defined %$glob) {
                $localconfig{$var} = \%$glob;
            }
        }
    }

    return \%localconfig;
}


#
# This is quite tricky. But fun!
#
# First we read the file 'localconfig'. Then we check if the variables we
# need are defined. If not, we will append the new settings to
# localconfig, instruct the user to check them, and stop.
#
# Why do it this way?
#
# Assume we will enhance Bugzilla and eventually more local configuration
# stuff arises on the horizon.
#
# But the file 'localconfig' is not in the Bugzilla CVS or tarfile. You
# know, we never want to overwrite your own version of 'localconfig', so
# we can't put it into the CVS/tarfile, can we?
#
# Now, when we need a new variable, we simply add the necessary stuff to
# LOCALCONFIG_VARS. When the user gets the new version of Bugzilla from CVS and
# runs checksetup, it finds out "Oh, there is something new". Then it adds
# some default value to the user's local setup and informs the user to
# check that to see if it is what the user wants.
#
# Cute, ey?
#
sub update_localconfig {
    my ($params) = @_;

    my $output      = $params->{output} || 0;
    my $answer      = $params->{answer} || {};
    my $localconfig = read_localconfig('include deprecated');

    my @new_vars;
    foreach my $var (LOCALCONFIG_VARS) {
        my $name = $var->{name};
        if (!defined $localconfig->{$name}) {
            push(@new_vars, $name);
            $localconfig->{$name} = $answer->{$name} || $var->{default};
        }
    }

    my @old_vars;
    foreach my $name (OLD_LOCALCONFIG_VARS) {
        push(@old_vars, $name) if defined $localconfig->{$name};
    }

    if (!$localconfig->{'interdiffbin'} && $output) {
        print <<EOT

OPTIONAL NOTE: If you want to be able to use the 'difference between two
patches' feature of Bugzilla (which requires the PatchReader Perl module
as well), you should install patchutils from:

    http://cyberelk.net/tim/patchutils/

EOT
    }

    my $filename = bz_locations->{'localconfig'};

    if (scalar @old_vars) {
        my $oldstuff = join(', ', @old_vars);
        print <<EOT

The following variables are no longer used in $filename, and
should be removed: $oldstuff

EOT
    }

    if (scalar @new_vars) {
        my $filename = bz_locations->{'localconfig'};
        my $fh = new IO::File($filename, '>>') || die "$filename: $!";
        $fh->seek(0, SEEK_END);
        foreach my $var (LOCALCONFIG_VARS) {
            if (grep($_ eq $var->{name}, @new_vars)) {
                print $fh "\n", $var->{desc},
                      Data::Dumper->Dump([$localconfig->{$var->{name}}], 
                                         ["*$var->{name}"]);
            }
        }

        my $newstuff = join(', ', @new_vars);
        print <<EOT;

This version of Bugzilla contains some variables that you may want to 
change and adapt to your local settings. Please edit the file 
$filename and rerun checksetup.pl.

The following variables are new to $filename since you last ran
checksetup.pl:  $newstuff

EOT
        exit;
    }

    # Now we do some checks on localconfig values.
    _check_web_server_group($localconfig->{'webservergroup'}) if $output;

    # Reset the cache for Bugzilla->localconfig so that it will be re-read
    delete Bugzilla->request_cache->{localconfig};

    return { old_vars => \@old_vars, new_vars => \@new_vars };
}

sub _get_default_cvsbin {
    return '' if ON_WINDOWS;

    my $cvs_executable = `which cvs`;
    if ($cvs_executable =~ /no cvs/ || $cvs_executable eq '') {
        # If which didn't find it, just set to blank
        $cvs_executable = "";
    } else {
        chomp $cvs_executable;
    }
    return $cvs_executable;
}

sub _get_default_interdiffbin {
    return '' if ON_WINDOWS;

    my $interdiff = `which interdiff`;
    if ($interdiff =~ /no interdiff/ || $interdiff eq '') {
        # If which didn't find it, just set to blank
        $interdiff = '';
    } else {
        chomp $interdiff;
    }
    return $interdiff;
}

sub _get_default_diffpath {
    return '' if ON_WINDOWS;

    my $diff_binaries;
    $diff_binaries = `which diff`;
    if ($diff_binaries =~ /no diff/ || $diff_binaries eq '') {
        # If which didn't find it, set to blank
        $diff_binaries = "";
    } else {
        $diff_binaries =~ s:/diff\n$::;
    }
    return $diff_binaries;
}

sub _check_web_server_group {
    my ($group) = @_;

    my $filename = bz_locations()->{'localconfig'};

    # If we are on Windows, webservergroup does nothing
    if (ON_WINDOWS && $group) {
        print <<EOT

Warning: You have set webservergroup in $filename
Please understand that this does not bring you any security when
running under Windows.
Verify that the file permissions in your Bugzilla directory are
suitable for your system. Avoid unnecessary write access.

EOT
    }

    # If we're not on Windows, make sure that webservergroup isn't
    # empty.
    elsif (!ON_WINDOWS && !$group) {
        print <<EOT;

********************************************************************************
WARNING! You have not entered a value for the "webservergroup" parameter
in localconfig. This means that certain files and directories which need
to be editable by both you and the webserver must be world writable, and
other files (including the localconfig file which stores your database
password) must be world readable. This means that _anyone_ who can obtain
local access to this machine can do whatever they want to your Bugzilla
installation, and is probably also able to run arbitrary Perl code as the
user that the webserver runs as.

You really, really, really need to change this setting.
********************************************************************************
EOT
    }

    # If we're not on Windows, make sure we are actually a member of
    # the webservergroup.
    elsif (!ON_WINDOWS && $group) {
        # If on unix, see if we need to print a warning about a webservergroup
        # that we can't chgrp to
        my $webservergid = (getgrnam($group))[2]
                            or die("no such group: $group");
        if ($< != 0 && !grep($_ eq $webservergid, split(" ", $)))) {
            my $root = ROOT_USER;
            print <<EOT;

Warning: you have entered a value for the "webservergroup" parameter in
localconfig, but you are not either a) running this script as $root; or b) a
member of this group. This can cause permissions problems and decreased
security.  If you experience problems running Bugzilla scripts, log in as
$root and re-run this script, become a member of the group, or remove the
value of the "webservergroup" parameter. Note that any warnings about
"uninitialized values" that you may see below are caused by this.

EOT
        }
    }
}

1;

__END__

=head1 NAME

Bugzilla::Install::Localconfig - Functions and variables dealing
  with the manipulation and creation of the F<localconfig> file.

=head1 SYNOPSIS

 use Bugzilla::Install::Requirements qw(update_localconfig);
 update_localconfig({ output => 1, answer => \%answer });

=head1 DESCRIPTION

This module is used primarily by L<checksetup.pl> to create and
modify the localconfig file. Most scripts should use L<Bugzilla/localconfig>
to access localconfig variables.

=head1 CONSTANTS

=over

=item C<LOCALCONFIG_VARS>

An array of hashrefs. These hashrefs contain three keys:

 name    - The name of the variable.
 default - The default value for the variable. Should always be
           something that can fit in a scalar.
 desc    - Additional text to put in localconfig before the variable
           definition. Must end in a newline. Each line should start
           with "#" unless you have some REALLY good reason not
           to do that.

=item C<OLD_LOCALCONFIG_VARS>

An array of names of variables. If C<update_localconfig> finds these
variables defined in localconfig, it will print out a warning.

=back

=head1 SUBROUTINES

=over

=item C<read_localconfig($include_deprecated)>

Description: Reads the localconfig file and returns all valid
             values in a hashref.

Params:      C<$include_deprecated> - C<true> if you want the returned
                 hashref to also include variables listed in 
                 C<OLD_LOCALCONFIG_VARS>, if they exist. Generally
                 this is only for use by C<update_localconfig>.

Returns:     A hashref of the localconfig variables. If an array
             is defined, it will be an arrayref in the returned hash. If a
             hash is defined, it will be a hashref in the returned hash.
             Only includes variables specified in C<LOCALCONFIG_VARS>
             (and C<OLD_LOCALCONFIG_VARS> if C<$include_deprecated> is
             specified).

=item C<update_localconfig({ output =E<gt> 1, answer =E<gt> \%answer })>

Description: Adds any new variables to localconfig that aren't
             currently defined there. Also optionally prints out
             a message about vars that *should* be there and aren't.
             Exits the program if it adds any new vars.

Params:      C<output> - C<true> if the function should display informational
                 output and warnings. It will always display errors or
                 any message which would cause program execution to halt.

Returns:     A hashref, with C<old_vals> being an array of names of variables
             that were removed, and C<new_vals> being an array of names
             of variables that were added to localconfig.

=back