[hcoop/debian/exim4.git] / src / routers / README

ROUTERS:

The yield of a router is one of:

  OK              the address was routed and either added to one of the
                  addr_local or addr_remote chains, or one or more new
                  addresses were added to addr_new. The original may be added
                  to addr_succeed.

  REROUTED        this is used when a child address is created and added to
                  addr_new as a consequence of a domain widening or because
                  "self = reroute" was encountered. The only time it is handled
                  differently from OK is when verifying, to force it to
                  continue with the child address.

  DECLINE         the address was not routed; pass to next router unless
                  no_more is set. It is permitted for additional addresses to
                  have been added to addr_new (or indeed for addresses to have
                  been put on the other chains).

  PASS            the address was not routed, but might have been modified;
                  pass to the next router unconditionally.

  DISCARD         the address was discarded (:blackhole: or "seen finish")

  FAIL            the address was not routed; do not pass to any subsequent
                  routers, i.e. cause routing to fail.

  DEFER           retry this address later.

Both ERROR and DEFER cause the message to be kept on the queue; either may
request freezing, but nowadays we try not to request freezing from routers
because it may hold up other addresses in the message.


When routing succeeds, the following field in the address can be set:

  transport       points to the transport instance control block

  uid, gid        are the uid and gid under which a local transport is to be
                  run if the transport does not itself specify them.

  initgroups      is set true if initgroups() is to be called when using the
                  uid and gid set up by the router.

  fallback_hosts  fallback host list - relevant only if the router sets up
                  a remote transport for the address.

  errors_address  where to send error messages for this address.

  extra_headers   additional headers to be added to the message for this
                  address.

  remove_headers  the names of headers to be removed from the message for this
                  address

****
Commit	Line	Data
420a0d19 CE	1	ROUTERS:
	2
	3	The yield of a router is one of:
	4
	5	OK the address was routed and either added to one of the
	6	addr_local or addr_remote chains, or one or more new
	7	addresses were added to addr_new. The original may be added
	8	to addr_succeed.
	9
	10	REROUTED this is used when a child address is created and added to
	11	addr_new as a consequence of a domain widening or because
	12	"self = reroute" was encountered. The only time it is handled
	13	differently from OK is when verifying, to force it to
	14	continue with the child address.
	15
	16	DECLINE the address was not routed; pass to next router unless
	17	no_more is set. It is permitted for additional addresses to
	18	have been added to addr_new (or indeed for addresses to have
	19	been put on the other chains).
	20
	21	PASS the address was not routed, but might have been modified;
	22	pass to the next router unconditionally.
	23
	24	DISCARD the address was discarded (:blackhole: or "seen finish")
	25
2813c06e	26	FAIL the address was not routed; do not pass to any subsequent
420a0d19 CE	27	routers, i.e. cause routing to fail.
	28
	29	DEFER retry this address later.
	30
	31	Both ERROR and DEFER cause the message to be kept on the queue; either may
	32	request freezing, but nowadays we try not to request freezing from routers
	33	because it may hold up other addresses in the message.
	34
	35
	36	When routing succeeds, the following field in the address can be set:
	37
	38	transport points to the transport instance control block
	39
	40	uid, gid are the uid and gid under which a local transport is to be
	41	run if the transport does not itself specify them.
	42
	43	initgroups is set true if initgroups() is to be called when using the
	44	uid and gid set up by the router.
	45
	46	fallback_hosts fallback host list - relevant only if the router sets up
	47	a remote transport for the address.
	48
	49	errors_address where to send error messages for this address.
	50
	51	extra_headers additional headers to be added to the message for this
	52	address.
	53
	54	remove_headers the names of headers to be removed from the message for this
	55	address
	56
	57	****