Split long lines

docs/en/rst/administering/parameters.rst

@@ -85,16 +85,24 @@ Options include whether to allow the deletion of bugs and users,
 and whether to allow users to change their email address.
 
 allowbugdeletion
-    The pages to edit products and components can delete all associated bugs when you delete a product (or component). Since that is a pretty scary idea, you have to turn on this option before any such deletions will ever happen.
+    The pages to edit products and components can delete all associated bugs
+    when you delete a product (or component). Since that is a pretty scary idea,
+    you have to turn on this option before any such deletions will ever happen.
 
 allowemailchange
-    Users can change their own email address through the preferences. Note that the change is validated by emailing both addresses, so switching this option on will not let users use an invalid address.
+    Users can change their own email address through the preferences. Note that
+    the change is validated by emailing both addresses, so switching this option
+    on will not let users use an invalid address.
 
 allowuserdeletion
-    The user editing pages are capable of letting you delete user accounts. Bugzilla will issue a warning in case you'd run into inconsistencies when you're about to do so, but such deletions still remain scary. So, you have to turn on this option before any such deletions will ever happen.
+    The user editing pages are capable of letting you delete user accounts.
+    Bugzilla will issue a warning in case you'd run into inconsistencies when
+    you're about to do so, but such deletions still remain scary. So, you have
+    to turn on this option before any such deletions will ever happen.
 
 last_visit_keep_days
-    This option controls how many days Bugzilla will remember that users have visited specific bugs.
+    This option controls how many days Bugzilla will remember that users have
+    visited specific bugs.
 
 .. _param-user-authentication:
 
@@ -110,69 +118,108 @@ of authentication cookies, and the regular expression used to
 validate email addresses. Some parameters are highlighted below.
 
 auth_env_id
-    Environment variable used by external authentication system to store a unique identifier for each user. Leave it blank if there isn't one or if this method of authentication is not being used.
+    Environment variable used by external authentication system to store a unique
+    identifier for each user. Leave it blank if there isn't one or if this method
+    of authentication is not being used.
 
 auth_env_email
-    Environment variable used by external authentication system to store each user's email address. This is a required field for environmental authentication. Leave it blank if you are not going to use this feature.
+    Environment variable used by external authentication system to store each
+    user's email address. This is a required field for environmental authentication.
+    Leave it blank if you are not going to use this feature.
 
 auth_env_realname
-    Environment variable used by external authentication system to store the user's real name. Leave it blank if there isn't one or if this method of authentication is not being used.
+    Environment variable used by external authentication system to store the
+    user's real name. Leave it blank if there isn't one or if this method of
+    authentication is not being used.
 
 user_info_class
-    Mechanism(s) to be used for gathering a user's login information. More than one may be selected. If the first one returns nothing, the second is tried, and so on. The types are:
+    Mechanism(s) to be used for gathering a user's login information. More than
+    one may be selected. If the first one returns nothing, the second is tried,
+    and so on. The types are:
 
     * :paramval:`CGI`: asks for username and password via CGI form interface.
-    * :paramval:`Env`: info for a pre-authenticated user is passed in system environment variables.
+    * :paramval:`Env`: info for a pre-authenticated user is passed in system
+      environment variables.
 
 user_verify_class
-    Mechanism(s) to be used for verifying (authenticating) information gathered by user_info_class. More than one may be selected. If the first one cannot find the user, the second is tried, and so on. The types are:
-
-    * :paramval:`DB`: Bugzilla's built-in authentication. This is the most common choice.
-    * :paramval:`RADIUS`: RADIUS authentication using a RADIUS server. Using this method requires additional parameters to be set. Please see :ref:`param-radius` for more information.
-    * :paramval:`LDAP`: LDAP authentication using an LDAP server. Using this method requires additional parameters to be set. Please see :ref:`param-ldap` for more information.
+    Mechanism(s) to be used for verifying (authenticating) information gathered
+    by user_info_class. More than one may be selected. If the first one cannot
+    find the user, the second is tried, and so on. The types are:
+
+    * :paramval:`DB`: Bugzilla's built-in authentication. This is the most common
+      choice.
+    * :paramval:`RADIUS`: RADIUS authentication using a RADIUS server. Using
+      this method requires additional parameters to be set. Please see
+      :ref:`param-radius` for more information.
+    * :paramval:`LDAP`: LDAP authentication using an LDAP server. Using this
+      method requires additional parameters to be set. Please see :ref:`param-ldap`
+      for more information.
 
 rememberlogin
     Controls management of session cookies.
 
