Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
POE::Component::ServerUserCContributed Perl DocuPOE::Component::Server::IRC(3)

NAME
       POE::Component::Server::IRC - A fully event-driven networkable IRC
       server daemon module.

SYNOPSIS
	# A fairly simple example:
	use strict;
	use warnings;
	use POE	qw(Component::Server::IRC);

	my %config = (
	    servername => 'simple.poco.server.irc',
	    nicklen    => 15,
	    network    => 'SimpleNET'
	);

	my $pocosi = POE::Component::Server::IRC->spawn( config	=> \%config );

	POE::Session->create(
	    package_states => [
		'main' => [qw(_start _default)],
	    ],
	    heap => { ircd => $pocosi },
	);

	$poe_kernel->run();

	sub _start {
	    my ($kernel, $heap)	= @_[KERNEL, HEAP];

	    $heap->{ircd}->yield('register', 'all');

	    # Anyone connecting	from the loopback gets spoofed hostname
	    $heap->{ircd}->add_auth(
		mask	 => '*@localhost',
		spoof	 => 'm33p.com',
		no_tilde => 1,
	    );

	    # We have to add an	auth as	we have	specified one above.
	    $heap->{ircd}->add_auth(mask => '*@*');

	    # Start a listener on the 'standard' IRC port.
	    $heap->{ircd}->add_listener(port =>	6667);

	    # Add an operator who can connect from localhost
	    $heap->{ircd}->add_operator(
		{
		    username =>	'moo',
		    password =>	'fishdont',
		}
	    );
	}

	sub _default {
	    my ($event,	$args) = @_[ARG0 .. $#_];

	    print "$event: ";
	    for	my $arg	(@$args) {
		if (ref($arg) eq 'ARRAY') {
		    print "[", join ( ", ", @$arg ), "]	";
		}
		elsif (ref($arg) eq 'HASH') {
		    print "{", join ( ", ", %$arg ), "}	";
		}
		else {
		    print "'$arg' ";
		}
	    }

	    print "\n";
	 }

DESCRIPTION
       POE::Component::Server::IRC is a	POE component which implements an IRC
       server (also referred to	as an IRC daemon or IRCd). It should be
       compliant with the pertient IRC RFCs and	is based on reverse
       engineering Hybrid IRCd behaviour with regards to interactions with IRC
       clients and other IRC servers.

       Yes, that's right. POE::Component::Server::IRC is capable of linking to
       foreign IRC networks. It	supports the TS5 server	to server protocol and
       has been	tested with linking to Hybrid-7	based networks.	It should in
       theory work with	any TS5-based IRC network.

       POE::Component::Server::IRC also	has a services API, which enables one
       to extend the IRCd to create IRC	Services. This is fully	event-driven
       (of course =]). There is	also a Plugin system, similar to that sported
       by POE::Component::IRC.

       Note: This is a subclass	of POE::Component::Server::IRC::Backend.  You
       should read its documentation too.

CONSTRUCTOR
   "spawn"
       Returns a new instance of the component.	Takes the following
       parameters:

       o   'config', a hashref of configuration	options, see the "configure"
	   method for details.

       Any other parameters will be passed along to
       POE::Component::Server::IRC::Backend's "create" method.

       If the component	is spawned from	within another session then that
       session will automagically be registered	with the component to receive
       events and be sent an "ircd_registered" event.

