commit 4189bd17a1b969911f904da66bc6b557f2acc03d
from: mischa <mischa@rx.high5.nl>
date: Sat Oct 14 14:44:58 2023 UTC

expand the README to make it a little bit more useful

commit - 8e8ec9534c96520ca30d248f6313421c1af0575d
commit + 4189bd17a1b969911f904da66bc6b557f2acc03d
blob - 38e1d5f3ce94d6b7a4dc50ca9dcdc0945f77fd00
blob + 688ea74db242ccb1217ff08d97bdfb4befe9b935
--- README.md
+++ README.md
@@ -1,9 +1,25 @@
 ## OpenSMTPD Admin
 
-Fork of Postfix Admin 2.1.0 (released in 2007)
+OpenSMTPD Admin started as a fork of Postfix Admin 2.1.0 (released
+in 2007), and grew quickly in a complete rewrite for OpenSMTPD.
 
-Database needed to use SQL with OpenSMTPD
+## Installation of packages
 
+To get going on OpenBSD you will need to install the following packages:
+
+	mariadb-server
+	php
+	php-pdo_mysql
+
+For OpenSMTPD you need the packages:
+
+	opensmtpd-extras
+	opensmtpd-extras-mysql
+
+Once the packages are installed follow the steps outlined in /usr/local/share/doc/pkg-readmes
+
+You need to create the database with:
+
 	CREATE DATABASE IF NOT EXISTS `opensmtpd` DEFAULT CHARACTER SET latin1 COLLATE latin1_swedish_ci;
 	USE `opensmtpd`;
 
@@ -15,7 +31,7 @@ Database needed to use SQL with OpenSMTPD
 	  `modified` datetime NOT NULL DEFAULT '0000-00-00 00:00:00',
 	  PRIMARY KEY (`username`),
 	  KEY `username` (`username`)
-	) ENGINE=InnoDB DEFAULT CHARSET=latin1 COMMENT='OpenSMTPD Admin - Virtual Admins'
+	) ENGINE=InnoDB DEFAULT CHARSET=latin1 COMMENT='OpenSMTPD Admin - Virtual Admins';
 
 	CREATE TABLE `alias` (
 	  `address` varchar(255) NOT NULL DEFAULT '',
@@ -25,7 +41,7 @@ Database needed to use SQL with OpenSMTPD
 	  `modified` datetime NOT NULL DEFAULT '0000-00-00 00:00:00',
 	  PRIMARY KEY (`address`),
 	  KEY `address` (`address`)
-	) ENGINE=InnoDB DEFAULT CHARSET=latin1 COMMENT='OpenSMTPD Admin - Virtual Aliases'
+	) ENGINE=InnoDB DEFAULT CHARSET=latin1 COMMENT='OpenSMTPD Admin - Virtual Aliases';
 
 	CREATE TABLE `domain` (
 	  `domain` varchar(255) NOT NULL DEFAULT '',
@@ -36,14 +52,14 @@ Database needed to use SQL with OpenSMTPD
 	  `modified` datetime NOT NULL DEFAULT '0000-00-00 00:00:00',
 	  PRIMARY KEY (`domain`),
 	  KEY `domain` (`domain`)
-	) ENGINE=InnoDB DEFAULT CHARSET=latin1 COMMENT='OpenSMTPD Admin - Virtual Domains'
+	) ENGINE=InnoDB DEFAULT CHARSET=latin1 COMMENT='OpenSMTPD Admin - Virtual Domains';
 
 	CREATE TABLE `domain_admins` (
 	  `username` varchar(255) NOT NULL DEFAULT '',
 	  `domain` varchar(255) NOT NULL DEFAULT '',
 	  `created` datetime NOT NULL DEFAULT '0000-00-00 00:00:00',
 	  KEY `username` (`username`)
-	) ENGINE=InnoDB DEFAULT CHARSET=latin1 COMMENT='OpenSMTPD Admin - Domain Admins'
+	) ENGINE=InnoDB DEFAULT CHARSET=latin1 COMMENT='OpenSMTPD Admin - Domain Admins';
 
 	CREATE TABLE `log` (
 	  `timestamp` datetime NOT NULL DEFAULT '0000-00-00 00:00:00',
@@ -52,7 +68,7 @@ Database needed to use SQL with OpenSMTPD
 	  `action` varchar(255) NOT NULL DEFAULT '',
 	  `data` varchar(255) NOT NULL DEFAULT '',
 	  KEY `timestamp` (`timestamp`)
-	) ENGINE=InnoDB DEFAULT CHARSET=latin1 COMMENT='OpenSMTPD Admin - Log'
+	) ENGINE=InnoDB DEFAULT CHARSET=latin1 COMMENT='OpenSMTPD Admin - Log';
 
 	CREATE TABLE `mailbox` (
 	  `username` varchar(255) NOT NULL DEFAULT '',
@@ -64,7 +80,7 @@ Database needed to use SQL with OpenSMTPD
 	  `modified` datetime NOT NULL DEFAULT '0000-00-00 00:00:00',
 	  PRIMARY KEY (`username`),
 	  KEY `username` (`username`)
-	) ENGINE=InnoDB DEFAULT CHARSET=latin1 COMMENT='OpenSMTPD Admin - Virtual Mailboxes'
+	) ENGINE=InnoDB DEFAULT CHARSET=latin1 COMMENT='OpenSMTPD Admin - Virtual Mailboxes';
 
 	CREATE TABLE `vacation` (
 	  `email` varchar(255) NOT NULL DEFAULT '',
@@ -75,17 +91,63 @@ Database needed to use SQL with OpenSMTPD
 	  `created` datetime NOT NULL DEFAULT '0000-00-00 00:00:00',
 	  PRIMARY KEY (`email`),
 	  KEY `email` (`email`)
-	) ENGINE=InnoDB DEFAULT CHARSET=latin1 COMMENT='OpenSMTPD Admin - Virtual Vacation'
+	) ENGINE=InnoDB DEFAULT CHARSET=latin1 COMMENT='OpenSMTPD Admin - Virtual Vacation';
 
 
-Config for OpenSMTPTD, MySQL/MariaDB example:
+You can create the database user with something like:
 
