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

FreeBSD Manual Pages

  
 
  

home | help
FILTER_API(3)		 BSD 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_timer, 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);

     void *
     filter_api_timer(uint64_t id, uint32_t tmo, void (*cb)(uint64_t, void *),
	 void *arg);

     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	exam-
     ple, 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 mes-
     sage 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.  Moreover,	this might be used to set up a filter
     session state.

     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 message state data structures for	fil-
     tering 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 finalize the deci-
     sion of accepting or rejecting the	message.

     The function filter_api_on_reset()	is called whenever the RSET command
     has been issued in	a session.  The	callback implictly calls the
     filter_api_on_rollback() callback.

     The function filter_api_on_disconnect() is	called on closed SMTP connec-
     tions.  The callback might	be used	to clean up earlier setup filter ses-
     sion state	data structures.  Moreover, the	callback implictly calls the
     filter_api_on_rollback() callback.

     The function filter_api_on_commit() is called on commit of	the current
     message.  The callback might be used to clean up earlier setup message
     state data	structures.

     The function filter_api_on_rollback() is called on	rollback of the	SMTP
     session, after the	SMTP RSET and before disconnect.  The callback might
     be	used to	clean up earlier setup message state data structures and to
     rollback the current filter message state.

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_timer() can be called to set up a timeout tmo in
     milliseconds, after which cb is called with the given argument arg.

     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 con-
     taining 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 in-
     tended 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)

BSD				 May 23, 2016				   BSD

NAME | SYNOPSIS | DESCRIPTION | CALLBACK FUNCTIONS | HELPER FUNCTIONS | RETURN VALUES | EXAMPLES | ERRORS | SEE ALSO

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

home | help