From fa3e4b146a977d9f60ba315bb84f5246d5c2abf1 Mon Sep 17 00:00:00 2001
From: John McLear <john@mclear.co.uk>
Date: Sun, 29 Mar 2020 22:27:22 +0000
Subject: [PATCH] settings: document the possibility of using Unix sockets

We have been supporting Unix sockets by ages, because express.listen()
(http://expressjs.com/en/4x/api.html#app.listen_path_callback) re-exposes
net.server.listen() (https://nodejs.org/api/net.html#net_server_listen), which
in turn supports Unix sockets.

The only remaining thing to do was documenting it.

Fixes #3312
---
 settings.json.docker       | 9 ++++++++-
 settings.json.template     | 9 ++++++++-
 src/node/hooks/express.js  | 8 +++++++-
 src/node/utils/Settings.js | 5 +++++
 4 files changed, 28 insertions(+), 3 deletions(-)

diff --git a/settings.json.docker b/settings.json.docker
index ef9893258..5c6188d13 100644
--- a/settings.json.docker
+++ b/settings.json.docker
@@ -92,7 +92,14 @@
   "skinName": "${SKIN_NAME:colibris}",
 
   /*
-   * IP and port which etherpad should bind at
+   * IP and port which Etherpad should bind at.
+   *
+   * Binding to a Unix socket is also supported: just use an empty string for
+   * the ip, and put the full path to the socket in the port parameter.
+   *
+   * EXAMPLE USING UNIX SOCKET:
+   *    "ip": "",                             // <-- has to be an empty string
+   *    "port" : "/somepath/etherpad.socket", // <-- path to a Unix socket
    */
   "ip": "${IP:0.0.0.0}",
   "port": "${PORT:9001}",
diff --git a/settings.json.template b/settings.json.template
index 161b83983..329f1f6cc 100644
--- a/settings.json.template
+++ b/settings.json.template
@@ -83,7 +83,14 @@
   "skinName": "colibris",
 
   /*
-   * IP and port which etherpad should bind at
+   * IP and port which Etherpad should bind at.
+   *
+   * Binding to a Unix socket is also supported: just use an empty string for
+   * the ip, and put the full path to the socket in the port parameter.
+   *
+   * EXAMPLE USING UNIX SOCKET:
+   *    "ip": "",                             // <-- has to be an empty string
+   *    "port" : "/somepath/etherpad.socket", // <-- path to a Unix socket
    */
   "ip": "0.0.0.0",
   "port": 9001,
diff --git a/src/node/hooks/express.js b/src/node/hooks/express.js
index 6394ffbfc..c755dd84c 100644
--- a/src/node/hooks/express.js
+++ b/src/node/hooks/express.js
@@ -18,7 +18,13 @@ exports.createServer = function () {
 
   exports.restartServer();
 
-  console.log(`You can access your Etherpad instance at http://${settings.ip}:${settings.port}/`);
+  if (settings.ip === "") {
+    // using Unix socket for connectivity
+    console.log(`You can access your Etherpad instance using the Unix socket at ${settings.port}`);
+  } else {
+    console.log(`You can access your Etherpad instance at http://${settings.ip}:${settings.port}/`);
+  }
+
   if (!_.isEmpty(settings.users)) {
     console.log(`The plugin admin page is at http://${settings.ip}:${settings.port}/admin/plugins`);
   } else {
diff --git a/src/node/utils/Settings.js b/src/node/utils/Settings.js
index 081663eb6..47712b9bd 100644
--- a/src/node/utils/Settings.js
+++ b/src/node/utils/Settings.js
@@ -710,6 +710,11 @@ exports.reloadSettings = function reloadSettings() {
     exports.dbSettings.filename = absolutePaths.makeAbsolute(exports.dbSettings.filename);
     console.warn(dirtyWarning + ` File location: ${exports.dbSettings.filename}`);
   }
+
+  if (exports.ip === "") {
+    // using Unix socket for connectivity
+    console.warn(`The settings file contains an empty string ("") for the "ip" parameter. The "port" parameter will be interpreted as the path to a Unix socket to bind at.`);
+  }
 };
 
 // initially load settings