Provided by: empty-expect_0.6.19b-1ubuntu1_amd64 bug

NAME

       empty - run processes under pseudo-terminal sessions

SYNOPSIS

       empty -f [-i fifo1 -o fifo2] [-p file.pid] [-L file.log] command [command args]
       empty -w [-Sv] [-t n] [-i fifo2 -o fifo1] key1 [answer1] ... [keyX answerX]
       empty -s [-Sc] -o fifo1 [request]
       empty -r [-b size] [-t n] [-i fifo2]
       empty -l
       empty -k [pid] [signal]
       empty -h

DESCRIPTION

       empty  is  an  utility  that  provides  a simple interface to execute and/or interact with
       processes under pseudo-terminal sessions. This tool is definitely useful in programming of
       shell  scripts which are used to communicate with interactive programs like telnet or ftp.
       In some cases empty can be a substitution for  TCL/expect  or  other  similar  programming
       tools.

       There  are  several  common  forms of command lines for empty.  But the first execution of
       empty is usually a start in the daemon mode to fork a new  command  (process)  under  PTY-
       session.  This  can  be  done  with  -f  key.   An interface for the input and output data
       channels of the forked process is performed by two fifo files which names may be specified
       with -i and -o keys. These files are automatically created/deleted any time you start/exit
       empty daemon, so you must not create them manually. If you  did  not  specify  these  fifo
       files  in the command line, empty names them by itself basing on its PID and PID of forked
       PTY process.

       At this point any application can easily communicate with forked process by  writing  data
       to  the  input fifo and reading answers from the output fifo, see EXAMPLES section for the
       details. To simplify this operations, empty offers an interface to just send any data (use
       -s  key),  or even to watch the output fifo for multiple keyphrases and reply to the input
       fifo with one of the responses (see -w key).

       Note!  Input fifo for empty -f ...  is usually an output fifo for empty -w  and  empty  -s
       forms. And output fifo of empty -f ...  is an input fifo for empty -w ...

       If  something goes wrong the forked process may be killed by the standard kill command, or
       using -k key of empty.  See -p option to save PID of empty daemon process.

       The following options are available:

       -f          fork, spawn, start or execute a new process specified by the command  and  its
                   arguments.  If  you omit fifo files, empty with its job control algorithm will
                   create them under /tmp directory using this templates:  empty.PPID.PID.in  and
                   empty.PPID.PID.out,  here PPID is usually your shell system process ID and PID
                   is system process ID of empty-daemon.

       -s          send data (request) to the forked process. If fifo file was not specified with
                   -o  key,  empty will try to find an automatically created fifo file it in /tmp
                   directory. Instead of command line you can send your request or data  directly
                   to standard input (stdin) of empty

       -w          watch  for  one  or  more  keyphrases  and  if specified send the appropriated
                   response to the input fifo.  If response is  not  set,  empty  waits  for  the
                   proper  keyphrase  then exits. With -w key empty returns the number of matched
                   keyphrase-response pair, or 255 if fails to find this match (see  -t  key  for
                   details of possible exit on timeout).

       -r          read  from output FIFO one line (default) or one block of data (if -b size was
                   specified). If -t n key was placed, exit on timeout.

       -l          list automatically created jobs by your shell.  NB!  Your custom  jobs,  which
                   fifo files you specified with -i and -o keys, are not displayed. So if you did
                   not specify fifo files with -i and -o keys all operations are done  under  the
                   job marked current

       -k          send  signal to the process with pid.  If you did not specify pid, empty tries
                   to find it within the list of automatically created jobs. If signal is omitted
                   the default SIGTERM is used.

       -h          print short help message and exit

       -i fifo1    a fifo file, which is used as input for a forked process.

       -o fifo2    a fifo file, which is used as output for a forked process.

       -L file.log This option allows to log the whole empty session to a file. Marks >>> and <<<
                   show the directions of data flow.

       --logfile-mode=mode
                   This option allows to choose the mode of the log  file  created  with  the  -L
                   option.  The default mode is 0600.

       -p file.pid Save PID of empty daemon process to a file

       -t n        If  input  FIFO  is  empty,  wait for n seconds (default is 10) to receive the
                   keyphrase then exit on timeout with 255 code.

       -c          force empty to use stdin for data or requests.

       -S          Strip the last character from the input. Works with -s and -w keys

       -v          kvazi verbose mode. Show all contents of received buffer.