METHODS
   Information
       "server_name"

       No arguments, returns the name of the ircd.

       "server_version"

       No arguments, returns the software version of the ircd.

       "server_created"

       No arguments, returns a string signifying when the ircd was created.

       "server_config"

       Takes one argument, the server configuration value to query.

   Configuration
       These methods provide mechanisms	for configuring	and controlling	the
       IRCd component.

       "configure"

       Configures your new shiny IRCd.

       Takes a number of parameters:

       o   'servername', a name	to bless your shiny new	IRCd with, defaults to
	   'poco.server.irc';

       o   'serverdesc', a description for your	IRCd, defaults to 'Poco? POCO?
	   POCO!';

       o   'network', the name of the IRC network you will be creating,
	   defaults to 'poconet';

       o   'nicklen', the max length of	nicknames to support, defaults to 9.
	   Note: the nicklen must be the same on all servers on	your IRC
	   network;

       o   'maxtargets', max number of targets a user can send
	   PRIVMSG/NOTICE's to,	defaults to 4;

       o   'maxchannels', max number of	channels users may join, defaults to
	   15;

       o   'version', change the server	version	that is	reported;

       o   'admin', an arrayref	consisting of the 3 lines that will be
	   returned by ADMIN;

       o   'info', an arrayref consisting of lines to be returned by INFO;

       o   'ophacks', set to true to enable oper hacks.	Default	is false;

       o   'whoisactually', setting this to a false value means	that only
	   opers can see 338. Defaults to true;

       "add_auth"

       By default the IRCd allows any user to connect to the server without a
       password. Configuring auths enables you to control who can connect and
       set passwords required to connect.

       Takes the following parameters:

       o   'mask', a user@host or user@ipaddress mask to match against,
	   mandatory;

       o   'password', if specified, any client	matching the mask must provide
	   this	to connect;

       o   'spoof', if specified, any client matching the mask will have their
	   hostname changed to this;

       o   'no_tilde', if specified, the '~' prefix is removed from their
	   username;

       Auth masks are processed	in order of addition.

       If auth masks have been defined,	then a connecting user *must* match
       one of the masks	in order to be authorised to connect. This is a
       feature >;)

       "del_auth"

       Takes a single argument,	the mask to remove.

       "add_operator"

       This adds an O line to the IRCd.	Takes a	number of parameters:

       o   'username', the username of the IRC oper, mandatory;

       o   'password', the password, mandatory;

       o   'ipmask', either a scalar ipmask or an arrayref of Net::Netmask
	   objects;

       A scalar	ipmask can contain '*' to match	any number of characters or
       '?' to match one	character. If no 'ipmask' is provided, operators are
       only allowed to OPER from the loopback interface.

       'password' can be either	plain-text, "crypt"'d or unix/apache md5. See
       the "mkpasswd" function in POE::Component::Server::IRC::Common for how
       to generate passwords.

       "del_operator"

       Takes a single argument,	the username to	remove.

       "add_peer"

       Adds peer servers that we will allow to connect to us and who we	will
       connect to. Takes the following parameters:

       o   'name', the name of the server. This	is the IRC name, not hostname,
	   mandatory;

       o   'pass', the password	they must supply to us,	mandatory;

       o   'rpass', the	password we need to supply to them, mandatory;

       o   'type', the type of server, 'c' for a connecting server, 'r'	for
	   one that we will connect to;

       o   'raddress', the remote address to connect to, implies 'type'	eq
	   'r';

       o   'rport', the	remote port to connect to, default is 6667;

       o   'ipmask', either a scalar ipmask or an arrayref of Net::Netmask
	   objects;

       o   'auto', if set to true value	will automatically connect to remote
	   server if type is 'r';

       o   'zip', set to a true	value to enable	ziplink	support. This must be
	   done	on both	ends of	the connection.	Requires
	   POE::Filter::Zlib::Stream;

       "del_peer"

       Takes a single argument,	the peer to remove. This does not disconnect
       the said	peer if	it is currently	connected.

   State queries
       The following methods allow you to query	state information regarding
       nicknames, channels, and	peers.

       "state_nicks"

       Takes no	arguments, returns a list of all nicknames in the state.

       "state_chans"

       Takes no	arguments, returns a list of all channels in the state.

       "state_peers"

       Takes no	arguments, returns a list of all irc servers in	the state.

       "state_nick_exists"

       Takes one argument, a nickname, returns true or false dependent on
       whether the given nickname exists or not.

       "state_chan_exists"

       Takes one argument, a channel name, returns true	or false dependent on
       whether the given channel exists	or not.

       "state_peer_exists"

       Takes one argument, a peer server name, returns true or false dependent
       on whether the given peer exists	or not.

       "state_user_full"

       Takes one argument, a nickname, returns that users full nick!user@host
       if they exist, undef if they don't.

       "state_user_nick"

       Takes one argument, a nickname, returns the proper nickname for that
       user.  Returns undef if the nick	doesn't	exist.

       "state_user_umode"

       Takes one argument, a nickname, returns that users mode setting.

       "state_user_is_operator"

       Takes one argument, a nickname, returns true or false dependent on
       whether the given nickname is an	IRC operator or	not.

       "state_user_chans"

       Takes one argument, a nickname, returns a list of channels that that
       nick is a member	of.

       "state_user_server"

       Takes one argument, a nickname, returns the name	of the peer server
       that that user is connected from.

       "state_chan_list"

       Takes one argument, a channel name, returns a list of the member	nicks
       on that channel.

       "state_chan_list_prefixed"

       Takes one argument, a channel name, returns a list of the member	nicks
       on that channel,	nicknames will be prefixed with	@%+ if they are	+o +h
       or +v, respectively.

       "state_chan_topic"

       Takes one argument, a channel name, returns undef if no topic is	set on
       that channel, or	an arrayref consisting of the topic, who set it	and
       the time	they set it.

       "state_chan_mode_set"

       Takes two arguments, a channel name and a channel mode character.
       Returns true if that channel mode is set, false otherwise.

       "state_is_chan_member"

       Takes two arguments, a nick and a channel name. Returns true if that
       nick is on channel, false otherwise.

       "state_user_chan_mode"

       Takes two arguments, a nick and a channel name. Returns that nicks
       status (+ohv or '') on that channel.

       "state_is_chan_op"

       Takes two arguments, a nick and a channel name. Returns true if that
       nick is an channel operator, false otherwise.

       "state_is_chan_hop"

       Takes two arguments, a nick and a channel name. Returns true if that
       nick is an channel half-operator, false otherwise.

       "state_has_chan_voice"

       Takes two arguments, a nick and a channel name. Returns true if that
       nick has	channel	voice, false otherwise.

   Server actions
       "daemon_server_kill"

       Takes two arguments, a nickname and a comment (which is optional);
       Issues a	SERVER KILL of the given nick;

       "daemon_server_mode"

       First argument is a channel name, remaining arguments are channel modes
       and their parameters to apply.

       "daemon_server_kick"

       Takes two arguments that	are mandatory and an optional one: channel
       name, nickname of the user to kick and a	pithy comment.

       "daemon_server_remove"

       Takes two arguments that	are mandatory and an optional one: channel
       name, nickname of the user to remove and	a pithy	comment.

       "daemon_server_wallops"

       Takes one argument, the message text to send.

