Remove -f from examples. Add -d example.

1 files changed, 55 insertions, 5 deletions

diff --git a/README.md b/README.md
index 9758a97..319a380 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,7 @@
 # jupyter_safe_port
 
 ```
-usage: jupyter_safe_port [-h] [-c] [-d] {host} [port]
+usage: jupyter_safe_port [-hcdf] {host} [port]
 
 Discovers the next TCP port available for your notebook server and returns
 execution instructions. If the argument '-c' is present and the requested
@@ -16,6 +16,7 @@ Arguments:
     -c    only generate the SSH connection string
     -d    dump ports (useful in scripts)
               format: local remote
+    -f    apply SSH argument to daemonize session (i.e. ssh -f)
 ```
 
 ## Install
@@ -34,7 +35,7 @@ Execute on example.lan:
 jupyter notebook --no-browser --port=1024
 
 Connect via:
-ssh -N -f -L1024:localhost:1024 user@example.lan
+ssh -N -L1024:localhost:1024 user@example.lan
 ```
 
 You start the first notebook server. Now run `jupyter_safe_port` again...
@@ -45,7 +46,7 @@ Execute on example.lan:
 jupyter notebook --no-browser --port=1025
 
 Connect via:
-ssh -N -f -L1025:localhost:1025 user@example.lan
+ssh -N -L1025:localhost:1025 user@example.lan
 ```
 
 The local port 1024 is already bound to the first server so it gives you 1025. On the remote system, `example.lan`, port 1024 is bound too so it returns 1025 as well. What if you want to use a higher port number on `example.lan`? Let's see...
@@ -56,7 +57,7 @@ Execute on example.lan:
 jupyter notebook --no-browser --port=8081
 
 Connect via:
-ssh -N -f -L1026:localhost:8081 user@example.lan
+ssh -N -L1026:localhost:8081 user@example.lan
 ```
 
 Oops, you forgot about that web server test. 8080 is already bound so you're given 8081 instead. Locally 1024 and 1025 are already bound so `jupyter_safe_port` returns 1026.
@@ -66,5 +67,54 @@ Let's say you have closed your laptop and lost all of your connections. If you c
 ```
 $ jupyter_safe_port example.lan -c 8081
 Connect via:
-ssh -N -f -L1024:localhost:8081 user@example.lan
+ssh -N -L1024:localhost:8081 user@example.lan
+```
+
+## Scripting
+
+You can use `jupyter_safe_port` in your scripts. `-d` returns the local port followed by the remote port.
+
+```
+$ jupyter_safe_port example.lan -c 8081
+1024 8081
+```
+
+Here are a few ways to use it...
+
+```shell
+#!/usr/bin/env bash
+
+if type -p jupyter_safe_port &>/dev/null; then
+    echo "jupyter_safe_port is not installed" >&2
+    exit 1
+fi
+
+result=$(jupyter_safe_port -d $server)
+if [ -z "$result" ]; then
+    # jupyter_safe_port failed
+    # case 1: not enough arguments
+    # case 2: invalid argument
+    # case 3: invalid port range
+    # case 4: ssh failed to connect to $server
+    exit 1
+fi
+
+# Extract ports from result
+read $port_local $port_remote <<< "$result"
+if (( port_remote < 0 )); then {
+    # case 1: no remote ports available
+    # case 2: if using '-c', no service is present on the requested port
+    exit 1
+}
+
+# Spawn a local screen session to manage a remote jupyter server.
+# You'd really want to use screen on the remote instead... This is just an example.
+screen -dmS "jupyter_$server_$remote_port" ssh $server "source ~/miniconda3/etc/profile.d/conda.sh \
+    && conda activate XYZ \
+    && jupyter notebook --no-browser --port=$port_remote"
+
+# Forward the ports to the local system
+echo "Forwarding $port_remote to localhost:$port_local"
+echo "To interrupt the session press: ctrl-c
+ssh -N $port_local:localhost:$port_remote $server
 ```