-    * :paramval:`on` - Session cookies never expire (the user has to login only once per browser).
-    * :paramval:`off` - Session cookies last until the users session ends (the user will have to login in each new browser session).
-    * :paramval:`defaulton`/:paramval:`defaultoff` - Default behavior as described above, but user can choose whether Bugzilla will remember their login or not.
+    * :paramval:`on` - Session cookies never expire (the user has to login only
+      once per browser).
+    * :paramval:`off` - Session cookies last until the users session ends (the
+      user will have to login in each new browser session).
+    * :paramval:`defaulton`/:paramval:`defaultoff` - Default behavior as described
+      above, but user can choose whether Bugzilla will remember their login or not.
 
 requirelogin
-    If this option is set, all access to the system beyond the front page will require a login. No anonymous users will be permitted.
+    If this option is set, all access to the system beyond the front page will
+    require a login. No anonymous users will be permitted.
 
 webservice_email_filter
-    Filter email addresses returned by the WebService API depending on if the user is logged in or not. This works similarly to how the web UI currently filters email addresses. If requirelogin is enabled, then this parameter has no effect as users must be logged in to use Bugzilla anyway.
+    Filter email addresses returned by the WebService API depending on if the
+    user is logged in or not. This works similarly to how the web UI currently
+    filters email addresses. If requirelogin is enabled, then this parameter
+    has no effect as users must be logged in to use Bugzilla anyway.
 
 emailregexp
-    Defines the regular expression used to validate email addresses
-    used for login names. The default attempts to match fully
-    qualified email addresses (i.e. 'user\@example.com') in a slightly
-    more restrictive way than what is allowed in RFC 2822.
-    Another popular value to put here is :paramval:`^[^@]+`, which means 'local usernames, no @ allowed.'
+    Defines the regular expression used to validate email addresses used for
+    login names. The default attempts to match fully qualified email addresses
+    (i.e. 'user\@example.com') in a slightly more restrictive way than what is
+    allowed in RFC 2822. Another popular value to put here is :paramval:`^[^@]+`,
+    which means 'local usernames, no @ allowed.'
 
 emailregexpdesc
-    This description is shown to the user to explain which email addresses are allowed by the :param:`emailregexp` param.
+    This description is shown to the user to explain which email addresses are
+    allowed by the :param:`emailregexp` param.
 
 emailsuffix
-    This is a string to append to any email addresses when actually sending mail to that address. It is useful if you have changed the :param:`emailregexp` param to only allow local usernames, but you want the mail to be delivered to username\@my.local.hostname.
+    This is a string to append to any email addresses when actually sending mail
+    to that address. It is useful if you have changed the :param:`emailregexp`
+    param to only allow local usernames, but you want the mail to be delivered
+    to username\@my.local.hostname.
 
 createemailregexp
-    This defines the (case-insensitive) regexp to use for email addresses that are permitted to self-register. The default (:paramval:`.*`) permits any account matching the emailregexp to be created. If this parameter is left blank, no users will be permitted to create their own accounts and all accounts will have to be created by an administrator.
+    This defines the (case-insensitive) regexp to use for email addresses that
+    are permitted to self-register. The default (:paramval:`.*`) permits any
+    account matching the emailregexp to be created. If this parameter is left
+    blank, no users will be permitted to create their own accounts and all
+    accounts will have to be created by an administrator.
 
 password_complexity
-    Set the complexity required for passwords. In all cases must the passwords be at least 6 characters long.
+    Set the complexity required for passwords. In all cases must the passwords
+    be at least 6 characters long.
 
     * :paramval:`no_constraints` - No complexity required.