INPUT EVENTS
       These are POE events that can be	sent to	the component.

   "add_spoofed_nick"
       Takes a single argument a hashref which should have the following keys:

       o   'nick', the nickname	to add,	mandatory;

       o   'user', the ident you want the nick to have,	defaults to the	same
	   as the nick;

       o   'hostname', the hostname, defaults to the server name;

       o   'umode', specify whether this is to be an IRCop etc,	defaults to
	   'i';

       o   'ts', unixtime, default is time(), best not to meddle;

       Note: spoofed nicks are currently only really functional	for use	as IRC
       services.

   "del_spoofed_nick"
       Takes a single mandatory	argument, the spoofed nickname to remove.
       Optionally, you may specify a quit message for the spoofed nick.

   Spoofed nick	commands
       The following input events are for the benefit of spoofed nicks.	All
       require a nickname of a spoofed nick as the first argument.

       "daemon_cmd_join"

       Takes two arguments, a spoofed nick and a channel name to join.

       "daemon_cmd_part"

       Takes two arguments, a spoofed nick and a channel name to part from.

       "daemon_cmd_mode"

       Takes at	least three arguments, a spoofed nick, a channel and a channel
       mode to apply. Additional arguments are parameters for the channel
       modes.

       "daemon_cmd_kick"

       Takes at	least three arguments, a spoofed nick, a channel name and the
       nickname	of a user to kick from that channel. You may supply a fourth
       argument	which will be the kick comment.

       "daemon_cmd_topic"

       Takes three arguments, a	spoofed	nick, a	channel	name and the topic to
       set on that channel. If the third argument is an	empty string then the
       channel topic will be unset.

       "daemon_cmd_nick"

       Takes two arguments, a spoofed nick and a new nickname to change	to.

       "daemon_cmd_gline"

       Takes three arguments, a	spoofed	nick, a	user@host mask to gline	and a
       reason for the gline.

       "daemon_cmd_kline"

       Takes a number of arguments depending on	where the KLINE	is to be
       applied and for how long:

       To set a	permanent KLINE:

	$ircd->yield(
	    'daemon_cmd_kline',
	    $spoofed_nick,
	    $nick || $user_host_mask,
	    $reason,
	);

       To set a	temporary 10 minute KLINE:

	$ircd->yield(
	    'daemon_cmd_kline',
	    $spoofed_nick,
	    10,
	    $nick || $user_host_mask,
	    $reason,
	);

       To set a	temporary 10 minute KLINE on all servers:

	$ircd->yield(
	    'daemon_cmd_kline',
	    $spoofed_nick,
	    10,
	    $nick || $user_host_mask,
	    'on',
	    '*',
	    $reason,
	);

       "daemon_cmd_unkline"

       Removes a KLINE as indicated by the user@host mask supplied.

       To remove a KLINE:

	$ircd->yield(
	    'daemon_cmd_unkline',
	    $spoofed_nick,
	    $user_host_mask,
	);

       To remove a KLINE from all servers:

	$ircd->yield(
	    'daemon_cmd_unkline',
	    $spoofed_nick,
	    $user_host_mask,
	    'on',
	    '*',
	);

       "daemon_cmd_rkline"

       Used to set a regex based KLINE.	The regex given	must be	based on a
       user@host mask.

       To set a	permanent RKLINE:

	$ircd->yield(
	    'daemon_cmd_rkline',
	    $spoofed_nick,
	    '^.*$@^(yahoo|google|microsoft)\.com$',
	    $reason,
	);

       To set a	temporary 10 minute RKLINE:

	$ircd->yield(
	    'daemon_cmd_rkline',
	    $spoofed_nick,
	    10,
	    '^.*$@^(yahoo|google|microsoft)\.com$',
	    $reason,
	);

       To set a	temporary 10 minute RKLINE on all servers:

	$ircd->yield(
	    'daemon_cmd_kline',
	    $spoofed_nick,
	    10,
	    '^.*$@^(yahoo|google|microsoft)\.com$',
	    'on',
	    '*',
	    $reason,
	);

       "daemon_cmd_sjoin"

       Takes two arguments a spoofed nickname and an existing channel name.
       This command will then manipulate the channel timestamp to clear	all
       modes on	that channel, including	existing channel operators, reset the
       channel mode to '+nt', the spoofed nick will then join the channel and
       gain channel ops.

       "daemon_cmd_privmsg"

       Takes three arguments, a	spoofed	nickname, a target (which can be a
       nickname	or a channel name) and whatever	text you wish to send.

       "daemon_cmd_notice"

       Takes three arguments, a	spoofed	nickname, a target (which can be a
       nickname	or a channel name) and whatever	text you wish to send.

       "daemon_cmd_locops"

       Takes two arguments, a spoofed nickname and the text message to send to
       local operators.

       "daemon_cmd_wallops"

       Takes two arguments, a spoofed nickname and the text message to send to
       all operators.

       "daemon_cmd_operwall"

       Takes two arguments, a spoofed nickname and the text message to send to
       all operators.

