~ubuntu-branches/ubuntu/hardy/postfix/hardy-security

« back to all changes in this revision

Viewing changes to proto/FILTER_README.html

• browse files at revision 30
• compare with another revision
• download diff
• download tarball
• view history from revision 30

Show diffs side-by-side

added

removed

proto/FILTER_README.html

71

71

be covered by a later version of this document.  </p>

72

72

 

73

73

<p> The after-queue content filter is not to be confused with the

74

 

approach that is described in the SMTPD_PROXY_README document,

 

74

approaches described in the SMTPD_PROXY_README or MILTER_README

 

75

documents,

75

76

where incoming SMTP mail is filtered BEFORE it is stored into the

76

77

Postfix queue.  </p>

77

78

 

125

126

 

126

127

<h2><a name="principles">Principles of operation</a> </h2>

127

128

 

128

 

<p> An external content filter receives unfiltered mail from Postfix

129

 

(as described further below) and does one of the following: </p>

 

129

<p> An after-queue content filter receives unfiltered mail from Postfix

 

130

(as described further below) and can do one of the following: </p>

130

131

 

131

132

<ol>

132

133

 

133

134

<li> <p> Re-inject the mail back into Postfix, perhaps after changing

134

135

    content and/or destination. </p>

135

136

 

 

137

<li> <p> Discard or quarantine the mail. </p>

 

138

 

136

139

<li> <p> Reject the mail (by sending a suitable status code back to

137

 

    Postfix). Postfix will return the mail to the sender. </p>

 

140

    Postfix). Postfix will send the mail back to the sender address. </p>

138

141

 

139

142

</ol>

140

143

 

146

149

 

147

150

<h2><a name="simple_filter">Simple content filter example</a></h2>

148

151

 

149

 

<p> The first example is simple to set up.  Postfix receives

 

152

<p> The first example is simple to set up, but has major limitations

 

153

that will be addressed in a second example.  Postfix receives

150

154

unfiltered mail from the network with the smtpd(8) server, and

151

155

delivers unfiltered mail to a content filter with the Postfix

152

156

pipe(8) delivery agent.  The content filter injects filtered mail

282

286

 

283

287

<ul>

284

288

 

285

 

<li> <p> Line 8: The -G option does nothing before Postfix 2.3,

286

 

otherwise it disables address rewriting of message headers. </p>

 

289

<li> <p> Line 8: The -G option says the filter output is not a local

 

290

mail submission: don't do silly things like appending the local

 

291

domain name to addresses in message headers.  This option does

 

292

nothing before Postfix version 2.3.  </p>

287

293

 

288

294

<li> <p> Line 8: The -i option says don't stop reading input when

289

295

a line contains "." only.  </p>

290

296

 

291

297

<li> <p> Line 8: NEVER NEVER NEVER use the "-t" command-line option

292

 

here. It will mis-deliver mail, like sending mailing list mail back

293

 

to the mailing list. </p>

 

298

here. It will mis-deliver mail, like sending messages from a mailing

 

299

list back to the mailing list. </p>

294

300

 

295

301

<li> <p> Line 21: The idea is to first capture the message to

296

302

file and then run the content through a third-party content filter

297

303

program. </p>

298

304

 

299

 

<li> <p> Line 22: If the mail cannot be captured to file, mail

 

305

<li> <p> Line 22: If the message cannot be captured to file, mail

300

306

delivery is deferred by terminating with exit status 75 (EX_TEMPFAIL).

301

307

Postfix places the message in the deferred mail queue and tries

302

308

again later.  </p>

306

312

 

307

313

<li> <p> Line 26: If the content filter program finds a problem,

308

314

the mail is bounced by terminating with exit status 69 (EX_UNAVAILABLE).

309

 

Postfix will return the message to the sender as undeliverable.

 

315

Postfix will send the message back to the sender as undeliverable

 

316

mail.

310

317

</p>

311

318

 

312

 

<li> <p> Note: in this time of mail worms and spam, it is a BAD

 

319

<li> <p> NOTE: in this time of mail worms and spam, it is a BAD

313

320

IDEA to send known viruses or spam back to the sender, because that

314

 

address is likely to be forged. It is safer to discard known to be

315

 

bad content and to quarantine suspicious content so that it can

 

321

address is likely to be forged. It is safer to discard known viruses

 

322

and to quarantine suspicious content so that it can