-    * :paramval:`mixed_letters` - Passwords must contain at least one UPPER and one lower case letter.
-    * :paramval:`letters_numbers` - Passwords must contain at least one UPPER and one lower case letter and a number.
-    * :paramval:`letters_numbers_specialchars` - Passwords must contain at least one letter, a number and a special character.
+    * :paramval:`mixed_letters` - Passwords must contain at least one UPPER
+      and one lower case letter.
+    * :paramval:`letters_numbers` - Passwords must contain at least one UPPER
+      and one lower case letter and a number.
+    * :paramval:`letters_numbers_specialchars` - Passwords must contain at least
+      one letter, a number and a special character.
 
 password_check_on_login
-    If set, Bugzilla will check that the password meets the current complexity rules and minimum length requirements when the user logs into the Bugzilla web interface. If it doesn't, the user would not be able to log in, and will receive a message to reset their password.
+    If set, Bugzilla will check that the password meets the current complexity
+    rules and minimum length requirements when the user logs into the Bugzilla
+    web interface. If it doesn't, the user would not be able to log in, and will
+    receive a message to reset their password.
 
 auth_delegation
-    If set, Bugzilla will allow other websites to request API keys from its own users. See :ref:`auth-delegation`.
+    If set, Bugzilla will allow other websites to request API keys from its own
+    users. See :ref:`auth-delegation`.
 
 .. _param-attachments:
 
@@ -184,18 +231,36 @@ regarding attachments to bugs. For example, control size limitations
 and whether to allow pointing to external files via a URI.
 
 allow_attachment_display
-    If this option is on, users will be able to view attachments from their browser, if their browser supports the attachment's MIME type. If this option is off, users are forced to download attachments, even if the browser is able to display them.
+    If this option is on, users will be able to view attachments from their
+    browser, if their browser supports the attachment's MIME type. If this
+    option is off, users are forced to download attachments, even if the browser
+    is able to display them.
 
-    If you do not trust your users (e.g. if your Bugzilla is public), you should either leave this option off, or configure and set the :param:`attachment_base` parameter (see below). Untrusted users may upload attachments that could be potentially damaging if viewed directly in the browser.
+    If you do not trust your users (e.g. if your Bugzilla is public), you should
+    either leave this option off, or configure and set the :param:`attachment_base`
+    parameter (see below). Untrusted users may upload attachments that could be
+    potentially damaging if viewed directly in the browser.
 
 attachment_base
-    When the :param:`allow_attachment_display` parameter is on, it is possible for a malicious attachment to steal your cookies or perform an attack on Bugzilla using your credentials.
-
-    If you would like additional security on attachments to avoid this, set this parameter to an alternate URL for your Bugzilla that is not the same as :param:`urlbase` or :param:`sslbase`. That is, a different domain name that resolves to this exact same Bugzilla installation.
-
-    Note that if you have set the :param:`cookiedomain` parameter, you should set :param:`attachment_base` to use a domain that would not be matched by :param:`cookiedomain`.
-
-    For added security, you can insert ``%bugid%`` into the URL, which will be replaced with the ID of the current bug that the attachment is on, when you access an attachment. This will limit attachments to accessing only other attachments on the same bug. Remember, though, that all those possible domain names (such as 1234.your.domain.com) must point to this same Bugzilla instance. To set this up you need to investigate wildcard DNS.
+    When the :param:`allow_attachment_display` parameter is on, it is possible
+    for a malicious attachment to steal your cookies or perform an attack on
+    Bugzilla using your credentials.
+
+    If you would like additional security on attachments to avoid this, set this
+    parameter to an alternate URL for your Bugzilla that is not the same as
+    :param:`urlbase` or :param:`sslbase`. That is, a different domain name that
+    resolves to this exact same Bugzilla installation.
+
+    Note that if you have set the :param:`cookiedomain` parameter, you should
+    set :param:`attachment_base` to use a domain that would not be matched by
+    :param:`cookiedomain`.
+
+    For added security, you can insert ``%bugid%`` into the URL, which will be
+    replaced with the ID of the current bug that the attachment is on, when you
+    access an attachment. This will limit attachments to accessing only other
+    attachments on the same bug. Remember, though, that all those possible domain
+    names (such as 1234.your.domain.com) must point to this same Bugzilla instance.
+    To set this up you need to investigate wildcard DNS.
 
 allow_attachment_deletion
     If this option is on, administrators will be able to delete the contents
