[alohalytics] Better server documentation.

3 files changed, 80 insertions, 49 deletions

diff --git a/3party/Alohalytics/server/fcgi_server.cc b/3party/Alohalytics/server/fcgi_server.cc
index fd29dba4b5..45a4d87465 100644
--- a/3party/Alohalytics/server/fcgi_server.cc
+++ b/3party/Alohalytics/server/fcgi_server.cc
@@ -23,54 +23,19 @@
  *******************************************************************************/
 
 // clang-format off
-/* This FastCGI server implementation is designed to store statistics received from remote clients.
-
-Validity checks for requests should be mostly done on nginx side:
-$request_method should be POST only
-$content_length should be set and greater than zero (we re-check it below anyway)
-$content_type should be set to application/alohalytics-binary-blob
-$http_content_encoding should be set to gzip
-
-This binary shoud be spawn as a FastCGI app, for example:
-$ spawn-fcgi [-n] -p 8888 -- ./fcgi_server /dir/to/store/received/data [/optional/path/to/log.file]
-
-# This is nginx config example to receive data from clients.
-http {
-  log_format alohalytics  '$remote_addr [$time_local] "$request" $status $content_length "$http_user_agent" $content_type $http_content_encoding';
-  server {
-    listen 8080;
-    server_name localhost;
-    # To hide nginx version.
-    server_tokens off;
-
-    location ~ ^/(ios|android)/(.+)/(.+) {
-      set $OS $1;
-      # Our clients send only POST requests.
-      limit_except POST { deny all; }
-      # Content-Length should be valid, but it is anyway checked on FastCGI app's code side.
-      # Content-Type should be application/alohalytics-binary-blob
-      if ($content_type != "application/alohalytics-binary-blob") {
-        return 415; # Unsupported Media Type
-      }
-      if ($http_content_encoding != "gzip") {
-        return 400; # Bad Request
-      }
-      client_body_buffer_size 1M;
-      client_body_temp_path /tmp 2;
-      client_max_body_size 100M;
-
-      access_log /var/log/nginx/aloha-$OS-access.log alohalytics;
-      # Unfortunately, error_log does not support variables.
-      error_log  /var/log/nginx/aloha-error.log notice;
-
-      fastcgi_pass_request_headers on;
-      fastcgi_param REMOTE_ADDR $remote_addr;
-      fastcgi_param REQUEST_URI $request_uri;
-      fastcgi_pass 127.0.0.1:8888;
-    }
-  }
-}
-*/
+// This FastCGI server implementation is designed to store statistics received from remote clients.
+// By default, everything is stored in <specified folder>/alohalytics_messages file.
+// If you have tons of data, it is better to use logrotate utility to archive it (see logrotate.conf).
+
+// Validity checks for requests should be mostly done on nginx side (see nginx.conf):
+// $request_method should be POST only
+// $content_length should be set and greater than zero (we re-check it below anyway)
+// $content_type should be set to application/alohalytics-binary-blob
+// $http_content_encoding should be set to gzip
+
+// This binary shoud be spawn as a FastCGI app, for example:
+// $ spawn-fcgi [-n] -a 127.0.0.1 -p <port number> -P /path/to/pid.file -- ./fcgi_server /dir/to/store/received/data [/optional/path/to/log.file]
+// pid.file can be used by logrotate (see logrotate.conf).
 // clang-format on
 
 #include <chrono>
@@ -135,7 +100,7 @@ struct CoutToFileRedirector {
 
 int main(int argc, char * argv[]) {
   if (argc < 2) {
-    ALOG("Usage:", argv[0], "<directory to store received data> <path to error log file>");
+    ALOG("Usage:", argv[0], "<directory to store received data> [path to error log file]");
     ALOG("  - SIGHUP reopens main data file and SIGUSR1 reopens debug log file for logrotate utility.");
     return -1;
   }
diff --git a/3party/Alohalytics/server/logrotate.conf b/3party/Alohalytics/server/logrotate.conf
new file mode 100644
index 0000000000..194901c55b
--- /dev/null
+++ b/3party/Alohalytics/server/logrotate.conf
@@ -0,0 +1,14 @@
+/data/cereal_logs/fcgi/alohalytics_messages
+{
+  daily
+  # Store logs for last 5 years.
+  rotate 1826
+  dateext
+  missingok
+  notifempty
+  compress
+  delaycompress
+  postrotate
+    /bin/kill -HUP $(cat /path/to/spawn-fcgi/pid.file 2>/dev/null) 2>/dev/null || true
+  endscript
+}
diff --git a/3party/Alohalytics/server/nginx.conf b/3party/Alohalytics/server/nginx.conf
new file mode 100644
index 0000000000..7a79cbe6c0
--- /dev/null
+++ b/3party/Alohalytics/server/nginx.conf
@@ -0,0 +1,52 @@
+# nginx config example to receive data from alohalytics clients.
+
+http {
+
+log_format alohalytics '$remote_addr [$time_local] "$request" $status $content_length "$http_user_agent"';
+
+# Default server which handles and ignores all invalid requests.
+server {
+  listen 80 default_server;
+  server_tokens off;
+  return 444;
+  access_log /var/log/nginx/default-access.log;
+  error_log /var/log/nginx/default-error.log warn;
+}
+
+server {
+  server_name aloha.with.you;
+  server_tokens off;
+  listen 80;
+  listen 443 ssl;
+  ssl_protocols TLSv1 TLSv1.1 TLSv1.2 SSLv2 SSLv3;
+  ssl_certificate /etc/nginx/ssl/aloha.with.you.crt;
+  ssl_certificate_key /etc/nginx/ssl/aloha.with.you.key;
+
+  # Config for the most recent client version.
+  location ~ ^/(ios|android)/(.+)/(.+) {
+    # Most filtering can be easily done on nginx side:
+    # - Our clients send only POST requests.
+    limit_except POST { deny all; }
+    # - Content-Length should be valid, but it is checked anyway on FastCGI app's code side.
+    # - Content-Type should be "application/alohalytics-binary-blob"
+    if ($content_type != "application/alohalytics-binary-blob") {
+      return 415; # Unsupported Media Type
+    }
+    # - Content-Encoding should be "gzip"
+    if ($http_content_encoding != "gzip") {
+      return 400; # Bad Request
+    }
+
+    client_body_buffer_size 1M;
+    client_max_body_size 10M;
+
+    access_log /var/log/nginx/alohalytics-access.log alohalytics;
+    error_log /var/log/nginx/alohalytics-error.log warn;
+
+    fastcgi_pass_request_headers on;
+    fastcgi_param REMOTE_ADDR $remote_addr;
+    fastcgi_param REQUEST_URI $request_uri;
+    # Specify valid port for your fcgi_server instance.
+    fastcgi_pass 127.0.0.1:8888;
+  }
+} # End of http block.