hostname
Change the server hostname and set up GoAdmio, mail, and SSL for it
- Command:
/go/hostname - Category: Server
- Required option: None (asks for the hostname if you do not pass one)
- Output: Messages about the change, or an error
- Last updated: 2026-11-20
On this page: Overview · Quick start · Syntax · Arguments · Output · Examples · Troubleshooting · Details · See also
Overview
/go/hostname changes the server's hostname, such as server.example.com, and updates everything in GoAdmio that depends on it. It:
- checks that the name looks like a real hostname and that its DNS points to this server
- sets the name in
/etc/hostname,/etc/hosts, and GoAdmio's configuration - sets the IMAP server name used by mail apps
- writes the SMTP settings GoAdmio uses to send its own mail
- installs the mail certificates if the new name has no certificate yet
[!WARNING] The command rewrites
/etc/hostsfrom scratch. Any entries you added there, and the IPv6 entries, are lost. See Details.
Quick start
# Change the hostname (run as root)
/go/hostname server.example.com
Create the DNS record first. The name must already point to this server's IPv4 address.
Syntax
/go/hostname [hostname]
/go/hostname restore
The command has no -- options. Run it as root.
Arguments
| Argument | Effect |
|---|---|
<hostname> |
Changes the hostname to this name. |
restore |
Changes the hostname to the name stored in /etc/hostname.bak. |
| (none) | Asks for the hostname, with the current one filled in for you to edit. |
The hostname must contain at least two dots, for example server.example.com. A name such as example.com is rejected.
The command does not create /etc/hostname.bak. restore works only when that file already exists.
Output
| Message | Meaning |
|---|---|
Invalid Server Hostname, A hostname should consist of a name and a domain name. All valid hostnames should have 2 dots in them. |
The name has fewer than two dots. Exit status 1. |
Failed to change server hostname. Hostname <name> Not Resolving To <ip> |
The name's DNS does not point to this server's IPv4 address. Nothing is changed. Exit status 1. |
Hostname changed to <name> |
The hostname, /etc/hosts, and the configuration were updated. The remaining steps follow. |
Examples
# Change the hostname
/go/hostname server.example.com
# Use a name that starts with smtp. so that an imap. name is set up too
/go/hostname smtp.example.com
# Check that the name points to this server before you run the command
dig +short server.example.com
# Review the log of past runs
tail -n 20 /var/log/go/hostname.log
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
Invalid Server Hostname... |
The name has fewer than two dots. | Use a name with a host part and a domain, such as server.example.com. |
Not Resolving To <ip> |
The A record is missing, wrong, or not yet visible. | Create an A record for the name that points to the IP shown. See dns. Wait, then check with dig +short <name>. |
Not Resolving To <ip> although the record exists |
The name is proxied through Cloudflare, so it returns Cloudflare's address. | Turn the proxy off for this record. See proxy. |
restore fails |
/etc/hostname.bak does not exist. |
Pass the hostname you want instead. |
Your own lines in /etc/hosts are gone |
The command writes the file from scratch. | Add them again after the command finishes. |
| The command waits for input | No hostname was passed, so it asks for one. | Pass the hostname as an argument, especially in scripts. |
| The shell prompt still shows the old name | The running shell has not picked up the change. | Open a new session. |
| The mail certificate step fails | The hostname's DNS does not resolve yet, or a firewall blocks the check. | Run mailssl again once DNS and the firewall are correct. |
| Mail apps use the wrong IMAP server | /etc/imap is set according to the name's prefix and DNS. See IMAP name. |
Check /etc/imap, then run autodiscover to refresh the mail app settings. |
Details
What it does, in order
| # | Step |
|---|---|
| 1 | Ask for the hostname if none was passed. For restore, read it from /etc/hostname.bak. |
| 2 | Reject names with fewer than two dots. |
| 3 | Look up the name's A record with dig. If the last address is not this server's public IPv4 address, stop. |
| 4 | Write the name to /etc/hostname and apply it to the running system. |
| 5 | Set or remove /etc/imap (see below). |
| 6 | Rewrite /etc/hosts. |
| 7 | Save the name in GoAdmio's configuration database, when GoAdmio is installed. |
| 8 | Print Hostname changed to <name>. |
| 9 | Write smtp.php with GoAdmio's SMTP settings. |
| 10 | If there is no certificate for the name in /etc/letsencrypt/live/, run mailssl, /go/postconf, and doveconf. |
| 11 | Run /go/welcome. |
Only the IPv4 address is checked. The IPv6 address plays no part in the check.
IMAP name
| Hostname | Result for /etc/imap |
|---|---|
Starts with smtp., and the matching imap. name points to this server |
Contains the imap. name, for example imap.example.com. |
Starts with smtp., and the imap. name does not point here |
Contains the hostname itself. |
| Anything else | The file is deleted. |
The mail app settings written by autodiscover read this file.
/etc/hosts
The file is replaced with exactly three entries:
# GoAdmio Setup
127.0.0.1 localhost.localdomain localhost
<server IPv4> <hostname> <first part of the hostname>
GoAdmio's SMTP settings
/usr/local/goadmio/include/config/smtp.php is rewritten on every run.
| Setting | Value |
|---|---|
SMTPHost |
The new hostname. |
SMTPUser |
goadmio@<hostname without its first part>, for example goadmio@example.com. |
SMTPPass |
A new value on every run, made from the server's MAC address and the time. Stored in plain text in the file. |
SMTPPort |
587 |
The command only writes this file. It does not create the mail account.
Requirements
| Tool | Used for |
|---|---|
dig |
The DNS check. |
curl |
Finding the server's public IP addresses. |
ifconfig |
Reading the MAC address for the SMTP password. |
Logging
Every run appends its arguments with a timestamp to /var/log/go/hostname.log.
What a run does
flowchart TD
A["hostname [name|restore]"] --> B{"At least 2 dots?"}
B -- "No" --> X1["Invalid hostname, exit 1"]
B -- "Yes" --> C{"DNS points to this server's IPv4?"}
C -- "No" --> X2["Not resolving, exit 1"]
C -- "Yes" --> D["Set /etc/hostname, /etc/imap, /etc/hosts"]
D --> E["Save in GoAdmio configuration, print: changed"]
E --> F["Write smtp.php"]
F --> G{"Certificate for the name exists?"}
G -- "No" --> H["mailssl, postconf, doveconf"]
G -- "Yes" --> I
H --> I["Run welcome"]
See also
| Command | Description |
|---|---|
mailssl |
Install SSL certificates for SMTP and IMAP |
doveconf |
Rebuild the Dovecot configuration |
autodiscover |
Write the Outlook Autodiscover file for every hosted domain |
reversedns |
Check reverse DNS (rDNS) in GoAdmio |
dns |
Add your domain to Cloudflare and edit the DNS zone |
proxy |
Change Cloudflare's proxy setting |
nameservers |
Change the nameservers for a GoAdmio server |