Backlog Enterprise Operations Guide

1 System requirements

This document assumes that Backlog Enterprise is installed in an environment that meets System requirements in Backlog Installation Guide.

2 Operation with HTTPS

To operate Backlog with HTTPS, it is necessary to prepare SSL server certificate in advance. Follow the procedure of the issuing organization that you use. For the rest of this document, it's assumed that the HTTPS port is set to 443.

2.1 Activating HTTPS

Follow the procedure below to activate HTTPS.

2.1.1 Stopping Backlog

Execute the following command to stop Backlog.

# systemctl stop backlog.target

2.1.2 Editing environment variables used by Backlog

Open the following file.

• /opt/backlog/scripts/env

Please edit the port numbers of the following two items from HTTP port to HTTPS port.

Example)
Before change: BACKLOG_DOMAIN="xxxx:8080" * You can omit ':80' if your HTTP port is 80
After change: BACKLOG_DOMAIN="xxxx:8443" * You can omit ':443' if your HTTPS port is 443

Example)
Before change: BACKLOG_API_GIT_HTTPURLPATTERN="http://xxxx:8080/backlog/git/%s/%s.git" * You can omit ':80' if your HTTP port is 80
After change: BACKLOG_API_GIT_HTTPURLPATTERN="https://xxxx:8443/backlog/git/%s/%s.git" * You can omit ':443' if your HTTPS port is 443

Please edit the following from "http" to "https".

Example)
Before change: BACKLOG_SCHEME="http"
After change: BACKLOG_SCHEME="https"

2.1.3 Editing ssl.conf

Edit the following part in /opt/backlog/httpd/conf/ssl.conf to match your environment.

### PLEASE CHANGE ###
ServerName www.example.com:443
#####################

### PLEASE CHANGE ###
SSLCertificateFile /etc/pki/tls/certs/localhost.crt
SSLCertificateKeyFile /etc/pki/tls/private/localhost.key
#####################

2.1.4 Editing httpd.conf

Execute the following command to add the setting to read ssl.conf.

# cp -a /opt/backlog/httpd/conf/httpd.conf /opt/backlog/httpd/conf/httpd.conf.bak
# echo 'Include conf/ssl.conf' >> /opt/backlog/httpd/conf/httpd.conf

2.1.5 Starting Backlog

Execute the following command to start Backlog.

# systemctl start backlog.target

2.1.6 Changing space URL

After logging into Backlog as an administrator, change the "Space URL" to that of HTTPS from the "management screen" → "edit space".

2.2 Redirecting to HTTPS

To limit Backlog access to HTTPS only, set up a redirect from HTTP to HTTPS by adding the following setting to /opt/backlog/httpd/conf/httpd.conf.

RewriteCond %{SERVER_PORT} !^443$
RewriteCond %{REMOTE_ADDR} !^127\.0\.0\.1$
RewriteCond %{HTTP_USER_AGENT} !^Backlog\ HttpClient
RewriteRule ^/(.*)$ https://%{HTTP_HOST}/$1 [R,L]

NOTE: Since Backlog uses HTTP access for internal API calls, do not stop HTTP usage itself with Apache settings. If you want to restrict HTTP access from outside the server, you can do so by setting the firewall.

3 Directory structure

Backlog Enterprise will be installed with the following directory structure.

/opt/backlog
|– api-server
|– bin
|– data
| |– image
| |– git
| |– lucene
| | `– index
| |– share
| | `– dav
| `– svn
|– git-server
|– httpd
|– httpd-mobile
|– licenses
|– licenses-mobile
|– perl
|– perl-mobile
|– perl-git
|– scripts
|– serf
|– subversion
`– tomcat

4 Log management

For logging management, use rotatelogs attached to Apache, or logrotate attached to OS. For details, please refer to the document provided in your usage environment.

4.1 Log file storage directory

The various middleware components comprising Backlog are stored in the following directory:

4.2 Rotating Apache log

Below is an example of a config using rotatelogs in /opt/backlog/httpd/conf/httpd.conf with a key line commented out. To use this method, configure as per the following:

# Comment out the following
#ErrorLog logs/error_log
# Enable below
ErrorLog "|/opt/backlog/httpd/bin/rotatelogs -l /opt/backlog/httpd/logs/error_log.%Y-%m-%d 86400"

#LogLevel debug
LogLevel warn

LogFormat "%h %l %u %t "%r" %>s %b "%{Referer}i" "%{User-Agent}i" %p %m %D" combined
LogFormat "%h %l %{note-x-backlog-user}n %t "%r" %>s %b "%{Referer}i" "%{User-Agent}i" %p %m %D" backlog_user_combined
LogFormat "%h %l %u %t "%r" %>s %b" common

# Comment out the following
#CustomLog logs/access_log combined env=!log-x-backlog-user
#CustomLog logs/access_log backlog_user_combined env=log-x-backlog-user
# Enable below
CustomLog "|/opt/backlog/httpd/bin/rotatelogs -l /opt/backlog/httpd/logs/access_log.%Y-%m-%d 86400" combined env=!log-x-backlog-user
CustomLog "|/opt/backlog/httpd/bin/rotatelogs -l /opt/backlog/httpd/logs/access_log.%Y-%m-%d 86400" backlog_user_combined env=log-x-backlog-user

