doc/swarm.1

   1 .TH swarm 1 "14 Feb 2013" "version 1.0"
   2 .SH NAME
   3 swarm - Tool for parallelising shell scripts
   4 .SH SYNOPSIS
   5 swarm [options] [file]
   6 .SH DESCRIPTION
   7 .B Swarm
   8 allows one to pass commands to simultaneously running instances of a shell such as
   9 .BR bash "(1)."
  10 .BR Swarm " can work with local shells and can also start shells on remote hosts."
  11 .PP
  12 The purpose of
  13 .BR swarm " is to speed up the execution of shell scripts which involve a large number of time consuming tasks, where the order in which the tasks are completed is unimportant.
  14
  15 .SH OPTIONS
  16 .TP
  17 .BI -n " processes"
  18 Set the number of shells for
  19 .B swarm
  20 to spawn.
  21 By default, one shell is spawned for each CPU found by a call to
  22 .BR sysconf "(3)."
  23 .TP
  24 .BI -s " shell"
  25 Set the type of shell which will be spawned. The default is
  26 .BR bash "(1)."
  27 .TP
  28 .BI -c " command"
  29 Treat command as a single line of input. This option is not very useful unless there is already an instance of
  30 .B swarm
  31 invoked with the
  32 .B --daemon
  33 option running in the current directory.
  34 .TP
  35 .BI -o " file"
  36 .B Swarm
  37 will send output to
  38 .I file
  39 instead of stdout.
  40
  41
  42 .TP
  43 .BI -l " [file][:level]"
  44 Set the log file and optionally level.
  45 If no file is given,
  46 .BR swarm " logs to stderr.
  47
  48 The levels are: 0 (errors), 1 (warnings), 2 (notices), 3 (info).
  49 Each level will include messages of a lower level.
  50
  51 By default
  52 .BR swarm " logs to stderr, at level 2.
  53
  54 Any errors occuring in locally running shells will also be sent to the log file.
  55
  56 .BR Note: " If swarm runs as a daemon, stderr (and hence all log messages) detached
  57 .IR unless " the
  58 .BR -l " option is used.
  59
  60 .BR Note: " Remote shells will log messages and stderr to ~/.swarm.slave.log
  61
  62 .TP
  63 .BI -p " port"
  64 Sets the port number to use for connections to remote hosts.
  65
  66 By default, swarm does not use a fixed port; the port numbers for connections are chosen dynamically. Initially swarm uses ssh (port 22) to start remote swarm slave instances, passing a port to connect to as an argument. Subsequent ports for shell processes are sent to the slave swarm instance over this connection, which connects to the ports and starts the shell processes.
  67 .TP
  68 .BI --daemon
  69 Run
  70 .B swarm
  71 as a daemon in the current directory.
  72 .B Swarm
  73 will background itself by using
  74 .BR fork "(2), and attach stdin to a " fifo "(7).
  75 The daemon will continue to run regardless of any EOF sent to the input
  76 .BR fifo "(7) until it receives an EXIT directive."
  77
  78 Unless the
  79 .BR -o " option is also used, the daemon's stdout will be redirected to /dev/null".
  80
  81 Unless the
  82 .BR -l " option is also used, the daemon's stderr (and all log messages) will be redirected to /dev/null".
  83
  84 Subsequent instances of
  85 .BR swarm " invoked with the " -c " option or a script file in the same directory as the daemon will not start their own shells, and will send the command to the daemon's input
  86 .BR fifo "(7). Certain directives will affect the behaviour of the 'wrapping' swarm. The daemon
  87 .BR does " " not " send any output to the wrapping instance of " swarm ".
  88
  89 Subsequent instances of
  90 .BR swarm " invoked without the " -c " option or a script file in the same directory will report an error.
  91
  92 It is of course possible to write commands directly to the daemon's input fifo using
  93 .BR echo "(1) or any other program. Using
  94 .BR swarm " is preferred, because it will check input for directives that will affect its behaviour.
  95
  96 .BR Note: " The 'daemon' is not really an official Unix style daemon, but 'daemon' sounds much cooler than 'background process'.
  97
  98
  99 .SH ARGUMENTS
 100 If the
 101 .BR -c " option was not supplied, a single argument remaining after option processing is assumed to name a file containing valid shell commands and
 102 .BR swarm " directives. If the
 103 .BR -c " option was also supplied, or there was more than a single additional argument, " swarm " will report an error and exit
 104
 105 .SH INPUT
 106 .B Swarm
 107 treats each line of input as a seperate command to send to a shell.
 108 By default, each command is sent to the first available shell that isn't currently executing a command.
 109
 110
 111 .SH OUTPUT
 112 .B Swarm
 113 will output the results of completed shell commands in the order of completion.
 114 .B swarm
 115 puts a prefix '%d: ' in front of the output to indicate the order in which commands were received.
 116 .PP
 117 It is also possible to direct the output of commands to specified files using the OUTPUT directive. This is probably more useful for scripting purposes.
 118
 119 .SH DIRECTIVES
 120 A directive is any line that starts and ends with a '#' character.
 121 .PP
 122 If a line starts with a '#' but does not contain a second '#', it is treated as a comment.
 123 .PP
 124 If a line contains characters
 125 .I after
 126 the second '#' character, it is treated as a SHELL SPECIFIC COMMAND,
 127 .I not
 128 a DIRECTIVE.
 129 .PP
 130 .B Swarm
 131 understands several directives which can be used to control its behaviour at runtime. Any unrecognised directive is treated as a comment.
 132
 133 .TP
 134 .B EXIT
 135 Tell
 136 .B swarm
 137 to quit
 138 .TP
 139 .BI OUTPUT " [file]"
 140 If
 141 .I file
 142 is supplied, the output of all commands received before the next OUTPUT directive will be sent to the file.
 143 The file is created if it didn't exist, and overwritten if it did exist.
 144
 145 If
 146 .I file
 147 contains a '%d' format string, the output of commands will be sent to individual files, where the filenames are created from a call to
 148 .B sprintf(3)
 149 using the commands number as a format argument, and
 150 .I file
 151 as the format string.
 152
 153 If
 154 .I file
 155 is not supplied, the output of commands received before the next OUTPUT directive will not be saved to any file.
 156
 157 .TP
 158 BARRIER
 159 .BR Swarm " will continue to read input and create tasks, but will not actually send any commands until all currently executing commands are finished.
 160
 161 .TP
 162 BARRIER BLOCK
 163 This directive is intended for use with the
 164 .BR -c " option. If a shell script starts a swarm daemon, running swarm -c '#BARRIER BLOCK#' allows the script to block until the swarm daemon finishes all tasks."
 165
 166 .BR WARNING: " Sending BARRIER BLOCK to a swarm daemon
 167 .I without
 168 using a wrapping instance of
 169 .BR swarm " will cause the swarm daemon to hang after it has completed all tasks.
 170
 171 For a non-daemon instance of swarm, this directive is essentially identical to BARRIER.
 172
 173 .TP
 174 .BI ABSORB " host[:name] [processes]
 175 .B Swarm
 176 will start and connect to shells on the remote host and name them accordingly. An exec'd
 177 .BR ssh "(1) is used to start the remote shells."
 178
 179 The default number of
 180 .I processes
 181 is equal to the number of CPUs on the remote host.
 182 The default
 183 .I name
 184 is the same as
 185 .I host.
 186
 187 .BR Swarm " will start instances of " ssh "(1) and use remote port forwarding to secure the connections.
 188
 189 .TP
 190 .BI ABSORB UNSECURE host[:name] [processes]
 191 .B There are security issues associated with the use of this directive
 192
 193 This directive is the same as ABSORB, except no
 194 .BR ssh "(1) instances will be spawned for remote port forwarding; all data will be sent unencrypted."
 195
 196 Obviously using unencrypted connections is faster, but dangerous.
 197
 198
 199
 200 .SH SHELL SPECIFIC COMMANDS
 201 By default, any command is sent to the first available shell.
 202 .PP
 203 A line containing two '#' characters followed by a command will be sent to any shells with names matching a POSIX regex between the '#' characters.
 204 .PP
 205 To send the command only to the first available shell with name matching the regex, the regex should be followed with ' &'.
 206 .PP
 207 Shells are normally named according to the host on which they are running, and the order they were spawned. The format is 'host:X' where X is an integer greater or equal to zero. Shells running locally are called 'local:X'. Using the ABSORB directive, it is possible to give remote shells a name that is not the same as the hostname of the remote host running the shell.
 208 .PP
 209 .TP
 210 To print the names of all shells, run:
 211 #.*# echo $name
 212 .TP
 213 To print the name of the first available shell, run:
 214 #.* &# echo $name
 215
 216 .TP
 217 To run a command only on the shell called 'local:0':
 218 #local:0# command
 219
 220 .SH EXITED SHELLS / SIGNAL HANDLING
 221 .BR Swarm " detects when locally running shell exits (using a handler for " SIGCHLD "). If the shell exits normally, regardless of error code,
 222 .BR swarm " will create a new shell to replace it. If the shell exits because of a signal that caused it to terminate,
 223 .BR swarm " will send " SIGTERM " to itself, which will cause itself (and as a result all other shells) to exit.
 224
 225 If a remote shell exits, for whatever reason,
 226 .BR swarm " will create a new shell to replace it. " Swarm " has no knowledge of and will not react to signals sent to remote shells on the remote host.
 227
 228 If
 229 .BR swarm " itself exits for whatever reason, it will terminate all local and remote shells.
 230
 231 .SH SECURITY ISSUES
 232 .B Never allow ssh access from accross a public internet to a host with swarm installed.
 233 .PP
 234 When the ABSORB UNSECURE directive is read,
 235 .B swarm
 236 will use
 237 .BR ssh "(1)
 238 to start slaves processes on the remote host.
 239 .PP
 240 These will then open
 241 .I unencrypted
 242 connections to the master. Because commands are sent as plain text over the network,
 243 The remote hosts become vulnerable to "man in the middle" attacks.
 244
 245 Never use ssh keys with empty passphrases, and restrict access to hosts with
 246 .BR swarm "installed.
 247
 248 .SH BUGS
 249 .B Swarm
 250 is very recently developed and therefore probably has a shit load of bugs. Probably related to buffering.
 251 .PP
 252 Do not place whitespace after a directive, or it will be treated as a host specific command.
 253 .PP
 254 The stderr of remote shells will always be lost to the void.
 255 .PP
 256 Using things that aren't shells with the
 257 .BR -s " option won't work, because " swarm " automatically adds extra commands for the shells.
 258 .PP
 259 Writing three bell characters in a row will cause
 260 .BR swarm " to break, because it looks for three bell characters to signal the end of output from each command."
 261 .PP
 262 .BR Swarm " does try to be nice and tell shells to 'exit', but usually this doesn't work and it sends them a " kill "(2)."
 263 .PP
 264 There are probably bugs with parsing, like assuming you never use ':' as part of a filename or a name for a shell, etc.
 265 Just don't do it and it won't break.
 266 .PP
 267 Report any other bugs to [email protected]
 268 .SH AUTHOR
 269 Sam Moore ([email protected])
 270 .SH SEE ALSO
 271 .BR bash "(1), " ssh "(1)."
 272