[remote] add some docs and allow ssh command customization

docs/source/howitworks.rst

@@ -5,3 +5,9 @@ How It Works
 ============
 
 "Magic"
+
+Internal Architecture
+---------------------
+
+The `ARCHITECTURE.md <https://github.com/tstack/lnav/blob/master/ARCHITECTURE.md>`_
+file in the source tree contains some information about lnav's internals.

src/internals/config-v1.schema.json

@@ -78,6 +78,16 @@
                                     "description": "The SSH command to execute",
                                     "type": "string"
                                 },
+                                "transfer-command": {
+                                    "title": "/tuning/remote/ssh/transfer-command",
+                                    "description": "Command executed on the remote host when transferring the file",
+                                    "type": "string"
+                                },
+                                "start-command": {
+                                    "title": "/tuning/remote/ssh/start-command",
+                                    "description": "Command executed on the remote host to start the tailer",
+                                    "type": "string"
+                                },
                                 "flags": {
                                     "title": "/tuning/remote/ssh/flags",
                                     "description": "The flags to pass to the SSH command",

src/lnav_config.cc

@@ -925,6 +925,18 @@ static struct json_path_container ssh_handlers = {
         .with_description("The SSH command to execute")
         .for_field(&_lnav_config::lc_tailer,
                    &tailer::config::c_ssh_cmd),
+    yajlpp::property_handler("transfer-command")
+        .with_synopsis("command")
+        .with_description(
+            "Command executed on the remote host when transferring the file")
+        .for_field(&_lnav_config::lc_tailer,
+                   &tailer::config::c_transfer_cmd),
+    yajlpp::property_handler("start-command")
+        .with_synopsis("command")
+        .with_description(
+            "Command executed on the remote host to start the tailer")
+        .for_field(&_lnav_config::lc_tailer,
+                   &tailer::config::c_start_cmd),
     yajlpp::property_handler("flags")
         .with_description("The flags to pass to the SSH command")
         .for_field(&_lnav_config::lc_tailer,

src/root-config.json

@@ -17,9 +17,10 @@
                 "command": "ssh",
                 "config": {
                     "BatchMode": "yes",
-                    "ConnectTimeout": "10",
-                    "StrictHostKeyChecking": "no"
-                }
+                    "ConnectTimeout": "10"
+                },
+                "start-command": "bash -c ./{0:}",
+                "transfer-command": "cat > {0:} && chmod ugo+rx ./{0:}"
             }
         }
     }

src/tailer/README.md

@@ -0,0 +1,35 @@
+# Tailer
+
+This directory contains the functionality for monitoring
+[remote files](https://docs.lnav.org/en/latest/usage.html#remote-files).  The
+name "tailer" refers to the binary that is transferred to the remote host that
+takes care of tailing files and sending the contents back to the host that is
+running the main lnav binary.  To ease integration with lnav's existing
+functionality, the remote files are mirrored locally.  The tailer also
+supports interactive use by providing previews of file contents and
+TAB-completion possibilities.
+
+## Files
+
+The important files in this directory are:
+
+- [tailer.main.c](tailer.main.c) - The main() implementation for the tailer.
+- [tailer.looper.hh](tailer.looper.hh) - The service in the main lnav binary
+  that transfers tailers to hosts and communicates with them.
+- [tailer.h](tailer.h) and [tailerpp.hh](tailerpp.hh) - Utility libraries for
+  the tailer protocol.
+- tailer.ape - The [αcτµαlly pδrταblε εxεcµταblε](https://justine.lol/ape.html)
+  build of the tailer.  This binary is produced by a GitHub Action and checked
+  in so the build process doesn't need to be supported on lots of platforms.
+
+## Flow
+
+When a remote-path is passed to lnav, the
+[file_collection.hh](../file_collection.hh) logic forwards the request to the
+`tailer::looper` service.  This service makes two connections to the remote
+host using the `ssh` command so that the user's custom configurations will be
+used.  The first connection is used to transfer the "tailer.ape" binary and
+make it executable.  The second connection starts the tailer and uses
+stdin/stdout for a binary protocol and stderr for logging.  The tailer then
+waits for requests to open files, preview files, and get possible paths for
+TAB-completions.

src/tailer/tailer.looper.cc

@@ -282,9 +282,7 @@ tailer::looper::host_tailer::for_host(const std::string& netloc)
             std::vector<char *> args;
 
             arg_strs.emplace_back(fmt::format(
-                "cat > {} && chmod ugo+rx ./{}",
-                tailer_bin_name,
-                tailer_bin_name));
+                cfg.c_transfer_cmd, tailer_bin_name));
 
             fmt::print(stderr, "tailer({}): executing -- {}\n",
                        netloc,
@@ -361,8 +359,7 @@ tailer::looper::host_tailer::for_host(const std::string& netloc)
         auto arg_strs = create_ssh_args_from_config(ssh_dest);
         std::vector<char *> args;
 
-        arg_strs.emplace_back(fmt::format(
-            "bash -c ./{}", tailer_bin_name, tailer_bin_name));
+        arg_strs.emplace_back(fmt::format(cfg.c_start_cmd, tailer_bin_name));
 
         fmt::print(stderr, "tailer({}): executing -- {}\n",
                    netloc,

src/tailer/tailer.looper.cfg.hh

@@ -33,13 +33,14 @@
 namespace tailer {
 
 struct config {
+    std::string c_transfer_cmd{"cat > {0:} && chmod ugo+rx ./{0:}"};
+    std::string c_start_cmd{"bash -c ./{0:}"};
     std::string c_ssh_cmd{"ssh"};
     std::string c_ssh_flags{};
     std::map<std::string, std::string> c_ssh_options{};
     std::map<std::string, std::string> c_ssh_config{
         {"BatchMode", "yes"},
         {"ConnectTimeout", "10"},
-        {"StrictHostKeyChecking", "yes"},
     };
 };