4.3 Rotating Tomcat log

Below is an example of a config using rotatelogs in /opt/backlog/tomcat/bin/catalina.sh with a key line commented out. To use this method, configure as per the following:

>> "$CATALINA_OUT" 2>&1 "&"
#2>&1 | LD_LIBRARY_PATH="/opt/backlog/httpd/lib" /opt/backlog/httpd/bin/rotatelogs -l "$CATALINA_BASE"/logs/catalina.out.%Y-%m-%d 86400 &

 2>&1 | LD_LIBRARY_PATH="/opt/backlog/httpd/lib" /opt/backlog/httpd/bin/rotatelogs -l "$CATALINA_BASE"/logs/catalina.out.%Y-%m-%d 86400 &
#>> "$CATALINA_OUT" 2>&1 "&"

4.4 Rotating Git server log

Rotate using logrotate. Add the following files to /etc/logrotate.d/backlog-git.

/opt/backlog/git-server/logs/httpd.log
/opt/backlog/git-server/logs/rpc.log
/opt/backlog/git-server/logs/hook-worker-backlog.log
/opt/backlog/git-server/logs/hook-worker-webhook.log
/opt/backlog/git-server/logs/hook-worker-diskusage.log
/opt/backlog/git-server/logs/sshd.log
{
  sharedscripts
  postrotate
  systemctl restart backlog-git.target
  endscript
}
                          

4.5 Rotating API v2 log

Below is an example of a config using rotatelogs in /opt/backlog/scripts/backlog-api.sh with a key line commented out. To use this method, configure as per the following:

>> ${LOGS_DIR}/play.log 2>&1 &
#2>&1 | LD_LIBRARY_PATH="/opt/backlog/httpd/lib" /opt/backlog/httpd/bin/rotatelogs -l ${LOGS_DIR}/play.log.%Y-%m-%d 86400 &

2>&1 | LD_LIBRARY_PATH="/opt/backlog/httpd/lib" /opt/backlog/httpd/bin/rotatelogs -l ${LOGS_DIR}/play.log.%Y-%m-%d 86400 &
#>> ${LOGS_DIR}/play.log 2>&1 &

5 Backup

5.1 Backup

We recommend regularly backing up the following two items:

• Database dump
• Data area directory under /opt/backlog/data

For database dumping various utilities are available: mysqldump and so on.

5.2 Data area

In addition to database data, data used by Backlog is stored in the following directories:

6 Stopping unwanted services

6.1 Git service

If you do not use Git-related functionality, you can stop the backlog-git service.

# systemctl stop backlog-git.target
# systemctl disable backlog-git.target \
    backlog-git-rpc.service \
    backlog-git-httpd.service \
    backlog-git-sshd.service \
    backlog-git-hook-diskusage-worker.service \
    backlog-git-hook-webhook-worker.service \
    backlog-git-hook-backlog-worker.service

6.2 API v2 service

If you do not use version two (v2) of the API, you can stop the backlog-api service.
For details on API v2, please see Nulab Developers.

# systemctl stop backlog-api.target
# systemctl disable backlog-api.target backlog-api.service

7 Resetting after installation

7.1 Starting setup tool

After installation, you can reset the following configuration values.

• SMTP server
• Database reset

Use the resetting tool enclosed in the Backlog package (backlog-app) to reconfigure Backlog application.

Execute the following command to start the setup tool.

# /opt/backlog/bin/config.sh

7.2 Changing notification sender email address

Backlog sends out notifications to update users of new changes. For example, if a user "closes" a Backlog Issue, Backlog will send out a notification email wherein the issue registrant's email address will be used as the email sender. In certain cases, the email address and the domain sending the email may differ - resulting in the email being mistakenly marked as spam.

You can prevent this by changing sender email address!

7.2.1 Stopping Backlog

Execute the following command to stop Backlog.

# systemctl stop backlog.target

7.2.2 Specifying sender email address as environment variable used by Backlog

Open the following file.

• /opt/backlog/scripts/env

Please specify sender email address in the following.

Example)
BACKLOG_MAIL_NOTIFICATIONS_ADDRESS_FORMAT="notifications@backlog.com"

7.2.3 Starting Backlog

Execute the following command to start Backlog.

# systemctl start backlog.target

7.2.4 Setting options

You can make the sender email address unique to each sender by including the "sender ID" in the sender email address, as shown below.
[notifications@backlog.com] -> [notifications-21@backlog.com]
If the sender email address is fixed, Gmail will judge that it's from the same sender, and only one sender name will be displayed.
To display sender name on the thread, set sender address again in the following procedure.

Example)
BACKLOG_MAIL_NOTIFICATIONS_ADDRESS_FORMAT="notifications-%d@backlog.com"

Example of sender email address)
notifications-21@backlog.com

After the correction, please restart the Backlog service to apply the changes. It corresponds to steps 7.2.2 and 7.2.3 above. This will enable the name of each user who performed an action appear on Gmail inbox.

