Provided by: empty-expect_0.6.19b-1ubuntu1_amd64 
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)