@@ -222,14 +287,30 @@ xsendfile_header
     this way.
 
 maxattachmentsize
-    The maximum size (in kilobytes) of attachments to be stored in the database. If a file larger than this size is attached to a bug, Bugzilla will look at the :param:`maxlocalattachment` parameter to determine if the file can be stored locally on the web server. If the file size exceeds both limits, then the attachment is rejected. Setting both parameters to 0 will prevent attaching files to bugs.
-
-    Some databases have default limits which prevent storing larger attachments in the database. E.g. MySQL has a parameter called `max_allowed_packet <http://dev.mysql.com/doc/refman/5.1/en/packet-too-large.html>`_, whose default varies by distribution. Setting :param:`maxattachmentsize` higher than your current setting for this value will produce an error.
+    The maximum size (in kilobytes) of attachments to be stored in the database.
+    If a file larger than this size is attached to a bug, Bugzilla will look at
+    the :param:`maxlocalattachment` parameter to determine if the file can be
+    stored locally on the web server. If the file size exceeds both limits,
+    then the attachment is rejected. Setting both parameters to 0 will prevent
+    attaching files to bugs.
+
+    Some databases have default limits which prevent storing larger attachments
+    in the database. E.g. MySQL has a parameter called
+    `max_allowed_packet <http://dev.mysql.com/doc/refman/5.1/en/packet-too-large.html>`_,
+    whose default varies by distribution. Setting :param:`maxattachmentsize`
+    higher than your current setting for this value will produce an error.
 
 maxlocalattachment
-    The maximum size (in megabytes) of attachments to be stored locally on the web server. If set to a value lower than the :param:`maxattachmentsize` parameter, attachments will never be kept on the local filesystem.
+    The maximum size (in megabytes) of attachments to be stored locally on the
+    web server. If set to a value lower than the :param:`maxattachmentsize`
+    parameter, attachments will never be kept on the local filesystem.
 
-    Whether you use this feature or not depends on your environment. Reasons to store some or all attachments as files might include poor database performance for large binary blobs, ease of backup/restore/browsing, or even filesystem-level deduplication support. However, you need to be aware of any limits on how much data your webserver environment can store. If in doubt, leave the value at 0.
+    Whether you use this feature or not depends on your environment. Reasons
+    to store some or all attachments as files might include poor database
+    performance for large binary blobs, ease of backup/restore/browsing, or
+    even filesystem-level deduplication support. However, you need to be aware
+    of any limits on how much data your webserver environment can store. If in
+    doubt, leave the value at 0.
 
     Note that changing this value does not affect any already-submitted attachments.
 
@@ -248,10 +329,14 @@ duplicate_or_move_bug_status
     When a bug is marked as a duplicate of another one, use this bug status.
 
 letsubmitterchoosepriority
-    If this is on, then people submitting bugs can choose an initial priority for that bug. If off, then all bugs initially have the default priority selected here.
+    If this is on, then people submitting bugs can choose an initial priority
+    for that bug. If off, then all bugs initially have the default priority
+    selected here.
 
 letsubmitterchoosemilestone
-    If this is on, then people submitting bugs can choose the Target Milestone for that bug. If off, then all bugs initially have the default milestone for the product being filed in.
+    If this is on, then people submitting bugs can choose the Target Milestone
+    for that bug. If off, then all bugs initially have the default milestone
+    for the product being filed in.
 
 commenton*
     All these fields allow you to dictate what changes can pass
@@ -354,10 +439,15 @@ For more information on Groups and Group Security, see
 :ref:`groups`.
 
 chartgroup
-    The name of the group of users who can use the 'New Charts' feature. Administrators should ensure that the public categories and series definitions do not divulge confidential information before enabling this for an untrusted population. If left blank, no users will be able to use New Charts.
+    The name of the group of users who can use the 'New Charts' feature.
+    Administrators should ensure that the public categories and series
+    definitions do not divulge confidential information before enabling this
+    for an untrusted population. If left blank, no users will be able to use
+    New Charts.
 
 insidergroup
-    The name of the group of users who can see/change private comments and attachments.
+    The name of the group of users who can see/change private comments and
+    attachments.
 
 timetrackinggroup
     The name of the group of users who can see/change time tracking information.
