1Net::Server::Proto(3) User Contributed Perl DocumentationNet::Server::Proto(3)
2
6 Net::Server::Proto - Net::Server Protocol compatibility layer
7
9 NOTE: beginning in Net::Server 2.005, the default value for
10 ipv is IPv* meaning that if no host is passed, or
11 a hostname is past, all available socket types will be
12 bound. You can force IPv4 only by adding an ipv => 4
13 configuration in any of the half dozen ways we let you
14 specify it.
15 # Net::Server::Proto and its accompanying modules are not
17 # intended to be used outside the scope of Net::Server.
18 # That being said, here is how you use them. This is
20 # only intended for anybody wishing to extend the
21 # protocols to include some other set (ie maybe a
22 # database connection protocol)
23 use Net::Server::Proto;
25 my @info = Net::Server::Proto->parse_info(
27 $port, # port to connect to
28 $default_host, # host to use if none found in port
29 $default_proto, # proto to use if none found in port
30 $default_ipv, # default of IPv6 or IPv4 if none found in port
31 $server_obj, # Net::Server object
32 );
33 my @raw_info = Net::Server::Proto->get_addr_info($host, $port, $proto);
35 # returns arrayref of resolved ips, ports, and ipv values
36 my $sock = Net::Server::Proto->object({
38 port => $port,
39 host => $host,
40 proto => $proto,
41 ipv => $ipv, # * (IPv*) if false (default false)
42 }, $server);
43 # Net::Server::Proto will attempt to interface with
45 # sub modules named similar to Net::Server::Proto::TCP
46 # Individual sub modules will be loaded by
47 # Net::Server::Proto as they are needed.
48 use Net::Server::Proto::TCP; # or UDP or UNIX etc
50 # Return an object which is a sub class of IO::Socket
52 # At this point the object is not connected.
53 # The method can gather any other information that it
54 # needs from the server object.
55 my $sock = Net::Server::Proto::TCP->object({
56 port => $port,
57 host => $host,
58 proto => $proto,
59 ipv => 6, # IPv6 - default is * - can also be '4'
60 }, $server);
61 # Log that a connection is about to occur.
64 # Use the facilities of the passed Net::Server object.
65 $sock->log_connect( $server );
66 # Actually bind to port or socket file. This
68 # is typically done by calling the configure method.
69 $sock->connect();
70 # Allow for rebinding to an already open fileno.
72 # Typically will just do an fdopen.
73 $sock->reconnect();
74 ### Return a unique identifying string for this sock that
76 # can be used when reconnecting.
77 my $str = $sock->hup_string();
78 # Return the proto that is being used by this module.
80 my $proto = $sock->NS_proto();
81
83 Net::Server::Proto is an intermediate module which returns IO::Socket
84 style objects blessed into its own set of classes (ie
85 Net::Server::Proto::TCP, Net::Server::Proto::UNIX).
86 Only three or four protocols come bundled with Net::Server. TCP, UDP,
88 UNIX, UNIXDGRAM, and SSLEAY. TCP is an implementation of SOCK_STREAM
89 across an INET socket. UDP is an implementation of SOCK_DGRAM across
90 an INET socket. UNIX uses a unix style socket file with the
91 SOCK_STREAM protocol. UNIXGRAM uses a unix style socket file with the
92 SOCK_DGRAM protocol. SSLEAY is actually just a layer on top of TCP but
93 uses Net::SSLeay to read and write from the stream.
94 The protocol that is passed to Net::Server can be the name of another
96 module which contains the protocol bindings. If a protocol of
97 MyServer::MyTCP was passed, the socket would be blessed into that
98 class. If Net::Server::Proto::TCP was passed, it would get that class.
99 If a bareword, such as tcp, udp, unix, unixdgram or ssleay, is passed,
100 the word is uppercased, and post pended to "Net::Server::Proto::" (ie
101 tcp = Net::Server::Proto::TCP).
102
104 Protocol names used by the Net::Server::Proto should be sub classes of
105 IO::Socket. These classes should also contain, as a minimum, the
106 following methods should be provided:
107 object
109 Return an object which is a sub class of IO::Socket At this point
110 the object is not connected. The method can gather any other
111 information that it needs from the server object. Arguments are
112 default_host, port, and a Net::Server style server object.
113 log_connect
115 Log that a connection is about to occur. Use the facilities of the
116 passed Net::Server object. This should be an informative string
117 explaining which properties are being used.
118 connect
120 Actually bind to port or socket file. This is typically done
121 internally by calling the configure method of the IO::Socket super
122 class.
123 reconnect
125 Allow for rebinding to an already open fileno. Typically will just
126 do an fdopen using the IO::Socket super class.
127 hup_string
129 Return a unique identifying string for this sock that can be used
130 when reconnecting. This is done to allow information including the
131 file descriptor of the open sockets to be passed via %ENV during an
132 exec. This string should always be the same based upon the
133 configuration parameters.
134 NS_port
136 Net::Server protocol. Return the port that is being used by this
137 module. If the underlying type is UNIX then port will actually be
138 the path to the unix socket file.
139 NS_host
141 Net::Server protocol. Return the protocol that is being used by
142 this module. This does not have to be a registered or known
143 protocol.
144 NS_proto
146 Net::Server protocol. Return the protocol that is being used by
147 this module. This does not have to be a registered or known
148 protocol.
149 show
151 Similar to log_connect, but simply shows a listing of which
152 properties were found. Can be used at any time.
153
155 The hostname may be either blank, '*', be an IPv4 address, an IPv6
156 address, a bare hostname, or a hostname with IPv* specifications.
157 host => "127.0.0.1", # an IPv4 address
159 host => "::1", # an IPv6 address
161 host => 'localhost', # addresses returned by localhost (default IPv* - IPv4 and/or IPv6)
163 host => 'localhost/IPv*', # same
165 ipv => '*',
167 host => 'localhost', # same
168 ipv => 6,
170 host => 'localhost', # addresses returned by localhost (IPv6)
171 ipv => 'IPv4 IPv6',
173 host => 'localhost', # addresses returned by localhost (requires IPv6 and IPv4)
174 host => '*', # any local interfaces (default IPv*)
177 ipv => '*',
179 host => '*', # any local interfaces (any IPv6 or IPv4)
180 host => '*/IPv*', # same
182
184 In addition to being able to specify IPV as a separate parameter, ipv
185 may also be passed as a part of the host, as part of the port, as part
186 of the protocol or may be specified via $ENV{'IPV'}. The order of
187 precidence is as follows:
188 1) Explicit IPv4 or IPv6 address - wins
190 2) ipv specified in port
191 3) ipv specified in host
192 4) ipv specified in proto
193 5) ipv specified in default settings
194 6) ipv specified in $ENV{'IPV'}
195 7) default to IPv*
196
198 The port is the most important argument passed to the sub module
199 classes and to Net::Server::Proto itself. For tcp, udp, and ssleay
200 style ports, the form is generally host:port/protocol,
201 [host]:port/protocol, host|port|protocol, host/port, or port. If host
202 is a numerical IPv6 address it should be enclosed in square brackets to
203 avoid ambiguity in parsing a port number, e.g.: "[::1]:80". Separating
204 with spaces, commas, or pipes is also allowed, e.g. "::1, 80". For
205 unix sockets the form is generally socket_file|unix or socket_file.
206 To help overcome parsing ambiguity, it is also possible to pass port as
208 a hashref (or as an array of hashrefs) of information such as:
209 port => {
211 host => "localhost",
212 ipv => 6, # could also pass IPv6 (* is default)
213 port => 20203,
214 proto => 'tcp',
215 }
216 If a hashref does not include host, ipv, or proto - it will use the
218 default value supplied by the general configuration.
219 A socket protocol family PF_INET or PF_INET6 is derived from a
221 specified address family of the binding address. A PF_INET socket can
222 only accept IPv4 connections. A PF_INET6 socket accepts IPv6
223 connections, but may also accept IPv4 connections, depending on OS and
224 its settings. For example, on FreeBSD systems setting a sysctl
225 net.inet6.ip6.v6only to 0 will allow IPv4 connections to a PF_INET6
226 socket. By default on linux, binding to host [::] will accept IPv4 or
227 IPv6 connections.
228 The Net::Server::Proto::object method returns a list of objects
230 corresponding to created sockets. For Unix and INET sockets the list
231 typically contains just one element, but may return multiple objects
232 when multiple protocol families are allowed or when a host name
233 resolves to multiple local binding addresses. This is particularly
234 true when an ipv value of '*' is passed in allowing hostname
235 resolution.
236 You can see what Net::Server::Proto parsed out by looking at the logs
238 to see what log_connect said. You could also include a post_bind_hook
239 similar to the following to debug what happened:
240 sub post_bind_hook {
242 my $self = shift;
243 foreach my $sock ( @{ $self->{server}->{sock} } ){
244 $self->log(2,$sock->show);
245 }
246 }
247 Rather than try to explain further, please look at the following
249 examples:
250 # example 1 #----------------------------------
252 $port = "20203";
254 $def_host = "default-domain.com";
255 $def_proto = undef;
256 $def_ipv = undef;
257 @info = Net::Server::Proto->parse_info($port,$def_host,$def_proto,$def_ipv);
258 # @info = {
259 # host => 'default-domain.com',
260 # port => 20203,
261 # proto => 'tcp', # will use Net::Server::Proto::TCP
262 # ipv => *, # IPv*
263 # };
264 # example 2 #----------------------------------
266 $port = "someother.com:20203";
268 $def_host = "default-domain.com";
269 $def_proto = "tcp";
270 $def_ipv = undef;
271 @info = Net::Server::Proto->parse_info($port,$def_host,$def_proto,$def_ipv);
272 # @info = {
273 # host => 'someother.com',
274 # port => 20203,
275 # proto => 'tcp', # will use Net::Server::Proto::TCP
276 # ipv => *,
277 # };
278 # example 3 #----------------------------------
280 $port = "someother.com:20203/udp";
282 $def_host = "default-domain.com";
283 $def_proto = "tcp";
284 $def_ipv = undef;
285 @info = Net::Server::Proto->parse_info($port,$def_host,$def_proto,$def_ipv);
286 # @info = {
287 # host => 'someother.com',
288 # port => 20203,
289 # proto => 'udp', # will use Net::Server::Proto::UDP
290 # ipv => *,
291 # };
292 # example 4 #----------------------------------
294 $port = "someother.com:20203/Net::Server::Proto::UDP";
296 $def_host = "default-domain.com";
297 $def_proto = "TCP";
298 $def_ipv = 4;
299 @info = Net::Server::Proto->parse_info($port,$def_host,$def_proto,$def_ipv);
300 # @info = {
301 # host => 'someother.com',
302 # port => 20203,
303 # proto => 'Net::Server::Proto::UDP',
304 # ipv => 4,
305 # };
306 # example 5 #----------------------------------
308 $port = "someother.com:20203/MyObject::TCP";
310 $def_host = "default-domain.com";
311 $def_proto = "tcp";
312 @info = Net::Server::Proto->parse_info($port,$def_host,$def_proto);
313 # @info = {
314 # host => 'someother.com',
315 # port => 20203,
316 # proto => 'MyObject::TCP',
317 # };
318 # example 6 #----------------------------------
320 $port = "/tmp/mysock.file|unix";
322 $def_host = "default-domain.com";
323 $def_proto = "tcp";
324 $def_ipv = undef;
325 @info = Net::Server::Proto->parse_info($port,$def_host,$def_proto,$def_ipv);
326 # @info = {
327 # host => '*', # irrelevant for UNIX socket
328 # port => '/tmp/mysock.file', # not really a port
329 # proto => 'unix', # will use Net::Server::Proto::UNIX
330 # ipv => '*', # irrelevant for UNIX socket
331 # };
332 # example 7 #----------------------------------
334 $port = "/tmp/mysock.file|unixdgram";
336 $def_host = "default-domain.com";
337 $def_proto = "tcp";
338 $def_ipv = undef;
339 @info = Net::Server::Proto->parse_info($port,$def_host,$def_proto,$def_ipv);
340 # @info = {
341 # host => '*', # irrelevant for UNIX socket
342 # port => '/tmp/mysock.file', # not really a port
343 # proto => 'unixdgram', # will use Net::Server::Proto::UNIXDGRAM
344 # ipv => '*', # irrelevant for UNIX socket
345 # };
346 # example 8 #----------------------------------
348 $port = "/tmp/mysock.file|SOCK_STREAM|unix"; # legacy
350 $def_host = "";
351 $def_proto = "tcp";
352 $def_ipv = undef;
353 @info = Net::Server::Proto->parse_info($port,$def_host,$def_proto,$def_ipv);
354 # @info = {
355 # host => '*', # irrelevant for UNIX socket
356 # port => '/tmp/mysock.file', # not really a port
357 # proto => 'unix', # will use Net::Server::Proto::UNIX
358 # unix_type => 'SOCK_STREAM',
359 # ipv => '*', # irrelevant for UNIX socket
360 # };
361 # example 9 #----------------------------------
363 $port = "/tmp/mysock.file|SOCK_DGRAM|unix"; # legacy
365 $def_host = "";
366 $def_proto = "tcp";
367 $def_ipv = undef;
368 @info = Net::Server::Proto->parse_info($port,$def_host,$def_proto,$def_ipv);
369 # @info = {
370 # host => '*', # irrelevant for UNIX socket
371 # port => '/tmp/mysock.file', # not really a port
372 # proto => 'unix', # will use Net::Server::Proto::UNIXDGRAM
373 # unix_type => 'SOCK_DGRAM',
374 # ipv => '*', # irrelevant for UNIX socket
375 # };
376 # example 10 #----------------------------------
378 $port = "someother.com:20203/ssleay";
380 $def_host = "default-domain.com";
381 $def_proto = "tcp";
382 $def_ipv = undef;
383 @info = Net::Server::Proto->parse_info($port,$def_host,$def_proto,$def_ipv);
384 # @info = {
385 # host => 'someother.com',
386 # port => 20203,
387 # proto => 'ssleay', # will use Net::Server::Proto::SSLEAY
388 # ipv => *,
389 # };
390 # example 11 #----------------------------------
392 $port = "[::1]:20203 ipv6 tcp";
394 $def_host = "default-domain.com";
395 $def_proto = "tcp";
396 $def_ipv = undef;
397 @info = Net::Server::Proto->parse_info($port,$def_host,$def_proto,$def_ipv);
398 # @info = {
399 # host => '::1',
400 # port => 20203,
401 # proto => 'tcp', # will use Net::Server::Proto::TCP
402 # ipv => 6,
403 # };
404 # example 12 #----------------------------------
406 $port = "[::1]:20203 tcp";
408 $def_host = "default-domain.com/IPv6";
409 $def_proto = "tcp";
410 $def_ipv = undef;
411 @info = Net::Server::Proto->parse_info($port,$def_host,$def_proto,$def_ipv);
412 # @info = {
413 # host => '::1',
414 # port => 20203,
415 # proto => 'tcp', # will use Net::Server::Proto::TCP
416 # ipv => 6,
417 # };
418 # example 13 #----------------------------------
420 $port = "[someother.com]:20203 ipv6 ipv4 tcp";
422 $def_host = "default-domain.com";
423 $def_proto = "tcp";
424 $def_ipv = undef;
425 @info = Net::Server::Proto->parse_info($port,$def_host,$def_proto,$def_ipv);
426 # @info = ({
427 # host => 'someother.com',
428 # port => 20203,
429 # proto => 'tcp', # will use Net::Server::Proto::TCP
430 # ipv => 4,
431 # }, {
432 # host => 'someother.com',
433 # port => 20203,
434 # proto => 'tcp', # will use Net::Server::Proto::TCP
435 # ipv => 6,
436 # });
437 # example 14 #----------------------------------
439 # depending upon your configuration
441 $port = "localhost:20203";
442 $def_host = "default-domain.com";
443 $def_proto = "tcp";
444 $def_ipv = undef;
445 @info = Net::Server::Proto->parse_info($port,$def_host,$def_proto,$def_ipv);
446 # @info = ({
447 # host => '127.0.0.1',
448 # port => 20203,
449 # proto => 'tcp', # will use Net::Server::Proto::TCP
450 # ipv => 4, # IPv4
451 # }, {
452 # host => '::1',
453 # port => 20203,
454 # proto => 'tcp', # will use Net::Server::Proto::TCP
455 # ipv => 6, # IPv6
456 # });
457 # example 15 #----------------------------------
459 # depending upon your configuration
461 $port = "localhost:20203";
462 $def_host = "default-domain.com IPv*";
463 $def_proto = "tcp";
464 $def_ipv = undef;
465 @info = Net::Server::Proto->parse_info($port,$def_host,$def_proto,$def_ipv);
466 # @info = ({
467 # host => '127.0.0.1',
468 # port => 20203,
469 # proto => 'tcp', # will use Net::Server::Proto::TCP
470 # ipv => 4, # IPv4
471 # }, {
472 # host => '::1',
473 # port => 20203,
474 # proto => 'tcp', # will use Net::Server::Proto::TCP
475 # ipv => 6, # IPv6
476 # });
477 # example 16 #----------------------------------
479 # depending upon your configuration
481 $ENV{'IPV'} = '4';
482 $port = "localhost:20203";
483 $def_host = "default-domain.com";
484 $def_proto = "tcp";
485 $def_ipv = undef;
486 @info = Net::Server::Proto->parse_info($port,$def_host,$def_proto,$def_ipv);
487 # @info = ({
488 # host => '127.0.0.1',
489 # port => 20203,
490 # proto => 'tcp', # will use Net::Server::Proto::TCP
491 # ipv => 4, # IPv4
492 # });
493
495 Distributed under the same terms as Net::Server
496perl v5.34.0 2022-01-21 Net::Server::Proto(3)