7.3 Using Active Directory with LDAP Signing

If you are using Backlog with Active Directory and want to support LDAP Signing, check out the following settings.
In order to use LDAPS (LDAP over SSL/TLS) between Backlog and Active Directory, you need to install a server certificate in Active Directory first.

7.3.1 Installing a server certificate in Active Directory

Please use one of the following ways to create a server certificate and install it in Active Directory.

• Using Active Directory Certificate Services

  For the setup, refer to the Step by Step Guide to Setup LDAPS on Windows Server page.
  Export the installed certificate and import it into your JRE keystore using the keytool command on your Backlog server.

• Using a third-party CA

  For the setup, refer to the Enable LDAP over SSL with a third-party certification authority page. If you have any questions about setting up a certificate, please contact the certification authority you are using.

7.3.2 Stopping Backlog

Execute the following command to stop Backlog.

# systemctl stop backlog.target

7.3.3 Setting environment variables used by Backlog

Open the following file.

• /opt/backlog/scripts/env

Set BACKLOG_LDAPS_USING to "true" to use LDAPS protocol. If BACKLOG_LDAPS_USING is set to "false", LDAP protocol is used instead of LDAPS.

Example)
BACKLOG_LDAPS_USING="false" * To use LDAP protocol
BACKLOG_LDAPS_USING="true"  * To use LDAPS protocol

Specify the port number of LDAPS in BACKLOG_LDPAS_PORT. This setting will not be used if BACKLOG_LDAPS_USING is false.

Example)
BACKLOG_LDAPS_PORT="636"

If you are using Active Directory Certificate Services, when users who are authenticated with Active Directory access Subversion, Git, or shared files, they may encounter an error when trying to verify the server certificate. BACKLOG_LDPAS_VERIFY can be edited from "require" to "none" to ignore the verification.
This setting will not be used if BACKLOG_LDAPS_USING is false.

Example)
BACKLOG_LDAPS_VERIFY="none"

If you are using Active Directory Certificate Services, an error may occur when searching for users from Active Directory. Add the following option to BACKLOG_CATALINA_OPTS to avoid the error.
This setting will not be used if BACKLOG_LDAPS_USING is false.

BACKLOG_CATALINA_OPTS="... -Dcom.sun.jndi.ldap.object.disableEndpointIdentification=true"

7.3.4 Starting Backlog

Execute the following command to start Backlog.

# systemctl start backlog.target

8 Port number to use

The Backlog service is published using the port numbers below. If you are using iptables or similar, please allow access from the outside to the following port numbers:

Other than the above, the following port numbers are internally used for Backlog.
5701, 8905, 8970, 8971, 8973, 8974, 8975

9 Automatic interactive mode

Installing, updating, and upgrading are performed in basic interactive mode, but it's also possible to run them in automatic interactive mode.

9.1 During installation

9.1.1 Copying setup file template for automatic interactive mode

Copy the setup file template for automatic interactive mode. You can name the copied file whatever you'd like.
In the following example, the name of the copied file is pro-init-interactive.properties.

cp /opt/backlog/bin/pro-init-interactive.properties.template pro-init-interactive.properties

9.1.2 Modifying setup value

Open the copied file and update the configuration values accordingly.
Items that require setting are described:
# [Required]
in the explanation column. Otherwise, it can be left unset, but default value will be used.
Please see the explanation column in the file for details.
The "#" at the beginning of a line indicates a comment line. Delete the first "#" to validate the setting.
Also, even if you write "#" in the middle of a line, it is not treated as a comment. If you want to invalidate the setting, write "#" at the beginning of the line.

9.1.3 Specifying saved file with -i to run installer

Specify -i during 4.6 Starting configuration tool in Installation Guide.

/opt/backlog/bin/init.sh -i pro-init-interactive.properties

9.2 During update

9.2.1 Copying setup file template for automatic interactive mode

Copy the setup file template for automatic interactive mode. You can name the copied file whatever you'd like.
In the following example, the name of the copied file is pro-update-interactive.properties.

cp /opt/backlog/bin/pro-update-interactive.properties.template pro-update-interactive.properties

9.2.2 Modifying setup value

Open the copied file in the same way as 9.1.2 Installation, and update the config values accordingly.

9.2.3 Specifying saved file with the -i flag to run updater

Specify the -i flag during 4.5 Starting up updater in Update Guide.

/opt/backlog/bin/update.sh -i pro-update-interactive.properties

10 Notes on using MySQL 5.7

10.1 Troubleshooting

MySQL 5.7 may cause issues in Backlog if the MySQL query cache is enabled. If query_cache_type has an existing value in my.cnf, set it to 0. If not, there’s no need to add it as the default value for query_cache_type in MySQL 5.7 is 0.

[mysqld]
max_allowed_packet = 16M
character-set-server=utf8mb4
sql_mode = "NO_ENGINE_SUBSTITUTION"
query_cache_type = 0

[mysql]
default-character-set=utf8mb4

[client]
default-character-set=utf8mb4