Essential Post Installation Configuration

TEXT 28

Guest on 19th March 2023 11:22:36 AM

Essential Post-Installation Configuration
*****************************************
Bugzilla is configured in the Administration Parameters. Log in with
the administrator account you defined in the last "checksetup.pl" run,
then click Administration in the header, and then Parameters. You will
see the different parameter sections down the left hand side of the
page.
Parameters
==========
There are a few parameters which it is very important to define (or
explicitly decide not to change).
The first set of these are in the Required Settings section.
* urlbase: this is the URL by which people should access Bugzilla's
front page.
* sslbase: if you have configured SSL on your Bugzilla server, this
is the SSL URL by which people should access Bugzilla's front page.
* ssl_redirect: Set this if you want everyone to be redirected to
use the SSL version. Recommended if you have set up SSL.
* cookiepath: Bugzilla uses cookies to remember who each user is. In
order to set those cookies in the correct scope, you may need to set
a cookiepath. If your Bugzilla is at the root of your domain, you
don't need to change the default value.
You may want to put your email address in the maintainer parameter in
the General section. This will then let people know who to contact if
they see problems or hit errors.
If you don't want just anyone able to read your Bugzilla, set the
requirelogin parameter in the User Authentication section, and change
or clear the createemailregexp parameter.
Email
=====
Bugzilla requires the ability to set up email. You have a number of
choices here. The simplest is to get Gmail or some other email
provider to do the work for you, but you can also hand the mail off to
a local email server, or run one yourself on the Bugzilla machine.
Bugzilla's approach to email is configured in the Email section of the
Parameters.
Use Another Mail Server
-----------------------
This section corresponds to choosing a mail_delivery_method of SMTP.
This method passes the email off to an existing mail server. Your
organization may well already have one running for their internal
email, and may prefer to use it for confidentiality reasons. If so,
you need the following information about it:
* The domain name of the server (Parameter: smtpserver)
* The username and password to use (Parameters: smtp_username and
smtp_password)
* Whether the server uses SSL (Parameter: smtp_ssl)
* The address you should be sending mail 'From' (Parameter:
mailfrom)
If your organization does not run its own mail server, you can use the
services of one of any number of popular email providers.
Gmail
~~~~~
Visit https://gmail.com and create a new Gmail account for your
Bugzilla to use. Then, set the following parameter values in the
"Email" section:
* mail_delivery_method: SMTP
* mailfrom: new_gmail_address@gmail.com
* smtpserver: smtp.gmail.com:465
* smtp_username: new_gmail_address@gmail.com
* smtp_password: new_gmail_password
* smtp_ssl: On
Run Your Own Mail Server
------------------------
This section corresponds to choosing a mail_delivery_method of
Sendmail.
Unless you know what you are doing, and can deal with the possible
problems of spam, bounces and blacklists, it is probably unwise to set
up your own mail server just for Bugzilla. However, if you wish to do
so, some guidance follows.
On Linux, any Sendmail-compatible MTA (Mail Transfer Agent) will
suffice. Sendmail, Postfix, qmail and Exim are examples of common
MTAs. Sendmail is the original Unix MTA, but the others are easier to
configure, and therefore many people replace Sendmail with Postfix or
Exim. They are drop-in replacements, so Bugzilla will not distinguish
between them.
If you are using Sendmail, version 8.7 or higher is required. If you
are using a Sendmail-compatible MTA, it must be compatible with at
least version 8.7 of Sendmail.
On Mac OS X 10.3 and later, Postfix is used as the built-in email
server. Postfix provides an executable that mimics sendmail enough to
satisfy Bugzilla.
On Windows, if you find yourself unable to use Bugzilla's built-in
SMTP support (e.g. because the necessary Perl modules are not
available), you can use Sendmail with a little application called
sendmail.exe, which provides sendmail-compatible calling conventions
and encapsulates the SMTP communication to another mail server. Like
Bugzilla, **sendmail.exe** can be configured to log SMTP communication
to a file in case of problems.
Detailed information on configuring an MTA is outside the scope of
this document. Consult the manual for the specific MTA you choose for
detailed installation instructions. Each of these programs will have
their own configuration files where you must configure certain
parameters to ensure that the mail is delivered properly. They are
implemented as services, and you should ensure that the MTA is in the
auto-start list of services for the machine.
If a simple mail sent with the command-line "mail" program succeeds,
then Bugzilla should also be fine.
Troubleshooting
---------------
If you are having trouble, check that any configured SMTP server can
be reached from your Bugzilla server and that any given authentication
credentials are valid. If these things seem correct and your mails are
still not sending, check if your OS uses SELinux or AppArmor. Either
of these may prevent your web server from sending email. The SELinux
boolean httpd_can_sendmail may need to be set to True.
If all those things don't help, activate the smtp_debug parameter and
check your webserver logs.
Products, Components, Versions and Milestones
=============================================
Bugs in Bugzilla are categorised into Products and, inside those
Products, Components (and, optionally, if you turn on the
useclassifications parameter, Classifications as a level above
Products).
Bugzilla comes with a single Product, called "TestProduct", which
contains a single component, imaginatively called "TestComponent". You
will want to create your own Products and their Components. It's OK to
have just one Component inside a Product. Products have Versions
(which represents the version of the software in which a bug was
found) and Target Milestones (which represent the future version of
the product in which the bug is hopefully to be fixed - or, for
RESOLVED bugs, was fixed. You may also want to add some of those.
Once you've created your own, you will want to delete TestProduct
(which will delete TestComponent automatically). Note that if you've
filed a bug in TestProduct to try Bugzilla out, you'll need to move it
elsewhere before it's possible to delete TestProduct.
Now, you may want to do some of the Optional Post-Install
Configuration.
======================================================================
This documentation undoubtedly has bugs; if you find some, please file
them here.

Raw Paste

Essential Post-Installation Configuration
*****************************************

Bugzilla is configured in the Administration Parameters. Log in with
the administrator account you defined in the last "checksetup.pl" run,
then click Administration in the header, and then Parameters. You will
see the different parameter sections down the left hand side of the
page.

Parameters
==========

There are a few parameters which it is very important to define (or
explicitly decide not to change).

The first set of these are in the Required Settings section.

* urlbase: this is the URL by which people should access Bugzilla's
  front page.

* sslbase: if you have configured SSL on your Bugzilla server, this
  is the SSL URL by which people should access Bugzilla's front page.

* ssl_redirect: Set this if you want everyone to be redirected to
  use the SSL version. Recommended if you have set up SSL.

* cookiepath: Bugzilla uses cookies to remember who each user is. In
  order to set those cookies in the correct scope, you may need to set
  a cookiepath. If your Bugzilla is at the root of your domain, you
  don't need to change the default value.

You may want to put your email address in the maintainer parameter in
the General section. This will then let people know who to contact if
they see problems or hit errors.

If you don't want just anyone able to read your Bugzilla, set the
requirelogin parameter in the User Authentication section, and change
or clear the createemailregexp parameter.

Email
=====

Bugzilla requires the ability to set up email. You have a number of
choices here. The simplest is to get Gmail or some other email
provider to do the work for you, but you can also hand the mail off to
a local email server, or run one yourself on the Bugzilla machine.

Bugzilla's approach to email is configured in the Email section of the
Parameters.

Use Another Mail Server
-----------------------

This section corresponds to choosing a mail_delivery_method of SMTP.

This method passes the email off to an existing mail server. Your
organization may well already have one running for their internal
email, and may prefer to use it for confidentiality reasons. If so,
you need the following information about it:

* The domain name of the server (Parameter: smtpserver)

* The username and password to use (Parameters: smtp_username and
  smtp_password)

* Whether the server uses SSL (Parameter: smtp_ssl)

* The address you should be sending mail 'From' (Parameter:
  mailfrom)

If your organization does not run its own mail server, you can use the
services of one of any number of popular email providers.

Gmail
~~~~~

Visit https://gmail.com and create a new Gmail account for your
Bugzilla to use. Then, set the following parameter values in the
"Email" section:

* mail_delivery_method: SMTP

* mailfrom: new_gmail_address@gmail.com

* smtpserver: smtp.gmail.com:465

* smtp_username: new_gmail_address@gmail.com

* smtp_password: new_gmail_password

* smtp_ssl: On

Run Your Own Mail Server
------------------------

This section corresponds to choosing a mail_delivery_method of
Sendmail.

Unless you know what you are doing, and can deal with the possible
problems of spam, bounces and blacklists, it is probably unwise to set
up your own mail server just for Bugzilla. However, if you wish to do
so, some guidance follows.

On Linux, any Sendmail-compatible MTA (Mail Transfer Agent) will
suffice.  Sendmail, Postfix, qmail and Exim are examples of common
MTAs. Sendmail is the original Unix MTA, but the others are easier to
configure, and therefore many people replace Sendmail with Postfix or
Exim. They are drop-in replacements, so Bugzilla will not distinguish
between them.

If you are using Sendmail, version 8.7 or higher is required. If you
are using a Sendmail-compatible MTA, it must be compatible with at
least version 8.7 of Sendmail.

On Mac OS X 10.3 and later, Postfix is used as the built-in email
server.  Postfix provides an executable that mimics sendmail enough to
satisfy Bugzilla.

On Windows, if you find yourself unable to use Bugzilla's built-in
SMTP support (e.g. because the necessary Perl modules are not
available), you can use Sendmail with a little application called
sendmail.exe, which provides sendmail-compatible calling conventions
and encapsulates the SMTP communication to another mail server. Like
Bugzilla, **sendmail.exe** can be configured to log SMTP communication
to a file in case of problems.

Detailed information on configuring an MTA is outside the scope of
this document. Consult the manual for the specific MTA you choose for
detailed installation instructions. Each of these programs will have
their own configuration files where you must configure certain
parameters to ensure that the mail is delivered properly. They are
implemented as services, and you should ensure that the MTA is in the
auto-start list of services for the machine.

If a simple mail sent with the command-line "mail" program succeeds,
then Bugzilla should also be fine.

Troubleshooting
---------------

If you are having trouble, check that any configured SMTP server can
be reached from your Bugzilla server and that any given authentication
credentials are valid. If these things seem correct and your mails are
still not sending, check if your OS uses SELinux or AppArmor. Either
of these may prevent your web server from sending email. The SELinux
boolean httpd_can_sendmail may need to be set to True.

If all those things don't help, activate the smtp_debug parameter and
check your webserver logs.

Products, Components, Versions and Milestones
=============================================

Bugs in Bugzilla are categorised into Products and, inside those
Products, Components (and, optionally, if you turn on the
useclassifications parameter, Classifications as a level above
Products).

Bugzilla comes with a single Product, called "TestProduct", which
contains a single component, imaginatively called "TestComponent". You
will want to create your own Products and their Components. It's OK to
have just one Component inside a Product. Products have Versions
(which represents the version of the software in which a bug was
found) and Target Milestones (which represent the future version of
the product in which the bug is hopefully to be fixed - or, for
RESOLVED bugs, was fixed. You may also want to add some of those.

Once you've created your own, you will want to delete TestProduct
(which will delete TestComponent automatically). Note that if you've
filed a bug in TestProduct to try Bugzilla out, you'll need to move it
elsewhere before it's possible to delete TestProduct.

Now, you may want to do some of the Optional Post-Install
Configuration.

======================================================================

This documentation undoubtedly has bugs; if you find some, please file
them here.