Add scatter(1), shoal(1), and shock(1)

8 files changed, 175 insertions, 0 deletions

diff --git a/Makefile b/Makefile
index 1c691bbc..d257d2c1 100644
--- a/Makefile
+++ b/Makefile
@@ -4,10 +4,12 @@ usage :
 	@echo "If you're happy with what it'll do, then run make install."
 
 install : install-bash \
+	install-bin \
 	install-curl \
 	install-git \
 	install-gnupg \
 	install-readline \
+	install-man \
 	install-sh \
 	install-terminfo \
 	install-vim
@@ -23,6 +25,20 @@ install-bash : test-bash
 	ln -s $(PWD)/bash/bash_logout $(HOME)/.bash_logout
 	ln -s $(PWD)/bash/bash_completion $(HOME)/.config/bash_completion
 
+install-bin : test-bin
+	mkdir -p $(HOME)/.local/bin
+	for bin in $(PWD)/bin/* ; do \
+		rm -f $(HOME)/.local/bin/"$${bin##*/}" ; \
+		ln -s "$$bin" $(HOME)/.local/bin/"$${bin##*/}" ; \
+	done
+
+install-man :
+	for man in $(PWD)/man/* ; do \
+		mkdir -p $(HOME)/.local/share/man/man"$${man##*.}" ; \
+		rm -f $(HOME)/.local/share/man/man"$${man##*.}"/"$${man##*/}" ; \
+		ln -s "$$man" $(HOME)/.local/share/man/man"$${man##*.}"/"$${man##*/}" ; \
+	done
+
 install-curl :
 	rm -f $(HOME)/.curlrc
 	ln -s $(PWD)/curl/curlrc $(HOME)/.curlrc
@@ -141,3 +157,13 @@ test-bash :
 	done
 	@echo "All bash(1) scripts parsed successfully."
 
+test-bin :
+	@for bin in $(PWD)/bin/* ; do \
+		if sed 1q "$$bin"" | grep -q bash && ! bash -n "$$bin" ; then \
+			exit 1 ; \
+		elsif sed 1q "$$bin"" | grep -q sh && ! sh -n "$$sh" ; then \
+			exit 1 ; \
+		fi ; \
+	done
+	@echo "All shell scripts in /bin/ parsed successfully."
+
diff --git a/README.markdown b/README.markdown
index efdc2148..303d5a95 100644
--- a/README.markdown
+++ b/README.markdown
@@ -48,6 +48,8 @@ Configuration is included for:
 *   [X11](http://www.x.org/wiki/) — Windowing system with network transparency
     for Unix
 
+Also included are a few scripts for `~/.local/bin`, and their `man(1)` pages.
+
 The configurations for Bash, Mutt, tmux, and Vim are the most expansive and
 most likely to be of interest. The configuration for GnuPG is tweaked to follow
 [RiseUp’s OpenPGP best
@@ -88,6 +90,9 @@ The remaining dotfiles can be installed with the other targets:
 *   `install-wyrd`
 *   `install-x`
 
+The miscellaneous `bin` scripts and their manuals can be installed with
+`install-bin` and `install-man` respectively.
+
 Shell
 -----
 
@@ -256,6 +261,20 @@ The configuration is extensively commented, mostly because I was reading
 through it one day and realised I’d forgotten what half of it did. Plugins are
 loaded using @tpope’s [pathogen.vim](https://github.com/tpope/vim-pathogen).
 
+Scripts
+-------
+
+Three SSH-related scripts and their manuals are included:
+
+*   `scatter(1)` -- Run command on multiple hosts read from `shoal(1)` and
+    print output
+*   `shock(1)` -- Run command on multiple hosts read from `shoal(1)` and print
+    the hostname if the command returns zero
+*   `shoal(1)` -- Print hostnames read from a `ssh_config(5)` file
+
+If you want to use the manuals, you may need to add `~/.local/share/man` to
+your `/etc/manpath` configuration, depending on your system.
+
 License
 -------
 
diff --git a/bin/scatter b/bin/scatter
new file mode 100755
index 00000000..5cb62e44
--- /dev/null
+++ b/bin/scatter
@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+
+#
+# scatter(1) -- Run a command on every hostname returned by shoal(1) and print
+# both stdout and stderr, including allocating a pty with -t.
+#
+# Author: Tom Ryder <tom@sanctum.geek.nz>
+# Copyright: 2014
+# License: Public domain
+#
+
+# Name self
+self=scatter
+
+# Handle ^C interrupts
+trap 'trap - INT; kill -INT $$' INT
+
+# Bail if we couldn't find shoal(1)
+hash shoal || exit
+
+# Exit with usage method if no arguments given
+if ! (($#)) ; then
+    printf 'USAGE: %s <command>\n' "$self" >&2
+    exit 1
+fi
+
+# Execute command, print both stdout and stderr, and use file descriptor 3 to
+# avoid clobbering any of the standard streams
+while read -r hostname <&3 ; do
+    printf '%s: %s\n' "$self" "$hostname"
+    ssh -qt -- "$hostname" "$@"
+    printf '\n'
+done 3< <(shoal)
+
diff --git a/bin/shoal b/bin/shoal
new file mode 100755
index 00000000..469ce487
--- /dev/null
+++ b/bin/shoal
@@ -0,0 +1,15 @@
+#!/bin/sh
+
+#
+# shoal(1) -- Print all the non-wildcard Host names (first
+# one per line) from an ssh_config(5) file, defaulting to
+# $HOME/.ssh/config.
+#
+# Author: Tom Ryder <tom@sanctum.geek.nz>
+# Copyright: 2014
+# License: Public domain
+#
+
+prog='$1 == "Host" && $2 !~ /[^a-z0-9_-]/ {print $2}'
+awk "$prog" "${1:-$HOME/.ssh/config}"
+
diff --git a/bin/shock b/bin/shock
new file mode 100755
index 00000000..0b61c52e
--- /dev/null
+++ b/bin/shock
@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+
+#
+# shock(1) -- Run a command on every hostname returned by shock(1) and print
+# the hostname if the command's return value was zero. Discard stdout, but do
+# print stderr.
+#
+
+# Name self
+self=shock
+
+# Handle ^C interrupts
+trap 'trap - INT; kill -INT $$' INT
+
+# Bail if we couldn't find shoal(1)
+hash shoal || exit
+
+# Exit with usage method if no command given
+if ! (($#)) ; then
+    printf 'USAGE: %s <command>\n' "$self" >&2
+    exit 1
+fi
+
+# Execute command, print hostname if it returns zero
+while read -r hostname ; do
+    if ssh -nq -- "$hostname" "$@" >/dev/null ; then
+        printf '%s\n' "$hostname"
+    fi
+done < <(shoal)
+
diff --git a/man/scatter.1 b/man/scatter.1
new file mode 100644
index 00000000..95addd23
--- /dev/null
+++ b/man/scatter.1
@@ -0,0 +1,16 @@
+.TH SCATTER 1 "May 2014" "Manual page for scatter"
+.SH NAME
+.B scatter
+\- run a command on shoal(1) hosts
+.SH SYNOPSIS
+.B scatter
+.I COMMAND
+.SH DESCRIPTION
+.B scatter
+runs a nominated command on all the hosts returned by shoal(1), and prints the
+hostname, stdout, and stderr for each call.
+.SH SEE ALSO
+shock(1), shoal(1)
+.SH AUTHOR
+Tom Ryder <tom@sanctum.geek.nz>
+
diff --git a/man/shoal.1 b/man/shoal.1
new file mode 100644
index 00000000..2399f974
--- /dev/null
+++ b/man/shoal.1
@@ -0,0 +1,18 @@
+.TH SHOAL 1 "May 2014" "Manual page for shoal"
+.SH NAME
+.B shoal
+\- list the first hostname on each line of an ssh_config(5) file
+.SH SYNOPSIS
+.B shoal
+.I [SSH_CONFIG]
+.SH DESCRIPTION
+.B shoal
+reads an ssh_config(5) file, defaulting to ~/.ssh/config, and returns a
+newline-delimited list of the first of the hostnames on each Host line in the
+file, ignoring all other lines. Suitable for use in batch scripts like
+scatter(1).
+.SH SEE ALSO
+scatter(1), shock(1), ssh(1), ssh_config(5)
+.SH AUTHOR
+Tom Ryder <tom@sanctum.geek.nz>
+
diff --git a/man/shock.1 b/man/shock.1
new file mode 100644
index 00000000..0b64d504
--- /dev/null
+++ b/man/shock.1
@@ -0,0 +1,17 @@
+.TH SHOCK 1 "May 2014" "Manual page for shock"
+.SH NAME
+.B shock
+\- run a command on shoal(1) hosts and print the hostname if successful
+.SH SYNOPSIS
+.B shock
+.I COMMAND
+.SH DESCRIPTION
+.B shock
+runs a nominated command on all the hosts returned by shoal(1), and prints the
+hostname if the command has an exit value of 0. The stdout from the commands is
+discarded.
+.SH SEE ALSO
+scatter(1), shoal(1)
+.SH AUTHOR
+Tom Ryder <tom@sanctum.geek.nz>
+