Below are tips on how to resolve common problems encountered when upgrading MailArchiva. Please also refer to Server Won't Start for further information on how to troubleshoot server startup issues.
MailArchiva v10 has an entirely overhauled authentication system. No configuration change is necessary if using LDAP, Azure, Google, or Basic authentication. If using Active Directory authentication, follow the procedure below after upgrading:
Log in to the MailArchiva web console using the MailArchiva master admin account (i.e. login using admin). Refer to locked out if admin account details are lost
Create a new service account in Active Directory (e.g., service@business.local), or reuse an existing one. This account can be a regular user with permission to search and read user attributes under the Base DN.
In the MailArchiva console, navigate to Configuration → Logins → Active Directory settings.
a) In the Default realm, enter the primary DNS domain name of your AD forest, written in uppercase (for example, BUSINESS.LOCAL).
b) In the FQDN of this server, enter the fully qualified domain name (FQDN) of the MailArchiva server (e.g. mailarchiva.business.local)
c) Set the service account login and password to the account created or re-used above (for example, service@business.local).
d) Verify the Active Directory server address is the FQDN of the AD server
e) Test the authentication by clicking on Test Login.
f) Optional: Delete the old computer account from Active Directory (for example, service$@business.local). It is no longer required.
g) Save the changes.
MailArchiva v9 uses an upgraded version of Tomcat (Version 10) application server. After performing an upgrade from MailArchiva V8 to V9, the server may fail to start due to differences in the manner in which TLS is configured in its server.xml file.
Edit C:ProgramDataMailArchivaTomcatconfserver.xml (Windows)
Edit /var/opt/mailarchiva/tomcat/conf/server.xml (Linux)
c) In the TLS connector (if enabled), either replace the entire connector or add the SSLHostConfig tag as shown below.
Restart the server. If the server still fails to start up, examine the Tomcat startup logs in /var/opt/mailarchiva/tomcat/logs (Linux) or C:ProgramDataMailArchivaTomcatlogs (Windows) and make corrections as needed.
When MailArchiva V8.11+ is downloaded and installed over any version prior to V8.11, the server may not start. The reason being, MailArchiva V8.11+ upgrades to Tomcat 9 and the auto-update system has been changed.
Edit C:ProgramDataMailArchivaTomcatconfserver.xml (Windows)
Edit /var/opt/mailarchiva/tomcat/conf/server.xml (Linux)
a) In the host tag, ensure autoDeploy and unpackWARS are set to true.
b) Remove all update service tag lines as illustrated below:
c) In the TLS connector (if enabled), change the keyPass attribute to keystorePass.
d) Ensure the AJP connector includes address and secretRequired attributes as follows:
Afterward, restart MailArchiva for changes to take effect.
In MailArchiva V9, V1 and V2 volume formats are marked read-only. If still using legacy V1 or V2 volume formats, it will be necessary to switch to V3 volume format. To resolve:
If you experience a slow startup, it could mean the server has run out of entropy or the graph database is busy upgrading/repairing itself. In the former case, install Haveged. In the latter case, it may take a while for the server to complete the repair of the graph database. Refer to GraphDB for a resolution.
A license file is tied to a specific customer and a major release of MailArchiva. After upgrading, it is necessary to obtain a new license file from our Business Portal and install the license file.
When running the installer on Windows, heap space settings may be lost. It is prudent to check the heap space settings after an upgrade. To do this, open the MailArchiva task tray applet from Windows→Program Files→Applet. Right click applet (bottom right corner of Windows task bar), click Configure, select the Java tab, verify that the maximum heap space setting is desirable. Typically, 5G or 6G.
The installer may lose the MailArchiva Service Logon Account settings. Therefore, especially in Windows environments that archive to remote storage (e.g. a NAS), after an upgrade it is advisable to reconfigure the logon account of the MailArchiva service. To do this, open Windows Services, right-click the MailArchiva service, change the Logon Account to a Windows account with sufficient privileges to read/write to the NAS. Restart MailArchiva service for changes to take effect.
As of V8.11, MailArchiva won't start if there is any abnormal condition, such as a corrupted graph database. To ascertain why the server won't start, refer to the debug.log files at /var/log/mailarchiva/ROOT/logs (C:ProgramDataMailArchivaROOTlogs) or /var/log/mailarchiva/core/logs (C:ProgramDataMailArchivacorelogs).
If there is a corrupted graph database, the debug.log file in /var/log/mailarchiva/ROOT/ or C:ProgramDataMailArchivaROOTlogs will contain database-related errors.
One possible solution is to delete/rename the graph database:
Stop MailArchiva service
Delete C:ProgramDataMailArchivaROOTdatabasearchiva (Windows)
rm /var/opt/mailarchiva/ROOT/database/archiva (Linux)
If there is a corrupted queue database:
Stop MailArchiva service
rename C:ProgamDataMailArchivaROOTqueuereceive to C:ProgamDataMailArchivaROOTqueuerestore_receive (Windows)
rename C:ProgamDataMailArchivaROOTqueueindex to C:ProgamDataMailArchivaROOTqueuerestore_index (Windows)
mv /var/opt/mailarchiva/ROOT/queue/receive to /var/opt/mailarchiva/ROOT/queue/restore_receive (Linux)
mv /var/opt/mailarchiva/ROOT/queue/index to /var/opt/mailarchiva/ROOT/queue/restore_index (Linux)
If there is a corrupted queue database:
Stop MailArchiva service
delete C:ProgamDataMailArchivaROOTlogsaudit/index (Windows)
rm /var/opt/mailarchiva/ROOT/logs/audit/index (Linux)
Restart MailArchiva and reindex the audit log file in Configuration→Logs.
The server may not start if either too much or too little heap space is allocated to MailArchiva. Refer to Heap Space Change and Memory Settings for further information on adjusting heap space within acceptable limits.
It is possible that MailArchiva includes a version of Tomcat that is expecting a newer version of its server.xml with a different structure. The installer preserves the old server.xml to protect against losing potential HTTP/S customizations. Assuming this is the case, the resolution is as follows:
Most likely your browser has cached pages. Press Shift + Refresh in your browser to reload the MailArchiva GUI and it should straighten out.
MailArchiva doesn't have sufficient privileges to read/write to the volumeinfo file residing at the root of the volume's store. Refer to Windows Logon Account Changed above.