---
title: "The Control Panel on Windows: every page, what it writes, and what applies when"
url: https://www.hmailserver.co.uk/topic/28223/the-control-panel-on-windows-every-page-what-it-writes-and-what-applies-when
author: "Progressiverobot"
published: 2026-09-27T19:05:13.731Z
updated: 2026-09-27T19:05:13.731Z
category: "General support"
tags: ["control-panel","windows","administration","database"]
site: hMailServer Community Forum
---

# The Control Panel on Windows: every page, what it writes, and what applies when

*Written for 6.3.4. hMailServer 6.3.7 (17 October 2026) moves the Control Panel's pages: Updates is a page of its own under Maintenance, the sidebar has Compliance and Virus scanning groups, API & monitoring is Monitoring & alerts, the PROXY protocol and XCLIENT are a card on Incoming relays, and Ctrl+K takes every old title and route to its page. A Control Panel signed in to a server on another computer now shows and saves the server's `hMailServer.ini` `[Settings]` values. The anti-virus action named Delete infected attachments only in 6.3.6's Control Panel is Remove all attachments and deliver the text in 6.3.7's. The installers carry the .NET Desktop Runtime 10.0.13, Microsoft's security release of 13 October 2026, on which the Control Panel runs, but install it only where no .NET 10 Desktop Runtime is installed at all: an upgraded server keeps the 10.0.12 that 6.3.4, 6.3.5 or 6.3.6 installed, so bring it to 10.0.13 or later through Microsoft Update or Microsoft's installer. See [the 6.3.7 announcement](/topic/28277).*

The hMailServer Control Panel (`hMailCP.exe`) is the Windows desktop administration application: a .NET 10 WPF program, x64 only, that talks to the server over the COM API. That is why it can administer a server on another machine over DCOM, and why there is none on Linux, where the Control Deck, the REST API and `hmctl` are the administration surfaces ([hMailServer on Linux: what you get and what you do not](/topic/28189)). This topic covers what it writes and where, connecting, the 65 pages with the store behind each, and, since 6.3.4, the mark under each field that says when a saved value applies, the pending bar, the Levels tab and the help pane. The one thing to know first: since 6.3.4 the Control Panel writes every `[Settings]` key over COM into the database, even when it runs on the server itself, and a Control Panel with no connection says it cannot change such a setting rather than writing to the file, where a stored key's line is ignored in favour of the database's value.

### What it holds, and what it writes where

**The Control Panel holds no configuration of its own.** Its per-user state (window bounds, theme, language) is under `HKCU\Software\hMailServer\ControlPanel`. The server is reached over COM. Files on the server (`hMailServer.INI`, `hMailServerApiKeys.ini`, the log folder, the event script, certificate and key files) are reachable only when the Control Panel runs on the server itself.

**Since 6.3.4 the database is the store of the `[Settings]` keys**, and the file holds a copy ([where each setting is kept, and what stays in the file](/topic/28222)). The Control Panel reads those keys over COM, falls back to the file only when it has no session, and writes them over COM only; a `[Settings]` line edited by hand in the file changes nothing, and the error log names it as `HM5804`. `[Database]`, `[Directories]` and `[LDAP]` are still read from the file only, and `[Database]` and `[Directories]` are deliberately not reachable over COM.

**Since 6.3.4 a new installation runs the service as `NT SERVICE\hMailServer`**; an upgrade keeps the account it had ([the service account, and moving to or from it](/topic/28227)). `hMailServer.INI` is read-only to that account on purpose, so its copy of the settings goes stale there. For the Control Panel that changes four things, each refused with a sentence rather than failing quietly:

| What | Under the virtual account |
|---|---|
| Settings saved on any page | Unchanged, since they are kept in the database; only `PasswordPepper`, kept in the file only, is refused |
| The **Administrator password** card, and enrolling or removing the administrator's second factor | Refused. For the password the sentence names `hMailServer.exe /SetAdministratorPassword` from an elevated prompt |
| The data, log and temporary directories | Refused: an administrator changes the file and approves the new folder for the service |
| Creating or switching the database | Refused before anything is made |

**Maintenance → Server limits & expert settings** carries a **Windows service account** card: what the service actually runs as, and three buttons, each run after the Windows elevation prompt: **Grant access** (`hMailServer.exe --confirm /GrantServiceAccess`), **Move to NT SERVICE\hMailServer** and **Move to LocalSystem**. The live update's apply and the auto-ban's firewall rules need LocalSystem, and are refused under the virtual account with a sentence. From 6.3.6 a service running as `NT SERVICE\hMailServer` downloads and verifies an update, and an administrator installs it with **Install update** on the Server status page of the Control Panel on the server, with one Windows prompt; on 6.3.4 and 6.3.5 Install update cannot do it, and the administrator runs the downloaded installer by hand.

