# Vexib Virtual Mailbox Implementation Notes

## Status

Virtual mailbox infrastructure has been implemented and tested successfully for the first Photosite mailbox.

Implementation branch:

```text
virtual-mailboxes
```

Project location:

```text
projects/vexib
```

## Purpose

The purpose of this work is to replace Linux system-user mailboxes with MySQL-backed virtual mailboxes so that Vexib can host mail for multiple services and subdomains, including:

```text
vexib.co.uk
photosite.vexib.co.uk
albumdb.vexib.co.uk
```

This allows application mail addresses such as:

```text
info@photosite.vexib.co.uk
admin@photosite.vexib.co.uk
noreply@photosite.vexib.co.uk
info@albumdb.vexib.co.uk
admin@albumdb.vexib.co.uk
noreply@albumdb.vexib.co.uk
```

without needing matching Linux user accounts.

## Architecture

```text
Inbound mail
    ↓
Postfix
    ↓
MySQL virtual domain / mailbox / alias lookup
    ↓
Dovecot LMTP
    ↓
/var/vmail
    ↓
IMAP client
```

```text
Outbound mail
    ↓
IMAP/SMTP client
    ↓
Postfix submission service
    ↓
SMTP2GO relay
    ↓
Internet recipient
```

## Database

Database:

```text
vexib_mail
```

Core tables:

```text
mail_domains
mail_users
mail_aliases
```

The database is used by both Postfix and Dovecot.

Postfix uses it for:

```text
virtual_mailbox_domains
virtual_mailbox_maps
virtual_alias_maps
```

Dovecot uses it for:

```text
SQL authentication
virtual user lookup
mailbox path lookup
```

## Virtual Mail Storage

Mail is stored under:

```text
/var/vmail
```

Virtual mail user/group:

```text
user:  vmail
uid:   5000
group: vmail
gid:   5000
```

Example mailbox path:

```text
/var/vmail/photosite.vexib.co.uk/noreply/Maildir
```

## Postfix Lookup Files

The following files were created in `/etc/postfix`:

```text
mysql-virtual-mailbox-domains.cf
mysql-virtual-mailbox-maps.cf
mysql-virtual-alias-maps.cf
```

Successful lookup tests included:

```bash
sudo postmap -q photosite.vexib.co.uk mysql:/etc/postfix/mysql-virtual-mailbox-domains.cf
sudo postmap -q noreply@photosite.vexib.co.uk mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf
sudo postmap -q info@photosite.vexib.co.uk mysql:/etc/postfix/mysql-virtual-alias-maps.cf
```

Expected examples:

```text
1
photosite.vexib.co.uk/noreply/
```

Blank alias result is acceptable when no alias exists.

## Postfix Settings Added

The following settings were added with `postconf -e`:

```text
virtual_mailbox_domains = mysql:/etc/postfix/mysql-virtual-mailbox-domains.cf
virtual_mailbox_maps = mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf
virtual_alias_maps = mysql:/etc/postfix/mysql-virtual-alias-maps.cf
virtual_mailbox_base = /var/vmail
virtual_uid_maps = static:5000
virtual_gid_maps = static:5000
virtual_transport = lmtp:unix:private/dovecot-lmtp
```

Existing SMTP2GO relay settings were preserved.

## Dovecot SQL Auth

The following file was created:

```text
/etc/dovecot/dovecot-sql-vmail.conf.ext
```

The SQL auth configuration returns:

```text
uid = 5000
gid = 5000
home = /var/vmail/<domain>/<local-part>
mail = maildir:/var/vmail/<domain>/<local-part>/Maildir
```

The following Dovecot components were enabled:

```text
SQL passdb
SQL userdb
LMTP service
```

PAM/passwd authentication was initially left in place to preserve current system-user mail behaviour during migration/testing.

## Dovecot LMTP

Postfix hands mail to Dovecot using:

```text
lmtp:unix:private/dovecot-lmtp
```

Dovecot saves mail into the virtual user's Maildir.

## LAN Mail Client Issue

Testing from inside the LAN using:

```text
mail.vexib.co.uk
```

initially failed because the DNS record resolved to the public WAN address. This appears to be a router NAT loopback / hairpin NAT issue.

Temporary workstation fix:

```text
192.168.0.39    mail.vexib.co.uk
```

in `/etc/hosts`.

This keeps the certificate hostname correct while routing traffic directly to the LAN server.

Longer-term recommendation: implement split DNS for internal clients.

## Thunderbird Settings Confirmed

Incoming IMAP:

```text
Server: mail.vexib.co.uk
Port: 993
Security: SSL/TLS
Authentication: Normal password
Username: noreply@photosite.vexib.co.uk
```

Outgoing SMTP:

```text
Server: mail.vexib.co.uk
Port: 587
Security: STARTTLS
Authentication: Normal password
Username: noreply@photosite.vexib.co.uk
```

## Current Limitations

The infrastructure is working, but manual SQL is still required for:

```text
adding domains
adding mailboxes
resetting mailbox passwords
adding aliases
disabling accounts
```

The next implementation phase is the Vexib Mail Admin UI.

## Phase 6 Pages

Planned PHP pages:

```text
vx_vm_login.php
vx_vm_logout.php
vx_vm_dashboard.php
vx_vm_domains.php
vx_vm_mailboxes.php
vx_vm_aliases.php
```

Common includes:

```text
inc/vx_vm_config.php
inc/vx_vm_db.php
inc/vx_vm_auth.php
inc/vx_vm_layout.php
```