Skip to content
hMailServer Community Forum
hMailServer 6.3.3 is the current release, signed 15 September 2026. Windows and Linux, and an in-place upgrade from 5.3 or later.Download 6.3.3 Documentation FAQ
  1. Support and discussion for hMailServer
  2. Running hMailServer
  3. Installation, migration & upgrades

Installation, migration & upgrades

2 Topics 2 Posts

First installs, 5.x → 6.3.3 in place, moves to new hardware, and imports from other mail servers. Say which version you are on, which you are going to, and the database.

  • ProgressiverobotP

    Upgrading to 6.3.3: any 5.3 or later goes straight there

    Pinned upgrade schema database
    1
    0 Votes
    1 Posts
    8 Views
    ProgressiverobotP
    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 and hMailServer.INI are untouched. Any 5.3 through 6.2 goes straight to 6.3.3. 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.3 needs schema 6040. A 6.2.27 or 6.2.28 database sits at 6031 and is walked through 6.3.2's seven steps and 6.3.3's two. Older ones are walked the whole way. Path table: §18.2. Nothing 6.3.0 added is on by default. The REST API, the Control Deck and the portal all need RestApiPort set. A server upgraded without touching its settings behaves as 6.2.28 did, apart from the 6.3.3 delivery fix and the rebuilt webmail. 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. That backup is the rollback. The upgrade is one way: an older server refuses a newer database rather than misreading it. Rolling back means uninstalling 6.3.3, reinstalling your previous version and restoring the database from backup (§18.6). The step that can fail Two 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. 6029 to 6030 is the one place an upgrade stops. 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. 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. 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, but the live-update helper is the one already installed. Close the Control Panel and run the installer by hand once. On Linux the package replaces the binary and its post-install step runs hmailserver --upgrade-database. Downloads and release notes · Chapter 18, upgrading
  • ProgressiverobotP

    Moving to new hardware, and why Windows to Linux is a rebuild

    migration linux windows
    1
    0 Votes
    1 Posts
    6 Views
    ProgressiverobotP
    Moving to new hardware is a restore onto fresh metal. Chapter 15 is the prerequisite, and the first time, rehearse onto a test machine. The plan (§33.2) Check the new machine against the chapter 3 checklist. Size the disk for the mail store you have now, not the one you had at installation. Install the same version, in the same path. The database records absolute paths to message files, so a different version or directory is where these go wrong. Back up the old server. The built-in backup does not include messages unless you tick the option. For a large store, stop the service, copy Data\, dump the database natively, and take hMailServer.INI, Events\ and your DKIM keys. Stop the old service for good and set it to Disabled. Anything it accepts after the backup is stranded. Restore the data directory, the database and hMailServer.INI, in chapter 15's order. Re-enter the protected secrets. Keep the host name if you can. Update the A record with a lowered TTL, get a PTR on the new IP, re-run the firewall rules, repoint your port forwards, and run Utilities, Diagnostics last. Leave the old machine powered off but intact for a week or two. It is the rollback. Budget for step 6. With ProtectStoredSecretsWithDPAPI=1, the default, stored passwords are encrypted with machine-scoped Windows DPAPI and cannot be decrypted on the new machine. Re-enter the database connection password with Bin\DBSetup.exe, then route, smart-host relayer and external-account passwords in the Control Panel. Forget this and you get a server that cannot reach its own database. Linux to Linux is easier: secrets sit under <DataFolder>/.hmailserver-secret-key, so copy that file too, preserving mode 0600 and its ownership. Windows to Linux is not a migration It is not supported and the project does not claim it is. The schema is the same on both, 6.3.3 needs 6040 either way, and the message store's on-disk format is the same. What is missing is a tested path: nobody has run a Windows installation onto Linux and verified the result (§35.14). What is known to break: SQL Server. An INI with Type=MSSQL or Type=MSSQLCE is refused by name. Move to PostgreSQL or MySQL on Windows first. Every DPAPI secret. Route, fetch-account and per-domain relay passwords, private-key passphrases and the administrator's TOTP secret. Each is reported once as HM6414 and answers empty. Event scripts and COM integrations. Neither exists on Linux. DKIM key paths. The per-domain key-file setting holds a Windows path such as C:\keys\mail.pem, which resolves to nothing on Linux. Copy the keys and re-point every signing domain. Directory case. The Linux build lower-cases directory names derived from an address; Windows leaves them as found. A store carrying Test.com is one this server looks for under test.com, and everything under it must end up owned by hmailserver. So treat it as a rebuild and a cutover. A new installation on Linux, accounts and mail brought over at mailbox level by mirroring folders over IMAP from the running Windows server. The Import Tool is not an option here: it is a Windows .NET program that drives the COM API, and Linux has neither (§33.8), verified against a still-running Windows server, DNS moved last.