@@ -368,10 +458,13 @@ querysharegroup
     saved searches, see :ref:`saved-searches`.
 
 comment_taggers_group
-    The name of the group of users who can tag comments. Setting this to empty disables comment tagging.
+    The name of the group of users who can tag comments. Setting this to empty
+    disables comment tagging.
 
 debug_group
-    The name of the group of users who can view the actual SQL query generated when viewing bug lists and reports. Do not expose this information to untrusted users.
+    The name of the group of users who can view the actual SQL query generated
+    when viewing bug lists and reports. Do not expose this information to
+    untrusted users.
 
 usevisibilitygroups
     If selected, user visibility will be restricted to members of
@@ -559,13 +652,19 @@ mailfrom
     it is recommended to choose a valid email address here.
 
 use_mailer_queue
-    In a large Bugzilla installation, updating bugs can be very slow because Bugzilla sends all email at once. If you enable this parameter, Bugzilla will queue all mail and then send it in the background. This requires that you have installed certain Perl modules (as listed by :file:`checksetup.pl` for this feature), and that you are running the :file:`jobqueue.pl` daemon (otherwise your mail won't get sent). This affects all mail sent by Bugzilla, not just bug updates.
+    In a large Bugzilla installation, updating bugs can be very slow because
+    Bugzilla sends all email at once. If you enable this parameter, Bugzilla
+    will queue all mail and then send it in the background. This requires that
+    you have installed certain Perl modules (as listed by :file:`checksetup.pl`
+    for this feature), and that you are running the :file:`jobqueue.pl` daemon
+    (otherwise your mail won't get sent). This affects all mail sent by Bugzilla,
+    not just bug updates.
 
 smtpserver
     The SMTP server address, if the :param:`mail_delivery_method`
-    parameter is set to :paramval:`SMTP`.  Use :paramval:`localhost` if you have a local MTA
-    running; otherwise, use a remote SMTP server.  Append ":" and the port
-    number if a non-default port is needed.
+    parameter is set to :paramval:`SMTP`.  Use :paramval:`localhost` if you have
+    a local MTA running; otherwise, use a remote SMTP server.  Append ":" and
+    the port number if a non-default port is needed.
 
 smtp_username
     Username to use for SASL authentication to the SMTP server.  Leave
@@ -611,8 +710,10 @@ needed to add a bug to the "most frequently reported" list.
 quip_list_entry_control
     Controls how easily users can add entries to the quip list.
 
-    * :paramval:`open` - Users may freely add to the quip list, and their entries will immediately be available for viewing.
-    * :paramval:`moderated` - Quips can be entered but need to be approved by a moderator before they will be shown.
+    * :paramval:`open` - Users may freely add to the quip list, and their
+      entries will immediately be available for viewing.
+    * :paramval:`moderated` - Quips can be entered but need to be approved by
+      a moderator before they will be shown.
     * :paramval:`closed` - No new additions to the quips list are allowed.
 
 mybugstemplate
@@ -625,15 +726,24 @@ defaultquery
     the advanced query page. It's in URL-parameter format.
 
 search_allow_no_criteria
-    When turned off, a query must have some criteria specified to limit the number of bugs returned to the user. When turned on, a user is allowed to run a query with no criteria and get all bugs in the entire installation that they can see. Turning this parameter on is not recommended on large installations.
+    When turned off, a query must have some criteria specified to limit the
+    number of bugs returned to the user. When turned on, a user is allowed to
+    run a query with no criteria and get all bugs in the entire installation
+    that they can see. Turning this parameter on is not recommended on large
+    installations.
 
 default_search_limit
-    By default, Bugzilla limits searches done in the web interface to returning only this many results, for performance reasons. (This only affects the HTML format of search results—CSV, XML, and other formats are exempted.) Users can click a link on the search result page to see all the results.
+    By default, Bugzilla limits searches done in the web interface to returning
+    only this many results, for performance reasons. (This only affects the HTML
+    format of search results—CSV, XML, and other formats are exempted.) Users
+    can click a link on the search result page to see all the results.
 
-    Usually you should not have to change this—the default value should be acceptable for most installations.
+    Usually you should not have to change this—the default value should be
+    acceptable for most installations.
 
 max_search_results
-    The maximum number of bugs that a search can ever return. Tabular and graphical reports are exempted from this limit, however.
+    The maximum number of bugs that a search can ever return. Tabular and
+    graphical reports are exempted from this limit, however.
 
 
 
@@ -702,7 +812,10 @@ contains parameters for how user names can be queried and matched
 when entered.
 
 usemenuforusers
-    If this option is set, Bugzilla will offer you a list to select from (instead of a text entry field) where a user needs to be selected. This option should not be enabled on sites where there are a large number of users.
+    If this option is set, Bugzilla will offer you a list to select from
+    (instead of a text entry field) where a user needs to be selected. This
+    option should not be enabled on sites where there are a large number of
+    users.
 
 ajax_user_autocompletion
     If this option is set, typing characters in a certain user fields
@@ -717,7 +830,8 @@ maxusermatches
     means no limit.
 
 confirmuniqueusermatch
-    Whether a confirmation screen should be displayed when only one user matches a search entry.
+    Whether a confirmation screen should be displayed when only one user
+    matches a search entry.
 
 .. _admin-advanced:
 
@@ -734,7 +848,11 @@ cookiedomain
     ``attachments.example.com/`` to access Bugzilla cookies.
 
 inbound_proxies
-    When inbound traffic to Bugzilla goes through a proxy, Bugzilla thinks that the IP address of the proxy is the IP address of every single user. If you enter a comma-separated list of IPs in this parameter, then Bugzilla will trust any ``X-Forwarded-For`` header sent from those IPs, and use the value of that header as the end user's IP address.
+    When inbound traffic to Bugzilla goes through a proxy, Bugzilla thinks that
+    the IP address of the proxy is the IP address of every single user. If you
+    enter a comma-separated list of IPs in this parameter, then Bugzilla will
+    trust any ``X-Forwarded-For`` header sent from those IPs, and use the value
+    of that header as the end user's IP address.
 
 proxy_url
     If this Bugzilla installation is behind a proxy, enter the proxy
@@ -745,8 +863,21 @@ proxy_url
     :paramval:`http://user:pass@proxy_url/`.
 
 strict_transport_security
-    Enables the sending of the Strict-Transport-Security header along with HTTP responses on SSL connections. This adds greater security to your SSL connections by forcing the browser to always access your domain over SSL and never accept an invalid certificate. However, it should only be used if you have the :param:`ssl_redirect` parameter turned on, Bugzilla is the only thing running on its domain (i.e., your :param:`urlbase` is something like :paramval:`http://bugzilla.example.com/`), and you never plan to stop supporting SSL.
-
-    * :paramval:`off` - Don't send the Strict-Transport-Security header with requests.
-    * :paramval:`this_domain_only` - Send the Strict-Transport-Security header with all requests, but only support it for the current domain.
-    * :paramval:`include_subdomains` - Send the Strict-Transport-Security header along with the includeSubDomains flag, which will apply the security change to all subdomains. This is especially useful when combined with an :param:`attachment_base` that exists as (a) subdomain(s) under the main Bugzilla domain.
+    Enables the sending of the Strict-Transport-Security header along with HTTP
+    responses on SSL connections. This adds greater security to your SSL
+    connections by forcing the browser to always access your domain over SSL
+    and never accept an invalid certificate. However, it should only be used
+    if you have the :param:`ssl_redirect` parameter turned on, Bugzilla is the
+    only thing running on its domain (i.e., your :param:`urlbase` is something
+    like :paramval:`http://bugzilla.example.com/`), and you never plan to stop
+    supporting SSL.
+
+    * :paramval:`off` - Don't send the Strict-Transport-Security header with
+      requests.
+    * :paramval:`this_domain_only` - Send the Strict-Transport-Security header
+      with all requests, but only support it for the current domain.
+    * :paramval:`include_subdomains` - Send the Strict-Transport-Security header
+      along with the includeSubDomains flag, which will apply the security change
+      to all subdomains. This is especially useful when combined with an
+      :param:`attachment_base` that exists as (a) subdomain(s) under the main
+      Bugzilla domain.