From d1619a459e23394ebf8d72503fd01a8df5c28517 Mon Sep 17 00:00:00 2001 From: "bugreport%peshkin.net" <> Date: Mon, 22 Mar 2004 06:09:31 +0000 Subject: Bug 207039: Add documentation explaining how to install bugzilla under regular user privileges r=vlad, a=justdave --- docs/xml/installation.xml | 366 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 365 insertions(+), 1 deletion(-) diff --git a/docs/xml/installation.xml b/docs/xml/installation.xml index b0995ed53..0c709e029 100644 --- a/docs/xml/installation.xml +++ b/docs/xml/installation.xml @@ -1,5 +1,5 @@ - + Installing Bugzilla @@ -1589,6 +1589,370 @@ $smtp->quit; +
+ UNIX (non-root) Installation Notes + +
+ Introduction + + If you are running an *NIX OS as non-root, either due + to lack of access (web hosts, for example) or for security + reasons, this will detail how to install Bugzilla on such + a setup. It is recommended that you read through the + + first to get an idea on the installation steps required. + (These notes will reference to steps in that guide.) + +
+ +
+ MySQL + + You may have MySQL installed as root. If you're + setting up an account with a web host, a MySQL account + needs to be set up for you. From there, you can create + the bugs account, or use the account given to you. + + + You may have problems trying to set up + GRANT permissions to the database. + If you're using a web host, chances are that you have a + separate database which is already locked down (or one big + database with limited/no access to the other areas), but you + may want to ask your system adminstrator what the security + settings are set to, and/or run the GRANT + command for you. + + Also, you will probably not be able to change the MySQL + root user password (for obvious reasons), so skip that + step. + + +
+ Running MySQL as Non-Root +
+ The Custom Configuration Method + Create a file .my.cnf in your + home directory (using /home/foo in this example) + as follows.... + +[mysqld] +datadir=/home/foo/mymysql +socket=/home/foo/mymysql/thesock +port=8081 + +[mysql] +socket=/home/foo/mymysql/thesock +port=8081 + +[mysql.server] +user=mysql +basedir=/var/lib + +[safe_mysqld] +err-log=/home/foo/mymysql/the.log +pid-file=/home/foo/mymysql/the.pid + +
+
+ The Custom Built Method + + You can install MySQL as a not-root, if you really need to. + Build it with PREFIX set to /home/foo/mysql, + or use pre-installed executables, specifying that you want + to put all of the data files in /home/foo/mysql/data. + If there is another MySQL server running on the system that you + do not own, use the -P option to specify a TCP port that is not + in use. +
+ +
+ Starting the Server + After your mysqld program is built and any .my.cnf file is + in place, you must initialize the databases (ONCE). + + bash$ + mysql_install_db + + Then start the daemon with + + bash$ + safe_mysql & + + After you start mysqld the first time, you then connect to + it as "root" and GRANT permissions to other + users. (Again, the MySQL root account has nothing to do with + the *NIX root account.) + + + You will need to start the daemons yourself. You can either + ask your system administrator to add them to system startup files, or + add a crontab entry that runs a script to check on these daemons + and restart them if needed. + + + + Do NOT run daemons or other services on a server without first + consulting your system administrator! Daemons use up system resources + and running one may be in violation of your terms of service for any + machine on which you are a user! + +
+
+ +
+ +
+ Perl + + On the extremely rare chance that you don't have Perl on + the machine, you will have to build the sources + yourself. The following commands should get your system + installed with your own personal version of Perl: + + + bash$ + wget http://perl.com/CPAN/src/stable.tar.gz + bash$ + tar zvxf stable.tar.gz + bash$ + cd perl-5.8.1 (or whatever the version of Perl is called) + bash$ + sh Configure -de -Dprefix=/home/foo/perl + bash$ + make && make test && make install + + + Once you have Perl installed into a directory (probably + in ~/perl/bin), you'll have to + change the locations on the scripts, which is detailed later on + this page. +
+ +
+ Perl Modules + + Installing the Perl modules as a non-root user is probably the + hardest part of the process. There are two different methods: a + completely independant Perl with its own modules, or personal + modules using the current (root installed) version of Perl. The + independant method takes up quite a bit of disk space, but is + less complex, while the mixed method only uses as much space as the + modules themselves, but takes more work to setup. + +
+ The Independant Method + + The independant method requires that you install your own + personal version of Perl, as detailed in the previous section. Once + installed, you can start the CPAN shell with the following + command: + + + + bash$ + /home/foo/perl/bin/perl -MCPAN -e 'shell' + + + + And then: + + + + cpan> + install Bundle::Bugzilla + + + + With this method, module installation will usually go a lot + smoother, but if you have any hang-ups, you can consult the next + section. +
+ +
+ The Mixed Method + + First, you'll need to configure CPAN to + install modules in your home directory. The CPAN FAQ says the + following on this issue: + + + +5) I am not root, how can I install a module in a personal directory? + + You will most probably like something like this: + + o conf makepl_arg "LIB=~/myperl/lib \ + INSTALLMAN1DIR=~/myperl/man/man1 \ + INSTALLMAN3DIR=~/myperl/man/man3" + install Sybase::Sybperl + + You can make this setting permanent like all "o conf" settings with "o conf commit". + + You will have to add ~/myperl/man to the MANPATH environment variable and also tell your Perl programs to + look into ~/myperl/lib, e.g. by including + + use lib "$ENV{HOME}/myperl/lib"; + + or setting the PERL5LIB environment variable. + + Another thing you should bear in mind is that the UNINST parameter should never be set if you are not root. + + + So, you will need to create a Perl directory in your home + directory, as well as the lib, + man, + man/man1, and + man/man3 directories in that + Perl directory. Set the MANPATH variable and PERL5LIB variable, so + that the installation of the modules goes smoother. (Setting + UNINST=0 in your "make install" options, on the CPAN first-time + configuration, is also a good idea.) + + After that, go into the CPAN shell: + + + + bash$ + perl -MCPAN -e 'shell' + + + + From there, you will need to type in the above "o conf" command + and commit the changes. Then you can run through the installation: + + + + cpan> + install Bundle::Bugzilla + + + + Most of the module installation process should go smoothly. However, + you may have some problems with Template. When you first start, you will + want to try to install Template with the XS Stash options on. If this + doesn't work, it may spit out C compiler error messages and croak back + to the CPAN shell prompt. So, redo the install, and turn it off. (In fact, + say no to all of the Template questions.) It may also start failing on a + few of the tests. If the total tests passed is a reasonable figure (90+%), + force the install with the following command: + + + + cpan> + force install Template + + + + You may also want to install the other optional modules: + + + cpan> + install GD + cpan> + install Chart::Base + cpan> + install MIME::Parser + + +
+
+ +
+ HTTP Server + + Ideally, this also needs to be installed as root and + running under a special webserver account. As long as + the web server will allow the running of *.cgi files outside of a + cgi-bin, and a way of denying web access to certain files (such as a + .htaccess file), you should be good in this department. + +
+ Running Apache as Non-Root + + You can run Apache as a non-root user, but the port will need + to be set to one above 1024. If you type httpd -V, + you will get a list of the variables that your system copy of httpd + uses. One of those, namely HTTPD_ROOT, tells you where that + installation looks for its config information. + + From there, you can copy the config files to your own home + directory to start editing. When you edit those and then use the -d + option to override the HTTPD_ROOT compiled into the web server, you + get control of your own customized web server. + + + You will need to start the daemons yourself. You can either + ask your system administrator to add them to system startup files, or + add a crontab entry that runs a script to check on these daemons + and restart them if needed. + + + + Do NOT run daemons or other services on a server without first + consulting your system administrator! Daemons use up system resources + and running one may be in violation of your terms of service for any + machine on which you are a user! + +
+
+ +
+ Bugzilla + + Since you probably can't set up a symbolic link to + /usr/bonsaitools/bin/perl as a non-root user, + you will need to hack the scripts to point to the right Perl: + + + perl -pi -e + 's@#\!/usr/bonsaitools/bin/perl@#\!/usr/bin/perl@' *cgi *pl Bug.pm + processmail syncshadowdb + + Change /usr/bin/perl to match the location + of Perl on your machine. If you had to install Perl as non-root, + this would be the location in your home directory. + + + + Version 2.17+ of Bugzilla now already has the scripts + pointing to /usr/bin/perl. + + + Of course, the scripts will not work if they don't know the + location of your newly install Perl modules, so you will have to hack + the scripts to look for those, too: + + + perl -pi -e + 's@use strict\;@use strict\; use lib \"/home/foo/perl/lib\"\;@' + *cgi *pl Bug.pm processmail syncshadowdb + + Change /home/foo/perl/lib to + your personal Perl library directory. You can probably skip this + step if you are using the independant method of Perl module + installation. + + + When you run ./checksetup.pl to create + the localconfig file, it will list the Perl + modules it finds. If one is missing, go back and double-check the + module installation from the CPAN shell, then delete the + localconfig file and try again. + + + The one option in localconfig you + might have problems with is the web server group. If you can't + successful browse to the index.cgi (like + a Forbidden error), you may have to relax your permissions, + and blank out the web server group. Of course, this may pose + as a security risk. Having a properly jailed shell and/or + limited access to shell accounts may lessen the security risk, + but use at your own risk. + +
+
+
Troubleshooting -- cgit v1.2.3-24-g4f1b