README
1SMTP::Server
2------------
3
4This module is a complete, RFC 821 compliant, SMTP server implementation
5written entirely in Perl. It has powerful extensively and customization
6facilities that allow for a variety of potential uses.
7
8You can always find the most current version at:
9
10http://www.macgyver.org/software/perl/
11
12This software is Copyright(C) 1999, MacGyver (aka Habeeb J. Dihu).
13All Rights Reserved.
14
15You may distribute this package under the terms of either the GNU
16General Public License or the Artistic License, as specified in the
17Perl README file.
18
19To install:
20
21perl Makefile.PL
22
23This will generate the necessary Makefiles for you.
24
25make
26make install
27
28And you're all set. If you really want to run a couple of tests, type
29make check
30
31You may not have 'make' available on Win32 platforms, if not, you can always
32just copy the Server.pm file and the Server directory to your Perl library
33underneath the Net/SMTP directory.
34
35----
36NAME
37 Net::SMTP::Server - A native Perl SMTP Server implementation for
38 Perl.
39
40SYNOPSIS
41 use Carp;
42 use Net::SMTP::Server;
43 use Net::SMTP::Client;
44 use Net::SMTP::Relay;
45
46 $server = new Net::SMTP::Server('localhost', 25) ||
47 croak("Unable to handle client connection: $!\n");
48
49 while($conn = $server->accept()) {
50 # We can perform all sorts of checks here for spammers, ACLs,
51 # and other useful stuff to check on a connection.
52
53 # Handle the client's connection and spawn off a new parser.
54 # This can/should be a fork() or a new thread,
55 # but for simplicity...
56 my $client = new Net::SMTP::Server::Client($conn) ||
57 croak("Unable to handle client connection: $!\n");
58
59 # Process the client. This command will block until
60 # the connecting client completes the SMTP transaction.
61 $client->process || next;
62
63 # In this simple server, we're just relaying everything
64 # to a server. If a real server were implemented, you
65 # could save email to a file, or perform various other
66 # actions on it here.
67 my $relay = new Net::SMTP::Server::Relay($client->{FROM},
68 $client->{TO},
69 $client->{MSG});
70 }
71
72DESCRIPTION
73 The Net::SMTP::Server module implements an RFC 821 compliant
74 SMTP server, completely in Perl. It's extremely extensible, so
75 adding in things like spam filtering, or more advanced routing
76 and handling features can be easily handled. An additional
77 module, Net::SMTP::Server::Relay has also been implemented as an
78 example of just one application of this extensibility. See the
79 pod for more details on that module. This extension has been
80 tested on both Unix and Win32 platforms.
81
82 Creating a new server is as trivial as:
83
84 $server = new Net::SMTP::Server($host, $port);
85
86 This creates a new SMTP::Server. Both $host and $port are
87 optional, and default to the current hostname and the standard
88 SMTP port (25). However, if you run on a multi-homed machine,
89 you may want to explicitly specify which interface to bind to.
90
91 The server loop should look something like this:
92
93 while($conn = $server->accept()) {
94 my $client = new Net::SMTP::Server::Client($conn) ||
95 croak("Unable to handle client connection: $!\n");
96
97 $client->process;
98 }
99
100 The server will continue to accept connections forever. Once we
101 have a connection, we create a new Net::SMTP::Server::Client.
102 This is a new client connection that will now be handled. The
103 reason why processing doesn't begin here is to allow for any
104 extensibility or hooks a user may want to add in after we've
105 accepted the client connection, but before we give the initial
106 welcome message to the client. Once we're ready to process an
107 SMTP session, we call $client->process. This may HANG while the
108 SMTP transaction takes place, as the client and server are
109 communicating back and forth (and if there's a lot of data to
110 transmit, well...).
111
112 Once $client->process returns, various fields have been filled
113 in. Those are:
114
115 $client->{TO} -- This is an array containing the intended
116 recipients for this message. There may be
117 multiple recipients for any given message.
118
119 $client->{FROM} -- This is the sender of the given message.
120 $client->{MSG} -- The actual message data. :)
121
122 The SMTP::Server module performs no other processing for the
123 user. It's meant to give you the building blocks of an
124 extensible SMTP server implementation. For example, using the
125 MIME modules, you can easily process $client->{MSG} to handle
126 MIME attachments, etc. Or you could implement ACLs to control
127 who can connect to the server, or what actions are taken.
128 Finally, a suggested use that the author himself uses, is as an
129 SMTP relay. There are lots of times I need access to an SMTP
130 server just to send a message, but don't have access to one for
131 whatever reason (firewalls, permissions, etc). You can run your
132 own SMTP server whether under Unix or Win32 environments, and
133 simply point your favorite mail client to it when sending
134 messages. See the Net::SMTP::Server::Relay modules for details
135 on that use.
136
137AUTHOR AND COPYRIGHT
138Net::SMTP::Server / SMTP::Server is Copyright(C) 1999,
139 MacGyver (aka Habeeb J. Dihu) <macgyver@tos.net>. ALL RIGHTS RESERVED.
140 You may distribute this package under the terms of either the
141 GNU General Public License or the Artistic License, as specified
142 in the Perl README file.
143
144SEE ALSO
145 Net::SMTP::Server::Client, Net::SMTP::Server::Relay
146
147