### Connecting

| Field | What to enter | When it is wrong |
|---|---|---|
| **Server** | `localhost`, or the remote server's name or IP; an empty box means `localhost` | A name that does not resolve, or does not answer on TCP 135, gets a sentence saying so. The check has a four-second budget, so a mistyped host is a pause, not a hang |
| **User name** | `Administrator`. A mailbox address also authenticates, but only a server administrator can read the settings | *"Authentication failed. Check the user name and password."* The server never says which of the two was wrong |
| **Password** | The administration password set during installation | The same message |

*"hMailServer COM API is not registered on the target machine."* means you reached the machine but hMailServer is not installed there. *"Unable to reach the server (RPC unavailable)."* is HRESULT `0x800706BA`: firewall, DCOM permissions, or the service is not running.

**Two second factors, and they are not the same thing.** The server-enforced one, whose secret is `[Security] AdministratorTotpSecret` in `hMailServer.ini`, protects every client of the administrator credential: this Control Panel, COM scripts, and the REST API through its `X-hMailServer-OTP` header. The older one, `AdminTotpSecret` under `HKLM\SOFTWARE\hMailServer`, protects this installation of the Control Panel on this machine and nothing else. The code is asked for once, never in a loop, because a wrong password and a missing code look identical from outside.

`hMailCP.exe /connect <host> <user> <password>` signs in as the window loads; the password is on the command line, where anything that can list processes can read it. Connecting opens the **Dashboard**, not Welcome. COM sign-in is deliberately outside the auto-ban and the per-name lockout, so guessing an administrator's name over IMAP cannot lock that administrator out.

### The window and the tree

**Since 6.3.4** the Control Panel is drawn on one design system. The window has three rows: the title bar; a command bar holding the sidebar toggle, a search field that opens the Ctrl+K palette, a server status pill (*Not connected*, *Connected*, *Reconnecting…*, *Connection lost*), the theme toggle and the administrator's menu; then the sidebar beside the content. Below 1,000 pixels of window width the sidebar collapses to a rail of one glyph per group. What did not change is the part you may have scripted: the navigation map, every page title, tab header, setting caption and automation id (`nav-<key>`) are what they were.

The sidebar holds **65 pages in eight groups** in 6.3.4 (55 in 6.3.3), never more than two levels deep: Monitoring & troubleshooting, Accounts & domains, Mail flow & delivery, Spam & virus filtering, Connections & protocols, TLS & certificates, Access & abuse protection and Maintenance, with Welcome, Dashboard and About outside them. The ten pages new in 6.3.4 are Suppression list, Journaling and dual delivery, Audit trail, Discovery, Administrator roles, Remote domains, Allow and block list, Greylisting bypass list, Domain white and black list and Setting profiles.

**Search (Ctrl+K)** answers three questions in one ranked list: a page name or any alias; what you are trying to do, from 97 outcome phrases such as "stop spam"; and a setting name or key, from an index of 448 settings in 6.3.4 (393 in 6.3.3). It also resolves 54 old navigation paths, so `Settings > Security > Auto-ban & SSL/TLS` opens Auto-ban.

**Welcome.** Since 6.3.4 it offers a throwaway sample domain, `example.test`, and a first-run tour of seven stops that never acts and is never modal.

### Every page, by what it writes

The wiki lists each page with its navigation key, which never changes when a page is renamed. Grouped by the store behind them, the 65 are:

| What the page writes | Pages | Applies |
|---|---|---|
| Nothing: no settings behind the page (6) | Welcome, Dashboard, Live logs, Diagnostics, MX query, About | not applicable |
| Read-only, or actions only (12) | Server status, Delivery queue, Message trace, Audit trail, Discovery, External setup, DNS records, Server sendout, Spam filtering overview, Quarantine, Virus scanning overview, Transport encryption overview | Actions at once |
| The COM settings tree, a COM collection, or the database through COM (25) | Diagnosing stalled mail, Suppression list, Journaling and dual delivery, Domains, Public folders, Groups, Administrator roles, Routes, Remote domains, Incoming relays, Rules, Server messages, SURBL servers, DNS blacklists, White list, Blocked senders, Allow and block list, Greylisting white list, Greylisting bypass list, Domain white and black list, Blocked attachments, TCP/IP ports, SSL certificates, IP ranges, Setting profiles | At once; a profile's entries as each setting's own mark says |
| `[Settings]` keys, in the database since 6.3.4 (7) | API & monitoring, Web services & autoconfiguration, DNS resolver, Certificates (ACME), Transport security, Authentication, Server limits & expert settings | As each field's mark says |
| COM and `[Settings]` keys together (11) | Logging, Delivery of e-mail, Anti-spam settings, Anti-virus settings, Protocols, SSL/TLS, Administrative access, Auto-ban, Backup & restore, Performance, Advanced | COM at once, except the syslog card on Logging (since 6.3.4), whose values the sink takes when it starts, at a reinitialise or a service start; the keys as each field's mark says |
| A file on the server (4) | REST API keys (`hMailServerApiKeys.ini`, re-read on every request), Directory authentication (LDAP) and Directory synchronisation (`[LDAP]`, re-read within two seconds), Event scripts (the script file; **Save & reload** reloads the engine) | Without a restart |

