Heads-up for extension developers: the GUI’s main iframe is being removed
Starting with the upcoming major release, Checkmk’s GUI no longer renders page content inside an <iframe name="main"> next to the sidebar. Navigation, sidebar, and page content now live in one shared document. Most users won’t notice — but if you maintain MKPs, custom GUI pages, snapins, or anything that produces HTML or links inside Checkmk, please read on.
What changed
For many years the Checkmk GUI was built as a frame construct: the sidebar and main navigation lived in an outer document (index.py), and the actual page content was loaded into an iframe named main. That iframe is gone:
- Every page now renders the main navigation, sidebar, and its content in a single document (via the regular page header rendering).
index.py?start_url=Xnow answers with an HTTP redirect straight toXinstead of rendering a frameset around it. Old bookmarks keep working.- The address bar now always shows the real page URL — no more percent-encoded
index.py?start_url=...wrapper. Pages are properly deep-linkable and reload-safe. - External apps that can’t render Checkmk chrome themselves (e.g. NagVis) are embedded through a small wrapper page instead.
Why you might care as an extension author
1. Unbalanced HTML now has visible consequences
This is the big one. Previously, the iframe acted as a containment wall: if a page produced broken markup — an unclosed <div>, an unbalanced <table> — the damage stayed inside the frame. The page might have looked slightly off, but navigation and sidebar were untouched.
That containment is gone. Broken markup on a page can now visually break the whole document: the sidebar may get swallowed, the navigation may shift or disappear, layout may collapse. If your extension renders HTML (custom pages, painters, dashlets, snapin content), please check that your open/close calls are balanced — including early-return and error paths between an open_* and its close_*.
If a page suddenly looks broken after upgrading: suspect the page’s markup first, not the theme.
2. target="main" is dead
Links that target the main frame no longer have a frame to land in — the browser opens a blank new window named “main” instead. If your extension generates links with target="main":
- For normal links, drop the target entirely (default
_selfis correct now). - From inside widget/dashlet iframes that should navigate the surrounding page, use
target="_top".
The shipped code has been swept, but MKPs, bookmark entries with hardcoded targets, and external integrations may still carry it.
3. Custom pages that bypass the standard header
The chrome (navigation + sidebar) is rendered per page through the standard page header. If a custom page builds its own <body> instead of going through the regular header rendering, it will come up without navigation and sidebar. Intentionally bare pages (login-style) are still possible — it’s just an explicit choice now, not an accident of the frameset.
The common page types are covered by the GUI end-to-end tests, but rarely-visited or custom pages may have been missed. If you find a shipped page without nav/sidebar after the upgrade, that’s a bug — please report it.
4. URL matching in scripts and tests
If you have automation, tests, or scripts that match Checkmk URLs: the browser URL is now the plain page URL (e.g. dashboard.py?name=main) instead of the encoded index.py?start_url=dashboard.py%3Fname%3Dmain form. Match the plain URL.
What stays the same
- Bookmarks of the form
index.py?start_url=...keep working (transparent redirect). - Kiosk mode (
?kiosk=...) is preserved. - Dashboards still embed their widgets via (unnamed) iframes — only the outer main frame is gone.
Happy to answer questions in this thread — and if you hit a page with missing chrome or a layout broken by leftover markup, a screenshot plus the page URL helps a lot.