Ncat can execute an external command after establishing a
connection. The command's standard input and output
streams are redirected to use Ncat's network connection. Anything received over
the connection is given to the command's stdin, and anything the
command writes to stdout is sent back out over the connection. This feature makes
almost any terminal application accessible over a network (with some
There are three ways of running a command:
runs a command without shell interpretation.
runs a command by passing a string to a system shell.
runs a Lua program using Ncat's built-in Lua interpreter.
takes the full pathname of a command to execute, along with its
arguments. The command is executed directly; Ncat does not interpret
the given string beyond splitting the command and its arguments.
shows an example of usage.
Example 3. Running a command with
ncat -l --exec "/bin/echo Hello."
works the same as
--exec, except that it
executes the command by passing it to /bin/sh -c
on Unix or cmd.exe /C on Windows.
You don't have to use the full pathname of the command if the
command is in the
Additionally you have access to shell facilities such as pipelines
and environment variable expansion.
shows a command run with
--sh-exec. This server,
when connected to, sends back the name of its working directory.
Example 4. Running a command with
ncat -l --sh-exec "echo `pwd`"
option takes the filename of a Lua program to run. Ncat runs the
program using its built-in interpreter and redirects its input and
output streams. Anything the program writes to standard output (for
io.write) is written
to the connection, and any reads from standard input come from the
connection. A nice thing about running programs written in Lua is that
the same interpreter is used on all platforms, in comparison with
shells that operate differently.
shows how to run a program stored in a file called
Example 5. Running a command with
ncat -l --lua-exec echo.lua
The exec options can be used in connect mode and listen mode. In
listen mode, Ncat accepts one connection, runs the command, and then
quits, just like listen mode without exec. But when listen mode is
Ncat will accept multiple connections, forking off a new handler for
each. This works even in UDP mode; the usual limit of only one client
doesn't apply. The server will keep running until you press
otherwise terminate it externally. In this way Ncat can work much like
Many examples of the use of
--sh-exec in listen mode are found in
the section called “Emulating Diagnostic Services”.
Example 6. Running an inetd-like server
ncat -l --keep-open --exec "/bin/echo Hello."
Whatever the exec mode, Ncat sets environment variables in the spawned
program's environment that describe the connection.
The IP address and port number of the remote host. In connect mode, it's
the target's address; in listen mode, it's the client's address.
The IP address and port number of the local end of the connection.
The protocol in use: one of
shows the output of a Lua program that reads these variables.
You can see these environment variables in action by running this
Example 7. Exec environment variables
The contents of the program
print(string.format("%s %q", v, os.getenv(v)))
The output of running the program:
ncat -l --lua-exec env.lua &
Any program that takes input and produces output can be executed by
Ncat, but not all programs are suited to this kind of interaction.
Many programs buffer their input and output,
so if they receive some bytes, they many not process those bytes and
write output until their input buffer is full, or the output may be
deferred until the output buffer is full. If another program sends a
few bytes and then waits for a response, it may hang indefinitely.
Buffers are flushed when input or output ends, so even those
programs that don't work interactively will work when run on an
entire file at a time.
Be careful when using the various exec
options. It can be dangerous to connect a
new application to a network, especially one that wasn't written
with potentially hostile input in mind. Any local vulnerabilities in
an application may become remote vulnerabilities when you execute
it through Ncat.