GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  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

CONTENTS

Synopsis
Description
Callback Functions
Helper Functions
Return Values
Examples
Errors
See Also

SYNOPSIS


.In smtpd-defines.h
.In 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 set up 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 accepted.
FILTER_CLOSE
  The filter is done and the message should not be accepted.

Moreover, with the function 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 function filter_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 set up 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 clean up 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 clean up 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 clean up earlier setup data structures.

HELPER FUNCTIONS

The function filter_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 functions filter_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.

EXAMPLES

filter-stub(8), which ships with the OpenSMTPD-extras package, is intended to provide an example code template.

ERRORS

The function filter_api_sockaddr_to_text may fail for any of the errors specified for the routine getnameinfo(3) and listed in gai_strerror(3).

SEE ALSO

smtpd.conf(5), filter-stub(8), smtpd(8)
Search for    or go to Top of page |  Section 3 |  Main Index


Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.