ncat: Usage, Options & Common CI Errors
ncat is the Nmap project's feature-rich netcat with TLS, proxy, and exec support.
ncat is a consistent, cross-platform netcat from the Nmap project - useful in CI to stand up a throwaway TCP/TLS listener (a mock endpoint) or to test connectivity, with behavior that does not vary the way classic netcat does.
What it does
ncat connects to or listens on TCP/UDP sockets, optionally with TLS (--ssl), connection brokering (-k for persistent listeners), and command execution (-e/--sh-exec). In CI it commonly fakes a server for an integration test or acts as a reliable port-connectivity probe.
Common usage
ncat -l 8080 # listen on TCP 8080
ncat -lk 8080 --sh-exec "echo ok" # keep-open mock responder
ncat --ssl example.com 443 # TLS connection
ncat -z -w 3 localhost 5432 && echo open # port check
echo "hello" | ncat -w 2 localhost 8080Options
| Flag | What it does |
|---|---|
| -l | Listen mode |
| -k | Keep listening after a client disconnects |
| -z | Connect without sending data (port check) |
| -w <secs> | Connect/idle timeout |
| --ssl | Wrap the connection in TLS |
| -e / --sh-exec <cmd> | Run a command on connect |
Common errors in CI
Without -k, a listener exits after the first client disconnects, so a second test connection gets "Connection refused" - add -k for a reusable mock. "Ncat: bind to ... Address already in use" means the port is taken (a previous run did not release it) - pick another port or kill the holder. ncat comes from the nmap package, which slim images lack ("ncat: command not found"). -e/--sh-exec can be disabled in hardened builds for safety. Unlike BusyBox nc, ncat's -z is reliable, making it a good cross-platform port probe.