View on
MetaCPAN is shutting down
For details read Perl NOC. After June 25th this page will redirect to
Uri Guttman > Mail-Postfix-Attr-0.03 > Mail::Postfix::Attr



Annotate this POD

View/Report Bugs
Module Version: 0.03   Source  


Mail::Postfix::Attr - Encode and decode Postfix attributes


  use Mail::Postfix::Attr;

  my $pf_attr = Mail::Postfix::Attr->new( 'codec' => '0',
                                          'path' => '/tmp/postfix_sock' ) ;

  my $pf_attr = Mail::Postfix::Attr->new( 'codec' => 'plain',
                                          'inet' => 'localhost:9999' ) ;

  my @result_attrs = $pf_attr->send( 'foo' => 4, 'bar' => 'blah' ) ;

  my $attr_text = $pf_attr->encode( 'foo' => 4, 'bar' => 'blah' ) ;

  my @attrs = $pf_attr->decode( $attr_text ) ;


Mail::Postfix::Attr supports encoding and decoding of the three formats of attributes used in the postfix MTA. Attributes are used by postfix to communicate with various of its services such as the verify program. These formats are:

  plain - key=value\n   (a collection of attributes has an \n appended)
  0     - key\0value\0  (a collection of attributes has a \0 appended)
  64    - base64(key):base64(value)\n
                        (a collection of attributes has an \n appended)

These formats are from the specifications in the postfix source files in the src/util directory:


If you run 'make test' (after building postfix) in this directory it will build these programs which can be used to test this Perl module:


new() method

        my $pf_attr = Mail::Postfix::Attr->new( 'codec' => '0',
                                          'path' => '/tmp/postfix_sock' ) ;

The new method takes a list of key/value arguments.

        codec   => <codec_type>
        path    => <unix_socket_path>
        inet    => <host:port>

        codec_type is one of '0', '64' or 'plain'. It defaults to
        'plain' if not set or it is not in the allowed codec set.

        The <unix_socket_path> argument is the unix domain socket that
        will be used to send a message to a postfix service. The
        message will be encoded and its response decoded with the
        selected codec.

        The <inet> argument is the internet domain address that will
        be used to send a message to a postfix service. It must be in
        the form of "host:port" where host can be a hostname or IP
        address and port can be a number or a name in
        /etc/services. The message will be encoded and its response
        decoded with the selected codec.

send() method

The send method is passed a list of postfix attribute key/value pairs. It first connects to a postfix service using the UNIX or INET socket. It then encodes the attributes using the selected codec and writes that data to the socket. It then reads from the socket to EOF and decodes that data with the codec and returns that list of attribute key/value pairs to the caller.

  my @result_attrs = $pf_attr->send( 'foo' => 4, 'bar' => 'blah' ) ;

encode() method

The encode method takes a list of key/values and encodes it according to the selected codec. It returns a single string which has the encoded text of the attribute/value pairs. Each call will create a single attribute section which is terminated by an extra separator char.

  my $attr_text = $pf_attr->encode( 'foo' => 4, 'bar' => 'blah' ) ;

You can also call each encoder directly as a class method:

  my $attr_text = Mail::Postfix::Attr->encode_0( 'foo' => 4, 'bar' => 'blah' ) ;
  my $attr_text =
        Mail::Postfix::Attr->encode_64( 'foo' => 4, 'bar' => 'blah' ) ;
  my $attr_text =
        Mail::Postfix::Attr->encode_plain( 'foo' => 4, 'bar' => 'blah' ) ;

decode() method

The decode method takes a single string of encoded attributes and decodes it into a list of attribute sections. Each section is decoded into a list of attribute/value pairs. It returns a list of array references, each of which has the attribute/value pairs of one attribute section.

  my @attrs = $pf_attr->decode( $attr_text ) ;

You can also call each decoder directly as a class method:

  my @attrs = Mail::Postfix::Attr->decode_0( $attr_text ) ;
  my @attrs = Mail::Postfix::Attr->decode_64( $attr_text ) ;
  my @attrs = Mail::Postfix::Attr->decode_plain( $attr_text ) ;


  # talk to the verify(8) service available in Postfix v2.
  # perl -MMail::Postfix::Attr -le 'print for Mail::Postfix::Attr
           ->new (codec=>0, path=>"/var/spool/postfix/private/verify")

  aliased to root


Uri Guttman,

syntax highlighting: