--- name: "empty" section: "1" platform: "linux" package: "empty-expect" version: "0.6.20b-1+b1" release: "Debian 9 (Stretch)" platforms: ["linux"] url: "https://new.carta.tech/empty" --- # empty(1) run processes under pseudo-terminal sessions ## 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)](/ps/1.md), sometimes they are visible even remotely with [finger(1)](/finger/1.md). Also your server may have some monitoring tools which may store the output from [ps(1)](/ps/1.md) 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)](/bash/1.md), [csh(1)](/csh/1.md) and FreeBSD's [sh(1)](/sh/1.md) do not call external [echo(1)](/echo/1.md) command but use their own builtin echo command. Since no external command is started (the shell itself does all that [echo(1)](/echo/1.md) 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)](/expect/1.md), [chat(8)](/chat/8.md) ## 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.