NAME

       sc_remoted — interact with a collection of remotely controlled scamper instances

SYNOPSIS

       sc_remoted  [-?46D]  [-O  options] [-P [ip:]port] [-U directory] [-c tls-certificate] [-p tls-privatekey]
                  [-e pidfile] [-Z zombie-time]

DESCRIPTION

       The sc_remoted utility provides the ability to connect to a  scamper(1)  instance  running  remotely  and
       interact with it by issuing commands and receiving results in warts format.  The options are as follows:

       -?      prints a list of command line options and a synopsis of each.

       -D      causes sc_remoted to operate as a daemon.

       -4      causes sc_remoted to only listen for IPv4-based connections.

       -6      causes sc_remoted to only listen for IPv6-based connections.

       -O options
               allows  the  behavior  of sc_remoted to be further tailored.  The current choices for this option
               are:
                 -  allowgroup: allow members of the unix domain socket's group to access  to  the  unix  domain
                    sockets created by sc_remoted
                 -  allowother:  allow  anyone  on  the  system  access  to  the  unix domain sockets created by
                    sc_remoted
                 -  debug: print debugging messages
                 -  select: use select(2) with all sockets, rather than epoll(2) or kqueue(2)

       -P [ip:]port
               specifies the IP address and port on the local host where sc_remoted should listen  for  incoming
               connections.   If  an  IP  address  is  not specified, sc_remoted will listen on all available IP
               addresses for incoming connections.

       -U directory
               specifies the directory on the local host where unix domain sockets corresponding to remote hosts
               should be placed.

       -c tls-certificate
               specifies the server certificate file in PEM format to advertise to remote scamper(1) instances.

       -p tls-privatekey
               specifies the private key file in PEM format that corresponds to the certificate file.  This  key
               should have a passphrase.  sc_remoted will prompt for the passphrase when starting up.

       -e pidfile
               specifies the name of a file to write the process ID to.

       -Z zombie-time
               specifies the length of time sc_remoted will retain state for a disconnected scamper(1) instance,
               allowing it to resume.  By default sc_remoted retains state for 15 minutes.

EXAMPLES

       The intended use of the remote control socket built into scamper(1) is as follows.  A central server with
       IP  addresses  192.0.2.1 and 2001:db8::1 runs a sc_remoted process listening on a port for remote scamper
       process, placing control sockets in a specified directory:

             sc_remoted -P 31337 -U scamper-remote-sockets

       Then, a remote host with IP address 198.51.100.55 runs scamper and connects to the remote controller:

             scamper -R 192.0.2.1:31337

       The sc_remoted process places a unix domain socket in the directory corresponding to the remote  process.
       The name corresponds to the source IP address and port the remote scamper process connected to controller
       with.  If the scamper process used source port 1025, then the unix domain socket's name will be

             scamper-remote-sockets/198.51.100.55:1025

       If  a  second  remote  host  with  IP  address  2001:db8:1234::1  runs scamper and connects to the remote
       controller:

             scamper -R [2001:db8::1]:31337

       The same sc_remoted process will place another unix domain socket in the directory corresponding  to  the
       remote process.  If the scamper process used source port 1026, then the unix domain socket's name will be

             scamper-remote-sockets/2001:db8:1234::1.1026

USING TRANSPORT LAYER SECURITY

       sc_remoted  and  scamper  support the use of transport layer security (TLS) using OpenSSL to authenticate
       and encrypt communications between sc_remoted and  scamper.   To  use  this  support  requires  a  public
       certificate  signed  by  a  certificate  authority.   Scamper  will  verify  the certificate presented by
       sc_remoted and disconnect if the certificate presented by sc_remoted cannot be validated.

       Generating a certificate that will be accepted by scamper requires you to create  a  certificate  request
       and  pass  it  for signing to a certificate authority.  To generate a private key in file remotepriv.pem,
       and a request to sign the key in remotereq.pem:

             openssl req -new -keyout remotepriv.pem -out remotereq.pem

       and  then  send  the  remotereq.pem  file  to  the  certificate  authority  for  signing.   Do  not  send
       remotepriv.pem;  that  key  must  remain private to you.  When openssl prompts for a passphrase, choose a
       passphrase that is unique and keep the passphrase secret.  When your chosen certificate  authority  signs
       your  private  key,  it  will  return  a file which we will call remotecert.pem.  Both remotecert.pem and
       remotepriv.pem are required parameters to sc_remoted to enable TLS support:

             sc_remoted -P 31337 -U scamper-remote-sockets -c remotecert.pem -p remotepriv.pem

       and then passing the -O tls option to scamper:

             scamper -R example.com:31337 -O tls

SIGNAL HANDLERS

       sc_remoted installs handlers for two signals: SIGINT  and  SIGHUP.   SIGINT  causes  sc_remoted  to  exit
       gracefully.  SIGHUP causes sc_remoted to reload the TLS certificate and private key, without interrupting
       existing TLS connections.

SEE ALSO

       scamper(1), sc_attach(1), sc_wartsdump(1), warts(5), openssl(1)

AUTHORS

       sc_remoted was written by Matthew Luckie <mjl@luckie.org.nz>.

Debian                                           March 28, 2020                                    SC_REMOTED(1)