table of contents
other versions
- jessie-backports 5.7.1-2~bpo8+1
- testing 5.7.1-4+b1
- unstable 5.7.1-4+b2
FILTER_API(3) | Library Functions Manual | FILTER_API(3) |
NAME¶
filter_api_loop
,
filter_api_accept
,
filter_api_reject
,
filter_api_reject_code
,
filter_api_writeln
,
filter_api_on_connect
,
filter_api_on_helo
,
filter_api_on_mail
,
filter_api_on_rcpt
,
filter_api_on_data
,
filter_api_on_dataline
,
filter_api_on_eom
,
filter_api_on_reset
,
filter_api_on_disconnect
,
filter_api_on_commit
,
filter_api_on_rollback
,
filter_api_setugid
,
filter_api_set_chroot
,
filter_api_no_chroot
,
filter_api_set_udata
,
filter_api_get_udata
,
filter_api_sockaddr_to_text
,
filter_api_mailaddr_to_text
—
filter API for smtpd
SYNOPSIS¶
#include
<smtpd-defines.h>
#include
<smtpd-api.h>
void
filter_api_loop
(void);
int
filter_api_accept
(uint64_t
id);
int
filter_api_reject
(uint64_t
id, enum
filter_status status);
int
filter_api_reject_code
(uint64_t
id, enum
filter_status status,
uint32_t code,
const char
*line);
void
filter_api_writeln
(uint64_t
id, const char *
line);
void
filter_api_on_connect
(int(*cb)(uint64_t,
struct filter_connect *));
void
filter_api_on_helo
(int(*cb)(uint64_t,
const char *));
void
filter_api_on_mail
(int(*cb)(uint64_t,
struct mailaddr *));
void
filter_api_on_rcpt
(int(*cb)(uint64_t,
struct mailaddr *));
void
filter_api_on_data
(int(*cb)(uint64_t));
void
filter_api_on_dataline
(void(*cb)(uint64_t,
const char *));
void
filter_api_on_eom
(int(*cb)(uint64_t,
size_t));
void
filter_api_on_reset
(void(*cb)(uint64_t));
void
filter_api_on_disconnect
(void(*cb)(uint64_t));
void
filter_api_on_commit
(void(*cb)(uint64_t));
void
filter_api_on_rollback
(void(*cb)(uint64_t));
void
filter_api_setugid
(uid_t
uid, gid_t
gid);
void
filter_api_set_chroot
(const
char *rootpath);
void
filter_api_no_chroot
(void);
void
filter_api_set_udata
(uint64_t
id, void
*data);
void *
filter_api_get_udata
(uint64_t
id);
const char *
filter_api_sockaddr_to_text
(const
struct sockaddr *sa);
const char *
filter_api_mailaddr_to_text
(const
struct mailaddr *maddr);
DESCRIPTION¶
filter_api
is an interface intended to
provide filter capabilities for the smtpd(8)
daemon. filter_api
is used in standalone
filter programs, which setup callback functions to hook into the SMTP dialog.
For example, each SMTP command can be intercepted with callback functions.
The function filter_api_loop
() is used to
enter the filter loop, waiting for callback functions to be called.
The function filter_api_accept
() can be
called to accept the current message with the given
id from within a callback function.
The functions filter_api_reject
() and
filter_api_reject_code
() can be called to
reject the current message with the given id
from within a callback function. Both expect the
status to be specified which should be one of
the following values.
FILTER_FAIL
- The filter failed and the message should not be accpeted.
FILTER_CLOSE
- The filter is done and the message should not be accepted.
filter_api_reject_code
() a
code and
line can be specified, to reject the current
message with a custom SMTP reply code and error message.
The function filter_api_writeln
() is intended
to write (received) SMTP DATA command lines (back) from within a callback
function. This might be used by a filter to add or modifiy DATA lines.
CALLBACK FUNCTIONS¶
The functionfilter_api_on_connect
() is
called on new SMTP connections. The callback can be used to accept or reject
messages based on the given connection information.
The function filter_api_on_helo
() is called
on SMTP HELO command. The callback can be used to accept or reject messages
based on the given HELO string.
The function filter_api_on_mail
() is called
on SMTP MAIL FROM command. The callback can be used to accept or reject
messages based on the given MAIL FROM address.
The function filter_api_on_rcpt
() is called
on SMTP RCPT TO command. The callback can be used to accept or reject messages
based on the given RCPT TO address.
The function filter_api_on_data
() is called
on SMTP DATA command. The callback might be used to setup data structures for
filtering the upcoming DATA lines.
The function filter_api_on_dataline
() is
called on each SMTP DATA line. The callback can be used to accept or reject
messaged based on the (header or body) content of the current message.
The function filter_api_on_eom
() is called on
the end (of DATA command) of the current message. The callback might be used
to cleanup data structures and finalize the decision of accepting or rejecting
the message.
The function filter_api_on_reset
() is called
on SMTP RSET command. The callback might be used to reset the current filter
state.
The function filter_api_on_disconnect
() is
called on closed SMTP connections. The callback might be used to cleanup
earlier setup data structures.
The function filter_api_on_commit
() is called
on commit of the current message.
The function filter_api_on_rollback
() is
called on rollback of the SMTP session. The callback might be used to cleanup
earlier setup data structures.
HELPER FUNCTIONS¶
The functionfilter_api_setugid
() can be
called using uid and
gid to set the running user and group of the
filter.
The function filter_api_set_chroot
() can be
called using rootpath to set the chroot path
of the filter.
The function filter_api_no_chroot
() can be
called to disable chroot for the filter.
The function filter_api_set_udata
() can be
called for the current message with the given
id to set a user data pointer
data from within a callback function.
The function filter_api_get_udata
() can be
called to get the user data pointer for the current message with the given
id from within a callback function.
The function filter_api_sockaddr_to_text
()
can be called to convert a socket address sa
to a string.
The function filter_api_mailaddr_to_text
()
can be called to convert a mail address maddr
to a string.
RETURN VALUES¶
The functionsfilter_api_accept
(),
filter_api_reject
(), and
filter_api_reject_code
(), return 1,
intended to be used in a return statement of a callback function.
The function filter_api_get_udata
() returns a
pointer to the user data set for the current message.
The functions filter_api_sockaddr_to_text
()
and filter_api_mailaddr_to_text
() return a
pointer to a static buffer containing the string representation. The buffer
remains valid until the next call to the conversion functions. In case of
error, the function
filter_api_sockaddr_to_text
() returns the
static string “(unknown)
” and the
function filter_api_mailaddr_to_text
()
returns NULL.
ERRORS¶
The functionfilter_api_sockaddr_to_text
()
may fail for any of the errors specified for the routine
getnameinfo(3) and listed in
gai_strerror(3).
EXAMPLES¶
filter-stub(8) which ships with OpenSMTPD-extras is intended to provide an example code template.SEE ALSO¶
smtpd.conf(5), smtpd(8), filter-stub(8)June 11, 2015 | Debian |