Upgrading to 6.3.4: any 5.3 or later goes straight there

[Progressiverobot]

Written for 6.3.4. hMailServer 6.3.8 (2 November 2026) is the newest release, a security release: upgrade every server running 6.3.7 or earlier. It requires schema 6108 and adds no step of its own (from 6.3.5 or older the upgrade runs 6.3.6's three one-way steps, from 6.3.3 or older 6.3.4's steps first, so this topic still applies on the way); a server on 6.3.4, 6.3.5, 6.3.6 or 6.3.7 installs it by the live update, with the exceptions the announcement lists, one from 6.2.28 to 6.3.3 by hand, once, and an older one by the installer, as always. 6.3.8's Windows installer refuses an installation of the original hMailServer's 5.7 (5.7.0, its pre-release builds 2788 and 2843, 5.7.1 and 5.7.2), which this fork's upgrade chain has no step from, before it changes anything, and the installers of 6.3.7 and earlier must never be run over one: move such a server's mail over IMAP instead (Migration.md, "From the original hMailServer"). Read "Before you upgrade" in the announcement first: some changes alter what an upgraded server does without anything being switched on, above all for TlsMode=verify-full without TlsCaFile to a MySQL or MariaDB server on the same machine, for file names outside ASCII, and for sign-in names spelt otherwise than the stored address. See the 6.3.8 announcement.

hMailServer upgrades in place. The installer stops the service, replaces the program files in Bin, upgrades the schema if needed, and restarts. Your data directory is untouched. The [Settings] section of hMailServer.INI is taken into the database at 6.3.4's first start (below).

Every server installs 6.3.4 by hand. It is Authenticode-signed and carries no Sigstore bundle, so no server's live update installs it: run hMailServer-6.3.4-x64.exe on Windows, or install the .deb or .rpm on Linux (release page).

Any 5.3 through 6.3.3 goes straight to 6.3.4. There are no intermediate steps. The upgrade chain is continuous on MySQL/MariaDB, MS SQL, PostgreSQL and SQL Server Compact, and DBUpdater walks whichever steps your database still needs. 6.3.4 needs schema 6104. A 6.3.3 database sits at 6040 and is walked through 64 steps. A 6.2.27 or 6.2.28 database sits at 6031 and is walked through 6.3.2's seven steps, 6.3.3's two and 6.3.4's 64. Older ones are walked the whole way. Path table: §18.2.

Most of what 6.3.0 to 6.3.4 added is off by default. The REST API, the Control Deck and the portal all need RestApiPort set. What 6.3.4 changes on upgrade without a switch is listed first in its release notes. The ones you will notice: the database becomes the settings store, so after the first start a line edited in hMailServer.INI is put back (HM5804) and a setting is changed in the Control Panel, over COM or REST, or with hmailserver --set-setting on Linux; SPF follows RFC 7208, so mail from 127.0.0.1 or ::1 no longer passes it unconditionally; the audit trail and the alerts are on, though nothing is mailed until AlertRecipient and AlertSenderAddress are set; a COM script that changes a route, a relay, a DNS black list, an SSL certificate or a group must now call Save() before the change takes effect; some IMAP answers change from BAD to NO; and a MySQL or MariaDB connection uses TLS whenever the database server offers it, without checking the certificate, and a SQL Server session through MSOLEDBSQL 18 or SQL Native Client is encrypted whole, where through SQLOLEDB only the login is unless [Database] TlsMode is require or verify-full, which checks the certificate (DatabaseTls.md). An upgrade keeps its listeners, its service account and its secrets as they were; only a new installation gets STARTTLS with a self-signed certificate, the Windows service as NT SERVICE\hMailServer and a stored-secrets key.

