Skip to content

tcpclient.1

Jump to bottom
Manvendra Bhangui edited this page Sep 6, 2024 · 10 revisions

NAME

tcpclient - creates an outgoing TLS/non-TLS TCP IPv4/IPv6 connection.

SYNOPSIS

tcpclient [opts] host/socket [port] [prog]

DESCRIPTION

opts is a series of getopt-style options. host/socket is one argument. If socket is provided as a path, tcpclient uses UNIX domain socket to connect (See unix(7)). In this case port is not provided. If host is not a filesystem path, host is used as a TCP/IP address and TCP port is used where port is one argument. prog consists of one or more arguments. tcpclient attempts to connect to a TCP server or a UNIX socket. Depending on whether prog is provided or omitted, tcpclient does one of the two things below.

if prog is provided, it runs prog, with descriptor 6 reading from the network/socket and descriptor 7 writing to the network/socket. It also sets up several environment variables (see .BR tcp-environ (5)).

If prog is omitted, tcpclient enters client mode where it passes data from descriptor 0 to the network and data from the network to descriptor 1. client mode is similar to how you would use programs like telnet(1), ssh(1), etc.

tcpclient can also initiate a SSL/TLS session with a remote host (-n option). This requires a clientcert to be provided. In client mode, one can also do opportunistic TLS by using -s starttls option. The currently supported option for starttls are smtp, pop3 and imap.

For TLS/SSL sessions, tcpclient sets the environment variable TLS_PROVIDER with details of the TLS connnection if passed the -z option.

The server's address is given by a socket path or host and port. port may be a name from /etc/services or a number. host may be 0, referring to the local machine, or a dotted-decimal IP address or IPv6 address, or a host name; it is fed through qualification using dns_ip4_qualify.

If the server has several IP addresses, tcpclient tries each address in turn.

OPTIONS

General options:

-q
Quiet. Do not print error messages.

-Q
(Default.) Print error messages.

-v
Verbose. Print error messages and status messages.

Connection options:

-T x+y
Timeout on the connection attempt after x+y seconds. Default: 2+58. When a host has several IP addresses, tcpclient tries to connect to the first IP address, waits x seconds, tries to connect to the second IP address, waits x seconds, etc.; then it retries each address that timed out, waiting y seconds per address. You may omit +y to skip the second try. Before version 0.88, tcpserver(1) will use only x (default: 60). For a UNIX domain socket, there is just one connection attempt.

-i localip
Use localip as the IP address for the local side of the connection; quit if localip is not available. Normally tcpclient lets the operating system choose an address. This option is not used for UNIX domain sockets.

-p localport
Use localport as the TCP port for the local side of the connection; quit if localport is not available. Normally tcpclient lets the operating system choose a port. This option is not used for UNIX domain sockets.

-d
Delay sending data for a fraction of a second whenever the remote host is responding slowly. This is currently the default, but it may not be in the future; if you want it, set it explicitly. This option is not used for UNIX domain sockets.

-D
Never delay sending data; enable TCP_NODELAY. This option is not used for UNIX domain sockets.

-C certdir
Directory having certificates. Default is /etc/indimail/certs.

-n clientcert
Use certfile as the TLS/SSL certificate. If the -n option is not provided, tcpclient will not initiate a TLS/SSL session. certfile can be an empty string to use TLS_CERTFILE environment variable.

-c cafile
Specify cafile as the file containing CA certificates. Sometimes, special CA certificates are needed if an intermediate certificate used by your issuing CA expires. Note that the file given with -c is passed to SSL_CTX_load_verify_locations and thus may contain several CA certificates, which will be used during SSL connection negotiation to close any gap in the certificate chain. If this is not provided, the file /etc/indimail/certs/serverca.pem will be used.

-L crlfile
A list of Certificate Revocation Lists (CRLs). If present it should contain the CRLs of the CAs in cafile and server certs that will be checked for revocation. If this is not provided, the file close any gap in the certificate chain. If this is not provided, the file /etc/indimail/certs/servercrl.pem will be used.

-z
Set TLS_PROVIDER environment variables with details of the TLS/SSL connection. This environment variable will be available for prog when using TLS/SSL.

-f cipher_list
Use ciphers listed in cipher_list. Without this tcpclient uses TLS_CIPHER_LIST environment variable if set (or system configured PROFILE=SYSTEM ciphers for TLSv1.2 and below). For TLSv1.3 the environment variable TLS_CIPHER_SUITE is used instead. See openssl-ciphers(1ossl).