+	CREATE USER IF NOT EXISTS 'opensmtpd'@'localhost' IDENTIFIED BY 'RandomString';
+	GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP,INDEX,ALTER ON opensmtpd.* TO 'opensmtpd'@'localhost';
+
+
+As an example configuration for httpd you can use:
+
+	server "opensmtpadmin" {
+		listen on * tls port 443
+		tls {
+			certificate "/etc/ssl/opensmtpdadmin.fullchain.pem"
+			key "/etc/ssl/private/opensmtpadmin.key"
+		}
+		tcp { nodelay, sack }
+		log style forwarded
+		location "/admin/*" {
+			authenticate with "/opensmtpdadmin/admin/.htpasswd"
+			root "/opensmtpdadmin"
+			fastcgi socket "/run/php-fpm.sock"
+		}
+		location "*.php*" {
+			root "/opensmtpdadmin"
+			directory index index.php
+			fastcgi socket "/run/php-fpm.sock"
+		}
+		location "/*" {
+			root "/opensmtpdadmin"
+			directory index index.php
+		}
+	}
+
+As soon as that is done you can go to https://<yourhost>/<br>
+You will be greeted by setup.php to check if everything is present to run OpenSMTPDAdmin.
+
+Copy or move the conf.php-sample to conf.php and make the needed changes for your setup.<br>
+You can remove setup.php if you want.
+
+After that you can go to https://<yourhost>/admin/admin.php where you create the SUPER ADMIN.<br>
+NOTE: Once this is done either remove or protect this directory / file.
+
+You are now ready to use OpenSMTPDAdmin.
+
+
+
+To use the accounts OpenSMTPDAdmin create in OpenSMTPD you can use the below config:
+
 	# /etc/mail/smtpd.conf
 	table credentials mysql:/etc/mail/sql.conf
 	table domains mysql:/etc/mail/sql.conf
 	table userinfo mysql:/etc/mail/sql.conf
 	table virtuals mysql:/etc/mail/sql.conf
 
+
 Connecting the database to smtpd:
 
 	# /etc/mail/sql.conf