First working version of emailautoconf

1 files changed, 115 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..601a6e8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,115 @@
+# Email Autoconfiguration legacy helper
+
+Email autoconfiguration should generally be done these days with SRV DNS
+records, as specified in [RFC-6186](https://www.rfc-editor.org/rfc/rfc6186.html).
+
+However, some email clients have their own, legacy, web-based
+autoconfiguration methods.
+Recent versions of many of these email clients now work with RFC-6186
+SRV records, and will prefer them if they exist, but old versions are
+still out in the wild, and it's nice to support them if at all possible.
+(Especially given that users who haven't upgraded to recent versions of
+their tools might be tricky if they have issues.)
+
+This project provides those web-based autoconfiguration methods, but
+using the information from standardised RFC-6186 SRV records.
+
+
+## System requirements
+
+* Web server (currently *Apache2* supported)
+* *PHP*
+
+
+## Installation
+
+    make install \[PREFIX=prefixdir\]
+
+Installs the files to the **PREFIX** (default `/usr/local`) base
+directory - mostly under the `PREFIX/share/emailautoconf` subdirectory.
+
+
+## Configuration
+
+### On the main domain
+
+Most email clients can look for autoconfiguration files on a website
+with the same domain as the main email domain.
+For example, if your email address is `jordan.doe@example.com`, then
+most mail clients will look for an autoconfiguration file on the
+`example.com` website.
+
+If you have an *Apache2* website on the main domain, and installed
+*emailautoconf* to `/usr/local`, then add the following to your
+*Apache2* config:
+
+    Include /usr/local/share/emailautoconf/apache2/main.conf
+
+And that should work.
+
+For other webservers, you'll have to look at the *Apache2* config and
+figure out the equivalent setup yourself.
+Patches welcome!
+
+### On specialised subdomains
+
+Some email clients will look on specialised autoconfiguration subdomains
+for the autoconfiguration information.
+For example, if your email address is `jordan.doe@example.com`, then
+*[Outlook](https://www.microsoft.com/outlook)* will preferentially look
+for autoconfiguration data on `autodiscover.example.com` before falling
+back to looking on `example.com`.
+Similarly, *[Thundebird](https://www.thunderbird.net/)* (and some others
+which implemented Thunderbird's system), will preferentially look for
+autoconfiguration data on `autoconfig.example.com`, before falling back
+to looking on `example.com`.
+
+If you have an *Apache2* website on the `autodiscover` subdomain, and
+installed *emailautoconf* to `/usr/local`, then add the following to
+your *Apache2* config:
+
+    Include /usr/local/share/emailautoconf/apache2/autodiscover.conf
+
+And that should work.
+There is an equivalent config files for the `autoconfig` subdomain.
+
+For other subdomains and webservers, you'll have to look at the provided
+configs and, once again, figure out the equivalent setup yourself.
+Also, again, Patches welcome!
+
+
+## Uninstallation
+
+    make uninstall \[PREFIX=prefixdir\]
+
+Just [because](https://www.gnu.org/prep/standards/html_node/Standard-Targets.html),
+but also - what knows better at how to uninstall a package, than the
+system that was used to install it.
+(Yes, I am looking at you,
+*[cmake](https://gitlab.kitware.com/cmake/community/-/wikis/FAQ#can-i-do-make-uninstall-with-cmake)*).
+
+
+## License
+
+GNU Lesser General Public License v3.0 or later
+
+
+## TODO?
+
+Support for more legacy autoconfig types.
+
+Support for more web servers.
+
+Add a `configure` script with an option to set whether users need to
+supply their full email address, including domain, as their server
+login?
+
+Maybe install conf scripts somewhere more convenient, e.g.
+`/etc/apache2/conf-available`?
+
+Move "build objects" (e.g. `apache2/main.conf`) outside of the source
+tree?
+
+Add POP3 support?
+Really?
+