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