doc: document ssl_ctx for "listen" directive

With the advent of Let's Encrypt, we'll see more users
interested in using yahns with OpenSSL support.
So document how a listener may be passed an SSLContext.

1 files changed, 31 insertions, 0 deletions

diff --git a/Documentation/yahns_config.pod b/Documentation/yahns_config.pod
index 12ec75e..858aaf1 100644
--- a/Documentation/yahns_config.pod
+++ b/Documentation/yahns_config.pod
@@ -422,6 +422,37 @@ ref: https://lwn.net/Articles/542629/
 
 Default: false (unset)
 
+=item ssl_ctx: OpenSSL::SSL::SSLContext Ruby object
+
+To enable TLS connections, you must configure this yourself.
+See documentation for OpenSSL::SSL::SSLContext
+for more information:
+
+L<http://docs.ruby-lang.org/en/trunk/OpenSSL/SSL/SSLContext.html>
+
+Default: none
+
+An example which seems to work is:
+
+  require 'openssl'
+  ctx = OpenSSL::SSL::SSLContext.new
+  ctx.cert =
+    OpenSSL::X509::Certificate.new(
+      IO.read('/etc/ssl/certs/example.crt')
+    )
+  ctx.extra_chain_cert = [
+    OpenSSL::X509::Certificate.new(
+      IO.read('/etc/ssl/certs/chain.crt')
+    )
+  ]
+  ctx.key = OpenSSL::PKey::RSA.new(
+    IO.read('/etc/ssl/private/example.key')
+  )
+
+  app(:rack, "/path/to/my/app/config.ru") do
+    listen 443, ssl_ctx: ctx
+  end
+
 =item umask: MODE
 
 Sets the file mode creation mask for UNIX sockets.  If specified,