-M tls_method
Use tls_method to set client/server method / protocol. This will be one of SSLv23, SSLv3, TLSv1, TLSv1_1, TLSv1_2, TLSv1_3 values. Without this option, the actual protocol version used will be negotiated to the highest version mutually supported by the client and the server. The supported protocols at this moment are TLSv1.2 and TLSv1.3. Older protocols have been deprecated and removed. It is best not to use this option to let tcpclient choose the highest protocol supported.

-s startlsType
Specify smtp, pop3 or imap for starttlsType. This works only when running in client mode (when prog is omitted). In client mode, tcpclient will initiate SSL/TLS negotation after issuing STARTTLS command itself to the remote server.

-m host
Match host with common name in certificate (CN)

-a timeoutdata
Timeout if read or write to/from host exceeds timeoutdata seconds.

Data-gathering options:

-h
(Default.) Look up the remote host name in DNS to set the environment variable $TCPREMOTEHOST. This option is not used for UNIX domain sockets.

-H
Do not look up the remote host name in DNS; remove the environment variable $TCPREMOTEHOST. This option is not used for UNIX domain sockets.

-l localname
Do not look up the local host name in DNS; use localname for the environment variable $TCPLOCALHOST. A common choice for localname is 0. This option is not used for UNIX domain sockets.

-r
(Default.) Attempt to obtain $TCPREMOTEINFO from the remote host. This option is not used for UNIX domain sockets.

-R
Do not attempt to obtain $TCPREMOTEINFO from the remote host. This option is not used for UNIX domain sockets.

-t n
Timeout on the $TCPREMOTEINFO connection attempt after n seconds. Default: 26. This option is not used for UNIX domain sockets.

ENVIRONMENT

TLS_CERTFILE
client ssl certificate. This is used when an empty string is passed as the argument to the -n option. Default is clientcert.pem

SERVERCA
CA certificate. This can be overriden by the -c option. Default is /etc/indimail/certs/serverca.pem

SERVERCRL
Certificate Revocation Lists. Default is /etc/indimail/certs/servercrl.pem

TLS_CIPHER_LIST
A set of OpenSSL cipher strings. Multiple ciphers contained in a string should be separated by a colon. This can be overriden by the -f option.

CERTDIR
Sub-directory relative to /etc/indimail, having clientcert.pem. Default is /etc/indimail/certs.

EXAMPLES

1. Connect to port 25 and issue the starttls command. Use default
   certificate /etc/indimail/certs/clientcert.pem.

   $ tcpclient -n "" -s smtp 0 25

2. Connect to port 110 and issue the STLS command. Use default certificate
   /etc/indimail/certs/clientcert.pem.

   $ tcpclient -n "" -s pop3 0 110

3. Connect to port 143, issue the STARTTLS  command and then run a script.
   read from descriptor 6 reads from network, write to descriptor 1 writes
   to network. Use default certificate /etc/indimail/certs/clientcert.pem.

   $ tcpclient -n "" -s imap 0 143 /usr/bin/my_script

4. Connect to port 143 and issue the STARTTLS command, like openssl
   s_client -starttls. Use default certificate
   /etc/indimail/certs/clientcert.pem.

   $ tcpclient -n "" -s imap 0 143

5. Connect to port 25 on 127.0.0.1.

   $ tcpclient 127.0.0.1 25

6. Connect to port 465 on 127.0.0.1 like openssl s_client

   $ tcpclient -n /etc/indimail/certs/clientcert.pem 127.0.0.1 465

7. Run a script under tcpclient that connects to a SSL server on port 5555
   read from descriptor 6 reads from network, write to descriptor 7 writes
   to network. Certificate used is the value of TLS_CERTFILE env variable.

   $ tcpclient -n "" 0 5555 /usr/bin/my_script

8. Connect to qmail-smtpd on UNIX socket /run/indimail/smtpd like telnet
   read from descriptor 0 reads from socket, write to descriptor 1 writes
   to socket.

   a) run tcpserver

   $ tcpserver -vn /etc/indimail/certs/servercert.pem \
     /run/indimail/smtpd /usr/sbin/qmail-smtpd

   b) run tcpclient

   $ tcpclient -n /etc/indimail/certs/clientcert.pem /run/indimail/smtpd

SEE ALSO

tcpserver(1), dotls(1), openssl(1) tcprules(1), tcprulescheck(1), argv0(1), fixcrio(1), recordio(1), rblsmtpd(1), who@(1), date@(1), finger@(1), http@(1), tcpcat(1), mconnect(1), tcp-environ(5), openssl-ciphers(1ossl). http://cr.yp.to/ucspi-tcp.html

Clone this wiki locally