From 3e7d0c08f98de75f582ae0c0f427dd9b76a585aa Mon Sep 17 00:00:00 2001 From: "gerv%gerv.net" <> Date: Fri, 4 Apr 2008 11:46:46 +0000 Subject: Phase 1 of a big documentation update before 2.17.6. --- docs/en/xml/installation.xml | 880 +++++++++++++++++++++++++------------------ 1 file changed, 517 insertions(+), 363 deletions(-) (limited to 'docs/en/xml/installation.xml') diff --git a/docs/en/xml/installation.xml b/docs/en/xml/installation.xml index 0d38b2ce4..a435b7f19 100644 --- a/docs/en/xml/installation.xml +++ b/docs/en/xml/installation.xml @@ -1,5 +1,5 @@ - + Installation @@ -40,24 +40,25 @@ with administrative access to install it for you. + + You are strongly recommended to make a backup of your system + before installing Bugzilla and at regular intervals thereafter. + + The listing below is a basic step-by-step list. More information can be found in the sections below. Minimum versions will be included in parenthesis where appropriate. - - Install MySQL - (&min-mysql-ver;) - - Install Perl (&min-perl-ver;) - Install Perl Modules + Install MySQL + (&min-mysql-ver;) @@ -68,12 +69,29 @@ Put Bugzilla in the Webspace + + Install Perl Modules + + Setup the MySQL Database +
+ Perl + + Any machine that doesn't have Perl on it is a sad machine indeed. + Perl can be got in source form from . + There are also binary versions available for many platforms, most of which + are linked to from perl.com. + Although Bugzilla runs with perl &min-perl-ver;, + it's a good idea to be up to the very latest version + if you can when running Bugzilla. As of this writing, that is Perl + version &newest-perl-ver;. +
+
MySQL @@ -121,19 +139,106 @@ set-variable = max_allowed_packet=1M also wish to utilize the option as mentioned in for the added security. + +
+ Configuring MySQL + + This first thing you'll want to do is make sure you've given the + root user a password as suggested in + . For clarity, these instructions will + assume that your MySQL user for Bugzilla will be bugs_user, + the database will be called bugs_db and the password for + the bugs_user user is bugs_password. You + should, of course, substitute the values you intend to use for your site. + + + + Most people use bugs for both the user and + database name. + + + + Next, we use an SQL GRANT command to create a + bugs_user + user, and grant sufficient permissions for checksetup.pl, which we'll + use later, to work its magic. This also restricts the + bugs_user + user to operations within a database called + bugs_db, and only allows the account to connect from + localhost. + Modify it to reflect your setup if you will be connecting from + another machine or as a different user. + + + mysql> GRANT SELECT,INSERT,UPDATE,DELETE,INDEX,ALTER,CREATE, + DROP,REFERENCES ON bugs_db.* TO bugs_user@localhost + IDENTIFIED BY 'bugs_password'; + mysql> FLUSH PRIVILEGES; + + + + If you are using MySQL 4, the bugs user also needs to be granted + the LOCK TABLES and + CREATE TEMPORARY TABLES permissions. + + +
-
- Perl +
+ HTTP Server - Any machine that doesn't have Perl on it is a sad machine indeed. - Perl can be got in source form from . - There are also binary versions available for many platforms, most of which - are linked to from perl.com. - Although Bugzilla runs with perl &min-perl-ver;, - it's a good idea to be up to the very latest version - if you can when running Bugzilla. As of this writing, that is Perl - version &newest-perl-ver;. + You have freedom of choice here, pretty much any web server that + is capable of running CGI + scripts will work. has more information about + configuring web servers to work with Bugzilla. + + + + We strongly recommend Apache as the web server to use. The + Bugzilla Guide installation instructions, in general, assume you are + using Apache. If you have got Bugzilla working using another webserver, + please share your experiences with us by filing a bug in &bzg-bugs;. + + + +
+ +
+ Bugzilla + + You should untar the Bugzilla files into a directory that you're + willing to make writable by the default web server user (probably + nobody). + You may decide to put the files in the main web space for your + web server or perhaps in + /usr/local + with a symbolic link in the web space that points to the Bugzilla + directory. + + + If you symlink the bugzilla directory into your Apache's HTML + hierarchy, you may receive + Forbidden + errors unless you add the + FollowSymLinks + directive to the <Directory> entry for the HTML root + in httpd.conf. + + + Once all the files are in a web accessible directory, make that + directory writable by your webserver's user. This is a temporary step + until you run the post-install + checksetup.pl + script, which locks down your installation. + + + The default Bugzilla distribution is not designed to be placed + in a cgi-bin directory (this + includes any directory which is configured using the + directive of Apache). + +
@@ -177,7 +282,7 @@ set-variable = max_allowed_packet=1M - The process of untaring the module as defined in + The process of untarring the module as defined in will create the <module> directory. @@ -660,122 +765,14 @@ ReadLine support enabled
-
- HTTP Server - - You have freedom of choice here, pretty much any web server that - is capable of running CGI - scripts will work. has more information about - configuring web servers to work with Bugzilla. - - - - We strongly recommend Apache as the web server to use. The - Bugzilla Guide installation instructions, in general, assume you are - using Apache. If you have got Bugzilla working using another webserver, - please share your experiences with us by filing a bug in &bzg-bugs;. - - - -
- -
- Bugzilla - - You should untar the Bugzilla files into a directory that you're - willing to make writable by the default web server user (probably - nobody). - You may decide to put the files in the main web space for your - web server or perhaps in - /usr/local - with a symbolic link in the web space that points to the Bugzilla - directory. - - - If you symlink the bugzilla directory into your Apache's HTML - hierarchy, you may receive - Forbidden - errors unless you add the - FollowSymLinks - directive to the <Directory> entry for the HTML root - in httpd.conf. - - - Once all the files are in a web accessible directory, make that - directory writable by your webserver's user. This is a temporary step - until you run the post-install - checksetup.pl - script, which locks down your installation. - - - The default Bugzilla distribution is not designed to be placed - in a cgi-bin directory (this - includes any directory which is configured using the - directive of Apache). This will probably - change as part of - bug - 44659. - - -
- -
- Setting Up the MySQL Database - - After you've gotten all the software installed and working you're - ready to start preparing the database for its life as the back end to - a high quality bug tracker. - - This first thing you'll want to do is make sure you've given the - root user a password as suggested in - . For clarity, these instructions will - assume that your MySQL user for Bugzilla will be bugs_user, - the database will be called bugs_db and the password for - the bugs_user user is bugs_password. You - should, of course, substitute the values you intend to use for your site. - - - - Most people use bugs for both the user and - database name. - - - - Next, we use an SQL GRANT command to create a - bugs_user - user, and grant sufficient permissions for checksetup.pl, which we'll - use later, to work its magic. This also restricts the - bugs_user - user to operations within a database called - bugs_db, and only allows the account to connect from - localhost. - Modify it to reflect your setup if you will be connecting from - another machine or as a different user. - - -mysql> GRANT SELECT,INSERT,UPDATE,DELETE,INDEX,ALTER,CREATE, - DROP,REFERENCES ON bugs_db.* TO bugs_user@localhost - IDENTIFIED BY 'bugs_password'; -mysql> FLUSH PRIVILEGES; - - - - If you are using MySQL 4, the bugs user also needs to be granted - the LOCK TABLES and - CREATE TEMPORARY TABLES permissions. - - -
<filename>checksetup.pl</filename> - Next, run the magic checksetup.pl script. (Many thanks to - Holger Schurig - for writing this script!) - This script is designed to make sure your perl modules are the correct + Next, run the magic checksetup.pl script. + This is designed to make sure your perl modules are the correct version and your MySQL database and other configuration options are consistent with the Bugzilla CGI files. It will make sure Bugzilla files and directories have reasonable @@ -849,6 +846,149 @@ ReadLine support enabled
+
+ HTTP Server Configuration + + The Bugzilla Team recommends Apache when using Bugzilla, however, any web server + that can be configured to run CGI scripts + should be able to handle Bugzilla. No matter what web server you choose, but + especially if you choose something other than Apache, you should be sure to read + . + + + The plan for this section is to eventually document the specifics of how to lock + down permissions on individual web servers. + + +
+ Apache <productname>httpd</productname> + + You will have to make sure that Apache is properly + configured to run the Bugzilla CGI scripts. You also need to make sure + that the .htaccess files created by + ./checksetup.pl are allowed to override Apache's normal access + permissions or else important password information may be exposed to the + Internet. + + + You need to configure Apache to run .cgi files outside the + cgi-bin directory. + Open your + httpd.conf file and make sure the + following line exists and is uncommented: + +AddHandler cgi-script .cgi + + + To allow .htaccess files to override + permissions and .cgi files to run in the Bugzilla directory, make sure + the following two lines are in a Directory + directive that applies to the Bugzilla directory on your system + (either the Bugzilla directory or one of its parents). + + +Options +ExecCGI +AllowOverride Limit + + + You should modify the <DirectoryIndex> parameter for + the Apache virtual host running your Bugzilla installation to + allow index.cgi as the index page for a + directory, as well as the usual index.html, + index.htm, and so forth. + + + For more information on Apache and its directives, see the + glossary entry on . + + +
+ +
+ Microsoft <productname>Internet Information Services</productname> + + If you need, or for some reason even want, to use Microsoft's + Internet Information Services or + Personal Web Server you should be able + to. You will need to configure them to know how to run CGI scripts, + however. This is described in Microsoft Knowledge Base article + Q245225 + for Internet Information Services and + Q231998 + for Personal Web Server. + + + Also, and this can't be stressed enough, make sure that files such as + localconfig and your data + directory are secured as described in . + + +
+ +
+ AOL Server + + Ben FrantzDale reported success using AOL Server with Bugzilla. He + reported his experience and what appears below is based on that. + + + AOL Server will have to be configured to run + CGI scripts, please consult + the documentation that came with your server for more information on + how to do this. + + + Because AOL Server doesn't support .htaccess + files, you'll have to create a TCL + script. You should create an aolserver/modules/tcl/filter.tcl + file (the filename shouldn't matter) with the following contents (change + /bugzilla/ to the web-based path to + your Bugzilla installation): + + + +ns_register_filter preauth GET /bugzilla/localconfig filter_deny +ns_register_filter preauth GET /bugzilla/localconfig~ filter_deny +ns_register_filter preauth GET /bugzilla/\#localconfig\# filter_deny +ns_register_filter preauth GET /bugzilla/*.pl filter_deny +ns_register_filter preauth GET /bugzilla/syncshadowdb filter_deny +ns_register_filter preauth GET /bugzilla/runtests.sh filter_deny +ns_register_filter preauth GET /bugzilla/data/* filter_deny +ns_register_filter preauth GET /bugzilla/template/* filter_deny + +proc filter_deny { why } { + ns_log Notice "filter_deny" + return "filter_return" +} + + + + This probably doesn't account for all possible editor backup + files so you may wish to add some additional variations of + localconfig. For more information, see + + bug 186383 or Bugtraq ID 6501. + + + + + If you are using webdot from research.att.com (the default + configuration for the paramater), you + will need to allow access to data/webdot/*.dot + for the reasearch.att.com machine. + + If you are using a local installation of GraphViz, you will need to allow + everybody to access *.png, + *.gif, *.jpg, and + *.map in the + data/webdot directory. + + +
+
+
Optional Additional Configuration @@ -961,20 +1101,9 @@ man 5 crontab
LDAP Authentication - - LDAP authentication has been rewritten for the 2.18 release of - Bugzilla. It no longer requires the Mozilla::LDAP module and now uses - Net::LDAP instead. This rewrite was part of a larger landing that - allowed for additional authentication schemes to be easily added - (bug - 180642). - - This patch originally landed in 21-Mar-2003 and was included - in the 2.17.4 development release. - - ]]> - + LDAP authentication is a module for Bugzilla's plugin + authentication architecture. + The existing authentication @@ -1093,56 +1222,31 @@ man 5 crontab Preventing untrusted Bugzilla content from executing malicious Javascript code - It is possible for a Bugzilla to execute malicious Javascript - code. Due to internationalization concerns, we are unable to - incorporate the code changes necessary to fulfill the CERT advisory - requirements mentioned in + It is possible for a Bugzilla attachment to contain malicious + Javascript + code, which would be executed in the domain of your Bugzilla, thereby + making it possible for the attacker to e.g. steal your login cookies. + Due to internationalization concerns, we are unable to + incorporate by default the code changes necessary to fulfill the CERT + advisory requirements mentioned in . - Making the change below will fix the problem if your installation is for - an English speaking audience. + If your installation is for an English speaking audience only, making the + change below will prevent this problem. - Telling Bugzilla to output a charset as part of the HTTP header is - much easier in version 2.18 and higher than it was - in previous versions. Simply locate the following line in + Simply locate the following line in Bugzilla/CGI.pm: - # Make sure that we don't send any charset headers $self->charset(''); and change it to: - # Send all data using the ISO-8859-1 charset $self->charset('ISO-8859-1'); - - - Using <meta> tags to set the charset is not - recommended, as there's a bug in Netscape 4.x which causes pages - marked up in this way to load twice. See - bug 126266 - for more information including progress toward making - bugzilla charset aware by default. - -
-
- - <filename>directoryindex</filename> for the Bugzilla default page. - - - You should modify the <DirectoryIndex> parameter for - the Apache virtual host running your Bugzilla installation to - allow index.cgi as the index page for a - directory, as well as the usual index.html, - index.htm, and so forth. -
-
Bugzilla and <filename>mod_perl</filename> @@ -1199,7 +1303,7 @@ man 5 crontab <section id="os-win32"> <title>Microsoft Windows - Making Bugzilla work on windows is still a very painful processes. + Making Bugzilla work on windows is still a painful processes. The Bugzilla Team is working to make it easier, but that goal is not considered a top priority. If you wish to run Bugzilla, we still recommend doing so on a Unix based system such as GNU/Linux. As of this @@ -1259,12 +1363,9 @@ C:\perl> ppm <module name>
Code changes required to run on win32 - Unfortunately, Bugzilla still doesn't run "out of the box" on - Windows. There is work in progress to make this easier, but until that - happens code will have to be modified. This section is an attempt to - list the required changes. It is an attempt to be all inclusive, but - there may be other changes required. If you find something is missing, - please file a bug in &bzg-bugs;. + As Bugzilla still doesn't run "out of the box" on + Windows, code has to be modified. This section is an attempt to + list the required changes.
@@ -1297,8 +1398,8 @@ my $webservergid = '8' To make bug e-mail work on Win32 (until bug 84876 lands), the - simplest way is to have Net::SMTP installed and change this (in - Bugzilla/BugMail.pm): + simplest way is to have the Net::SMTP Perl module installed and + change this: open(SENDMAIL, "|/usr/lib/sendmail $sendmailparam -t -i") || @@ -1452,217 +1553,270 @@ $smtp->quit;
-
- HTTP Server Configuration - - The Bugzilla Team recommends Apache when using Bugzilla, however, any web server - that can be configured to run CGI scripts - should be able to handle Bugzilla. No matter what web server you choose, but - especially if you choose something other than Apache, you should be sure to read - . - - - The plan for this section is to eventually document the specifics of how to lock - down permissions on individual web servers. - - -
- Apache <productname>httpd</productname> +
+ Bugzilla Security - As mentioned above, the Bugzilla Team recommends Apache for use - with Bugzilla. You will have to make sure that Apache is properly - configured to run the Bugzilla CGI scripts. You also need to make sure - that the .htaccess files created by - ./checksetup.pl (shown in - for the curious) are allowed to override Apache's normal access - permissions or else important password information may be exposed to the - Internet. + + Poorly-configured MySQL and Bugzilla installations have + given attackers full access to systems in the past. Please take these + guidelines seriously, even for Bugzilla machines hidden away behind + your firewall. 80% of all computer trespassers are insiders, not + anonymous crackers. + + This is not meant to be a comprehensive list of every possible + security issue pertaining to the software mentioned in this section. + There is + no subsitute for reading the information written by the authors of any + software running on your system. + + +
+ TCP/IP Ports + + + TCP/IP defines 65,000 some ports for trafic. Of those, Bugzilla + only needs 1, or 2 if you need to use features that require e-mail such + as bug moving or the e-mail interface from contrib. You should audit + your server and make sure that you aren't listening on any ports you + don't need to be. You may also wish to use some kind of firewall + software to be sure that trafic can only be recieved on ports you + specify. + +
- Many Apache installations are not configured to run scripts - anywhere but in the cgi-bin - directory; however, we recommend that Bugzilla not be installed in the - cgi-bin, otherwise the static - files such as images and - will not work correctly. To allow scripts to run in the normal - web space, the following changes should be made to your - httpd.conf file. - - - To allow files with a .cgi extension to be run, make sure the - following line exists and is uncommented: - -AddHandler cgi-script .cgi - - - To allow .htaccess files to override - permissions and .cgi files to run in the Bugzilla directory, make sure - the following two lines are in a Directory - directive that applies to the Bugzilla directory on your system - (either the Bugzilla directory or one of its parents). - - -Options +ExecCGI -AllowOverride Limit - - - - For more information on Apache and its directives, see the - glossary entry on . - - +
+ MySQL - - <filename>.htaccess</filename> files for Apache - - $BUGZILLA_HOME/.htaccess - - deny from all - - - allow from all - - ]]> - + MySQL ships by default with many settings that should be changed. + By defaults it allows anybody to connect from localhost without a + password and have full administrative capabilities. It also defaults to + not have a root password (this is not the same as + the system root). Also, many installations default to running + mysqld as the system root. + - $BUGZILLA_HOME/data/.htaccess - - allow from all - - ]]> + + + Consult the documentation that came with your system for + information on making mysqld run as an + unprivleged user. + - $BUGZILLA_HOME/data/webdot - - Allow from 192.20.225.10 - Deny from all - - -# Allow access by a local copy of 'dot' to .png, .gif, .jpg, and -# .map files - - Allow from all - - -# And no directory listings, either. -Deny from all - ]]> + + You should also be sure to disable the anonymous user account + and set a password for the root user. This is accomplished using the + following commands: - - $BUGZILLA_HOME/Bugzilla/.htaccess -# nothing in this directory is retrievable unless overriden by an .htaccess -# in a subdirectory -deny from all +bash$ mysql mysql +mysql> DELETE FROM user WHERE user = ''; +mysql> UPDATE user SET password = password('new_password') WHERE user = 'root'; +mysql> FLUSH PRIVILEGES; + From this point forward you will need to use + mysql -u root -p and enter + new_password when prompted when using the + mysql client. + - $BUGZILLA_HOME/template/.htaccess + + If you run MySQL on the same machine as your httpd server, you + should consider disabling networking from within MySQL by adding + the following to your /etc/my.conf: + -# nothing in this directory is retrievable unless overriden by an .htaccess -# in a subdirectory -deny from all +[myslqd] +# Prevent network access to MySQL. +skip-networking + + + + You may also consider running MySQL, or even all of Bugzilla + in a chroot jail; however, instructions for doing that are beyond + the scope of this document. + - +
-
- Microsoft <productname>Internet Information Services</productname> - - If you need, or for some reason even want, to use Microsoft's - Internet Information Services or - Personal Web Server you should be able - to. You will need to configure them to know how to run CGI scripts, - however. This is described in Microsoft Knowledge Base article - Q245225 - for Internet Information Services and - Q231998 - for Personal Web Server. +
+ Daemon Accounts + + Many daemons, such as Apache's httpd and MySQL's mysqld default to + running as either root or nobody. Running + as root introduces obvious security problems, but the + problems introduced by running everything as nobody may + not be so obvious. Basically, if you're running every daemon as + nobody and one of them gets compromised, they all get + compromised. For this reason it is recommended that you create a user + account for each daemon. - Also, and this can't be stressed enough, make sure that files such as - localconfig and your data - directory are secured as described in . - + + You will need to set the webservergroup to + the group you created for your webserver to run as in + localconfig. This will allow + ./checksetup.pl to better adjust the file + permissions on your Bugzilla install so as to not require making + anything world-writable. + +
-
- AOL Server +
+ Web Server Access Controls - Ben FrantzDale reported success using AOL Server with Bugzilla. He - reported his experience and what appears below is based on that. + There are many files that are placed in the Bugzilla directory + area that should not be accessable from the web. Because of the way + Bugzilla is currently laid out, the list of what should and should + not be accessible is rather complicated. - - AOL Server will have to be configured to run - CGI scripts, please consult - the documentation that came with your server for more information on - how to do this. + + Users of Apache don't need to worry about this, however, because + Bugzilla ships with .htaccess files which restrict access to all the + sensitive files in this section. Users of other webservers, read on. - Because AOL Server doesn't support .htaccess - files, you'll have to create a TCL - script. You should create an aolserver/modules/tcl/filter.tcl - file (the filename shouldn't matter) with the following contents (change - /bugzilla/ to the web-based path to - your Bugzilla installation): - + + + In the main Bugzilla directory, you should: + + + Block: + + *.pl + *localconfig* + runtests.sh + + + + + But allow: + + localconfig.js + localconfig.rdf + + + + + - -ns_register_filter preauth GET /bugzilla/localconfig filter_deny -ns_register_filter preauth GET /bugzilla/localconfig~ filter_deny -ns_register_filter preauth GET /bugzilla/\#localconfig\# filter_deny -ns_register_filter preauth GET /bugzilla/*.pl filter_deny -ns_register_filter preauth GET /bugzilla/syncshadowdb filter_deny -ns_register_filter preauth GET /bugzilla/runtests.sh filter_deny -ns_register_filter preauth GET /bugzilla/data/* filter_deny -ns_register_filter preauth GET /bugzilla/template/* filter_deny - -proc filter_deny { why } { - ns_log Notice "filter_deny" - return "filter_return" -} - + + In data: + + + Block everything + + + But allow: + + duplicates.rdf + + + + + - - This probably doesn't account for all possible editor backup - files so you may wish to add some additional variations of - localconfig. For more information, see - - bug 186383 or Bugtraq ID 6501. - - + + In data/webdot: + + + If you use a remote webdot server: + + + Block everything + + + But allow + + *.dot + + only for the remote webdot server + + + + + Otherwise, if you use a local GraphViz: + + + Block everything + + + But allow: + + *.png + *.gif + *.jpg + *.map + + + + + + + And if you don't use any dot: + + + Block everything + + + + + - - If you are using webdot from research.att.com (the default - configuration for the paramater), you - will need to allow access to data/webdot/*.dot - for the reasearch.att.com machine. + + In Bugzilla: + + + Block everything + + + + + + In template: + + + Block everything + + + + + + You should test to make sure that the files mentioned above are + not accessible from the Internet, especially your + localconfig file which contains your database + password. To test, simply point your web browser at the file; for + example, to test mozilla.org's installation, we'd try to access + . You should + get a 403 Forbidden + error. + + + + Not following the instructions in this section, including + testing, may result in sensitive information being globally + accessible. - If you are using a local installation of GraphViz, you will need to allow - everybody to access *.png, - *.gif, *.jpg, and - *.map in the - data/webdot directory. + + + + You should check to see if instructions + have been included for your web server. You should also compare those + instructions with this list to make sure everything is properly + accounted for. - + +
+
-- cgit v1.2.3-24-g4f1b