OUTPUT EVENTS
   "ircd_daemon_error"
       Emitted:	when we	fail to	register with a	peer;
       Target: all plugins and registered sessions;
       Args:
	   o   "ARG0", the connection id;

	   o   "ARG1", the server name;

	   o   "ARG2", the reason;

   "ircd_daemon_server"
       Emitted:	when a server is introduced onto the network;
       Target: all plugins and registered sessions;
       Args:
	   o   "ARG0", the server name;

	   o   "ARG1", the name	of the server that is introducing them;

	   o   "ARG2", the hop count;

	   o   "ARG3", the server description;

   "ircd_daemon_squit"
       Emitted:	when a server quits the	network;
       Target: all plugins and registered sessions;
       Args:
	   o   "ARG0", the server name;

   "ircd_daemon_nick"
       Emitted:	when a user is introduced onto the network or changes their
       nickname
       Target: all plugins and registered sessions;
       Args (new user):
	   o   "ARG0", the nickname;

	   o   "ARG1", the hop count;

	   o   "ARG2", the time	stamp (TS);

	   o   "ARG3", the user	mode;

	   o   "ARG4", the ident;

	   o   "ARG5", the hostname;

	   o   "ARG6", the server name;

	   o   "ARG7", the real	name;

       Args (nick change):
	   o   "ARG0", the full	nick!user@host;

	   o   "ARG1", the new nickname;

   "ircd_daemon_umode"
       Emitted:	when a user changes their user mode;
       Target: all plugins and registered sessions;
       Args:
	   o   "ARG0", the full	nick!user@host;

	   o   "ARG1", the user	mode change;

   "ircd_daemon_quit"
       Emitted:	when a user quits or the server	they are on squits;
       Target: all plugins and registered sessions;
       Args:
	   o   "ARG0", the full	nick!user@host;

	   o   "ARG1", the quit	message;

   "ircd_daemon_join"
       Emitted:	when a user joins a channel
       Target: all plugins and registered sessions;
       Args:
	   o   "ARG0", the full	nick!user@host;

	   o   "ARG1", the channel name;

   "ircd_daemon_part"
       Emitted:	when a user parts a channel;
       Target: all plugins and registered sessions;
       Args:
	   o   "ARG0", the full	nick!user@host;

	   o   "ARG1", the channel name;

	   o   "ARG2", the part	message;

   "ircd_daemon_kick"
       Emitted:	when a user is kicked from a channel;
       Target: all plugins and registered sessions;
       Args:
	   o   "ARG0", the full	nick!user@host of the kicker;

	   o   "ARG1", the channel name;

	   o   "ARG2", the nick	of the kicked user;

	   o   "ARG3", the kick	message;

   "ircd_daemon_mode"
       Emitted:	when a channel mode is changed;
       Target: all plugins and registered sessions;
       Args:
	   o   "ARG0", the full	nick!user@host or server name;

	   o   "ARG1", the channel name;

	   o   "ARG2..$#_", the	modes and their	arguments;

   "ircd_daemon_topic"
       Emitted:	when a channel topic is	changed
       Target: all plugins and registered sessions;
       Args:
	   o   "ARG0", the full	nick!user@host of the changer;

	   o   "ARG1", the channel name;

	   o   "ARG2", the new topic;

   "ircd_daemon_public"
       Emitted:	when a channel message is sent (a spoofed nick must be in the
       channel)
       Target: all plugins and registered sessions;
       Args:
	   o   "ARG0", the full	nick!user@host of the sender;

	   o   "ARG1", the channel name;

	   o   "ARG2", the message;

   "ircd_daemon_privmsg"
       Emitted:	when someone sends a private message to	a spoofed nick
       Target: all plugins and registered sessions;
       Args:
	   o   "ARG0", the full	nick!user@host of the sender;

	   o   "ARG1", the spoofed nick	targeted;

	   o   "ARG2", the message;

   "ircd_daemon_notice"
       Emitted:	when someone sends a notice to a spoofed nick or channel
       Target: all plugins and registered sessions;
       Args:
	   o   "ARG0", the full	nick!user@host of the sender;

	   o   "ARG1", the spoofed nick	targeted or channel spoofed nick is
	       in;

	   o   "ARG2", the message;

   "ircd_daemon_invite"
       Emitted:	when someone invites a spoofed nick to a channel;
       Target: all plugins and registered sessions;
       Args:
	   o   "ARG0", the full	nick!user@host of the inviter;

	   o   "ARG1", the spoofed nick	being invited;

	   o   "ARG2", the channel being invited to;

   "ircd_daemon_rehash"
       Emitted:	when an	oper issues a REHASH command;
       Target: all plugins and registered sessions;
       Args:
	   o   "ARG0", the full	nick!user@host of the oper;

   "ircd_daemon_die"
       Emitted:	when an	oper issues a DIE command;
       Target: all plugins and registered sessions;
       Args:
	   o   "ARG0", the full	nick!user@host of the oper;

       Note: the component will	shutdown, this is a feature;

   "ircd_daemon_gline"
       Emitted:	when an	oper issues a GLINE command;
       Target: all plugins and registered sessions;
       Args:
	   o   "ARG0", the full	nick!user@host;

	   o   "ARG1", the user	mask;

	   o   "ARG2", the host	mask;

	   o   "ARG3", the reason;

   "ircd_daemon_kline"
       Emitted:	when an	oper issues a KLINE command;
       Target: all plugins and registered sessions;
       Args:
	   o   "ARG0", the full	nick!user@host;

	   o   "ARG1", the target for the KLINE;

	   o   "ARG2", the duration in seconds;

	   o   "ARG3", the user	mask;

	   o   "ARG4", the host	mask;

	   o   "ARG5", the reason;

   "ircd_daemon_rkline"
       Emitted:	when an	oper issues an RKLINE command;
       Target: all plugins and registered sessions;
       Args:
	   o   "ARG0", the full	nick!user@host;

	   o   "ARG1", the target for the RKLINE;

	   o   "ARG2", the duration in seconds;

	   o   "ARG3", the user	mask;

	   o   "ARG4", the host	mask;

	   o   "ARG5", the reason;

   "ircd_daemon_unkline"
       Emitted:	when an	oper issues an UNKLINE command;
       Target: all plugins and registered sessions;
       Args:
	   o   "ARG0", the full	nick!user@host;

	   o   "ARG1", the target for the UNKLINE;

	   o   "ARG2", the user	mask;

	   o   "ARG3", the host	mask;

   "ircd_daemon_locops"
       Emitted:	when an	oper issues a LOCOPS command;
       Target: all plugins and registered sessions;
       Args:
	   o   "ARG0", the full	nick!user@host;

	   o   "ARG1", the locops message;

   "ircd_daemon_operwall"
       Emitted:	when an	oper issues a WALLOPS or OPERWALL command;
       Target: all plugins and registered sessions;
       Args:
	   o   "ARG0", the full	nick!user@host;

	   o   "ARG1", the wallops or operwall message;

   "ircd_daemon_wallops"
       Emitted:	when a server issues a WALLOPS;
       Target: all plugins and registered sessions;
       Args:
	   o   "ARG0", the server name;

	   o   "ARG1", the wallops message;

