miltertest ~~~~~~~~~~ This is the development area for the OpenDKIM "miltertest" tool, for exercising milter-based filters. The design is essentially a sequence of commands that indicate either a message to be sent to the filter, a state change (e.g. new connection) to make, or a response to expect from the filter. A test succeeds if the script runs to completion, and fails if anything unexpected happens. miltertest requires a configuration file, which amounts to the test script to be run preceded by information about starting and stopping the filter. The filter to be tested must either already be running (in which case only the socket to which to connect needs to be specified), or miltertest will execute it in a child process and terminate it afterwards (which means the filter being tested has to have a "no fork" option). TEST CONFIGURATION The configuration file is the usual text file with comments delimited by hash ("#") characters, blank lines ignored, and everything else being a keyword followed by its parameters. They are as follows: Socket The socket to which to connect to run tests. Standard milter-style string, e.g. "inet:port@host" or "local:/path". RunFilter miltertest has to start and stop the filter itself by executing the command described by . If that process returns right away because the child will fork() and exit, you must also define "StopFilter" (below). Otherwise, upon completion, miltertest will attempt to terminate the filter by signaling it. StopFilter Upon completion of the test, miltertest will signal the child process in which the filter is running by sending it the specified signal. The default is SIGTERM, followed some seconds later by SIGKILL if it still hasn't died (see "KillDelay"). KillDelay When enacting "StopFilter" above, if the termination signal has been sent and the specified number of seconds have elapsed without the child terminating, SIGKILL will be sent. The default is 20. TestDelay When enacting "RunFilter" above, once the child has been forked, wait this many seconds before beginning the test. The default is 3. Timeout Whenever miltertest is expecting a reply from the filter, this specifies the maximum amount of time it will wait for that reply before deciding the test has failed. The default is 10. Set to 0 for unlimited time. Connect Create a new connection to the filter, with label claiming to be from IP address with name . If names an existing connection, the test will abort; for all other commands with an parameter, must match an established connection or the test will abort. Expect [] Wait for a reply for the connection labeled . The reply should match and may also require specific (see MILTER REPLIES below). Close Terminate the connection labeled . Macros =[,...] Sends a vector of macros down to the filter from the connection labeled . must correspond to a milter state (see MILTER STATES below). Automatically expects a "continue" response from the filter. Negotiate Initiate option negotiation, offering the specified and (each expressed as a bit mask, so an integer is required). Immediately expect that the filter will request and . See MILTER OPTIONS for details. BadCommand [parameters] Tell the filter that connection got the specified unknown command and parameters. Abort Tell the filter that connection aborted the transaction currently in progress. MailFrom
[parameters] Tell the filter that connection got a MAIL FROM with the specified address and optional parameters. RcptTo
[parameters] Tell the filter that connection got a RCPT TO with the specified address and optional parameters. Data Tell the filter that connection received the DATA command. Header Tell the filter that connection sent the specified header (name and value). If has non-standard spacing, quote it. EOH Tell the filter connection announced end-of-headers. Body Tell the filter connection sent a body chunk. is in one of the following forms: arandom: bytes of random ASCII text, with CRLFs thrown in random: bytes of random binary data file: the contents of file the literal string specified, with "\r" translated to a CR and "\n" to an LF EOM Tell the filter connection announced end-of-message. MILTER STATES (finish me!) MILTER OPTIONS (finish me!) MILTER REPLIES (finish me!) $Id$