Edit hMailServer.INI after the upgrade, not to prepare it. At 6.3.4's first start a [Settings] line changed since the old server last started is taken for an edit and put back (HM5804). Set again every password with a character above U+00FF. 6.3.4 refuses a hash stored before 6.3.4 of such a password (Cyrillic, Greek or CJK letters, say) at every password sign-in, and the application log names the account. Set those passwords again soon after the upgrade: in the Control Panel, over COM or REST, and the administrator's own with hMailServer.exe --set-admin-password (hmailserver --set-admin-password on Linux). ASCII passwords are unchanged.

Before you start

Back up the database, the data directory and hMailServer.INI (chapter 15). Record your current version. Pick a quiet window; the service is down for a minute or two and senders retry. On a large store allow longer for the steps below.

That backup is the rollback. The upgrade is one way: an older server refuses a newer database rather than misreading it. Rolling back means restoring the pre-upgrade database backup and then reinstalling your previous version, with the pre-upgrade hMailServer.ini put back beside the database if 6.3.4 had sealed the stored secrets (the older version's installer would otherwise hand Windows the sealed service-account password, and the service would not start) (§18.6).

The steps that can take time, and the two that can stop

Four schema steps want a maintenance window on a large database. 6024 to 6025 rewrites hm_messages.messageflags from tinyint to smallint: a locking table rewrite on your largest table, on every backend except PostgreSQL. 6029 to 6030 adds seventeen FOREIGN KEY constraints with ON DELETE CASCADE and reads every child table once. 6100 to 6101 adds two columns to hm_messages, which is not instant on every backend. 6101 to 6102, on MySQL and MariaDB, rebuilds every table as utf8mb4.

6029 to 6030 is one place an upgrade can stop. It sweeps orphaned rows before adding those constraints, and that sweep ran children before parents, so pruning an orphaned account, fetch account or distribution list could re-orphan rows nothing revisits, and the constraint that followed was refused. The reordering fix shipped in 6.3.2 and is in 6.3.3 and 6.3.4. It fires only from a schema below 6030, only against a database that already holds orphaned rows, on all four backends. No installation has reported hitting it. When that step fails it fails loudly, in the database engine's own words, and rolls back rather than doing anything quietly. The database is where it was, the error names the constraint it could not add, and those orphaned rows have to go before the upgrade will pass.

6101 to 6102 is the other. It needs MySQL 5.7.9 or MariaDB 10.2.2 or later, as 6040 to 6041 and 6100 to 6101 do, so on an older server the upgrade stops at 6041 with error 1071 and changes nothing; and it needs the ALTER privilege on the database. Two rows the old collation told apart and utf8mb4 does not, such as straße and strase in one address book on MariaDB 11.8, stop it with error 1062 until one of them is removed; a step stopped part of the way is finished by running it again. SQL Server, SQL Server Compact and PostgreSQL only move the version number at that step (Upgrading.md).

On 6.3.1 or 6.3.2

6.3.2 could not upgrade a database older than its own schema; those attempts stopped with The server has not loaded its configuration and changed nothing. The Control Panel's live update to 6.3.2 failed with installer exit code 5, because the Control Panel that started it held its files open. Both are fixed in 6.3.3. No live update installs 6.3.4 on any version, so close the Control Panel and run the installer by hand.

On Linux the package replaces the binary and its post-install step runs hmailserver --upgrade-database. 6.3.4's packages are x86-64 only; the AArch64 packages were last published with 6.3.3 before 6.3.6, and 6.3.8 carries hmailserver_6.3.8_arm64.deb and hmailserver-6.3.8-1.aarch64.rpm, which a server from 6.3.3's AArch64 packages installs by hand, once.

Servers you are not upgrading yet

A server from 6.2.28 to 6.3.3 still looks for updates at GitHub, which answers 404. Under [Settings] in its hMailServer.INI, add UpdateFeedUrl=https://updates.progressiverobot.com/releases.json, then restart the service, and its update check works again. Keep UpdateAutoDownload off on such a server until it runs 6.3.4 (UpdateFeed.md).

Downloads and release notes · Chapter 18, upgrading