When your Exim4 mail server attempts to deliver email, remote SMTP servers may reject connections with errors like:

504 5.5.2 <localhost>: Helo command rejected: need fully-qualified hostname

This occurs because your server is presenting an invalid HELO identifier (typically "localhost") instead of a proper fully-qualified domain name (FQDN).

Debian's Exim4 configuration follows this resolution order for primary_hostname:

1. First checks explicit configuration in Exim4 files
2. Falls back to system's uname() call
3. If uname returns unqualified name, attempts DNS resolution
4. Finally defaults to localhost if all else fails

The most maintainable solutions in order of preference:

Method 1: System-Wide Hostname Configuration

First ensure your system hostname is properly configured:

# Set hostname (replace with your FQDN)
sudo hostnamectl set-hostname mail.example.com

# Verify
hostname -f

Edit /etc/hosts to include:

127.0.0.1   mail.example.com mail localhost
::1     localhost ip6-localhost ip6-loopback

Method 2: Exim4 Configuration File

For Debian's split configuration:

# Edit or create /etc/exim4/conf.d/main/02_exim4-config_options
primary_hostname = mail.example.com

# Update configuration and restart
sudo update-exim4.conf
sudo systemctl restart exim4

Method 3: Using /etc/mailname (Debian-specific)

# Set your FQDN in mailname
echo "mail.example.com" | sudo tee /etc/mailname

# Reconfigure exim4
sudo dpkg-reconfigure exim4-config

Test your HELO response:

telnet localhost 25
EHLO example.com

You should see your configured hostname in the response headers.

• DNS resolution failures: Ensure your FQDN resolves both forward and reverse
• Split configuration problems: Run sudo exim4 -bP primary_hostname to check effective value
• Debian package quirks: After changes, always run sudo update-exim4.conf and restart the service

For complex environments, you can use macros in 02_exim4-config_options:

# Use system hostname but ensure FQDN
primary_hostname = ${if def:primary_hostname {$primary_hostname}\
                   {${lookup dnsdb{>: ptr=$interface_address}\
                   {${lc:$value}}{$primary_hostname}}}}

---

When your Debian mail server encounters SMTP rejection with error 504 5.5.2 <localhost>: Helo command rejected: need fully-qualified hostname, this indicates a fundamental configuration issue in Exim4's identity presentation.

Exim4's HELO/EHLO behavior follows this resolution chain:

1. Explicit primary_hostname in config
2. System hostname (from uname())
3. DNS resolution (via gethostbyname())
4. Fallback to localhost.localdomain

For package-maintained Exim4 installations, modify the primary hostname through:

# Method 1: Update /etc/exim4/update-exim4.conf.conf
dc_other_hostnames='yourdomain.com'
dc_readhost='yourdomain.com'

# Method 2: Set in split config (recommended)
echo "primary_hostname = mail.yourdomain.com" > /etc/exim4/conf.d/main/00_local-macros

After configuration changes:

# Reload configuration
service exim4 reload

# Test HELO presentation
telnet localhost 25
EHLO test

Expected output should show your FQDN in the greeting banner.

For systems where hostnames may change, implement dynamic resolution:

# In /etc/exim4/exim4.conf.template
primary_hostname = ${lookup dnsdb{>: ptr=$primary_ip}}

# With fallback
primary_hostname = ${if exists{/etc/mailname}\
                   {${readfile{/etc/mailname}{$value}fail}}\
                   {${perl{getfqdn}}}}

When issues persist:

1. Verify /etc/hosts contains proper FQDN:

   127.0.1.1 mail.yourdomain.com mail

2. Check reverse DNS matches:

   host $(hostname -i)

3. Validate Exim runtime config:

   exim4 -bP primary_hostname