What the table cannot say:

- **Three overview pages are deliberately read-only**: Spam filtering overview, Virus scanning overview and Transport encryption overview. They show what no single editor can: a virus scanner that is switched on but cannot run is treated as no virus found, so infected mail is delivered as though examined; a TLS port with no certificate fails to start rather than falling back to plaintext.
- **Discovery** (since 6.3.4) changes nothing and is the one page that reads the REST listener, because discovery has no COM interface. It needs `RestApiPort` set, a certificate it can check for an address beyond loopback, and an administrator without a second factor. A case is opened, searched, held and exported on the Control Deck ([eDiscovery and legal holds](/topic/28242)).
- **Journaling and dual delivery** and **Audit trail** are the server administrator's only.
- **Message trace** and **Quarantine** are inert unless `MessageTraceEnabled` and `QuarantineEnabled` are set, and **Blocked attachments** unless attachment blocking is on in Anti-virus settings.
- **Server limits & expert settings** also edits `[SendingLimits]` and `[SendingLimitsOverrides]`, which stay in the file and are re-read within seconds. **Performance** also edits the local `[Database]` rows, and since 6.3.4 has a **Message store** tab: `MessageStoreCompression`, off by default, and `MessageStoreDedupMinKB`, 256.
- **The dialogs.** Since 6.3.4 the domain dialog has fourteen tabs (seven in 6.3.3) and the account dialog fifteen (twelve), each ending in **Levels**.

### The mark under each field, and the pending bar

**Since 6.3.4.** On 6.3.3 a save of a page whose settings live in `hMailServer.INI` offers to restart the service. Against a 6.3.4 server a save publishes, and under every field kept in the settings store a small line says when the value takes effect ([which keys carry each mark, and what a reinitialise takes](/topic/28222)):

| The line | Meaning |
|---|---|
| **Applies on save** | In effect when the save returns |
| **After reinitialize** | A listener's port or bind address, a TLS context, a work queue's size: waits for **Apply now** |
| **After a restart** | `ServiceAccountName` and `ServiceAccountPassword`, which are retired. The `[Database]` rows on Performance carry the same words |

Every key's mark comes in one COM call when such a page is opened, `Settings.IniSettingAppliesAll`. A page's save writes only the fields whose value changed, because every write publishes, and it says how many of its keys still wait.

**The pending bar** sits at the foot of the window: "N saved setting(s) wait for a reinitialize", with **Apply now**. The list behind it is `Settings.PendingIniSettings`, recomputed by the server at every request, so a value put back before anything applied it is not pending.

**Apply now** is `Application.Reinitialize` over COM: every service stops and starts again in place, with no service restart and no UAC prompt.

1. It asks first. While the server is draining for maintenance the question says that the listeners open again and delivery resumes, because a reinitialise ends the drain.
2. It takes every `reinitialize` key and not a `restart` key.
3. When a `restart` key waits too, what it says afterwards is how many still wait for a service restart, not that the saved settings are in effect.
4. The Control Panel's COM session survives it. The Control Deck's session does not.

**Three things the pages will not do.**

- **Return a key to its default.** Clearing a box stores an empty value, which a number reads as `0`. The default comes back through `DELETE /api/v1/settings/ini/{name}`, `hmctl ini delete <name>` or COM `Settings.DeleteIniSetting(name)`.
- **Change a setting the environment names.** A setting set by `HM_SETTING_<key>` or `HM_PROPERTY_<name>` ([configuration from the environment](/topic/28231)) is shown disabled, with *Set by the environment* in place of the mark.
- **Claim more than an older server does.** Against a 6.3.3 server, which lacks `IniSettingAppliesAll` and `PendingIniSettings`, every field kept in the store is marked *After a restart*, a save says the service must be restarted, and no pending bar is shown.

**The Levels tab.** Since 6.3.4 the domain and account dialogs list [the twenty-seven settings a domain or an account may hold its own value of](/topic/28222), ticked where this level holds one, with "In effect: ..., from the ..." beside each. **Save levels now** writes what changed over COM at once, reads every line back, and shows the server's sentence when it refuses one. Against a server older than schema 6088 the tab says the server has no levels.

### The help pane

**Since 6.3.4.** Every page has a `?` button in the command bar, and `F1` does the same: a right-hand pane opens beside the page with what the operator documentation says about it, scrolled to the right heading. It has the document's headings as a list, a search box over the open document, and two links at the foot: *Open on the wiki* and *All documentation*.

