@smbcloud / smbcloud-mail-imap
Code Commits Issues Pulls Cloud Agent CI/CD
copilot/add-pop3-protocol-examples
copilot/add-pop3-protocol-examples copilot/add-pop3-protocol-implementation copilot/implement-mail-handling-separation development main
md 676 lines 12.5 KB
Rendered Raw
1 # Mail Server Configuration Examples
2
3 This document provides example configurations for the mail server, including SMTP, POP3, and IMAP settings.
4
5 ## Table of Contents
6
7 1. [Basic Configuration](#basic-configuration)
8 2. [POP3 Server Configuration](#pop3-server-configuration)
9 3. [SMTP Server Configuration](#smtp-server-configuration)
10 4. [Integrated Mail Server Configuration](#integrated-mail-server-configuration)
11 5. [Security Configuration](#security-configuration)
12 6. [Production Configuration](#production-configuration)
13
14 ## Basic Configuration
15
16 ### Simple POP3 Server (Development)
17
18 ```toml
19 # pop3-dev.toml
20 [server]
21 host = "127.0.0.1"
22 port = 110
23 timeout = 600 # 10 minutes
24
25 [authentication]
26 # Simple file-based authentication for development
27 backend = "file"
28 users_file = "users.txt"
29
30 [storage]
31 # Maildir storage backend
32 backend = "maildir"
33 maildir_path = "./mailboxes"
34 ```
35
36 **users.txt** format:
37 ```
38 testuser:testpass
39 alice:password123
40 bob:secret
41 ```
42
43 ### Simple SMTP Server (Development)
44
45 ```toml
46 # smtp-dev.toml
47 [server]
48 host = "127.0.0.1"
49 port = 2525
50 timeout = 300
51
52 [storage]
53 backend = "maildir"
54 maildir_path = "./mailboxes"
55
56 [tls]
57 enabled = false
58 ```
59
60 ## POP3 Server Configuration
61
62 ### Minimal POP3 Configuration
63
64 ```toml
65 [server]
66 host = "0.0.0.0"
67 port = 110
68
69 [authentication]
70 backend = "file"
71 users_file = "/etc/pop3/users.txt"
72
73 [storage]
74 backend = "maildir"
75 maildir_path = "/var/mail"
76 ```
77
78 ### POP3 with TLS/SSL (POP3S)
79
80 ```toml
81 [server]
82 host = "0.0.0.0"
83 port = 995 # POP3S standard port
84 timeout = 600
85
86 [tls]
87 enabled = true
88 cert_path = "/etc/ssl/certs/mail.crt"
89 key_path = "/etc/ssl/private/mail.key"
90 min_tls_version = "1.2"
91
92 [authentication]
93 backend = "database"
94 db_url = "postgresql://popuser:password@localhost/maildb"
95
96 [storage]
97 backend = "maildir"
98 maildir_path = "/var/mail"
99
100 [limits]
101 max_message_size = 52428800 # 50MB
102 max_connections = 500
103 max_messages_per_session = 1000
104
105 [logging]
106 level = "info"
107 file = "/var/log/pop3/server.log"
108 ```
109
110 ### POP3 with Database Authentication
111
112 ```toml
113 [server]
114 host = "0.0.0.0"
115 port = 110
116
117 [authentication]
118 backend = "database"
119 db_type = "postgresql"
120 db_url = "postgresql://user:password@localhost:5432/maildb"
121 # SQL query to authenticate user
122 auth_query = "SELECT password_hash FROM users WHERE email = $1 AND active = true"
123 # Password hashing algorithm
124 password_hash = "bcrypt"
125
126 [storage]
127 backend = "database"
128 db_url = "postgresql://user:password@localhost:5432/maildb"
129 ```
130
131 ### POP3 with LDAP Authentication
132
133 ```toml
134 [server]
135 host = "0.0.0.0"
136 port = 110
137
138 [authentication]
139 backend = "ldap"
140 ldap_url = "ldap://ldap.example.com:389"
141 ldap_base_dn = "ou=users,dc=example,dc=com"
142 ldap_bind_dn = "cn=admin,dc=example,dc=com"
143 ldap_bind_password = "admin_password"
144 ldap_user_filter = "(&(objectClass=person)(mail=%u))"
145
146 [storage]
147 backend = "maildir"
148 maildir_path = "/var/mail"
149 ```
150
151 ## SMTP Server Configuration
152
153 ### Basic SMTP Configuration
154
155 ```toml
156 [server]
157 host = "0.0.0.0"
158 port = 25
159 timeout = 300
160
161 [relay]
162 # Allow relay from local network
163 allowed_networks = ["127.0.0.0/8", "192.168.0.0/16"]
164
165 [storage]
166 backend = "maildir"
167 maildir_path = "/var/mail"
168
169 [limits]
170 max_message_size = 10485760 # 10MB
171 max_recipients = 100
172 ```
173
174 ### SMTP with Authentication and TLS
175
176 ```toml
177 [server]
178 host = "0.0.0.0"
179 port = 587 # Submission port
180 timeout = 300
181
182 [tls]
183 enabled = true
184 starttls = true # Allow STARTTLS
185 cert_path = "/etc/ssl/certs/mail.crt"
186 key_path = "/etc/ssl/private/mail.key"
187
188 [authentication]
189 required = true # Require authentication for sending
190 backend = "database"
191 db_url = "postgresql://user:password@localhost/maildb"
192
193 [storage]
194 backend = "maildir"
195 maildir_path = "/var/mail"
196 ```
197
198 ## Integrated Mail Server Configuration
199
200 ### Complete Mail Server (SMTP + POP3 + IMAP)
201
202 ```toml
203 # mail-server.toml
204
205 [global]
206 hostname = "mail.example.com"
207 domain = "example.com"
208
209 # Shared authentication backend
210 [authentication]
211 backend = "database"
212 db_url = "postgresql://mailuser:password@localhost:5432/maildb"
213 password_hash = "argon2"
214
215 # Shared storage backend
216 [storage]
217 backend = "maildir"
218 maildir_path = "/var/mail"
219 # Alternative: use database storage
220 # backend = "database"
221 # db_url = "postgresql://mailuser:password@localhost:5432/maildb"
222
223 # SMTP Server Configuration
224 [smtp]
225 enabled = true
226 host = "0.0.0.0"
227 port = 25
228 submission_port = 587
229 timeout = 300
230
231 [smtp.tls]
232 enabled = true
233 starttls = true
234 cert_path = "/etc/ssl/certs/mail.crt"
235 key_path = "/etc/ssl/private/mail.key"
236
237 [smtp.limits]
238 max_message_size = 52428800 # 50MB
239 max_recipients = 100
240 max_connections = 1000
241
242 # POP3 Server Configuration
243 [pop3]
244 enabled = true
245 host = "0.0.0.0"
246 port = 110
247 timeout = 600
248
249 [pop3.tls]
250 enabled = true
251 port = 995 # POP3S port
252 cert_path = "/etc/ssl/certs/mail.crt"
253 key_path = "/etc/ssl/private/mail.key"
254
255 [pop3.limits]
256 max_message_size = 52428800
257 max_connections = 500
258 max_messages_per_session = 1000
259
260 # IMAP Server Configuration
261 [imap]
262 enabled = true
263 host = "0.0.0.0"
264 port = 143
265 timeout = 1800 # 30 minutes
266
267 [imap.tls]
268 enabled = true
269 starttls = true
270 port = 993 # IMAPS port
271 cert_path = "/etc/ssl/certs/mail.crt"
272 key_path = "/etc/ssl/private/mail.key"
273
274 [imap.limits]
275 max_message_size = 52428800
276 max_connections = 1000
277
278 # Logging Configuration
279 [logging]
280 level = "info"
281 format = "json"
282 smtp_log = "/var/log/mail/smtp.log"
283 pop3_log = "/var/log/mail/pop3.log"
284 imap_log = "/var/log/mail/imap.log"
285 max_size = "100MB"
286 max_age = 30 # days
287 compress = true
288 ```
289
290 ## Security Configuration
291
292 ### Security Best Practices Configuration
293
294 ```toml
295 [security]
296 # Rate limiting
297 [security.rate_limit]
298 enabled = true
299 max_connections_per_ip = 10
300 max_auth_attempts = 3
301 auth_failure_delay = 5 # seconds
302 ban_duration = 3600 # 1 hour
303
304 # IP whitelist/blacklist
305 [security.access_control]
306 whitelist = ["192.168.1.0/24", "10.0.0.0/8"]
307 blacklist = ["203.0.113.0/24"]
308
309 # Password policies
310 [security.passwords]
311 min_length = 12
312 require_uppercase = true
313 require_lowercase = true
314 require_digit = true
315 require_special = true
316 hash_algorithm = "argon2"
317 hash_iterations = 3
318
319 # TLS settings
320 [security.tls]
321 min_version = "1.2"
322 cipher_suites = [
323 "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384",
324 "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
325 ]
326 prefer_server_ciphers = true
327
328 # Session security
329 [security.sessions]
330 timeout = 600
331 max_idle_time = 300
332 require_encryption = true
333 ```
334
335 ## Production Configuration
336
337 ### High-Performance Production Setup
338
339 ```toml
340 # production.toml
341
342 [global]
343 hostname = "mail.example.com"
344 domain = "example.com"
345 environment = "production"
346
347 # Performance settings
348 [performance]
349 worker_threads = 16
350 max_blocking_threads = 512
351 async_io_threads = 8
352
353 # Connection pooling
354 [database]
355 url = "postgresql://mailuser:password@db-cluster.example.com:5432/maildb"
356 max_connections = 100
357 min_connections = 10
358 connection_timeout = 5
359 idle_timeout = 600
360
361 # Redis cache for sessions and rate limiting
362 [cache]
363 backend = "redis"
364 url = "redis://cache-cluster.example.com:6379"
365 ttl = 3600
366 max_connections = 50
367
368 # SMTP Configuration
369 [smtp]
370 enabled = true
371 host = "0.0.0.0"
372 port = 25
373 submission_port = 587
374 timeout = 300
375
376 [smtp.tls]
377 enabled = true
378 starttls = true
379 cert_path = "/etc/ssl/certs/mail.crt"
380 key_path = "/etc/ssl/private/mail.key"
381 min_version = "1.2"
382
383 [smtp.limits]
384 max_message_size = 52428800
385 max_recipients = 100
386 max_connections = 2000
387 rate_limit_per_sender = 100 # messages per hour
388
389 [smtp.queue]
390 backend = "database"
391 retry_attempts = 5
392 retry_delay = 300 # 5 minutes
393 max_age = 432000 # 5 days
394
395 # POP3 Configuration
396 [pop3]
397 enabled = true
398 host = "0.0.0.0"
399 port = 110
400 timeout = 600
401
402 [pop3.tls]
403 enabled = true
404 port = 995
405 cert_path = "/etc/ssl/certs/mail.crt"
406 key_path = "/etc/ssl/private/mail.key"
407
408 [pop3.limits]
409 max_connections = 1000
410 max_messages_per_session = 1000
411 rate_limit_per_ip = 50 # connections per hour
412
413 # Authentication
414 [authentication]
415 backend = "database"
416 db_url = "postgresql://mailuser:password@db-cluster.example.com:5432/maildb"
417 password_hash = "argon2"
418 cache_ttl = 3600
419 mfa_enabled = true
420
421 # Storage
422 [storage]
423 backend = "s3"
424 s3_bucket = "mail-storage"
425 s3_region = "us-east-1"
426 s3_endpoint = "https://s3.amazonaws.com"
427 # Or use Maildir
428 # backend = "maildir"
429 # maildir_path = "/mnt/mail-storage"
430
431 # Monitoring and Metrics
432 [monitoring]
433 enabled = true
434 prometheus_port = 9090
435 health_check_port = 8080
436
437 [monitoring.metrics]
438 collect_interval = 60 # seconds
439 retention_days = 30
440
441 # Logging
442 [logging]
443 level = "info"
444 format = "json"
445 output = "syslog"
446 syslog_address = "localhost:514"
447 syslog_facility = "mail"
448
449 # Backup
450 [backup]
451 enabled = true
452 schedule = "0 2 * * *" # Daily at 2 AM
453 destination = "s3://backups/mail"
454 retention_days = 90
455 ```
456
457 ### Multi-Node Cluster Configuration
458
459 ```toml
460 # cluster-node.toml
461
462 [cluster]
463 enabled = true
464 node_id = "node-1"
465 nodes = [
466 "node-1.example.com:7000",
467 "node-2.example.com:7000",
468 "node-3.example.com:7000",
469 ]
470
471 [cluster.consensus]
472 algorithm = "raft"
473 election_timeout = 1000
474 heartbeat_interval = 100
475
476 [cluster.replication]
477 factor = 3
478 sync_mode = "async"
479
480 # Shared distributed storage
481 [storage]
482 backend = "distributed"
483 cluster_nodes = [
484 "storage-1.example.com:9000",
485 "storage-2.example.com:9000",
486 "storage-3.example.com:9000",
487 ]
488
489 # Load balancer configuration
490 [load_balancer]
491 algorithm = "round_robin"
492 health_check_interval = 5
493 health_check_timeout = 2
494 ```
495
496 ## Environment-Specific Configurations
497
498 ### Development
499
500 ```toml
501 [global]
502 environment = "development"
503 debug = true
504
505 [server]
506 host = "127.0.0.1"
507
508 [logging]
509 level = "debug"
510 output = "stdout"
511
512 [tls]
513 enabled = false # Use plain text for easier debugging
514 ```
515
516 ### Staging
517
518 ```toml
519 [global]
520 environment = "staging"
521 debug = false
522
523 [server]
524 host = "0.0.0.0"
525
526 [logging]
527 level = "info"
528 output = "file"
529
530 [tls]
531 enabled = true
532 # Use staging certificates
533 cert_path = "/etc/ssl/staging/cert.pem"
534 key_path = "/etc/ssl/staging/key.pem"
535 ```
536
537 ### Production
538
539 ```toml
540 [global]
541 environment = "production"
542 debug = false
543
544 [server]
545 host = "0.0.0.0"
546
547 [logging]
548 level = "warn"
549 output = "syslog"
550
551 [tls]
552 enabled = true
553 cert_path = "/etc/ssl/certs/production.crt"
554 key_path = "/etc/ssl/private/production.key"
555
556 [security]
557 strict_mode = true
558 require_tls = true
559 ```
560
561 ## Docker Configuration
562
563 ### Docker Compose Example
564
565 ```yaml
566 # docker-compose.yml
567 version: '3.8'
568
569 services:
570 mail-server:
571 image: smbcloud-mail:latest
572 container_name: mail-server
573 ports:
574 - "25:25" # SMTP
575 - "587:587" # SMTP Submission
576 - "110:110" # POP3
577 - "995:995" # POP3S
578 - "143:143" # IMAP
579 - "993:993" # IMAPS
580 volumes:
581 - ./config:/etc/mail:ro
582 - ./mail-data:/var/mail
583 - ./logs:/var/log/mail
584 - ./certs:/etc/ssl/mail:ro
585 environment:
586 - RUST_LOG=info
587 - CONFIG_FILE=/etc/mail/production.toml
588 depends_on:
589 - postgres
590 - redis
591 restart: unless-stopped
592
593 postgres:
594 image: postgres:15
595 container_name: mail-db
596 volumes:
597 - postgres-data:/var/lib/postgresql/data
598 environment:
599 - POSTGRES_DB=maildb
600 - POSTGRES_USER=mailuser
601 - POSTGRES_PASSWORD=securepassword
602 restart: unless-stopped
603
604 redis:
605 image: redis:7
606 container_name: mail-cache
607 volumes:
608 - redis-data:/data
609 restart: unless-stopped
610
611 volumes:
612 postgres-data:
613 redis-data:
614 ```
615
616 ## Configuration Loading in Code
617
618 ### Rust Configuration Loading Example
619
620 ```rust
621 use serde::Deserialize;
622 use std::fs;
623
624 #[derive(Debug, Deserialize)]
625 struct MailConfig {
626 global: GlobalConfig,
627 smtp: Option<SmtpConfig>,
628 pop3: Option<Pop3Config>,
629 imap: Option<ImapConfig>,
630 authentication: AuthConfig,
631 storage: StorageConfig,
632 }
633
634 #[derive(Debug, Deserialize)]
635 struct Pop3Config {
636 enabled: bool,
637 host: String,
638 port: u16,
639 timeout: u64,
640 tls: Option<TlsConfig>,
641 limits: Option<LimitsConfig>,
642 }
643
644 fn load_config(path: &str) -> Result<MailConfig, Box<dyn std::error::Error>> {
645 let contents = fs::read_to_string(path)?;
646 let config: MailConfig = toml::from_str(&contents)?;
647 Ok(config)
648 }
649
650 fn main() -> Result<(), Box<dyn std::error::Error>> {
651 let config = load_config("mail-server.toml")?;
652
653 if let Some(pop3_config) = config.pop3 {
654 if pop3_config.enabled {
655 println!("Starting POP3 server on {}:{}",
656 pop3_config.host, pop3_config.port);
657 // Start POP3 server with config
658 }
659 }
660
661 Ok(())
662 }
663 ```
664
665 ## Notes
666
667 1. Always use strong passwords and secure password hashing (argon2, bcrypt)
668 2. Enable TLS/SSL for production environments
669 3. Implement rate limiting to prevent abuse
670 4. Use database or LDAP authentication in production
671 5. Regular backup of configuration and data
672 6. Monitor logs for security issues
673 7. Keep certificates up to date
674 8. Use environment variables for sensitive data (passwords, keys)
675 9. Test configurations in staging before production
676 10. Document any custom configuration changes