Bug 346344: Move checksetup's localconfig-handling code into Bugzilla::Install::Localconfig

Patch By Max Kanat-Alexander <mkanat@bugzilla.org> (module owner) a=justdave

1 files changed, 531 insertions, 0 deletions

diff --git a/Bugzilla/Install/Localconfig.pm b/Bugzilla/Install/Localconfig.pm
new file mode 100644
index 000000000..ba18fcfd9
--- /dev/null
+++ b/Bugzilla/Install/Localconfig.pm
@@ -0,0 +1,531 @@
+# -*- 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 Fcntl qw(SEEK_END);
+use IO::File;
+use Safe;
+
+use base qw(Exporter);
+our @EXPORT = qw(
+    read_localconfig
+);
+
+our @EXPORT_OK = qw(
+    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;
+
+    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(read_localconfig update_localconfig)
+ my $localconfig = read_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.
+
+=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