Add/improve documentation

Signed-off-by: Blaine Gardner <[email protected]>

README.md

@@ -1,2 +1,29 @@
-# octopus
-A small go tool for running shell commands on multiple hosts in parallel.
+Octopus
+=========
+Octopus is a commandline tool for running the same command on multiple remote hosts in parallel.
+
+Theory
+--------
+Octopus is a simple tool inspired by `pdsh`'s ability to execute commands on multiple hosts in
+parallel. In environments where `pdsh` cannot be installed, Go's ability to produce static binaries
+is useful; thus, Octopus is written in Go. As long as one has the ability to `scp` or `rsync` files
+to a host, a static `octopus` executable can be copied to it. A host may be a cluster admin node,
+for example.
+
+Octopus can execute arbitrary commands on multiple hosts in parallel, and hosts are grouped together
+into "host groups" in a file which inspired by `pdsh`'s "genders" file. The host groups file for
+Octopus is actually a Bash file with groups defined by variable definitions. A file which defines
+host groups as Bash variables was chosen so that so that the same file may be used easily by both
+Octopus and by user-made scripts.
+
+Under the hood, Octopus uses `ssh` connections, and some `ssh` arguments are reflected in Octopus's
+arguments.
+
+**warning:** Octopus does not do verification of the remote hosts (`StrictHostKeyChecking=no`), and
+it does not add entries to the user's known hosts file.
+
+Usage
+-------
+See `octopus -help` for command usage.
+
+An example host groups file can be found in the [config](config) directory.

cmd/octopus/octopus.go

@@ -1,5 +1,7 @@
 // Package octopus is a commandline tool for running the same command on multiple remote hosts in
 // parallel.
+//
+// See config for a sample host groups file
 package main
 
 import (
@@ -13,9 +15,9 @@ import (
 func main() {
 	command := flag.String("command", "", "(required) command to execute on remote hosts")
 	hostGroups := flag.String("host-groups", "",
-		"(required) named host groups on which to execute the command")
+		"(required) comma-separated list of host groups on which to execute the command")
 	hostsFile := flag.String("hosts-file", defaultHostsFile, fmt.Sprintf(
-		"file which defines which remote hosts are available for execution (default: %s)", defaultHostsFile))
+		"file which defines which groups of remote hosts are available for execution (default: %s)", defaultHostsFile))
 	identityFile := flag.String("identity-file", "~/.ssh/id_rsa",
 		"identity file used to authenticate to remote hosts")
 	flag.Parse()

config/hosts-list-file-template

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+
+# The host groups file is intended to be able to be used by Bash scripts in addition to Octopus. In
+# fact, Octopus will not be able to parse the host groups file if the group entries are not in a Bash
+# variable declaration.
+
+# A sample list of host groups for a theoretical Kubernetes cluster is shown below. In this
+# example, the internal cluster network is 172.24.0.0/16, and the internet-facing (public) network
+# is 192.168.0.0/16
+
+# In this example, the primary place to run Octopus is from the admin node
+admin="172.24.1.1"
+# We may also run it from a laptop, but we will be limited to executing on public nodes
+admin_public="192.168.101.1"
+
+# Definitions must begin with (including either a single- or double-quote): <variable_name>=["']
+masters="172.24.2.1 172.24.2.2 172.24.2.3"
+masters_public="192.168.102.1 192.168.102.2 192.168.102.3"
+
+# Definitions do not need to be on a single line as long as there is a quote following the equal
+nodes='
+172.24.3.1
+172.24.3.2
+172.24.3.3
+172.24.3.4
+172.24.3.5'
+# nodes do not have an internet-facing network in this example
+
+# Deinitions may include previous definitions as variables just as one could do in Bash
+all="${admin} ${masters} ${nodes}"
+all_public="${admin_public} ${masters_public}"
+
+k8s="${masters} ${nodes}"
+
+
+# Examples of using Octopus with this host groups file. We will assume that the file is named the
+# default value of "_node-list".
+#
+#   List all disks on nodes:
+#     octopus -host-groups nodes -command 'ls /dev/sd*'
+#
+#   Get the date from the admin and the nodes:
+#     octopus -host-groups admin,nodes -command 'date'
+#
+#   Get the iptables status on all public-facing nodes:
+#     octopus -host-groups all_public -command 'systemctl status iptables'