Add inbuxa rename to change the server's and front ends' names #81

Closed
opened 2026-11-18 15:20:13 +00:00 by jcoffey-dev · 1 comment
Owner

A server that started as a sandbox and became production often needs a new name, sometimes on a different domain from the one it was installed with. There's no single command for that today. It takes an install re-run, two console pages and a manual DNS pass, and two of the installer's own commands don't help. This came up on the forum in t/324.

What it takes today

  1. Re-run install with every option from the first install plus the new --mail-host, --console-host and --webmail-host. The re-run doesn't use the recorded shapes or --proxy, so leaving one out changes the install (a missing --server host starts a move).
  2. In the console, order a certificate for the new mail host (Settings → Security → Certificates).
  3. In the console, change the server's hostname (x:SystemSettings.defaultHostname) and its default certificate (Settings → Network → General). The installer sets the hostname only at bootstrap.
  4. Update MX, SPF, autoconfig and PTR by hand.

Where the current commands fall short

  • certs can't cover a name on another domain. It only retries the order for the install's st.Domain. The server adds its own hostname to a domain's certificate only when the hostname is inside that domain's zone (crates/common/src/network/acme/order.rs, build_domains). With a new mail host on another domain, certs waits three minutes and fails.
  • dns without --refresh prints old names. It reads the dns.zone written at first install, and a re-run doesn't rewrite that file.
  • The old console and webmail names stop working at once. After the re-run, Caddy serves only the new names. There's no grace period, and nothing tells you this before it happens.

Proposal: inbuxa rename

sudo inbuxa rename --mail-host NAME [--console-host NAME] [--webmail-host NAME] --key - [--dry-run] [--yes]
  • Starts from the install record and changes only the names. Shapes, proxy, dir and domain stay as they are.
  • Checks first that each new name resolves to this machine, and refuses if one doesn't.
  • Converges the proxy, the compose file or host units, and the front ends, as a re-run of install does now.
  • Through the API key:
    • sets defaultHostname;
    • gets the new mail host a certificate: on the domain that covers it, or a certificate-only domain like the console's Order a certificate adds;
    • waits until the mail ports present that certificate, then makes it the default.
  • Rewrites dns.zone and prints the records that changed, including PTR as a reminder.
  • Optionally (--keep-old) keeps the old names on the proxy as redirects for a while, so clients can be moved over.
  • Records the new names in the install state, so status, certs and doctor use them.

--dry-run should show each of these steps, like install --dry-run.

Split out

The smaller fixes are their own issues, so they can land before rename: #82 (certs on another domain), #83 (dns.zone after a name change) and #84 (install reusing the recorded options). rename builds on them.

An e2e case (e2e/cases/) should rename a private-CA install to a name on a second domain, and check that the mail ports and the console sign-in both work afterwards.

A server that started as a sandbox and became production often needs a new name, sometimes on a different domain from the one it was installed with. There's no single command for that today. It takes an `install` re-run, two console pages and a manual DNS pass, and two of the installer's own commands don't help. This came up on the forum in t/324. ## What it takes today 1. Re-run `install` with every option from the first install plus the new `--mail-host`, `--console-host` and `--webmail-host`. The re-run doesn't use the recorded shapes or `--proxy`, so leaving one out changes the install (a missing `--server host` starts a move). 2. In the console, order a certificate for the new mail host (Settings → Security → Certificates). 3. In the console, change the server's hostname (`x:SystemSettings.defaultHostname`) and its default certificate (Settings → Network → General). The installer sets the hostname only at bootstrap. 4. Update MX, SPF, autoconfig and PTR by hand. ## Where the current commands fall short - **`certs` can't cover a name on another domain.** It only retries the order for the install's `st.Domain`. The server adds its own hostname to a domain's certificate only when the hostname is inside that domain's zone (`crates/common/src/network/acme/order.rs`, `build_domains`). With a new mail host on another domain, `certs` waits three minutes and fails. - **`dns` without `--refresh` prints old names.** It reads the `dns.zone` written at first install, and a re-run doesn't rewrite that file. - **The old console and webmail names stop working at once.** After the re-run, Caddy serves only the new names. There's no grace period, and nothing tells you this before it happens. ## Proposal: `inbuxa rename` ``` sudo inbuxa rename --mail-host NAME [--console-host NAME] [--webmail-host NAME] --key - [--dry-run] [--yes] ``` - Starts from the install record and changes only the names. Shapes, proxy, dir and domain stay as they are. - Checks first that each new name resolves to this machine, and refuses if one doesn't. - Converges the proxy, the compose file or host units, and the front ends, as a re-run of `install` does now. - Through the API key: - sets `defaultHostname`; - gets the new mail host a certificate: on the domain that covers it, or a certificate-only domain like the console's Order a certificate adds; - waits until the mail ports present that certificate, then makes it the default. - Rewrites `dns.zone` and prints the records that changed, including PTR as a reminder. - Optionally (`--keep-old`) keeps the old names on the proxy as redirects for a while, so clients can be moved over. - Records the new names in the install state, so `status`, `certs` and `doctor` use them. `--dry-run` should show each of these steps, like `install --dry-run`. ## Split out The smaller fixes are their own issues, so they can land before `rename`: #82 (`certs` on another domain), #83 (`dns.zone` after a name change) and #84 (`install` reusing the recorded options). `rename` builds on them. An e2e case (`e2e/cases/`) should rename a private-CA install to a name on a second domain, and check that the mail ports and the console sign-in both work afterwards.
jcoffey-dev added this to the 27.7 milestone 2026-11-18 15:20:13 +00:00
jcoffey-dev added the enhancement label 2026-11-18 15:20:13 +00:00
jcoffey-dev modified the milestone from 27.7 to 27.1 2026-11-18 15:28:00 +00:00
jcoffey-dev self-assigned this 2026-11-18 15:40:59 +00:00
jcoffey-dev added the
priority
p3
label 2026-11-18 15:56:34 +00:00
Author
Owner

The gaps listed here are fixed and shipped in installer v27.1-rc.16:

  • #84 (#85): install run again keeps every option it isn't given, so a rename only needs the new names.
  • #83 (#86): dns says when the saved records don't name this install's mail host.
  • #82 (#87): certs orders on the domain that covers the mail host, including one on another domain.
  • #88 adds the lab case for a rename to names on another domain.

The steps are on https://docs.inbuxa.org/install/installer/#rename. A separate inbuxa rename command would only wrap those steps, so I'm closing this. Reopen it if a single command still turns out to be worth having.

The gaps listed here are fixed and shipped in installer v27.1-rc.16: - #84 (#85): `install` run again keeps every option it isn't given, so a rename only needs the new names. - #83 (#86): `dns` says when the saved records don't name this install's mail host. - #82 (#87): `certs` orders on the domain that covers the mail host, including one on another domain. - #88 adds the lab case for a rename to names on another domain. The steps are on https://docs.inbuxa.org/install/installer/#rename. A separate `inbuxa rename` command would only wrap those steps, so I'm closing this. Reopen it if a single command still turns out to be worth having.
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: inbuxa/inbuxa-installer#81