cs.1

.\" Copyright (c) 2014 Andy Kosela.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"   notice, this list of conditions and the following disclaimer in the
.\"   documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.Dd July 19, 2017
.Dt CS 1
.Os
.Sh NAME
.Nm cs
.Nd concurrent ssh client
.Sh SYNOPSIS
.Nm cs
.Bk -words
.Op Fl emqrstuVv1
.Op Fl c Ar file
.Op Fl cmd
.Op Fl cname
.Op Fl d Ar file
.Op Fl dd
.Op Fl du Ar path
.Op Fl f Ar script.sh
.Op Fl h Ar hosts_file
.Op Fl hba
.Op Fl i Ar identity_file
.Op Fl io
.Op Fl ip
.Op Fl l Ar login_name
.Op Fl lip
.Op Fl mx
.Op Fl nc
.Op Fl nmap
.Op Fl ns
.Op Fl o Ar output_file
.Op Fl P Ar port
.Op Fl p Ar path
.Op Fl ping
.Op Fl soa
.Op Fl to Ar timeout
.Op Fl top
.Op Fl tr
.Op Fl tri
.Op Fl uname
.Op Fl vm
.Op Ar command
.Sm off
.Oo
.Op Ar user No @
.Ar host
.Oc
.Sm on
.Ar ...
.Sh DESCRIPTION
.Nm
is a program for concurrently executing local or remote commands on
multiple hosts.
It is using OpenSSH for running remote commands.
Its main purpose is to help automate and manage large network of hosts.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl c Ar file
Copy
.Ar file
to the remote machine.
.It Fl cmd
Run an arbitrary local command concurrently on multiple hosts.
.It Fl cname
Run a local DNS query of type CNAME.
.It Fl d Ar file
Download
.Ar file
from the remote machine.
It will be saved in a directory named after the remote host only when
you download from multiple servers.
.It Fl dd
Prints basic hardware information for a specific host (sudo(8) and
dmidecode(8) required).
.It Fl du Ar path
Prints the list of largest files in a specific directory (sudo(8)
required, units in M).
.It Fl e
Prints hosts with errors only.
.It Fl f Ar script.sh
Run a local shell script on the remote host.
.It Fl h Ar hosts_file
Read hostnames from the given
.Ar hosts_file .
Lines in the
.Ar hosts_file
can include commented lines beginning with a
.Sq Li #
and only one host per line is allowed.
.It Fl hba
Lists installed HBAs and their WWPNs (Linux only).
.It Fl i Ar identity_file
Selects a file from which the identity (private key) for public key
authentication is read.
The default is
.Ar ~/.ssh/id_rsa .
.It Fl io
Run remote iostat(1) on a specific host.
.It Fl ip
Lists network interfaces.
.It Fl l Ar login_name
Specifies the user to log in as on the remote machine.
This also may be specified on a per-host basis on the command line.
.It Fl lip
Scans storage interconnects for new luns (Linux only).
.It Fl m
Lists mounted filesystems on a speficic host.
.It Fl mx
Run a local DNS query of type MX.
.It Fl nc
Tests a specific port with nc(1).
Default is 22/tcp.
.It Fl nmap
Scans host with nmap(1).
.It Fl ns
Run a local DNS query of type NS.
.It Fl o Ar output_file
Saves standard output and standard error to a file.
.It Fl P Ar port
Port to connect to on the remote host.
.It Fl p Ar path
Specifies remote or local path for files in a remote copy or download
mode.
.It Fl ping
Sends ICMP ECHO_REQUEST to network hosts.
.It Fl q
Quiet mode.
Supresses verbose standard output from remote machines.
This mode reports success or failure only.
.It Fl r
Recursively copy entire directories.
It follows symbolic links encountered in the tree traversal.
.It Fl s
Sort output.
.It Fl soa
Run a local DNS query of type SOA.
.It Fl t
Force pseudo-tty allocation.
.It Fl to Ar timeout
Specifies the timeout (in seconds) used when connecting to the SSH
server.
The default value is 4 seconds.
.It Fl top
Run remote top(1) in batch mode on a specific host.
.It Fl tr
Run local traceroute(8).
.It Fl tri
Run local traceroute(8) using ICMP (local sudo(8) required).
.It Fl uname
Prints remote system information including OS version.
.It Fl u
Run remote uptime(1) on a specific host.
.It Fl V
Displays the version number and exit.
.It Fl v
Verbose mode.
Causes
.Nm
to print debugging messages from ssh(1) about its progress.
This is helpful in debugging connection, authentication, and
configuration problems.
Multiple
.Fl v
options increase the verbosity.
The maximum is 3.
.It Fl vm
Run remote vmstat(8) on a specific host.
.It Fl 1
One line mode, useful for sorting output later.
.El
.Sh AUTHENTICATION
The default method for authentication is a public key authentication
which serves its purpose when dealing with multiple hosts.
You can read more about public key authentication in
.Xr ssh 1 .
.Sh EXIT STATUS
.Ex -std cs
.Sh EXAMPLES
Run a series of commands on hosts foo and bar:
.Pp
.Dl $ cs 'uptime; uname -a' foo bar
.Pp
Run a command on multiple hosts specified in a hosts_file:
.Pp
.Dl $ cs -h hosts_file uptime
.Pp
Run a local shell script on multiple hosts:
.Pp
.Dl $ cs -f script.sh foo{1..100}
.Pp
Run a local shell script with sudo(8) on multiple hosts:
.Pp
.Dl $ cs -t -f script.sh foo{1..100}
.Pp
Copy file to multiple hosts using a specific remote path:
.Pp
.Dl $ cs -c file -h hosts_file -p /foo/bar
.Pp
Download file from host:~ foo to a current working directory:
.Pp
.Dl $ cs -d file foo
.Pp
Download recursively files from /foo/bar from multiple hosts to a
specific local path /tmp with subdirectories named after remote hosts:
.Pp
.Dl $ cs -r -d '/foo/bar/*' -h hosts_file -p /tmp
.Pp
Run a command on multiple hosts and sort the output:
.Pp
.Dl $ cs -1 -h hosts_file 'free -m | grep Swap' | sort -rnk4 | head
.Pp
Run local ping(1) on multiple hosts:
.Pp
.Dl $ cs -ping foo{1..100}
.Pp
Show name and size of all files matching the glob pattern:
.Pp
.Dl $ cs -du '/var/log/mes*' foo{1..100}
.Sh SEE ALSO
.Xr scp 1 ,
.Xr ssh 1 ,
.Xr ssh_config 5 ,
.Xr sudo 8
.Sh AUTHORS
.An Andy Kosela Aq akosela@andykosela.com