--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/mod_onions/README.markdown Fri Aug 28 18:03:58 2015 +0200
@@ -0,0 +1,81 @@
+---
+labels:
+- 'Stage-Alpha'
+summary: s2s to Tor hidden services
+...
+
+Introduction
+============
+
+This plugin allows Prosody to connect to other servers that are running
+as a Tor hidden service. Running Prosody on a hidden service works
+without this module, this module is only necessary to allow Prosody to
+federate to hidden XMPP servers.
+
+For general info about creating a hidden service, see
+https://www.torproject.org/docs/tor-hidden-service.html.en.
+
+Usage
+=====
+
+This module depends on the bit32 Lua library.
+
+To create a hidden service that can federate with other hidden XMPP
+servers, first add a hidden serivce to Tor. It should listen on port
+5269 and optionally also on 5222 (if c2s connections to the hidden
+service should be allowed).
+
+Use the hostname that Tor gives with a virtualhost:
+
+ VirtualHost "555abcdefhijklmn.onion"
+ modules_enabled = { "onions" };
+
+Configuration
+=============
+
+ Name Description Type Default value
+ ---------------------- ----------------------------------------------------- --------- ---------------
+ onions\_socks5\_host the host to connect to for Tor's SOCKS5 proxy string "127.0.0.1"
+ onions\_socks5\_port the port to connect to for Tor's SOCKS5 proxy integer 9050
+ onions\_only forbid all connection attempts to non-onion servers boolean false
+ onions\_tor\_all pass all s2s connections through Tor boolean false
+ onions\_map override the address for a host table {}
+
+By setting `onions_map`, it is possible to override the address used to
+connect to a given host with the address of a hidden service. The
+configuration of `onions_map` works as follows:
+
+ onions_map = {
+ ["jabber.calyxinstitute.org"] = "ijeeynrc6x2uy5ob.onion";
+ }
+
+or, to also specify a port:
+
+ onions_map = {
+ ["jabber.calyxinstitute.org"] = { host = "ijeeynrc6x2uy5ob.onion", port = 5269 };
+ }
+
+Compatibility
+=============
+
+ ----- --------------
+ 0.8 Doesn't work
+ 0.9 Works
+ ----- --------------
+
+Notes
+=====
+
+- `onions_tor_all` does not look up SRV records first. Therefore it
+ will fail for many servers.
+- mod\_onions currently does not support connecting to `.onion`
+ entries in SRV records.
+
+Security considerations
+=======================
+
+- Running a hidden service on a server together with a normal server
+ might expose the hidden service.
+- A hidden service that wants to remain hidden should either disallow
+ s2s to non-hidden servers or pass all s2s traffic through Tor
+ (setting either `onions_only` or `onions_tor_all`).