1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
|
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta http-equiv="Content-Language" content="en" />
<title>s6-networking: the s6-tcpclient program</title>
<meta name="Description" content="s6-networking: the s6-tcpclient program" />
<meta name="Keywords" content="s6-networking s6-tcpclient tcpclient ucspi tcp inet network tcp/ip client" />
<!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
</head>
<body>
<p>
<a href="index.html">s6-networking</a><br />
<a href="//skarnet.org/software/">Software</a><br />
<a href="//skarnet.org/">skarnet.org</a>
</p>
<h1> The <tt>s6-tcpclient</tt> program </h1>
<p>
<tt>s6-tcpclient</tt> is an
<a href="https://cr.yp.to/proto/ucspi.txt">UCSPI client tool</a> for
INET domain sockets. It establishes a TCP connection to a server,
then executes into a program.
</p>
<h2> Interface </h2>
<pre>
s6-tcpclient [ -q | -Q | -v ] [ -4 | -6 ] [ -d | -D ] [ -r | -R ] [ -h ] [ -H ] [ -n | -N ] [ -t <em>timeout</em> ] [ -l <em>localname</em> ] [ -T <em>timeoutconn</em> ] [ -i <em>localip</em> ] [ -p <em>localport</em> ] <em>host</em> <em>port</em> <em>prog...</em>
</pre>
<ul>
<li> s6-tcpclient establishes a TCP connection to host <em>host</em>
port <em>port</em>. </li>
<li> It executes into <em>prog...</em> with descriptor 6 reading from
the network and descriptor 7 writing to it. </li>
</ul>
<h2> Host address determination </h2>
<ul>
<li> <em>host</em> may be an IP address, in which case s6-tcpclient will
connect to that IP address. If the underlying skalibs has been
compiled with IPv6 support, <em>host</em> can be an IPv6 address as
well as an IPv4 one. </li>
<li> <em>host</em> may be a domain name, in which case a DNS
resolution will be performed on it, and a connection will be tried to
all the resulting IP addresses in a round-robin fashion, twice:
first with a small timeout, then with a longer timeout. The first
address to answer wins. The connection attempt fails if no address
in the list is able to answer. </li>
</ul>
<h2> Environment variables </h2>
<p>
<em>prog...</em> is run with the following variables set:
</p>
<ul>
<li> PROTO: always set to TCP </li>
<li> TCPREMOTEIP: set to the chosen IP address of <em>host</em>. </li>
<li> TCPREMOTEPORT: set to <em>port</em>. </li>
<li> TCPREMOTEHOST: if the <tt>-H</tt> option has been given, set to the
name obtained by a reverse DNS resolution of the IP address chosen
for <em>host</em>. Else unset. </li>
<li> TCPLOCALHOST: if the <tt>-l</tt> option has been given, set to
<em>localname</em>. Else set to the name obtained by a reverse DNS
resolution of the IP address chosen for the local host. </li>
<li> TCPREMOTEINFO: if the <tt>-r</tt> option has been given, set
to the information given by an IDENT server on <em>host</em> about
the current connection (very unreliable). Else unset. </li>
</ul>
<h2> Options </h2>
<ul>
<li> <tt>-q</tt> : be quiet. </li>
<li> <tt>-Q</tt> : be normally verbose. This is the default. </li>
<li> <tt>-v</tt> : be verbose. </li>
<li> <tt>-4</tt> : Interpret <em>host</em> as an IPv4 address or make A
queries to determine its addresses. Do not attempt IPv6. </li>
<li> <tt>-6</tt> : (only valid if the underlying skalibs has
IPv6 support) Interpret <em>host</em> as an IPv6 address or make
AAAA queries to determine its addresses. Do not attempt IPv4. </li>
<li> <tt>-d</tt> : don't use the TCP_NODELAY socket option. This
is the default. </li>
<li> <tt>-D</tt> : use the TCP_NODELAY socket option, which disables
Nagle's algorithm. </li>
<li> <tt>-r</tt> : try and obtain a TCPREMOTEINFO string via the
IDENT protocol. This is obsolete and unreliable, and should only be used for
compatibility with legacy programs. </li>
<li> <tt>-R</tt> : do not use the IDENT protocol. This is the
default. </li>
<li> <tt>-h</tt> : Consult the <tt>/etc/hosts</tt> database before
performing DNS queries. The default, when this option is not given, is to
ignore <tt>/etc/hosts</tt>. The <tt>-H</tt> option overrides <tt>-h</tt> and
voids any kind of lookup. </li>
<li> <tt>-H</tt> : do not try and obtain the local or remote host names
via DNS. The default, when this option is not given, is to look up the
local and remote host IPs in the DNS database to get the corresponding names. </li>
<li> <tt>-n</tt> : qualify <em>host</em> when resolving it to
find suitable IP addresses. This is the default. </li>
<li> <tt>-N</tt> : do not qualify <em>host</em>. </li>
<li> <tt>-t :<em>timeout</em></tt> : put a global timeout
on the connection attempt. If no fully functional connection has been
established after <em>timeout</em> seconds, abort the program. By
default, <em>timeout</em> is 0, which means no timeout. </li>
<li> <tt>-i <em>localip</em></tt> : use <em>localip</em> as
the local socket address for the connection. By default, address selection
is left to the operating system. </li>
<li> <tt>-p <em>localport</em></tt> : use <em>localport</em>
as the local socket port for the connection. By default, port selection
is left to the operating system. </li>
<li> <tt>-l <em>localname</em></tt> : use <em>localname</em>
as the value of the TCPLOCALHOST environment variable instead of
looking it up via the DNS. </li>
<li> <tt>-T :<em>timeoutconn</em></tt> : configure the
connection timeouts. <em>timeoutconn</em> must be of the form
<em>x</em><tt>+</tt><em>y</em>, where <em>x</em> and <em>y</em> are
integers. <em>x</em> is the first timeout and <em>y</em> is the
second one: all suitable addresses for <em>host</em> are first
tried with a timeout of <em>x</em> seconds, and if all of them
fail, then they are tried again with a timeout of <em>y</em>
seconds. (Be aware that the timeout specified with the <tt>-t</tt>
option overrides everything.) By default, <em>x</em> is 2 and
<em>y</em> is 58. </li>
</ul>
</body>
</html>
|
