(brooklyn-docs) branch master updated: document ssh close and cache behaviour

[he...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

heneveld pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/brooklyn-docs.git


The following commit(s) were added to refs/heads/master by this push:
     new 936ac07b document ssh close and cache behaviour
936ac07b is described below

commit 936ac07b69c7f29737ac5f306cd875094c47bcf0
Author: Alex Heneveld <gi...@alex.heneveld.org>
AuthorDate: Thu Jun 27 10:52:29 2024 +0100

    document ssh close and cache behaviour
---
 guide/locations/_clouds.md                     |  9 +++++++++
 guide/ops/troubleshooting/slow-unresponsive.md | 15 +++++++++++++++
 2 files changed, 24 insertions(+)

diff --git a/guide/locations/_clouds.md b/guide/locations/_clouds.md
index ef59924b..7ecf7d37 100644
--- a/guide/locations/_clouds.md
+++ b/guide/locations/_clouds.md
@@ -230,6 +230,8 @@ For more keys and more detail on the keys below, see
   This setting prevents scripts executed on the VMs from being deleted on completion.
   Note that some scripts run periodically so this can eventually fill a disk; it should only be used for dev/test. 
 
+###### SSH Low-Level Configuration
+
 - Use `scripts.ignoreCerts: false` to issue `curl` and other download commands on-box
   in such a way that they require valid certificates from the servers they connect to
   (e.g. without the `-k` argument to `curl`, or GPG check for package installers);
@@ -285,6 +287,13 @@ For more keys and more detail on the keys below, see
   the CLI is not good practice. It can be tricky to pass password directly (e.g. using expect scripts or askpass) and
   password-less mechanisms are normally recommended when using a CLI-based SSH.
 
+- `sshCacheExpiryDuration` will override how long SSH sessions are kept open for reuse, defaulting to 5 minutes.
+  This can be any positive duration, such as `15s` to close pretty quickly, or `forever` not to close
+  (unless the location is unmanaged or there is another trigger). This may not be 0, but see the next key.
+
+- `brooklyn.ssh.config.close` can be set `true` to cause SSH sessions to be closed immediately after use.
+  This overrides any `sshCacheExpiryDuration`, and is useful where many entities may SSH to the same target.
+
 Other low level parameters are available in specific contexts, as described in the JavaDoc for the relevant classes
 and in some cases in `BrooklynConfigKeys`.
 
diff --git a/guide/ops/troubleshooting/slow-unresponsive.md b/guide/ops/troubleshooting/slow-unresponsive.md
index 9c777615..a2e8a777 100644
--- a/guide/ops/troubleshooting/slow-unresponsive.md
+++ b/guide/ops/troubleshooting/slow-unresponsive.md
@@ -109,6 +109,21 @@ tasks like ssh to also be extremely slow. See
 for details of how to work around this.
 
 
+#### SSHD Limits
+
+Apache Brooklyn will attempt to re-use the SSH connections to machines on a per-location basis, by default,
+keeping sessions open for up to 5 minutes if the entity/location is managed.
+If the same target is used via multiple `SshMachineLocation` instances
+(such as through BYON or localhost), this may trigger SSHD throttling.
+
+This can be resolved by setting either `sshCacheExpiryDuration: 10s` or `brooklyn.ssh.config.close: true`, 
+on the location, as described [here](/guide/locations#ssh-low-level-configuration).
+
+It could also be resolved by increasing `MaxSessions` and `MaxStartups` in `sshd_config` on the target system.
+More info on SSHD limits are documented [here](https://en.wikibooks.org/wiki/OpenSSH/Cookbook/Load_Balancing).
+
+
+
 ## Process Diagnostics
 
 #### Thread and Memory Usage