**The text is built in.** It is the repository's `hmailserver/docs/*.md`, embedded in the Control Panel as resources (each named `Help.<Name>.md`, with `README.md` and `DeckParity.md` excluded). The Control Panel must work with no REST listener, so it carries its own copy and reads it over no route at all.

**What is thinner than it sounds.**

- A page whose subject has no document of its own (the TCP/IP ports, the certificates, the groups) opens the nearest one.
- The search is within the open document only, not across all of them.
- *Open on the wiki* is `HelpWikiBaseUrl` followed by the document's name. The wiki's pages are not named after the documents, so for most documents that link finds no page yet; the pane's own text is the complete one.

`HelpWikiBaseUrl` is a row of `hm_settings`, shipped as `https://gitlab.com/hmailserver/hmailserver/-/wikis/` and edited on the **Advanced** page under General. A value that is not empty and not an absolute `http://` or `https://` URL is refused, and empty hides the link. The Control Deck and the webmail have the same pane, served by the server from `GET /api/v1/help/{page}`.

### Administering a server on another machine

Type the server's name into the Server box and the Control Panel connects over DCOM. That covers everything the COM API can reach. What degrades is anything that means reading a file on the server:

| On a remote session | What you see |
|---|---|
| Live logs | "Log folder not found on this machine (live logs need a local server)." |
| REST API keys | The key store is a file beside `hMailServer.INI`; the page needs it |
| The "Listening" badge on TCP/IP ports | Every port reads "Unknown": the TCP table probed is this machine's |
| Certificate and private-key inspection | "cannot be checked from here" |
| Event scripts | The script is loaded from and saved to local disk |
| The `[LDAP]` and `[Database]` editors | Those sections are read from the file only |

**Editing the `[Settings]` pages from another machine is not confirmed for 6.3.4.** The wiki's Control Panel page says, in section 5.5 on remote administration, that such a page answers "hMailServer.INI was not found on this machine. These settings can only be edited on the server itself." Its 6.3.4 note in section 5.0 says that these keys are now read and written over COM, and that section 5.5 describes 6.3.3 and was not re-checked against the change. Test it on your own installation before relying on it; if a remote page refuses, use Remote Desktop or the REST API. Since 6.3.7 a Control Panel signed in to a server on another computer shows and saves the server's `hMailServer.ini` `[Settings]` values, and no longer reads or writes this computer's file for the `[Database]`, `[SendingLimits]` and `[LDAP]` values, which it cannot read from there.

### When the Control Panel itself is the problem

| Symptom | What it means | What to do |
|---|---|---|
| It does not reconnect after you stop the service | Deliberate: it rebuilds only a link that broke while the service was up, because activating the COM class would start a service you stopped on purpose | Start the service, then use any page |
| An unexpected-error dialog | An unhandled UI fault | See `%LOCALAPPDATA%\hMailServer\ControlPanel\control-panel-errors.log` |
| Signing in freezes the window | The host accepted TCP 135 and then stalled inside DCOM | Check DCOM permissions and the firewall on the server |

With a server-enforced second factor, a silent reconnect cannot produce a fresh code, so after a service restart you sign in again through the prompt.

### What it does not do, and where to read more

There is no Control Panel on Linux and no COM there; [the Control Deck](/topic/28192), [the REST API](/topic/28264) and [the `hmctl` client](/topic/28265) are the surfaces. The Control Panel never returns a key to its default, and it has no page for an account's kind (a person, a meeting room or equipment), encryption at rest, object storage or working an eDiscovery case: those are the Control Deck's and REST's. The public documentation's [chapter 20](https://www.progressiverobot.com/hmailserver-documentation/#20-every-control-panel-page) lists all 65 pages of 6.3.4 by group, and the wiki's Control Panel Pages is the source it follows.

- Connecting, the shell, the tour and the help pane: https://gitlab.com/hmailserver/hmailserver/-/wikis/The-Control-Panel
- Every page with its key and its store: https://gitlab.com/hmailserver/hmailserver/-/wikis/Control-Panel-Pages
- Every page, dialog and field with the setting behind it: https://gitlab.com/hmailserver/hmailserver/-/wikis/Control-Panel-Reference
- When a saved setting takes effect: https://gitlab.com/hmailserver/hmailserver/-/blob/v6.3.4/hmailserver/docs/SettingsApply.md
- The help pane: https://gitlab.com/hmailserver/hmailserver/-/blob/v6.3.4/hmailserver/docs/Help.md
- The public documentation: https://www.progressiverobot.com/hmailserver-documentation/#5-the-control-panel-your-first-look and https://www.progressiverobot.com/hmailserver-documentation/#20-every-control-panel-page