BUGS
       A few have turned up in the past	and they are sure to again. Please use
       <http://rt.cpan.org/> to	report any. Alternatively, email the current
       maintainer.

DEVELOPMENT
       You can find the	latest source on github:
       <http://github.com/bingos/poe-component-server-irc>

       The project's developers	usually	hang out in the	"#poe" IRC channel on
       irc.perl.org. Do	drop us	a line.

MAINTAINER
       Hinrik Arn SigurA<degree>sson <hinrik.sig@gmail.com>

AUTHOR
       Chris 'BinGOs' Williams

LICENSE
       Copyright "(c)" Chris Williams

       This module may be used,	modified, and distributed under	the same terms
       as Perl itself. Please see the license that came	with your Perl
       distribution for	details.

KUDOS
       Rocco Caputo for	creating POE.

       Buu for pestering me when I started to procrastinate =]

SEE ALSO
       POE <http://poe.perl.org/>

       POE::Component::Server::IRC::Backend

       Net::Netmask

       Hybrid IRCD <http://ircd-hybrid.com/>

       TSOra <http://www.idolnet.org/docs/README.TSora>

       RFC 2810	<http://www.faqs.org/rfcs/rfc2810.html>

       RFC 2811	<http://www.faqs.org/rfcs/rfc2811.html>

       RFC 2812	<http://www.faqs.org/rfcs/rfc2812.html>

       RFC 2813	<http://www.faqs.org/rfcs/rfc2813.html>

perl v5.32.0			  2011-11-25	POE::Component::Server::IRC(3)

NAME | SYNOPSIS | DESCRIPTION | CONSTRUCTOR | METHODS | INPUT EVENTS | OUTPUT EVENTS | BUGS | DEVELOPMENT | MAINTAINER | AUTHOR | LICENSE | KUDOS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=POE::Component::Server::IRC&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help