logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

nc.1 (15628B)


  1. .\" $OpenBSD: nc.1,v 1.98 2024/04/01 12:40:18 deraadt Exp $
  2. .\"
  3. .\" Copyright (c) 1996 David Sacerdote
  4. .\" All rights reserved.
  5. .\"
  6. .\" Redistribution and use in source and binary forms, with or without
  7. .\" modification, are permitted provided that the following conditions
  8. .\" are met:
  9. .\" 1. Redistributions of source code must retain the above copyright
  10. .\" notice, this list of conditions and the following disclaimer.
  11. .\" 2. Redistributions in binary form must reproduce the above copyright
  12. .\" notice, this list of conditions and the following disclaimer in the
  13. .\" documentation and/or other materials provided with the distribution.
  14. .\" 3. The name of the author may not be used to endorse or promote products
  15. .\" derived from this software without specific prior written permission
  16. .\"
  17. .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  18. .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  19. .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  20. .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  21. .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  22. .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  23. .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  24. .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  25. .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  26. .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  27. .\"
  28. .Dd $Mdocdate: April 1 2024 $
  29. .Dt NC 1
  30. .Os
  31. .Sh NAME
  32. .Nm nc
  33. .Nd arbitrary TCP and UDP connections and listens
  34. .Sh SYNOPSIS
  35. .Nm nc
  36. .Op Fl 46cDdFhklNnrStUuvz
  37. .Op Fl C Ar certfile
  38. .Op Fl e Ar name
  39. .Op Fl H Ar hash
  40. .Op Fl I Ar length
  41. .Op Fl i Ar interval
  42. .Op Fl K Ar keyfile
  43. .Op Fl M Ar ttl
  44. .Op Fl m Ar minttl
  45. .Op Fl O Ar length
  46. .Op Fl o Ar staplefile
  47. .Op Fl P Ar proxy_username
  48. .Op Fl p Ar source_port
  49. .Op Fl R Ar CAfile
  50. .Op Fl s Ar sourceaddr
  51. .Op Fl T Ar keyword
  52. .Op Fl V Ar rtable
  53. .Op Fl W Ar recvlimit
  54. .Op Fl w Ar timeout
  55. .Op Fl X Ar proxy_protocol
  56. .Op Fl x Ar proxy_address Ns Op : Ns Ar port
  57. .Op Fl Z Ar peercertfile
  58. .Op Ar destination
  59. .Op Ar port
  60. .Sh DESCRIPTION
  61. The
  62. .Nm
  63. (or
  64. .Nm netcat )
  65. utility is used for just about anything under the sun involving TCP,
  66. UDP, or
  67. .Ux Ns -domain
  68. sockets.
  69. It can open TCP connections, send UDP packets, listen on arbitrary
  70. TCP and UDP ports, do port scanning, and deal with both IPv4 and
  71. IPv6.
  72. Unlike
  73. .Xr telnet 1 ,
  74. .Nm
  75. scripts nicely, and separates error messages onto standard error instead
  76. of sending them to standard output, as
  77. .Xr telnet 1
  78. does with some.
  79. .Pp
  80. Common uses include:
  81. .Pp
  82. .Bl -bullet -offset indent -compact
  83. .It
  84. simple TCP proxies
  85. .It
  86. shell-script based HTTP clients and servers
  87. .It
  88. network daemon testing
  89. .It
  90. a SOCKS or HTTP ProxyCommand for
  91. .Xr ssh 1
  92. .It
  93. and much, much more
  94. .El
  95. .Pp
  96. The options are as follows:
  97. .Bl -tag -width Ds
  98. .It Fl 4
  99. Use IPv4 addresses only.
  100. .It Fl 6
  101. Use IPv6 addresses only.
  102. .It Fl C Ar certfile
  103. Load the public key part of the TLS peer certificate from
  104. .Ar certfile ,
  105. in PEM format.
  106. Requires
  107. .Fl c .
  108. .It Fl c
  109. Use TLS to connect or listen.
  110. Cannot be used together with any of the options
  111. .Fl FuU .
  112. .It Fl D
  113. Enable debugging on the socket.
  114. .It Fl d
  115. Do not attempt to read from stdin.
  116. .It Fl e Ar name
  117. Only accept the TLS peer certificate if it contains the
  118. .Ar name .
  119. Requires
  120. .Fl c .
  121. If not specified,
  122. .Ar destination
  123. is used.
  124. .It Fl F
  125. Pass the first connected socket using
  126. .Xr sendmsg 2
  127. to stdout and exit.
  128. This is useful in conjunction with
  129. .Fl X
  130. to have
  131. .Nm
  132. perform connection setup with a proxy but then leave the rest of the
  133. connection to another program (e.g.\&
  134. .Xr ssh 1
  135. using the
  136. .Xr ssh_config 5
  137. .Cm ProxyUseFdpass
  138. option).
  139. Cannot be used with
  140. .Fl c
  141. or
  142. .Fl U .
  143. .It Fl H Ar hash
  144. Only accept the TLS peer certificate if its hash returned from
  145. .Xr tls_peer_cert_hash 3
  146. matches
  147. .Ar hash .
  148. Requires
  149. .Fl c
  150. and cannot be used with
  151. .Fl T Cm noverify .
  152. .It Fl h
  153. Print out the
  154. .Nm
  155. help text and exit.
  156. .It Fl I Ar length
  157. Specify the size of the TCP receive buffer.
  158. .It Fl i Ar interval
  159. Sleep for
  160. .Ar interval
  161. seconds between lines of text sent and received.
  162. Also causes a delay time between connections to multiple ports.
  163. .It Fl K Ar keyfile
  164. Load the TLS private key from
  165. .Ar keyfile ,
  166. in PEM format.
  167. Requires
  168. .Fl c .
  169. .It Fl k
  170. When a connection is completed, listen for another one.
  171. Requires
  172. .Fl l .
  173. When used together with the
  174. .Fl u
  175. option, the server socket is not connected and it can receive UDP datagrams from
  176. multiple hosts.
  177. .It Fl l
  178. Listen for an incoming connection rather than initiating a
  179. connection to a remote host.
  180. Cannot be used together with any of the options
  181. .Fl psxz .
  182. Additionally, any timeouts specified with the
  183. .Fl w
  184. option are ignored.
  185. .It Fl M Ar ttl
  186. Set the TTL / hop limit of outgoing packets.
  187. .It Fl m Ar minttl
  188. Ask the kernel to drop incoming packets whose TTL / hop limit is under
  189. .Ar minttl .
  190. .It Fl N
  191. .Xr shutdown 2
  192. the network socket after EOF on the input.
  193. Some servers require this to finish their work.
  194. .It Fl n
  195. Do not perform domain name resolution.
  196. If a name cannot be resolved without DNS, an error will be reported.
  197. .It Fl O Ar length
  198. Specify the size of the TCP send buffer.
  199. .It Fl o Ar staplefile
  200. During the TLS handshake, load data to be stapled from
  201. .Ar staplefile ,
  202. which is expected to contain an OCSP response from an OCSP server in
  203. DER format.
  204. Requires
  205. .Fl c
  206. and
  207. .Fl C .
  208. .It Fl P Ar proxy_username
  209. Specifies a username to present to a proxy server that requires authentication.
  210. If no username is specified then authentication will not be attempted.
  211. Proxy authentication is only supported for HTTP CONNECT proxies at present.
  212. .It Fl p Ar source_port
  213. Specify the source port
  214. .Nm
  215. should use, subject to privilege restrictions and availability.
  216. Cannot be used together with
  217. .Fl l .
  218. .It Fl R Ar CAfile
  219. Load the root CA bundle for TLS certificate verification from
  220. .Ar CAfile ,
  221. in PEM format, instead of
  222. .Pa /etc/ssl/cert.pem .
  223. Requires
  224. .Fl c .
  225. .It Fl r
  226. Choose source and/or destination ports randomly
  227. instead of sequentially within a range or in the order that the system
  228. assigns them.
  229. .It Fl S
  230. Enable the RFC 2385 TCP MD5 signature option.
  231. .It Fl s Ar sourceaddr
  232. Set the source address to send packets from,
  233. which is useful on machines with multiple interfaces.
  234. For
  235. .Ux Ns -domain
  236. datagram sockets, specifies the local temporary socket file
  237. to create and use so that datagrams can be received.
  238. Cannot be used together with
  239. .Fl l
  240. or
  241. .Fl x .
  242. .It Fl T Ar keyword
  243. Change the IPv4 TOS/IPv6 traffic class value or the TLS options.
  244. .Pp
  245. For TLS options,
  246. .Ar keyword
  247. may be one of:
  248. .Cm noverify ,
  249. which disables certificate verification;
  250. .Cm noname ,
  251. which disables certificate name checking;
  252. .Cm notime ,
  253. which disables certificate validity time checking;
  254. .Cm clientcert ,
  255. which requires a client certificate on incoming connections; or
  256. .Cm muststaple ,
  257. which requires the peer to provide a valid stapled OCSP response
  258. with the handshake.
  259. The following TLS options specify a value in the form of a
  260. .Ar key Ns = Ns Ar value
  261. pair:
  262. .Cm ciphers ,
  263. which allows the supported TLS ciphers to be specified (see
  264. .Xr tls_config_set_ciphers 3
  265. for further details);
  266. .Cm protocols ,
  267. which allows the supported TLS protocols to be specified (see
  268. .Xr tls_config_parse_protocols 3
  269. for further details).
  270. Specifying TLS options requires
  271. .Fl c .
  272. .Pp
  273. For the IPv4 TOS/IPv6 traffic class value,
  274. .Ar keyword
  275. may be one of
  276. .Cm critical ,
  277. .Cm inetcontrol ,
  278. .Cm lowdelay ,
  279. .Cm netcontrol ,
  280. .Cm throughput ,
  281. .Cm reliability ,
  282. or one of the DiffServ Code Points:
  283. .Cm ef ,
  284. .Cm af11 No ... Cm af43 ,
  285. .Cm cs0 No ... Cm cs7 ;
  286. or a number in either hex or decimal.
  287. .It Fl t
  288. Send RFC 854 DON'T and WON'T responses to RFC 854 DO and WILL requests.
  289. This makes it possible to use
  290. .Nm
  291. to script telnet sessions.
  292. .It Fl U
  293. Use
  294. .Ux Ns -domain
  295. sockets.
  296. Cannot be used together with any of the options
  297. .Fl cFx .
  298. .It Fl u
  299. Use UDP instead of TCP.
  300. Cannot be used together with
  301. .Fl c
  302. or
  303. .Fl x .
  304. For
  305. .Ux Ns -domain
  306. sockets, use a datagram socket instead of a stream socket.
  307. If a
  308. .Ux Ns -domain
  309. socket is used, a temporary receiving socket is created in
  310. .Pa /tmp
  311. unless the
  312. .Fl s
  313. flag is given.
  314. .It Fl V Ar rtable
  315. Set the routing table to be used.
  316. .It Fl v
  317. Produce more verbose output.
  318. .It Fl W Ar recvlimit
  319. Terminate after receiving
  320. .Ar recvlimit
  321. packets from the network.
  322. .It Fl w Ar timeout
  323. Connections which cannot be established or are idle timeout after
  324. .Ar timeout
  325. seconds.
  326. The
  327. .Fl w
  328. flag has no effect on the
  329. .Fl l
  330. option, i.e.\&
  331. .Nm
  332. will listen forever for a connection, with or without the
  333. .Fl w
  334. flag.
  335. The default is no timeout.
  336. .It Fl X Ar proxy_protocol
  337. Use
  338. .Ar proxy_protocol
  339. when talking to the proxy server.
  340. Supported protocols are
  341. .Cm 4
  342. (SOCKS v.4),
  343. .Cm 5
  344. (SOCKS v.5)
  345. and
  346. .Cm connect
  347. (HTTPS proxy).
  348. If the protocol is not specified, SOCKS version 5 is used.
  349. .It Fl x Ar proxy_address Ns Op : Ns Ar port
  350. Connect to
  351. .Ar destination
  352. using a proxy at
  353. .Ar proxy_address
  354. and
  355. .Ar port .
  356. If
  357. .Ar port
  358. is not specified, the well-known port for the proxy protocol is used (1080
  359. for SOCKS, 3128 for HTTPS).
  360. An IPv6 address can be specified unambiguously by enclosing
  361. .Ar proxy_address
  362. in square brackets.
  363. A proxy cannot be used with any of the options
  364. .Fl lsuU .
  365. .It Fl Z Ar peercertfile
  366. Save the peer certificates to
  367. .Ar peercertfile ,
  368. in PEM format.
  369. Requires
  370. .Fl c .
  371. .It Fl z
  372. Only scan for listening daemons, without sending any data to them.
  373. Cannot be used together with
  374. .Fl l .
  375. .El
  376. .Pp
  377. .Ar destination
  378. can be a numerical IP address or a symbolic hostname
  379. (unless the
  380. .Fl n
  381. option is given).
  382. In general, a destination must be specified,
  383. unless the
  384. .Fl l
  385. option is given
  386. (in which case the local host is used).
  387. For
  388. .Ux Ns -domain
  389. sockets, a destination is required and is the socket path to connect to
  390. (or listen on if the
  391. .Fl l
  392. option is given).
  393. .Pp
  394. .Ar port
  395. can be specified as a numeric port number or as a service name.
  396. Port ranges may be specified as numeric port numbers of the form
  397. .Ar nn Ns - Ns Ar mm .
  398. In general,
  399. a destination port must be specified,
  400. unless the
  401. .Fl U
  402. option is given.
  403. For some options, the value 0 requests that the system choose a port number.
  404. .Sh CLIENT/SERVER MODEL
  405. It is quite simple to build a very basic client/server model using
  406. .Nm .
  407. On one console, start
  408. .Nm
  409. listening on a specific port for a connection.
  410. For example:
  411. .Pp
  412. .Dl $ nc -l 1234
  413. .Pp
  414. .Nm
  415. is now listening on port 1234 for a connection.
  416. On a second console
  417. .Pq or a second machine ,
  418. connect to the machine and port being listened on:
  419. .Pp
  420. .Dl $ nc -N 127.0.0.1 1234
  421. .Pp
  422. There should now be a connection between the ports.
  423. Anything typed at the second console will be concatenated to the first,
  424. and vice-versa.
  425. After the connection has been set up,
  426. .Nm
  427. does not really care which side is being used as a
  428. .Sq server
  429. and which side is being used as a
  430. .Sq client .
  431. The connection may be terminated using an
  432. .Dv EOF
  433. .Pq Sq ^D ,
  434. as the
  435. .Fl N
  436. flag was given.
  437. .Sh DATA TRANSFER
  438. The example in the previous section can be expanded to build a
  439. basic data transfer model.
  440. Any information input into one end of the connection will be output
  441. to the other end, and input and output can be easily captured in order to
  442. emulate file transfer.
  443. .Pp
  444. Start by using
  445. .Nm
  446. to listen on a specific port, with output captured into a file:
  447. .Pp
  448. .Dl $ nc -l 1234 > filename.out
  449. .Pp
  450. Using a second machine, connect to the listening
  451. .Nm
  452. process, feeding it the file which is to be transferred:
  453. .Pp
  454. .Dl $ nc -N host.example.com 1234 < filename.in
  455. .Pp
  456. After the file has been transferred, the connection will close automatically.
  457. .Sh TALKING TO SERVERS
  458. It is sometimes useful to talk to servers
  459. .Dq by hand
  460. rather than through a user interface.
  461. It can aid in troubleshooting,
  462. when it might be necessary to verify what data a server is sending
  463. in response to commands issued by the client.
  464. For example, to retrieve the home page of a web site:
  465. .Bd -literal -offset indent
  466. $ printf "GET / HTTP/1.0\er\en\er\en" | nc host.example.com 80
  467. .Ed
  468. .Pp
  469. Note that this also displays the headers sent by the web server.
  470. They can be filtered, using a tool such as
  471. .Xr sed 1 ,
  472. if necessary.
  473. .Pp
  474. More complicated examples can be built up when the user knows the format
  475. of requests required by the server.
  476. As another example, an email may be submitted to an SMTP server using:
  477. .Bd -literal -offset indent
  478. $ nc localhost 25 << EOF
  479. HELO host.example.com
  480. MAIL FROM:<user@host.example.com>
  481. RCPT TO:<user2@host.example.com>
  482. DATA
  483. Body of email.
  484. \&.
  485. QUIT
  486. EOF
  487. .Ed
  488. .Sh PORT SCANNING
  489. It may be useful to know which ports are open and running services on
  490. a target machine.
  491. The
  492. .Fl z
  493. flag can be used to tell
  494. .Nm
  495. to report open ports,
  496. rather than initiate a connection.
  497. For example:
  498. .Bd -literal -offset indent
  499. $ nc -z host.example.com 20-30
  500. Connection to host.example.com 22 port [tcp/ssh] succeeded!
  501. Connection to host.example.com 25 port [tcp/smtp] succeeded!
  502. .Ed
  503. .Pp
  504. The port range was specified to limit the search to ports 20 \- 30.
  505. .Pp
  506. Alternatively, it might be useful to know which server software
  507. is running, and which versions.
  508. This information is often contained within the greeting banners.
  509. In order to retrieve these, it is necessary to first make a connection,
  510. and then break the connection when the banner has been retrieved.
  511. This can be accomplished by specifying a small timeout with the
  512. .Fl w
  513. flag, or perhaps by issuing a
  514. .Qq Dv QUIT
  515. command to the server:
  516. .Bd -literal -offset indent
  517. $ echo "QUIT" | nc host.example.com 20-30
  518. SSH-1.99-OpenSSH_3.6.1p2
  519. Protocol mismatch.
  520. 220 host.example.com IMS SMTP Receiver Version 0.84 Ready
  521. .Ed
  522. .Sh EXAMPLES
  523. Open a TCP connection to port 42 of host.example.com, using port 31337 as
  524. the source port, with a timeout of 5 seconds:
  525. .Pp
  526. .Dl $ nc -p 31337 -w 5 host.example.com 42
  527. .Pp
  528. Open a TCP connection to port 443 of www.example.com, and negotiate TLS with
  529. any supported TLS protocol version and "compat" ciphers:
  530. .Pp
  531. .Dl $ nc -cv -T protocols=all -T ciphers=compat www.example.com 443
  532. .Pp
  533. Open a TCP connection to port 443 of www.google.ca, and negotiate TLS.
  534. Check for a different name in the certificate for validation:
  535. .Pp
  536. .Dl $ nc -cv -e adsf.au.doubleclick.net www.google.ca 443
  537. .Pp
  538. Open a UDP connection to port 53 of host.example.com:
  539. .Pp
  540. .Dl $ nc -u host.example.com 53
  541. .Pp
  542. Open a TCP connection to port 42 of host.example.com using 10.1.2.3 as the
  543. IP for the local end of the connection:
  544. .Pp
  545. .Dl $ nc -s 10.1.2.3 host.example.com 42
  546. .Pp
  547. Create and listen on a
  548. .Ux Ns -domain
  549. stream socket:
  550. .Pp
  551. .Dl $ nc -lU /var/tmp/dsocket
  552. .Pp
  553. Connect to port 42 of host.example.com via an HTTP proxy at 10.2.3.4,
  554. port 8080.
  555. This example could also be used by
  556. .Xr ssh 1 ;
  557. see the
  558. .Cm ProxyCommand
  559. directive in
  560. .Xr ssh_config 5
  561. for more information.
  562. .Pp
  563. .Dl $ nc -x10.2.3.4:8080 -Xconnect host.example.com 42
  564. .Pp
  565. The same example again, this time enabling proxy authentication with username
  566. .Dq ruser
  567. if the proxy requires it:
  568. .Pp
  569. .Dl $ nc -x10.2.3.4:8080 -Xconnect -Pruser host.example.com 42
  570. .Sh SEE ALSO
  571. .Xr cat 1 ,
  572. .Xr ssh 1
  573. .Sh AUTHORS
  574. Original implementation by
  575. .An *Hobbit* Aq Mt hobbit@avian.org .
  576. .br
  577. Rewritten with IPv6 support by
  578. .An Eric Jackson Aq Mt ericj@monkey.org .
  579. .Sh CAVEATS
  580. UDP port scans using the
  581. .Fl uz
  582. combination of flags will always report success irrespective of
  583. the target machine's state.
  584. However,
  585. in conjunction with a traffic sniffer either on the target machine
  586. or an intermediary device,
  587. the
  588. .Fl uz
  589. combination could be useful for communications diagnostics.
  590. Note that the amount of UDP traffic generated may be limited either
  591. due to hardware resources and/or configuration settings.