commit 2c1a20a1aa7a8f8261c425e784bf7305b59ad00b from: Martijn van Duren date: Fri Aug 23 04:57:39 2019 UTC Add fixes suggested by jmc@ commit - 30f1cbacdec202675f3b67c0012a07733e5420a0 commit + 2c1a20a1aa7a8f8261c425e784bf7305b59ad00b blob - 089c86c392647191806288894f7d67cb10139b48 blob + ee8414951af4e8b725d4b76f1bcdb7aaf43d7bc9 --- osmtpd_run.3 +++ osmtpd_run.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: smtpd_init.3,v 1.13 2018/07/09 19:47:20 tb Exp $ +.\" $OpenBSD$ .\" .\" Copyright (c) 2019 Martijn van Duren .\" @@ -56,8 +56,8 @@ .Nm osmtpd_filter_disconnect , .Nm osmtpd_filter_rewrite , .Nm osmtpd_filter_dataline , -.Nm osmtpd_run -.Nm osmtpd_err +.Nm osmtpd_run , +.Nm osmtpd_err , .Nm osmtpd_errx .Nd C filter API for .Xr smtpd 8 @@ -238,7 +238,7 @@ class of functions, followed by .Nm osmtpd_run . .Pp .Nm osmtpd_run -starts the communication with the server and transforms netwerk queries to +starts the communication with the server and transforms network queries to callbacks. Internally it uses .Xr event_dispatch 3 , @@ -247,12 +247,12 @@ which allows filters to be written fully asynchronousl Each callback .Fa cb gets at least a pointer of the type -.Fa struct osmtpd_ctx. +.Fa struct osmtpd_ctx . It contains the following elements: -.Bl -tag -compact -width Ds +.Bl -tag -width Ds .It Fa "enum osmtpd_type type" The type of request being made. -The possible values are +The possible values are .Dv OSMTPD_TYPE_FILTER and .Dv OSMTPD_TYPE_REPORT . @@ -333,18 +333,15 @@ Most filters don't need this information. The time the event was triggered inside .Xr smtpd 8 . .It Vt int Va incoming -Set to -.Dv 1 -if the event was based on an incoming connection, -.Dv 2 -if it's an outgoing connection. +Set to 1 if the event was based on an incoming connection, 2 if it's an outgoing +connection. The .Nm osmtpd_register_filter class of functions is always based on incoming connections. .Nm osmtpd_register_report can be both incoming and outgoing. .It Vt uint64_t Va reqid -The request id of the connection the event was issued on. +The request ID of the connection the event was issued on. This value can be useful for logging. Filters in need of filter specific data can use .Nm osmtpd_local_session @@ -363,9 +360,9 @@ It can have the following families: .Dv AF_INET6 and .Dv AF_UNIX . -To use this attribute +To use this attribute, initialize .Nm osmtpd_need -needs to be initialized with +with .Dv OSMTPD_NEED_SRC . If not available the entire attribute is zeroed out. .It Vt "struct sockaddr_storage" Va dst @@ -378,46 +375,46 @@ It can have the following families: .Dv AF_INET6 and .Dv AF_UNIX . -To use this attribute +To use this attribute, initialize .Nm osmtpd_need -needs to be initialized with +with .Dv OSMTPD_NEED_DST . If not available the entire attribute is zeroed out. .It Vt char Va *rdns The reverse DNS hostname of the connection. -To use this attribute +To use this attribute, initialize .Nm osmtpd_need -needs to be initialized with +with .Dv OSMTPD_NEED_RDNS . If not available the attribute is set to .Dv NULL . .It Vt enum osmtpd_status Va fcrdns Whether the reverse DNS hostname is forward confirmed. -To use this attribute +To use this attribute, initialize .Nm osmtpd_need -needs to be initialized with +with .Dv OSMTPD_NEED_FCRDNS . If not available the attribute is set to .Dv OSMTPD_STATUS_TEMPFAIL . .It Vt char Va *identity -The identity of the remote host as presented by the helo or ehlo smtp command. -To use this attribute +The identity of the remote host as presented by the HELO or EHLO SMTP command. +To use this attribute, initialize .Nm osmtpd_need -needs to be initialized with +with .Dv OSMTPD_NEED_IDENTITY . If not available the attribute is set to .Dv NULL . .It Vt char Va *ciphers The ciphers used during .Po start Pc Ns tls . -To use this attribute +To use this attribute, initialize .Nm osmtpd_need -needs to be initialized with +with .Dv OSMTPD_NEED_CIPHERS . If not available the attribute is set to .Dv NULL . .It Vt uint32_t Va msgid -The message id of the current message being handled in the smtp transaction. +The message ID of the current message being handled in the SMTP transaction. This value can be useful for logging. .Nm osmtpd_need needs to be initialized with @@ -429,28 +426,28 @@ Filters in need of filter specific data can use and .Va local_message . .It Vt char Va *mailfrom -The envelope mail from address in the smtp transaction. +The envelope MAIL FROM address in the SMTP transaction. .Nm osmtpd_need needs to be initialized with .Dv OSMTPD_NEED_MAILFROM . If not available the attribute is set to .Dv NULL . .It Vt char Va **rcptto -The envelope rcpt to address in the smtp transaction. +The envelope RCPT TO address in the SMTP transaction. .Nm osmtpd_need needs to be initialized with .Dv OSMTPD_NEED_RCPTTO . This attribute is a NULL-terminated array of address strings. If not available the first element in the array is set to .Dv NULL . -.It Vt "uint64_t Va evpid -The envelope id we're currently working on. +.It Vt uint64_t Va evpid +The envelope ID we're currently working on. .Nm osmtpd_need needs to be initialized with .Dv OSMTPD_NEED_EVPID . If not available the attribute is set to .Dv 0 . -.It Vt "void Va *local_session +.It Vt void Va *local_session Any filter specific data that needs to be stored during the session. This is initialized on .Fa ctx @@ -458,7 +455,7 @@ creation by calling .Fa oncreate argument from .Nm osmtpd_local_session . -.It Vt "void Va *local_message +.It Vt void Va *local_message Any filter specific data that needs to be stored during the message transaction. This is initialized on .Fa ctx @@ -481,7 +478,9 @@ through another callback. Note that the session stalls until the .Nm osmtpd_filter has been called. +.Pp Exceptions to the above reply options are: +.Pp .Bl -bullet -compact -width Ds .It .Nm osmtpd_register_filter_connect Ns 's