/ 
Mail-Karmasphere-Client-2.18
River stage zero No dependents
/ karmad

NAME

karmad - Karmasphere daemon for postfix and exim

DESCRIPTION

This is a small daemon which listens on a Unix domain socket and interfaces between Postfix or Exim and Mail::Karmasphere::Client.

See the sample configuration and startup files in the eg/ directory of the source distribution for more information.

COMMAND LINE PARAMETERS

--mta

Optional.

If you're running postfix, set --mta=postfix and karmad will behave as an SMTPD policy daemon.

If you're running exim, set --mta=exim and use the exim ACL provided with Mail::Karmasphere::Client.

If not specified, defaults to exim.

--cutoff-pass =item --cutoff-fail

Recommended.

Scores below cutoff-fail will turn into a "fail/reject". Scores above cutoff-pass will turn into a "pass". You should set these thresholds yourself: Karmasphere provides the score, but you decide policy. If you do not, they will default to +300 and -300.

--action

Optional.

If you're running postfix, you can set --action to one of prepend (default) or reject. Prepend will prepend an X-Karma header. Reject will cause any mail with a karma score below cutoff-fail to be rejected. Use this only if you are happy with the results you've observed.

If not specified, defaults to prepend.

--verbose-header

Optional.

If you've set action to prepend, this flag will add two fields to the X-Karma header: identities shows what was queried, and query_id includes the timestamp and (if available) the MTA's queue ID.) This is useful for debugging purposes: it allows one to replay the query.

--username
--password

Optional.

Query credentials for authenticated queries. You only need to set this if you're querying a restricted feedset. For more information, see http://www.karmasphere.com/devzone/client/configuration#credentials

--socket

Where to listen. Defaults to /tmp/karmad. You probably don't need to set this.

--server

Hostname of the Karmasphere Query Server to connect to. Defaults to query.karmasphere.com. You probably don't need to set this, unless you have set up a local query server, in which case you should be following the directions provided with that server.

--feedset

The name of the feedset you want to query. Defaults to karmasphere.email-sender. You probably don't need to set this.

--socketuser
--socketgroup

Who to listen as; defaults to 'nobody'. The socket file will be chowned to this user and group. You probably don't need to set this.

--socketmode

Mode to chmod the socket. You probably don't need to set this.

--user =item --group

When running, setuid to this user and group. Defaults to 'nobody', 'nobody'. You probably don't need to set this.

--syslog

Syslog verbosely to mail.info and mail.debug.

OPERATIONAL USAGE

Connect to the socket (default: /tmp/karmad) and send the following newline-terminated stanza:

client_address=192.0.2.1
helo_name=host.example.com
sender=localpart@example.com

Each of the above lines is optional; you may omit whatever is unavailable.

If all goes well, Karmad will return the following stanza:

value=NN
opinion=(good|bad|neutral)
data=.....

"Value" is a number between -1000 and +1000.

"Opinion" is one of good, bad, or neutral. If the value is greater than 300, opinion is good. If the value is less than -300, the opinion is bad. If it's between, opinion is neutral.

"Data" contains a brief explanation of how the verdict was reached.

If an error occurs, Karmad will return:

error=...

usually, something like

error=timeout
error=Incorrect user and/or password.

HOW TO TEST THAT IT'S WORKING

This section assumes you're running Postfix.

% ./karmad --mta=postfix --action=prepend --verbose-header

Then, connect to it:

% perl -MIO::Socket::UNIX -le 'my $sock = IO::Socket::UNIX->new("/tmp/karmad"); print $sock "client_address=127.0.0.2\n\n"; print <$sock>;'

You should get back something along the lines of:

prepend X-Karma verdict=fail score=-1000 identities=ip4=127.0.0.2=smtp.client-ip query_id=karmad-1206640966 comment=cymru.bogons: if-match(0) => return-bad(1.0)

You should expect to see some STDERR from the karmad.

The karmac script does pretty much the same thing.

If troubleshooting is necessary, use karmaclient to talk to Karmasphere directly, without going through karmad. Then use karmac to talk to karmad.

BUGS

In the response, "opinion" might be more correctly termed "verdict".

SEE ALSO

Mail::Karmasphere::Client Mail::Karmasphere::Query Mail::Karmasphere::Response karmaclient http://www.karmasphere.com/ http://www.postfix.org/SMTPD_POLICY_README.html

COPYRIGHT

Copyright (c) 2005 Shevek, Karmasphere. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.