EXAMPLES

       Start a new PTY-session with telnet to localhost:
            empty -f -i in.fifo -o out.fifo -p empty.pid -L empty.log telnet localhost

       Interact with telnet:
            empty -w -i out.fifo -o in.fifo ogin 'my_user\n'
            empty -w -i out.fifo -o in.fifo assword 'my_password\n'

       Send commands to telnet with empty:
            empty -s -o in.fifo who
            empty -s -o in.fifo "ls -la /\n"

       The same using STDIN:
            echo who | empty -s -o in.fifo
            echo "ls -la /" | empty -s -o in.fifo

       Just cat output from telnet:
            cat out.fifo

       Read one line from out.fifo:
            empty -r -i out.fifo

       Send commands to telnet with ordinary echo:
            echo "who am i" > in.fifo
            echo "uname -a" > in.fifo

       Kill a process with PID 1234:
            empty -k 1234
       or
            kill 1234

       Telnet session with automatically created jobs:
            empty -f telnet localhost

       Interact with telnet using job control:
            empty -w ogin 'my_user\n'
            empty -w assword 'my_password\n'

       List automatically created jobs:
            empty -l

            PPID    PID     TYPE    FILENAME
            479     706     in      /tmp/empty.479.706.in
            479     706     out     /tmp/empty.479.706.out
            479     711     in      /tmp/empty.479.711.in
            479     711     out     /tmp/empty.479.711.out

            479     711     current

SECURITY

       It is considered insecure to send a password in the command line like this:

            empty -w assword 'my_password\n'

       or like this:

            empty -s 'my_password\n'

       The reason is that the command line arguments are visible to the  system  while  empty  is
       running.  Any local user can see them with ps(1), sometimes they are visible even remotely
       with finger(1).  Also your server may have some  monitoring  tools  which  may  store  the
       output from ps(1) in their logs. There are also other, more complicated ways to compromise
       this information. Generally, you should take command line arguments as (possibly)  visible
       to every one unless you really know what you're doing.

       empty  with  '-s'  flag  runs quickly in most cases, but still it can hang for a number of
       reasons (like fifo overloading), and even if it runs quick you still cannot be  sure  that
       no  one will see its command line arguments even in this short time.  empty with '-w' flag
       is even worse because it must wait for the keyphrase.

       A better way to send the password to the supervised program is to read it from file:

            empty -s [common options] <./password-file

       or from a pipe:

            get-password-of-user "$user" |empty -s [common options]

       You should still make sure that you do not  send  any  password  via  command  line  while
       creating  this  file,  and certainly you should set some safe permissions to this file AND
       its directory (with the parent directories) before reading the password from the  file  OR
       writing the password to it.

       Another possible way is to use your shell's builtin (but see below):

            echo "$password" |empty -s [common options]

       Many  shells like bash(1), csh(1) and FreeBSD's sh(1) do not call external echo(1) command
       but use their own builtin echo command. Since no external command is  started  (the  shell
       itself  does all that echo(1) must do), nothing is shown in the process list. It is beyond
       this manual page to discuss the way to make sure that your shell uses the builtin command.

RETURN VALUES

       If any error occurs empty usually exits with code 255. Otherwise  zero  or  some  positive
       value (see -w key) is returned.

SEE ALSO

       expect(1), chat(8)

AUTHOR

       empty  was  made  by Mikhail E. Zakharov. This software was based on the basic idea of pty
       version 4.0 Copyright (c) 1992, Daniel J. Bernstein but no  code  was  ported  from  pty4.
       SECURITY section of this manual page was contributed by Sergey Redin.

                                          March, 05 2006                                 empty(1)