GoAdmio

hostname

Change the server hostname and set up GoAdmio, mail, and SSL for it

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:

[!WARNING] The command rewrites /etc/hosts from 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