316

323

be inspected by a human being. </p>

317

324

 

318

325

<li> <p> Line 28: If the content is OK, it is given as input to

331

338

 

332

339

<blockquote>

333

340

<pre>

334

 

% /path/to/script -f sender recipient... &lt;message-file

 

341

% /path/to/script -f sender -- recipient... &lt;message-file

335

342

</pre>

336

343

</blockquote>

337

344

 

381

388

        -o content_filter=filter:dummy

382

389

</pre>

383

390

 

384

 

<p> The "content_filter" line causes Postfix to add one content

 

391

<p> The "-o content_filter" line causes Postfix to add one content

385

392

filter request record to each incoming mail message, with content

386

393

"filter:dummy". This record overrides the normal mail routing

387

394

and causes mail to be given to the content filter instead. </p>

432

439

Postfix SMTP server. </p>

433

440

 

434

441

<li> <p> Execute "<b>postsuper -r ALL</b>" to remove content

435

 

filter information from existing queue files. </p>

 

442

filter request records from existing queue files. </p>

436

443

 

437

444

<li> <p> Execute another "<b>postfix reload</b>". </p>

438

445

 

553

560

 

554

561

<p> The example given here filters all mail, including mail that

555

562

arrives via SMTP and mail that is locally submitted via the Postfix

556

 

sendmail command. See examples near the end of this document for

 

563

sendmail command (local submissions enter Postfix via the pickup(8)

 

564

server; to keep the figure simple we omit local submission details).

 

565

See examples near the end of this document for

557

566

how to exclude local users from filtering, or how to configure a

558

567

destination dependent content filter. </p>

559

568

 

638

647

<li> <p> The "-o disable_mime_output_conversion=yes" is a workaround

639

648

that prevents the breaking of domainkeys and other digital signatures.

640

649

This is needed because some SMTP-based content filters don't announce

641

 

8BITMIME support, even though they can handle it just fine.  </p>

 

650

8BITMIME support, even though they can handle 8-bit mail. </p>

642

651

 

643

652

<li> <p> The "-o smtp_generic_maps=" is a workaround that prevents

644

653

local address rewriting with generic(5) maps. Such rewriting should

672

681

dangerous mail content - that is why it should be a separate account.

673

682

</p>

674

683

 

 

684

<li> <p> By default, Postfix will terminate a command that runs

 

685

longer than command_time_limit seconds (default: 1000s). This is a

 

686

safety measure that prevents filters from running forever. </p>

 

687

 

675

688

</ul>

676

689

 

677

690

<p> If you want to have your filter listening on port localhost:10025

711

724

 

712

725

<ul>

713

726

 

714

 

<li> <p> Note: do not use spaces around the "=" or "," characters. </p>

 

727

<li> <p> NOTE: do not use spaces around the "=" or "," characters. </p>

715

728

 

716

 

<li> <p> Note: the SMTP server must not have a smaller process

 

729

<li> <p> NOTE: the SMTP server must not have a smaller process

717

730

limit than the "filter" master.cf entry. </p>

718

731

 

719

732

<li> <p> The "-o content_filter=" overrides main.cf settings, and

720

733

requests no content filtering for mail from the content filter.

721

 

This is required or else mail will stay in the content filtering

722

 

loop. </p>

 

734

This is required or else mail will loop. </p>

723

735

 

724

736

<li> <p> The "-o receive_override_options" overrides main.cf settings

725

737

to avoid duplicating work that was already done before the content

737

749

    <li> <p> We specify "no_milters" to disable Milter applications

738

750

    (this option is available only in Postfix 2.3 and later).  </p>

739

751

 

740

 

    <li> <p> We don't specify "no_address_mapping" here.  This

 

752

    <li> <p> We don't specify "no_address_mappings" here.  This

741

753

    enables virtual alias expansion, canonical mappings, address

742

754

    masquerading, and other address mappings after the content

743

755

    filter. The main.cf setting of "receive_override_options"

794

806

</blockquote>

795

807

 

796

808

<li> <p> Execute "<b>postsuper -r ALL</b>" to remove content

797

 

filter information from existing queue files. </p>

 

809

filter request records from existing queue files. </p>

798

810

 

799

811

<li> <p> Execute another "<b>postfix reload</b>". </p>

800

812

 

• Older »

Loggerhead is a web-based interface for Breezy
Version: 2.0.1