1This is mailutils.info, produced by makeinfo version 6.7 from 2mailutils.texi. 3 4Published by the Free Software Foundation, 51 Franklin Street, Fifth 5Floor Boston, MA 02110-1301, USA 6 7 Copyright (C) 1999-2021 Free Software Foundation, Inc. 8 9 Permission is granted to copy, distribute and/or modify this document 10under the terms of the GNU Free Documentation License, Version 1.2 or 11any later version published by the Free Software Foundation; with no 12Invariant Sections, no Front-Cover, and no Back-Cover texts. A copy of 13the license is included in the section entitled "GNU Free Documentation 14License". 15INFO-DIR-SECTION Email 16START-INFO-DIR-ENTRY 17* Mailutils: (mailutils). GNU Mail Utilities. 18END-INFO-DIR-ENTRY 19 20INFO-DIR-SECTION Individual utilities 21START-INFO-DIR-ENTRY 22* comsatd: (mailutils) comsatd. Comsat Daemon. 23* frm: (mailutils) frm. List Headers from a Mailbox. 24* guimb: (mailutils) guimb. Mailbox Processing Language. 25* imap4d: (mailutils) imap4d. IMAP4 Daemon. 26* mail: (mailutils) mail. Send and Receive Mail. 27* maidag: (mailutils) maidag. A General-Purpose Mail Delivery Agent. 28* messages: (mailutils) messages. Count Messages in a Mailbox. 29* movemail: (mailutils) movemail. Move Mail between Mailboxes. 30* pop3d: (mailutils) pop3d. POP3 Daemon. 31* readmsg: (mailutils) readmsg. Extract Messages from a Folder. 32* decodemail: (mailutils) decodemail. Decode MIME messages. 33* sieve: (mailutils) sieve. Mail Filtering Utility. 34* mimeview: (mailutils) mimeview. View MIME Messages. 35* mailutils: (mailutils) mailutils. Mailutils Multi-Purpose Tool 36END-INFO-DIR-ENTRY 37 38 39File: mailutils.info, Node: Top, Next: Introduction, Up: (dir) 40 41GNU Mailutils 42************* 43 44This edition of the 'GNU Mailutils Manual', last updated on 10 June 452021, documents GNU Mailutils Version 3.13. 46 47* Menu: 48 49* Introduction:: Preliminary Information. 50* Mailbox:: Mailboxes and URLs. 51* Programs:: Mailutils Programs. 52* Libraries:: Mailutils Libraries. 53* Sieve Language:: The Sieve Language. 54* Reporting Bugs:: How to Report a Bug. 55* News:: Getting News About GNU Mailutils. 56* Acknowledgement:: Thanks and Credits. 57 58Appendices 59 60* References:: References. 61* Date Input Formats:: 62* Date/time Format String:: 63* Usage Vars:: Configuring Help Summary 64* GNU FDL:: This manual is under the GNU Free 65 Documentation License. 66 67Indices 68 69* Function Index:: All Mailutils Functions. 70* Variable Index:: All Mailutils Variables. 71* Keyword Index:: Index of Keywords. 72* Program Index:: All Mailutils Programs. 73* Concept Index:: Index of Concepts. 74 75 -- The Detailed Node Listing -- 76 77Introduction 78 79* Book Contents:: What this Book Contains 80* History:: A bit of History 81 82Mailbox 83 84* Local Mailboxes:: Mailboxes stored on the local file system. 85* Remote Mailboxes:: Mailboxes stored on remote hosts. 86* SMTP Mailboxes:: Mailboxes that send mail. 87* Program Mailboxes:: 88 89Mailutils Programs 90 91* command line:: Command Line Syntax. 92* configuration:: Common Configuration File. 93* debugging:: 94 95* frm and from:: List Headers from a Mailbox. 96* mail:: Send and Receive Mail. 97* messages:: Count the Number of Messages in a Mailbox. 98* movemail:: Moves Mail from the User Maildrop to the Local File. 99* readmsg:: Extract Messages from a Folder. 100* decodemail:: Decode multipart messages. 101 102* sieve:: Mail Filtering Utility. 103* guimb:: Mailbox Scanning and Processing Language. 104 105* mda:: Local Mail Delivery Agent. 106* lmtpd:: LMTP Daemon. 107* putmail:: Incorporate a Message to a Mailbox. 108 109* mimeview:: Universal File Viewer. 110 111* pop3d:: POP3 Daemon. 112* imap4d:: IMAP4 Daemon. 113* comsatd:: Comsat Daemon. 114 115* mh:: The MH Message Handling System. 116 117* mailutils:: The Mailutils Multi-Purpose Tool. 118* dotlock:: The External Locker Utility. 119 120Command Line 121 122* Option Basics:: Basic Notions About Command Line Options. 123* Common Options:: Options That are Common for All Utilities. 124 125Mailutils Configuration File 126 127* conf-syntax:: Configuration File Syntax 128* Variables:: Variable Expansion 129* include:: Include Statement 130* program statement:: 131* logging statement:: 132* debug statement:: 133* mailbox statement:: 134* mime statement:: 135* locking statement:: 136* mailer statement:: 137* acl statement:: 138* tcp-wrappers statement:: 139* Server Settings:: 140* auth statement:: 141* pam statement:: 142* virtdomain statement:: 143* radius statement:: 144* sql statement:: 145* ldap statement:: 146* tls statement:: 147* tls-file-checks statement:: 148* gsasl statement:: 149 150Configuration File Syntax 151 152* Comments:: 153* Statements:: 154* Paths:: 155 156Server Settings 157 158* General Server Configuration:: 159* Server Statement:: 160 161Debugging 162 163* Level Syntax:: 164* Level BNF:: 165* Debugging Categories:: 166 167'mail' -- Send and Receive Mail 168 169* Invoking Mail:: Command Line Options. 170* Reading Mail:: Reading Mail. 171* Saving and Recording:: Where Mail Messages are Stored. 172* Composing Mail:: Composing Mail. 173* MIME:: How to Attach Files. 174* Scripting:: Scripting. 175* Mail Variables:: How to Alter the Behavior of 'mail'. 176* Mail Configuration Files:: Personal and System-wide Configuration Files. 177 178Reading Mail 179 180* Command Syntax:: Syntax of mail internal commands. 181* Quitting the Program:: 182* Obtaining Online Help:: 183* Moving Within a Mailbox:: 184* Changing mailbox/directory:: 185* Controlling Header Display:: 186* Displaying Information:: 187* Displaying Messages:: 188* Marking Messages:: 189* Disposing of Messages:: 190* Saving Messages:: 191* Editing Messages:: 192* Aliasing:: 193* Replying:: 194* Controlling Sender Fields:: 195* Incorporating New Mail:: 196* Shell Escapes:: 197 198Composing Mail 199 200* Quitting Compose Mode:: 201* Getting Help on Compose Escapes:: 202* Editing the Message:: 203* Modifying the Headers:: 204* Enclosing Another Message:: 205* Adding a File to the Message:: 206* Attaching a File to the Message:: 207* Printing And Saving the Message:: 208* Signing the Message:: 209* Printing Another Message:: 210* Inserting Value of a Mail Variable:: 211* Executing Other Mail Commands:: 212* Executing Shell Commands:: 213 214'movemail' -- Moves Mail from the User Maildrop to the Local File 215 216* Movemail Configuration:: 217* Ownership:: Setting Destination Mailbox Ownership 218* Summary:: Short Movemail Invocation Summary 219 220'readmsg' -- Extract Messages from a Folder 221 222* Opt-readmsg:: Invocation of 'readmsg'. 223* Conf-readmsg:: Configuration of 'readmsg'. 224 225'decodemail' - Decode multipart messages 226 227* Opt-decodemail:: Invocation of 'decodemail'. 228* Conf-decodemail:: Configuration of 'decodemail'. 229* Using-decodemail:: Purpose and caveats of 'decodemail'. 230 231'sieve' 232 233* sieve interpreter:: A Sieve Interpreter 234 235A Sieve Interpreter 236 237* Invoking Sieve:: 238* Sieve Configuration:: 239* Logging and Debugging:: 240* Extending Sieve:: 241 242'guimb' -- A Mailbox Scanning and Processing Language 243 244* Specifying Scheme Program to Execute:: 245* Specifying Mailboxes to Operate Upon:: 246* Passing Options to Scheme:: 247* Command Line Option Summary:: 248 249mda 250 251* Sendmail-mda:: Using 'mda' with Sendmail. 252* Exim-mda:: Using 'mda' with Exim. 253* MeTA1-mda:: Using 'mda' with MeTA1. 254* Mailbox Quotas:: 255* MDA Scripting:: 256* Forwarding:: 257* Conf-mda:: 'mda' Configuration File Summary. 258* Mailing lists:: How to implement Mailing Lists with 'mda'. 259 260Mailbox Quotas 261 262* DBM Quotas:: Keeping Quotas in DBM File. 263* SQL Quotas:: Keeping Quotas in SQL Database. 264 265Scripting in 'mda' 266 267* Sieve MDA Filters:: 268* Scheme MDA Filters:: 269* Python MDA Filters:: 270 271lmtpd 272 273* MeTA1-lmtpd:: Using 'lmtpd' with MeTA1. 274 275putmail 276 277* putmail options:: 278* putmail configuration:: 279 280mimeview 281 282* Mimeview Invocation:: 283* Mimeview Config:: 284 285POP3 Daemon 286 287* Login delay:: 288* Auto-expire:: 289* Bulletins:: 290* Conf-pop3d:: Pop3d Configuration 291* Command line options:: 292 293IMAP4 Daemon 294 295* Namespace:: Namespace. 296* Conf-imap4d:: Configuration. 297* Starting imap4d:: Invocation Options. 298 299Comsat Daemon 300 301* Starting comsatd:: Invocation. 302* Configuring comsatd:: Configuration of 'comsatd'. 303* dot.biffrc:: A per-user configuration file. 304 305Configuring 'comsatd' 306 307* General Settings:: 308* Security Settings:: 309 310MH -- The MH Message Handling System 311 312* Diffs:: Major differences between Mailutils MH and other MH 313 implementations. 314 315Major differences between Mailutils MH and other MH implementations 316 317* Format String Diffs:: 318* Profile Variable Diffs:: 319* Program Diffs:: 320 321mailutils 322 323* mailutils invocation syntax:: 324* mailutils help:: Display a terse help summary. 325* mailutils info:: Show Mailutils configuration. 326* mailutils cflags:: Show compiler options. 327* mailutils ldflags:: List libraries required to link. 328* mailutils stat:: Show mailbox status. 329* mailutils query:: Query configuration values. 330* mailutils 2047:: Decode/encode email message headers. 331* mailutils filter:: Apply a chain of filters to the input. 332* mailutils acl:: Test access control lists. 333* mailutils wicket:: Scan wickets for matching URLs. 334* mailutils dbm:: DBM management tool. 335* mailutils logger:: Log data using Mailutils log facility. 336* mailutils pop:: POP3 client shell. 337* mailutils imap:: IMAP4 client shell. 338* mailutils send:: Send a message. 339* mailutils smtp:: Run a SMTP session. 340* mailutils maildir_fixup:: Fix-up maildirs created by versions prior to 3.10.90 341 342mailutils dbm 343 344* Create a Database:: 345* Add Records to a Database:: 346* Delete Records:: 347* List the Database:: 348* Dump the Database:: 349* Dump Formats:: 350* Dbm Exit Codes:: 351 352Sieve Language 353 354* Lexical Structure:: 355* Syntax:: 356* Preprocessor:: 357* Require Statement:: 358* Comparators:: 359* Tests:: 360* Actions:: 361* Extensions:: 362* GNU Extensions:: 363 364Syntax 365 366* Commands:: 367* Actions Described:: 368* Control Flow:: 369* Tests and Conditions:: 370 371Preprocessor 372 373* #include:: Include the contents of a file. 374* #searchpath:: Modify the current search path. 375 376Tests 377 378* Built-in Tests:: 379* External Tests:: 380 381Actions 382 383* Built-in Actions:: 384* External Actions:: 385 386Extensions 387 388* encoded-character:: 389* relational:: 390* variables:: 391* environment:: 392* numaddr:: 393* editheader:: 394* list:: 395* moderator:: 396* pipe:: 397* spamd:: 398* timestamp:: 399* vacation:: 400 401Date Input Formats 402 403* General date syntax:: Common rules. 404* Calendar date items:: 19 Dec 1994. 405* Time of day items:: 9:20pm. 406* Time zone items:: EST, PDT, GMT. 407* Day of week items:: Monday and others. 408* Relative items in date strings:: next tuesday, 2 years ago. 409* Pure numbers in date strings:: 19931219, 1440. 410* Seconds since the Epoch:: @1078100502. 411* Specifying time zone rules:: TZ="America/New_York", TZ="UTC0". 412* Authors of get_date:: Bellovin, Eggert, Salz, Berets, et al. 413 414 415 416File: mailutils.info, Node: Introduction, Next: Mailbox, Prev: Top, Up: Top 417 4181 Introduction 419************** 420 421GNU Mailutils is a set of libraries and utilities for handling 422electronic mail. It addresses a wide audience and can be of interest to 423application developers, casual users and system administrators alike. 424 425 It provides programmers with a consistent API allowing them to handle 426a variety of different mailbox formats transparently and without having 427to delve into complexities of their internal structure. While doing so, 428it also provides interfaces that simplify common programming tasks, such 429as handling lists, parsing configuration files, etc. The philosophy of 430Mailutils is to have a single and consistent programming interface for 431various objects designed to handle the same task. It tries to use their 432similarities to create an interface that hides their differences and 433complexities. This covers a wide variety of programming tasks: apart 434from mailbox handling, Mailutils also contains a unified iterface for 435work with various DBM databases and much more. 436 437 The utilities built upon these libraries share that same distinctive 438feature: no matter what is the internal structure of an object, it is 439always handled the same way as other objects that do the same task. 440Again, the most common example of this approach are, of course, 441mailboxes. Whatever Mailutils program you use, you can be sure it is 442able to handle various mailbox formats. You even don't have to inform 443it about what type a mailbox is: it will do its best to discover it 444automatically. 445 446 This approach sometimes covers entities which are seldom regarded as 447compatible. For example, using Mailutils it is possible to treat an 448SMTP connection as a mailbox opened only for appending new messages. 449This in turn, provides a way for extending the functionality of some 450utilities. As an example, using this concept of mailboxes, the usual 451mail delivery agent becomes able to do things usually reserved for mail 452transport agents only! 453 454 At the core of Mailutils is 'libmailutils', a library which provides 455an API for accessing a generalized mailbox. A set of complementary 456libraries provide methods for handling particular mailbox 457implementations: UNIX mailbox, Maildir, MH, POP3, IMAP4, even SMTP. 458Mailutils offers functions for almost any mail-related task, such as 459parsing of messages, email addresses and URLs, handling MIME messages, 460listing mail folders, mailcap facilities, extensible Sieve filtering, 461access control lists. It supports various modern data security and 462authentication techniques: TLS encryption, SASL and GSSAPI, to name a 463few. Mailutils is able to work with a wide variety of authorization 464databases, ranging from traditional system password database up to 465RADIUS, SQL and LDAP. 466 467 The utilities provided by Mailutils include 'imap4d' and 'pop3d' mail 468servers, mail reporting utility 'comsatd', general-purpose mail delivery 469agent 'maidag', mail filtering program 'sieve', an implementation of MH 470message handling system and much more. 471 472 All utilities share the same subset of command line options and use a 473unified configuration mechanism, which allows to easily configure the 474package as a whole. 475 476 This software is part of the GNU Project and is copyrighted by the 477Free Software Foundation. All libraries are distributed under the terms 478of the Lesser GNU Public License. The documentation is licensed under 479the GNU FDL, and everything else is licensed under the GNU GPL. 480 481* Menu: 482 483* Book Contents:: What this Book Contains 484* History:: A bit of History 485 486 487File: mailutils.info, Node: Book Contents, Next: History, Up: Introduction 488 4891.1 What this Book Contains 490=========================== 491 492This book addresses a wide audience of both system administrators and 493users that aim to use Mailutils programs, and programmers who wish to 494use Mailutils libraries in their programs. Given this audience, the 495book is divided in three major parts. 496 497 The first part provides a detailed description of each Mailutils 498utility, and advices on how to use them in various situations. This 499part is intended for users and system administrators who are using 500Mailutils programs. If you are not interested in programming using 501Mailutils, this is the only part you need to read. 502 503 Subsequent parts address programmers. 504 505 The second part is a tutorial which provides an introduction to 506programming techniques for writing mail applications using GNU 507Mailutils. 508 509 Finally, the third part contains a complete Mailutils library 510reference. 511 512 This version of the book is not finished. The places that may 513contain inaccurate information carry prominent notices stating so. For 514updated versions of the documentation, visit 515<http://mailutils.org/manual>. All material that ends up in this 516document is first published in the Mailutils Wiki, available at 517<http://mailutils.org/wiki>. Be sure to visit it for latest updates. 518 519 If you have any questions that are not answered there, feel free to 520ask them at the mailing list <bug-mailutils@gnu.org>. 521 522 523File: mailutils.info, Node: History, Prev: Book Contents, Up: Introduction 524 5251.2 A bit of History, and why use this package? 526=============================================== 527 528 ================================================================== 529 *Editor's note:* 530 The information in this node may be obsolete or otherwise 531 inaccurate. This message will disappear, once this node revised. 532 ================================================================== 533 534 This package started off to try and handle large mailbox files more 535gracefully then available at that time POP3 servers did. While it 536handles this task, it also allows you to support a variety of different 537mailbox formats without any real effort on your part. Also, if a new 538format is added at a later date, your program will support that new 539format automatically as soon as it is compiled against the new library. 540 541 542File: mailutils.info, Node: Mailbox, Next: Programs, Prev: Introduction, Up: Top 543 5442 Mailbox 545********* 546 547The principal object Mailutils operates on is "mailbox" - a collection 548of mail messages. The two main characteristics of a mailbox are its 549type and path. The "type" defines how the messages are stored within a 550mailbox. The "path" specifies the location of the mailbox. The two 551characteristics are usually combined within a "Uniform Resource Locator" 552(URL), which uniquely identifies the mailbox. The syntax for URL is: 553 554 TYPE:[//[USER:PASSWORD@]HOST[:PORT]]PATH[?QUERY][;PARAMS] 555 556 The square brackets do not appear in a URL, instead they are used to 557denote optional parts. 558 559 Not all parts are meaningful for all types. Their usage and purpose 560are described in the sections that follow. 561 562* Menu: 563 564* Local Mailboxes:: Mailboxes stored on the local file system. 565* Remote Mailboxes:: Mailboxes stored on remote hosts. 566* SMTP Mailboxes:: Mailboxes that send mail. 567* Program Mailboxes:: 568 569 570File: mailutils.info, Node: Local Mailboxes, Next: Remote Mailboxes, Up: Mailbox 571 5722.1 Local Mailboxes 573=================== 574 575"Local mailboxes" store mail in files on the local file system. A local 576mailbox URL is: 577 578 TYPE://PATH[;PARAMS] 579 580 The PATH defines its location in the file system. For example: 581 582 mbox:///var/spool/mail/gray 583 584 Optional PARAMS is a semicolon-separated list of optional arguments 585that configures indexed directory structure. *Note local URL 586parameters::, for a detailed description. 587 588 The local mailbox types are: 589 590mbox 591 A traditional UNIX mailbox format. Messages are stored 592 sequentially in a single file. Each message begins with a 'From' 593 line, identifying its sender and date when it was received. A 594 single empty line separates two adjacent messages. 595 596 This is the default format. 597 598maildir 599 The "Maildir" mailbox format. Each message is kept in a separate 600 file with a unique name. Each mailbox is therefore a directory. 601 This mailbox format eliminates file locking and makes message 602 access much faster. 603 604 This format was originally described by D. J. Bernstein in 605 <http://cr.yp.to/proto/maildir.html>. 606 607mh 608 MH Message Handling System format. Each message is kept in a 609 separate file named after its sequential numeric identifier within 610 the mailbox. Deleted messages are not removed, but instead the 611 corresponding file is renamed by prepending a comma to its original 612 name. Each mailbox is a directory. Mailboxes can be nested. 613 614 This format was originally developed by RAND Corporation. 615 Mailutils implementation is compatible both with the original 616 implementation and with its descendant "nmh". 617 618file 619 This type can be used when accessing an existing mailbox of any of 620 the formats defined above. The actual mailbox format is determined 621 automatically. This type is assumed when a mailbox is referred to 622 by its full pathname. 623 624 625File: mailutils.info, Node: Remote Mailboxes, Next: SMTP Mailboxes, Prev: Local Mailboxes, Up: Mailbox 626 6272.2 Remote Mailboxes 628==================== 629 630"Remote mailboxes" are accessed via one of the remote message protocols. 631 632 The basic remote mailbox types are: 633 634pop 635 Remote mailbox accessed using the "Post Office Protocol" (POP3). 636 Default port number 110. 637 638 The URL is: 639 640 pop://[USER[:PASS][;auth=+APOP]@]HOST[:PORT][;notls] 641 642 The HOST gives the name or IP address of the host running a POP3 643 server. Optional PORT can be used to connect to a port other than 644 the default 110. 645 646 The USER and PASS supply authentication credentials. If any of 647 them is missing, Mailtils will first try to obtain it from the 648 ticket file. If that fails, the behavior depends on the type of 649 the controlling terminal. If the terminal is a tty device (i.e. 650 the program accessing the mailbox was started from the command 651 line), it will ask the user to supply the missing credentials. 652 Otherwise it will issue an appropriate error message and refuse to 653 access the mailbox. 654 655 By default, the usual POP3 authentication is used. The 656 'auth=+APOP' authentication parameter instructs Mailutils to use 657 APOP authentication instead. 658 659 If the server offers the STLS capability, Mailutils will attempt to 660 establish encrypted TLS connection. The 'notls' parameter disables 661 this behavior. 662 663pops 664 Remote mailbox accessed using the "Post Office Protocol" (POP3). 665 The transmission channel is encrypted using the "transport layer 666 security" (TLS). The default port is 995. 667 668 The URL is: 669 670 pops://[USER[:PASS][;auth=+APOP]@]HOST[:PORT] 671 672 The meaning of its components is the same as for 'pop' type. 673 674imap 675 Remote mailbox accessed via the "Internet Message Access Protocol". 676 Default port number is 143. 677 678 The URL is: 679 680 imap://[USER[:PASS]@]HOST[:PORT][;notls] 681 682 The HOST gives the name or IP address of the host running a IMAP4 683 server. Optional PORT can be used to connect to a port other than 684 the default 143. 685 686 The USER and PASS supply authentication credentials. If any of 687 them is missing, Mailtils will first try to obtain it from the 688 ticket file. If that fails, the behavior depends on the type of 689 the controlling terminal. If the terminal is a tty device (i.e. 690 the program accessing the mailbox was started from the command 691 line), it will ask the user to supply the missing credentials. 692 Otherwise it will issue an appropriate error message and refuse to 693 access the mailbox. 694 695 If the server offers the STARTTLS capability, Mailutils will 696 attempt to establish encrypted TLS connection. The 'notls' 697 parameter disables this behavior. 698 699imaps 700 701 The 'imaps' type differs in that its transmission channel is 702 encrypted using the "transport layer security" (TLS). The default 703 port is 993. 704 705 The URL is: 706 707 imaps://[USER[:PASS]@]HOST[:PORT] 708 709 The meaning of its components is the same as for 'imap' type. 710 711 712File: mailutils.info, Node: SMTP Mailboxes, Next: Program Mailboxes, Prev: Remote Mailboxes, Up: Mailbox 713 7142.3 SMTP Mailboxes 715================== 716 717SMTP mailboxes types are special remote mailboxes that allow only append 718operation. Appending a message is equivalent to sending it to the given 719recipient or recipients. 720 721smtp 722 A remote mailbox accessed using the Simple Message Transfer 723 Protocol. 724 725 The SMTP URL syntax is: 726 727 smtp://[USER[:PASS][;auth=MECH,...]@]HOST[:PORT][;PARAMS] 728 729 The HOST gives the name or IP address of the host running SMTP 730 server. Optional PORT can be used to connect to a port other than 731 the default 25. 732 733 The USER, PASS, and 'auth=' elements supply credentials for ESMTP 734 authentication, if the server supports it. 735 736 If the ESMTP authentication is used, Mailutils will select the best 737 authentication mechanism from the list offered by the server. To 738 force it to use a particular authentication mechanism, use the 739 'auth' authentication parameter. Its value is a comma-separated 740 list of authentication mechanisms, in the order from the most to 741 the least preferred one, e.g.: 742 743 smtp://smith:guessme;auth=cram-md5,digest-md5@localhost 744 745 Optional PARAMS is a semicolon-separated list of additional 746 parameters. Valid parameters are: 747 748 domain=STRING 749 Append '@STRING' to those recipient addresses that lack the 750 domain part. 751 752 from=ADDR 753 Use ADDR as sender address. 754 755 noauth 756 Disable ESMTP authentication. 757 758 notls 759 Disable TLS. 760 761 recipient-headers[=NAME[,NAME...]] 762 Use the supplied header names to determine recipient 763 addresses. When no values are supplied, disables header 764 scanning. 765 766 strip-domain 767 Strip domain part from all recipient addresses. 768 769 to=ADDR[,ADDR...] 770 Deliver messages to the supplied email addresses. 771 772smtps 773 A remote mailbox accessed using the Simple Message Transfer 774 Protocol, with the transmission channel encrypted using the 775 "transport layer security" (TLS). The default port is 465. 776 777 The URL is 778 779 smtps://[USER[:PASS][;auth=MECH,...]@]HOST[:PORT][;PARAMS] 780 781 See the 'smtp' type for a detailed description of its types. The 782 only difference from 'smtp' is that the 'notls' parameter is not 783 used. 784 785 786File: mailutils.info, Node: Program Mailboxes, Prev: SMTP Mailboxes, Up: Mailbox 787 7882.4 Program Mailboxes 789===================== 790 791Program mailboxes support only append operation. Appending a message is 792performed by invoking the specified program and passing the message to 793its standard input stream. 794 795 A 'sendmail' mailbox is identified by the following URL: 796 797 sendmail[://PATH] 798 799 The messages are sent by invoking 'sendmail' binary with the '-oi -t' 800options. If the message being appended has the 'From:' header, its 801value is passed to 'sendmail' using the '-f' option. 802 803 The default path to the sendmail binary is system-dependent. The 804PATH part can be used to specify it explicitly. 805 806 The 'prog' mailbox URL is: 807 808 prog://PATHNAME[?QUERY] 809 810 Messages are appended by invoking the program PATHNAME with the 811arguments supplied by QUERY. The latter is a list of words delimited by 812'&' characters. 813 814 Arguments can contain the following variables (*note Variables::): 815 816sender 817 Expands to the sender email address. 818 819rcpt 820 Expands to comma-separated list of email addresses obtained from 821 'To:', 'Cc:' and 'Bcc:' headers of the message. 822 823 824File: mailutils.info, Node: Programs, Next: Libraries, Prev: Mailbox, Up: Top 825 8263 Mailutils Programs 827******************** 828 829GNU Mailutils provides a broad set of utilities for handling electronic 830mail. These utilities address the needs of both system administrators 831and users. 832 833 All utilities are built around a single core subsystem and share many 834common aspects. All of them are able to work with almost any existing 835mailbox formats. They use a common configuration file syntax, and their 836configuration files are located in a single subdirectory. 837 838 In this chapter we will discuss each utility, and give some advices 839on how to use them in various real life situations. 840 841 First of all we will describe command line and configuration file 842syntax. 843 844* Menu: 845 846* command line:: Command Line Syntax. 847* configuration:: Common Configuration File. 848* debugging:: 849 850* frm and from:: List Headers from a Mailbox. 851* mail:: Send and Receive Mail. 852* messages:: Count the Number of Messages in a Mailbox. 853* movemail:: Moves Mail from the User Maildrop to the Local File. 854* readmsg:: Extract Messages from a Folder. 855* decodemail:: Decode multipart messages. 856 857* sieve:: Mail Filtering Utility. 858* guimb:: Mailbox Scanning and Processing Language. 859 860* mda:: Local Mail Delivery Agent. 861* lmtpd:: LMTP Daemon. 862* putmail:: Incorporate a Message to a Mailbox. 863 864* mimeview:: Universal File Viewer. 865 866* pop3d:: POP3 Daemon. 867* imap4d:: IMAP4 Daemon. 868* comsatd:: Comsat Daemon. 869 870* mh:: The MH Message Handling System. 871 872* mailutils:: The Mailutils Multi-Purpose Tool. 873* dotlock:: The External Locker Utility. 874 875 876File: mailutils.info, Node: command line, Next: configuration, Up: Programs 877 8783.1 Command Line 879================ 880 881* Menu: 882 883* Option Basics:: Basic Notions About Command Line Options. 884* Common Options:: Options That are Common for All Utilities. 885 886 887File: mailutils.info, Node: Option Basics, Next: Common Options, Up: command line 888 8893.1.1 Basic Notions About Command Line Options 890---------------------------------------------- 891 892Many command line options have two forms, called short and long forms. 893Both forms are absolutely identical in function; they are 894interchangeable. 895 896 The "short" form is a traditional form for UNIX utilities. In this 897form, the option consists of a single dash, followed by a single letter, 898e.g. '-c'. 899 900 Short options which require arguments take their arguments 901immediately following the option letter, optionally separated by white 902space. For example, you might write '-f name', or '-fname'. Here, '-f' 903is the option, and 'name' is its argument. 904 905 Short options which allow optional arguments take their arguments 906immediately following the option letter, _without any intervening white 907space characters_. This is important, so that the command line parser 908might discern that the text following option is its argument, not the 909next command line parameter. For example, if option '-d' took an 910optional argument, then '-dname' would mean the option with its argument 911('name' in this case), and '-d name' would mean the '-d' option without 912any argument, followed by command line argument 'name'. 913 914 Short options' letters may be clumped together, but you are not 915required to do this. When short options are clumped as a set, use one 916(single) dash for them all, e.g. '-cvl' is equivalent to '-c -v -l'. 917However, only options that do not take arguments may be clustered this 918way. If an option takes an argument, it can only be the last option in 919such a cluster, otherwise it would be impossible to specify the argument 920for it. Anyway, it is much more readable to specify such options 921separated. 922 923 The "long" option names are probably easier to memorize than their 924short counterparts. They consist of two dashes, followed by a 925multi-letter option name, which is usually selected to be a mnemonics 926for the operation it requests. For example, '--verbose' is a long 927option that increases the verbosity of a utility. In addition, long 928option names can abbreviated, provided that such an abbreviation is 929unique among the options understood by a given utility. For example, if 930a utility takes options '--foreground' and '--forward', then the 931shortest possible abbreviations for these options are '--fore' and 932'--forw', correspondingly. If you try to use '--for', the utility will 933abort and inform you that the abbreviation you use is ambiguous, so it 934is not clear which of the options you intended to use. 935 936 Long options which require arguments take those arguments following 937the option name. There are two ways of specifying a mandatory argument. 938It can be separated from the option name either by an equal sign, or by 939any amount of white space characters. For example, if the '--file' 940option requires an argument, and you wish to supply 'name' as its 941argument, then you can do so using any of the following notations: 942'--file=name' or '--file name'. 943 944 In contrast, optional arguments must always be introduced using an 945equal sign. 946 947 948File: mailutils.info, Node: Common Options, Prev: Option Basics, Up: command line 949 9503.1.2 Options That are Common for All Utilities. 951------------------------------------------------ 952 953All GNU Mailutils programs understand a common subset of options. 954 955'--help' 956'-?' 957 Display a short summary of the command line options understood by 958 this utilities, along with a terse description of each. 959 960 The output of this option consists of three major parts. First, a 961 usage synopsis is displayed. For example: 962 963 Usage: sieve [OPTION...] SCRIPT 964 GNU sieve -- a mail filtering tool 965 966 The first line tells that the 'sieve' utility takes any number of 967 options (brackets indicate optional part) and a single mandatory 968 argument ('SCRIPT'). The second lines summarizes the purpose of 969 the utility. 970 971 Following this header is an option summary. It consists of two 972 columns: 973 974 -c, --compile-only Compile script and exit 975 -d, --debug[=FLAGS] Debug flags 976 -e, --email=ADDRESS Override user email address 977 978 The leftmost column contains a comma-separated list of option 979 names. Short options are listed first. The options are ordered 980 alphabetically. Arguments, if any, are specified after the last 981 option name in the list, so that, e.g. the option '-e' in the 982 example above requires an argument: '-e ADDRESS'. Optional 983 arguments are enclosed in square brackets, as in '--debug' option 984 in the example above. 985 986 The rightmost column contains a short description of the option 987 purpose. 988 989 The last part of '--help' output contains some additional notices 990 and lists the email address for reporting bugs. 991 992'--usage' 993 Display a short summary of options. In the contrast to the 994 '--help' option, only option names and arguments are printed, 995 without any textual description. For example: 996 997 Usage: sieve [-cv?V] [--compile-only] [--debug[=FLAGS]] 998 [--email=ADDRESS] SCRIPT 999 1000 The exact formatting of the output produced by these two options is 1001configurable. *Note Usage Vars::, for a detailed descriptions of it. 1002 1003'--version' 1004'-V' 1005 Print program version and exit. 1006 1007'--show-config-options' 1008 Show configuration options used when compiling the package. You 1009 can use this option to verify if support for a particular mailbox 1010 format or other functionality is compiled in the binary. The 1011 output of this option is intended to be both machine-readable and 1012 understandable by humans. 1013 1014 The following command line options affect parsing of configuration 1015files. Here we provide a short summary, the next section will describe 1016them in detail. 1017 1018'--config-file=FILE' 1019 Load this configuration file, instead of the default. 1020 1021'--config-help' 1022 Show configuration file summary. 1023 1024'--config-lint' 1025 Check configuration file syntax and exit 1026 1027'--config-verbose' 1028 Verbosely log parsing of the configuration files. 1029 1030'--no-site-config' 1031 Do not load site-wide configuration file. 1032 1033'--no-user-config' 1034 Do not load user configuration file. 1035 1036'--no-config' 1037 Don't load site-wide and user configuration files. 1038 1039'--set=PATH=VALUE' 1040 Set configuration variable. *Note the --set option::. 1041 1042 1043File: mailutils.info, Node: configuration, Next: debugging, Prev: command line, Up: Programs 1044 10453.2 Mailutils Configuration File 1046================================ 1047 1048Configuration files are the principal means of configuring any GNU 1049Mailutils component. When started, each utility tries to load its 1050configuration from the following locations, in that order: 1051 1052 1. Main site-wide configuration file. 1053 1054 It is named 'SYSCONFDIR/mailutils.conf', where SYSCONFDIR stands 1055 for the system configuration directory set when compiling the 1056 package. You can obtain the value of SYSCONFDIR by running 1057 1058 $ mailutils info sysconfdir 1059 1060 or 1061 1062 $ PROG --show-config-options | grep SYSCONFDIR 1063 1064 where PROG stands for any GNU Mailutils utility. 1065 1066 The site-wide configuration file is not read if any of 1067 '--no-site-config' or '--no-config' command line options was given. 1068 1069 Older versions of GNU Mailutils read configuration from file 1070 'mailutils.rc'. To facilitate transition, mailutils will look for 1071 that file as well. If both the default site-wide configuration 1072 file and legacy configuration file are present you will get the 1073 following warning: 1074 1075 legacy configuration file /etc/mailutils.rc ignored 1076 1077 Otherwise, if 'mailutils.conf' does not exist and 'mailutils.rc' is 1078 present, it will be used instead and the following warning will be 1079 issued: 1080 1081 using legacy configuration file /etc/mailutils.rc: 1082 please rename it to /etc/mailutils.conf 1083 1084 2. Per-user configuration file. 1085 1086 Client utilities, such as 'frm' or 'sieve', look in the user home 1087 directory for a file named '.PROG', where PROG is the name of the 1088 utility. If present, this file will be loaded after loading the 1089 site-wide configuration file. For example, the per-user 1090 configuration file for 'sieve' utility is named '.sieve'. 1091 1092 Loading of per-user configuration file is disabled by 1093 '--no-user-config' and '--no-config' options. 1094 1095 Server programs, such as 'imap4d' don't use per-user configuration 1096files. 1097 1098 The '--no-config' option provides a shortcut for disabling loading of 1099the default configuration files. For servers, its effect is the same as 1100of '--no-site-config'. For client utilities, it is equivalent to 1101'--no-site-config --no-user-config' used together. 1102 1103 The '--config-file' command line option instructs the program to read 1104configuration from the file supplied as its argument. In that case, 1105default configuration files are not used at all. 1106 1107 Neither site-wide nor user configuration files are required to exist. 1108If any or both of them are absent, GNU Mailutils won't complain - the 1109utility will silently fall back to its default settings. 1110 1111 To make configuration processing more verbose, use the 1112'--config-verbose' command line option. Here is an example of what you 1113might get using this option: 1114 1115 imap4d: parsing file `/etc/mailutils.conf' 1116 imap4d: finished parsing file `/etc/mailutils.conf' 1117 1118 Specifying this option more than once adds more verbosity to this 1119output. If this option is given two times, GNU Mailutils will print 1120each configuration file statement it parsed, along with the exact 1121location where it occurred (the exact meaning of each statement will be 1122described later in this chapter): 1123 1124 imap4d: parsing file `/etc/mailutils.conf' 1125 # 1 "/etc/mailutils.conf" 1126 mailbox { 1127 # 2 "/etc/mailutils.conf" 1128 mailbox-pattern maildir:/var/spool/mail;type=index;param=2;user=${user}; 1129 # 3 "/etc/mailutils.conf" 1130 mailbox-type maildir; 1131 }; 1132 # 6 "/etc/mailutils.conf" 1133 include /etc/mailutils.d; 1134 imap4d: parsing file `/etc/mailutils.d/imap4d' 1135 ... 1136 1137 To test configuration file without actually running the utility, use 1138the '--config-lint' command line option. With this option, any 1139Mailutils utility exits after finishing parsing of the configuration 1140files. Any errors occurred during parsing are displayed on the standard 1141error output. This option can be combined with '--config-verbose' to 1142obtain more detailed output. 1143 1144 The '--config-help' command line option produces on the standard 1145output the summary of all configuration statements understood by the 1146utility, with detailed comments and in the form suitable for 1147configuration file. For example, the simplest way to write a 1148configuration file for, say, 'imap4d' is to run 1149 1150 $ imap4d --config-help > imap4d.conf 1151 1152and to edit the 'imap4d.conf' file with your editor of choice. 1153 1154 The order in which configuration files are loaded defines the 1155precedence of their settings. Thus, for client utilities, settings from 1156the per-user configuration file override those from the site-wide 1157configuration. 1158 1159 It is also possible to set or override arbitrary configuration 1160variables in the command line. It can be done via the '--set' option. 1161Its argument is a "pathname" of the variable to be set, followed by an 1162equals sign and a value. For example, to define the variable 'syslog' 1163in section 'logging' to 'no', do the following: 1164 1165 $ imap4d --set .logging.syslog=no 1166 1167 Configuration pathnames are discussed in detail in *note Paths::. 1168For a detailed description of this option, *note the --set option::. 1169 1170 The '--set' options are processed after loading all configuration 1171files. 1172 1173* Menu: 1174 1175* conf-syntax:: Configuration File Syntax 1176* Variables:: Variable Expansion 1177* include:: Include Statement 1178* program statement:: 1179* logging statement:: 1180* debug statement:: 1181* mailbox statement:: 1182* mime statement:: 1183* locking statement:: 1184* mailer statement:: 1185* acl statement:: 1186* tcp-wrappers statement:: 1187* Server Settings:: 1188* auth statement:: 1189* pam statement:: 1190* virtdomain statement:: 1191* radius statement:: 1192* sql statement:: 1193* ldap statement:: 1194* tls statement:: 1195* tls-file-checks statement:: 1196* gsasl statement:: 1197 1198 1199File: mailutils.info, Node: conf-syntax, Next: Variables, Up: configuration 1200 12013.2.1 Configuration File Syntax 1202------------------------------- 1203 1204The configuration file consists of statements and comments. 1205 1206 There are three classes of lexical tokens: keywords, values, and 1207separators. Blanks, tabs, newlines and comments, collectively called 1208"white space" are ignored except as they serve to separate tokens. Some 1209white space is required to separate otherwise adjacent keywords and 1210values. 1211 1212* Menu: 1213 1214* Comments:: 1215* Statements:: 1216* Paths:: 1217 1218 1219File: mailutils.info, Node: Comments, Next: Statements, Up: conf-syntax 1220 12213.2.1.1 Comments 1222................ 1223 1224"Comments" may appear anywhere where white space may appear in the 1225configuration file. There are two kinds of comments: single-line and 1226multi-line comments. "Single-line" comments start with '#' or '//' and 1227continue to the end of the line: 1228 1229 # This is a comment 1230 // This too is a comment 1231 1232 "Multi-line" or "C-style" comments start with the two characters '/*' 1233(slash, star) and continue until the first occurrence of '*/' (star, 1234slash). 1235 1236 Multi-line comments cannot be nested. However, single-line comments 1237may well appear within multi-line ones. 1238 1239 1240File: mailutils.info, Node: Statements, Next: Paths, Prev: Comments, Up: conf-syntax 1241 12423.2.1.2 Statements 1243.................. 1244 1245A "simple statement" consists of a keyword and value separated by any 1246amount of whitespace. Simple statement is terminated with a semicolon 1247(';'). 1248 1249 The following is a simple statement: 1250 1251 standalone yes; 1252 pidfile /var/run/pop3d.pid; 1253 1254 A "keyword" begins with a letter and may contain letters, decimal 1255digits, underscores ('_') and dashes ('-'). Examples of keywords are: 1256'expression', 'output-file'. 1257 1258 A "value" can be one of the following: 1259 1260number 1261 A number is a sequence of decimal digits. 1262 1263boolean 1264 A boolean value is one of the following: 'yes', 'true', 't' or '1', 1265 meaning "true", and 'no', 'false', 'nil', '0' meaning "false". 1266 1267unquoted string 1268 An unquoted string may contain letters, digits, and any of the 1269 following characters: '_', '-', '.', '/', '@', '*', ':'. 1270 1271quoted string 1272 A quoted string is any sequence of characters enclosed in 1273 double-quotes ('"'). A backslash appearing within a quoted string 1274 introduces an "escape sequence", which is replaced with a single 1275 character according to the following rules: 1276 1277 Sequence Replaced with 1278 \a Audible bell character (ASCII 7) 1279 \b Backspace character (ASCII 8) 1280 \f Form-feed character (ASCII 12) 1281 \n Newline character (ASCII 10) 1282 \r Carriage return character (ASCII 1283 13) 1284 \t Horizontal tabulation character 1285 (ASCII 9) 1286 \v Vertical tabulation character 1287 (ASCII 11) 1288 \\ A single backslash ('\') 1289 \" A double-quote. 1290 1291 Table 3.1: Backslash escapes 1292 1293 In addition, the sequence '\NEWLINE' is removed from the string. 1294 This allows to split long strings over several physical lines, 1295 e.g.: 1296 1297 "a long string may be\ 1298 split over several lines" 1299 1300 If the character following a backslash is not one of those 1301 specified above, the backslash is ignored and a warning is issued. 1302 1303 Two or more adjacent quoted strings are concatenated, which gives 1304 another way to split long strings over several lines to improve 1305 readability. The following fragment produces the same result as 1306 the example above: 1307 1308 "a long string may be" 1309 " split over several lines" 1310 1311Here-document 1312 A "here-document" is a special construct that allows to introduce 1313 strings of text containing embedded newlines. 1314 1315 The '<<WORD' construct instructs the parser to read all the 1316 following lines up to the line containing only WORD, with possible 1317 trailing blanks. Any lines thus read are concatenated together 1318 into a single string. For example: 1319 1320 <<EOT 1321 A multiline 1322 string 1323 EOT 1324 1325 The body of a here-document is interpreted the same way as a 1326 double-quoted string, unless WORD is preceded by a backslash (e.g. 1327 '<<\EOT') or enclosed in double-quotes, in which case the text is 1328 read as is, without interpretation of escape sequences. 1329 1330 If WORD is prefixed with '-' (a dash), then all leading tab 1331 characters are stripped from input lines and the line containing 1332 WORD. Furthermore, if '-' is followed by a single space, all 1333 leading whitespace is stripped from them. This allows to indent 1334 here-documents in a natural fashion. For example: 1335 1336 <<- TEXT 1337 The leading whitespace will be 1338 ignored when reading these lines. 1339 TEXT 1340 1341 It is important that the terminating delimiter be the only token on 1342 its line. The only exception to this rule is allowed if a 1343 here-document appears as the last element of a statement. In this 1344 case a semicolon can be placed on the same line with its 1345 terminating delimiter, as in: 1346 1347 help-text <<-EOT 1348 A sample help text. 1349 EOT; 1350 1351list 1352 A "list" is a comma-separated list of values. Lists are enclosed 1353 in parentheses. The following example shows a statement whose 1354 value is a list of strings: 1355 1356 alias (test,null); 1357 1358 In any case where a list is appropriate, a single value is allowed 1359 without being a member of a list: it is equivalent to a list with a 1360 single member. This means that, e.g. 1361 1362 alias test; 1363 1364 is equivalent to 1365 1366 alias (test); 1367 1368 A "block statement" introduces a logical group of statements. It 1369consists of a keyword, followed by an optional value, and a sequence of 1370statements enclosed in curly braces, as shown in the example below: 1371 1372 server srv1 { 1373 host 10.0.0.1; 1374 community "foo"; 1375 } 1376 1377 The closing curly brace may be followed by a semicolon, although this 1378is not required. 1379 1380 1381File: mailutils.info, Node: Paths, Prev: Statements, Up: conf-syntax 1382 13833.2.1.3 Statement Path 1384...................... 1385 1386'Mailutils' configuration files have a distinct hierarchical structure. 1387Each statement in such files can therefore be identified by its name and 1388the names of block statements containing it. Such names form the 1389"pathname", similar to that used by UNIX file system. 1390 1391 For example, consider the following file: 1392 1393 foo { 1394 bar { 1395 baz 45; # A. 1396 } 1397 baz 98; # B. 1398 } 1399 1400 The full pathname of the statement marked with 'A' can be written as: 1401 1402 .foo.bar.baz 1403 1404 Similarly, the statement marked with 'B' has the following pathname: 1405 1406 .foo.baz 1407 1408 The default path component separator is dot. A pathname beginning 1409with a component separator is called "absolute pathname". Absolute 1410pathnames uniquely identify corresponding statements. If the leading 1411dot is omitted, the resulting pathname is called "relative". Relative 1412pathnames identify statements in relation to the current point of 1413reference in the configuration file. 1414 1415 Any other punctuation character can be used as a component separator, 1416provided that it appears at the beginning of the pathname. In other 1417words, only absolute pathnames allow for a change in component 1418separators. 1419 1420 A block statement that has a tag is referred to by the statement's 1421name, followed by an equals sign, followed by the tag value. For 1422example, the statement 'A' in the file below: 1423 1424 program x { 1425 bar { 1426 baz 45; # A. 1427 } 1428 } 1429 1430 is identified by the following pathname: 1431 1432 .program=x.bar.baz 1433 1434 The tag can optionally be enclosed in a pair of double quotes. Such 1435a quoting becomes mandatory for tags that contain white space or path 1436component separator, e.g.: 1437 1438 .program="a.out".bar.baz 1439 1440 The '--set' command line option allows you to set configuration 1441variables from the command line. Its argument consists of the statement 1442path and value, separated by a single equals sign (no whitespace is 1443permitted at either side of it). For example, the following option: 1444 1445 --set .logging.facility=mail 1446 1447has the same effect as the following statement in the configuration 1448file: 1449 1450 logging { 1451 facility mail; 1452 } 1453 1454 Values set using this option override those set in the configuration 1455files. This provides a convenient way for temporarily changing 1456configuration without altering configuration files. 1457 1458 Notice, that when using '--set', the '=' sign has two purposes: first 1459it separates statement path from the value, thus forming an assignment, 1460and secondly it can be used within the path itself to introduce a tag. 1461To illustrate this, let's assume you have the following statement in 1462your configuration file: 1463 1464 program pop3d { 1465 logging { 1466 facility mail; 1467 } 1468 server 0.0.0.0 { 1469 transcript no; 1470 } 1471 } 1472 1473 Now assume you wish to temporarily change logging facility to 1474'local1'. The following option will do this: 1475 1476 --set .program=pop3d.logging.facility=local1 1477 1478 When splitting the argument to '--set', the option parser always 1479looks for the rightmost equals sign. Everything to the right of it is 1480the value, and everything to the left of it - the path. 1481 1482 If the tag contains dots (as the 'server' statement in the example 1483above), you should either escape them with slashes or change the 1484pathname separator to some other character, e.g.: 1485 1486 --set .program=pop3d.server='0\.0\.0\.0'.transcript=yes 1487 1488or 1489 1490 --set /program=pop3d/server="0.0.0.0"/transcript=yes 1491 1492 1493File: mailutils.info, Node: Variables, Next: include, Prev: conf-syntax, Up: configuration 1494 14953.2.2 Configuration Variables 1496----------------------------- 1497 1498Certain configuration statements allow for the use of variable 1499references in their values. A variable reference has the form 1500'$VARIABLE' or '${VARIABLE}', where VARIABLE is the variable name. It 1501is expanded to the actual value of VARIABLE when Mailutils consults the 1502configuration statement in question. 1503 1504 The two forms are entirely equivalent. The form with curly braces is 1505normally used if the variable name is immediately followed by an 1506alphanumeric symbol, which will otherwise be considered part of it. 1507This form also allows for specifying the action to take if the variable 1508is undefined or expands to an empty value. 1509 1510 During variable expansion, the forms below cause Mailutils to test 1511for a variable that is unset or null. Omitting the colon results in a 1512test only for a variable that is unset. 1513 1514${VARIABLE:-WORD} 1515 "Use Default Values". If VARIABLE is unset or null, the expansion 1516 of WORD is substituted. Otherwise, the value of VARIABLE is 1517 substituted. 1518 1519${VARIABLE:=WORD} 1520 "Assign Default Values". If VARIABLE is unset or null, the 1521 expansion of WORD is assigned to variable. The value of VARIABLE 1522 is then substituted. 1523 1524${VARIABLE:?WORD} 1525 "Display Error if Null or Unset". If VARIABLE is null or unset, 1526 the expansion of WORD (or a message to that effect if WORD is not 1527 present) is output to the current logging channel. Otherwise, the 1528 value of VARIABLE is substituted. 1529 1530${VARIABLE:+WORD} 1531 "Use Alternate Value". If VARIABLE is null or unset, nothing is 1532 substituted, otherwise the expansion of WORD is substituted. 1533 1534 When a value is subject to variable expansion, it is also subject to 1535"command expansion". Commands are invoked in string values using the 1536following format: 1537 1538 $(CMD ARG) 1539 1540where CMD is the command name, and ARGS is a list of arguments separated 1541by whitespace. Arguments can in turn contain variable and command 1542references. 1543 1544 The following commands are defined: 1545 1546 -- Command: localpart STRING 1547 Treats STRING as an email address and returns the part preceding 1548 the '@' sign. If there is no '@' sign, returns STRING. 1549 1550 -- Command: domainpart STRING 1551 Treats STRING as an email address and returns the part following 1552 the '@' sign. If there is no '@' sign, returns empty string. 1553 1554 -- Command: shell CMD ARGS 1555 Runs the shell command CMD with the given arguments. Returns the 1556 standard output from the command. The command is invoked using 1557 '/bin/sh -c' and can contain any valid shell constructs. 1558 1559 The subsections below define variable names that are valid for use in 1560each configuration statement. 1561 1562 1563File: mailutils.info, Node: include, Next: program statement, Prev: Variables, Up: configuration 1564 15653.2.3 The 'include' Statement 1566----------------------------- 1567 1568A special statement is provided that causes inclusion of the named file. 1569It has the following syntax: 1570 1571 include FILE; 1572 1573 When reading the configuration file, this statement is effectively 1574replaced with the content of FILE. It is an error if FILE does not 1575exist. 1576 1577 In site-wide configuration file, FILE can be a directory name. In 1578this case, Mailutils will search this directory for a file with the same 1579name as the utility being executed. If found, this file will be loaded. 1580 1581 It is a common to end the site-wide configuration file with an 1582include statement, e.g.: 1583 1584 include /etc/mailutils.d; 1585 1586 This allows each particular utility to have its own configuration 1587file. Thus, 'imap4d' will read '/etc/mailutils.d/imap4d', etc. 1588 1589 1590File: mailutils.info, Node: program statement, Next: logging statement, Prev: include, Up: configuration 1591 15923.2.4 The 'program' statement 1593----------------------------- 1594 1595Another way to configure program-specific settings is by using the 1596'program' statement. The syntax is as follows: 1597 1598 program PROGNAME { 1599 ... 1600 } 1601 1602 The 'program' statement is allowed only in the site-wide 1603configuration file. When encountered, its tag (PROGNAME) is compared 1604with the name of the program being run. If two strings are the same, 1605the statements between curly braces are stored in a temporary memory, 1606otherwise the statement is ignored. When entire configuration file is 1607loaded, the statements accumulated in the temporary storage are 1608processed. 1609 1610 Notice the difference between this statement and a per-program 1611configuration file loaded via an 'include' statement. No matter where 1612in the file the 'program' statement is, its content will be processed 1613after the content of the enclosing file. In the contrast, the 1614per-program configuration file loaded via 'include' is processed right 1615where it is encountered. 1616 1617 1618File: mailutils.info, Node: logging statement, Next: debug statement, Prev: program statement, Up: configuration 1619 16203.2.5 The 'logging' Statement 1621----------------------------- 1622 1623Syntax 1624------ 1625 1626 logging { 1627 # Send diagnostics to syslog. 1628 syslog BOOLEAN; 1629 1630 # Print message severity levels. 1631 print-severity BOOLEAN; 1632 1633 # Output only messages with a severity equal to or 1634 # greater than this one. 1635 severity STRING; 1636 1637 # Set syslog facility. 1638 facility NAME; 1639 1640 # Log session ID 1641 session-id BOOLEAN; 1642 1643 # Tag syslog messages with this string. 1644 tag TEXT; 1645 } 1646 1647Description 1648----------- 1649 1650The 'logging' block statement configures where the diagnostic output 1651goes and how verbose it is. 1652 1653 -- Configuration: syslog bool 1654 If 'syslog' is set to 'yes', the diagnostics will go to syslog. 1655 Otherwise, it goes to the standard error. 1656 1657 The default syslog facility is determined at compile time, it can be 1658inspected using the following command (*note mailutils info::): 1659 1660 $ mailutils info log_facility 1661 1662 -- Configuration: facility name 1663 Use syslog facility NAME. Valid argument values are: 'user', 1664 'daemon', 'auth', 'authpriv', 'mail', 'cron', 'local0' through 1665 'local7' (all names case-insensitive), or a facility number. 1666 1667 -- Configuration: tag text 1668 Tag syslog messages with TEXT. By default, program name is used as 1669 syslog tag. 1670 1671 -- Configuration: print-severity bool 1672 Print Mailutils severity name before each message. 1673 1674 -- Configuration: severity name 1675 Output only messages with a severity equal to or greater than this 1676 one. Valid arguments are: 'debug', 'info', 'notice', 'warning', 1677 'error', 'crit', 'alert', 'emerg', 1678 1679 -- Configuration: session-id bool 1680 Print session ID with each diagnostic message. This is useful for 1681 programs that handle multiple user sessions simultaneously, such as 1682 'pop3d' and 'imap4d'. 1683 1684 1685File: mailutils.info, Node: debug statement, Next: mailbox statement, Prev: logging statement, Up: configuration 1686 16873.2.6 The 'debug' Statement 1688--------------------------- 1689 1690Syntax 1691------ 1692 1693 debug { 1694 # Set Mailutils debugging level. 1695 level SPEC; 1696 1697 # Prefix debug messages with Mailutils source locations. 1698 line-info BOOL; 1699 } 1700 1701Description 1702----------- 1703 1704The 'debug' statement controls the amount of additional debugging 1705information output by Mailutils programs. The 'level' statement enables 1706additional debugging information. Its argument (SPEC) is a Mailutils 1707debugging specification as described in *note debugging::. 1708 1709 The 'line-info' statement, when set to 'true' causes debugging 1710messages to be prefixed with locations in Mailutils source files where 1711they appear. Normally, only Mailutils developers need this option. 1712 1713 1714File: mailutils.info, Node: mailbox statement, Next: mime statement, Prev: debug statement, Up: configuration 1715 17163.2.7 The 'mailbox' Statement 1717----------------------------- 1718 1719Syntax 1720------ 1721 1722 mailbox { 1723 # Use specified URL as a mailspool. 1724 mail-spool URL; 1725 1726 # Create mailbox URL using PATTERN. 1727 mailbox-pattern PATTERN; 1728 1729 # Default mailbox type. 1730 mailbox-type TYPE; 1731 1732 # Default user mail folder. 1733 folder DIR; 1734 } 1735 1736Description 1737----------- 1738 1739The 'mailbox' statement configures the location, name and type of user 1740mailboxes. 1741 1742 The mailbox location can be specified using 'mail-spool' or 1743'mail-pattern' statements. 1744 1745 -- Configuration: mail-spool PATH 1746 The 'mail-spool' statement specifies directory that holds user 1747 mailboxes. Once this statement is given, the 'libmailutils' 1748 library will assume that the mailbox of user LOGIN is kept in file 1749 'PATH/LOGIN'. 1750 1751 Historically, PATH can contain mailbox type prefix, e.g.: 1752 'maildir:///var/spool/mail', but such usage is discouraged in favor 1753 of 'mailbox-pattern' statement. 1754 1755 -- Configuration: mailbox-pattern URL 1756 The 'mailbox-pattern' statement is a preferred way of configuring 1757 mailbox locations. It supersedes 'mail-spool' statement. 1758 1759 The URL must be a valid mailbox URL (*note Mailbox::), which may 1760 contain references to the 'user' variable (*note Variables::). 1761 This variable will be expanded to the actual user name. 1762 1763 Optional URL parameters can be used to configure "indexed directory 1764 structure". Such structure is a special way of storing mailboxes, 1765 which allows for faster access in case of very large number of 1766 users. 1767 1768 By default, all user mailboxes are stored in a single directory and 1769 are named after user login names. To find the mailbox for a given 1770 user, the system scans the directory for the corresponding file. 1771 This usually implies linear search, so the time needed to locate a 1772 mailbox is directly proportional to the ordinal number of the 1773 mailbox in the directory. 1774 1775 GNU Mailutils supports three types of indexed directories: 1776 'direct', 'reverse', and 'hashed'. 1777 1778 In direct indexed directory structure, PATH contains 26 1779 subdirectories named with lower-case letters of Latin alphabet. 1780 The location of the user mailbox is determined using the following 1781 algorithm: 1782 1783 1. Take the first letter of the user name. 1784 2. Map it to a lower-case letter using "index mapping" table. 1785 The result gives the name of a sub-directory where the mailbox 1786 is located. 1787 3. Descend into this directory. 1788 1789 For example, using this algorithm, the mailbox of the user 'smith' 1790 is stored in file 'PATH/s/smith'. 1791 1792 If each of single-letter subdirectories contains the indexed 1793 directory structure, we have second level of indexing. In this 1794 case the file name of 'smith''s mailbox is 'PATH/s/m/smith'. 1795 1796 The "reverse" indexed structure uses the same principles, but the 1797 indexing letters are taken from the _end_ of the user name, instead 1798 of from the beginning. For example, in the 2nd level reverse 1799 indexed structure, the 'smith''s mailbox is located in 1800 'PATH/h/t/smith'. 1801 1802 Finally, the "hashed" structure consists of 256 subdirectories 1803 under PATH, named by 2-letter hex codes from '00' to 'FF'. 1804 Mailboxes are stored in these subdirectories. The name of the 1805 subdirectory is computed by hashing first LEVEL letters of the user 1806 name. The hashing algorithm is: 1807 1808 1. Take next letter from the user name 1809 2. Add its ASCII value to the hash sum. 1810 3. Continue (1-2) until LEVEL letters are processed, or all 1811 letters from the file name are used, whichever occurs first. 1812 4. Convert the computed sum modulo 256 to a hex code. 1813 1814 Indexed directory structures are configured using the following 1815 arguments: 1816 1817 type=VALUE 1818 Specifies the type of indexing. Valid values are 'index', for 1819 direct indexed structure, 'rev-index' for reverse indexing, 1820 and 'hash' for hashed structure. 1821 1822 param=NUMBER 1823 Specifies indexing level. 1824 1825 user=STRING 1826 Specifies indexing key. The only meaningful value, as of 1827 Mailutils version 3.13 is 'user=${user}'. 1828 1829 Let's assume the traditional mail layout, in which incoming mails 1830 are stored in a UNIX mailbox named after the recipient user name 1831 and located in '/var/mail' directory. The 'mailbox-pattern' for 1832 this case is: 1833 1834 mailbox-pattern "/var/mail/${user}"; 1835 1836 It is entirely equivalent to specifying 'mail-spool "/var/mail"'. 1837 1838 Now, if the layout is the same, but mailboxes are kept in 'maildir' 1839 format, then the corresponding statement is: 1840 1841 mailbox-pattern "maildir:///var/mail/${user}"; 1842 1843 Finally, if the mailboxes are stored in a directly-indexed 1844 directory with two levels of indexing, the URL is: 1845 1846 mailbox-pattern "maildir:///var/mail;type=index;param=2;user=${user}"; 1847 1848 If neither 'mailbox-pattern' nor 'mail-spool' are given, the mailbox 1849names are determined using the following algorithm: 1850 1851 1. If environment variable 'FOLDER' is set, use its value. 1852 2. Otherwise, if environment variable 'MAIL' is set, use its value. 1853 3. If neither of these is set, construct the mailbox name by 1854 concatenating the built-in mail spool directory name, a directory 1855 separator, and the user name. 1856 1857 The built-in mail spool directory name is determined at compile 1858 time, using the '_PATH_MAILDIR' define from the include file 1859 'paths.h'. If this value is not defined, '/var/mail' or 1860 '/usr/spool/mail' is used. 1861 1862 -- Configuration: mailbox-type TYPE 1863 Specifies the type of mailboxes. By default, 'mbox' (UNIX mailbox) 1864 is assumed. This can be changed while configuring the package by 1865 setting 'MU_DEFAULT_SCHEME' configuration variable. The default 1866 value can be verified by running 'mailutils info scheme'. 1867 1868 -- Configuration: folder DIR 1869 Sets user mail folder directory. Its value is used when expanding 1870 'plus-notation', i.e. such mailbox names as '+inbox'. The '+' 1871 sign is replaced by DIR, followed by a directory separator ('/'). 1872 1873 The DIR argument can contain mailbox type prefix, e.g 'mh://Mail'. 1874 1875 The default folder name is 'Mail/'. 1876 1877 1878File: mailutils.info, Node: mime statement, Next: locking statement, Prev: mailbox statement, Up: configuration 1879 18803.2.8 The 'mime' Statement 1881-------------------------- 1882 1883Syntax 1884------ 1885 1886 mime { 1887 # Define additional textual mime types. 1888 text-type PATTERN; 1889 # or 1890 text-type ( PATTERN-LIST ); 1891 } 1892 1893Description 1894----------- 1895 1896The 'mime' compound statement is used by utilities that process MIME 1897messages, in particular 'mail', 'readmsg', and 'decodemail'. As of 1898mailutils version 3.13 it contains only one statement: 1899 1900 -- Configuration: text-type PATTERN 1901 -- Configuration: text-type ( PATTERN-LIST ) 1902 Defines additional patterns for recognition of textual message 1903 parts. The PATTERN is a shell globbing pattern that will be 1904 compared against the 'Content-Type' header of a MIME message part 1905 in order to determine whether it can be treated as a text part. In 1906 second form, PATTERN-LIST is a comma-separated list of such 1907 patterns. 1908 1909 In both forms, the new patterns are appended to the built-in 1910 textual pattern list, which contains: 1911 1912 * text/* 1913 * application/*shell 1914 * application/shellscript 1915 * */x-csrc 1916 * */x-csource 1917 * */x-diff 1918 * */x-patch 1919 * */x-perl 1920 * */x-php 1921 * */x-python 1922 * */x-sh 1923 1924 1925File: mailutils.info, Node: locking statement, Next: mailer statement, Prev: mime statement, Up: configuration 1926 19273.2.9 The 'locking' Statement 1928----------------------------- 1929 1930Syntax 1931------ 1932 1933 locking { 1934 # Default locker flags. 1935 type default | dotlock | external | kernel | null; 1936 1937 # Set the maximum number of times to retry acquiring the lock. 1938 retry-count NUMBER; 1939 1940 # Set the delay between two successive locking attempts. 1941 retry-sleep ARG; 1942 1943 # Expire locks older than this amount of time. 1944 expire-timeout NUMBER; 1945 1946 # Check if PID of the lock owner is active, steal the lock if it not. 1947 pid-check BOOL; 1948 1949 # Use PROG as external locker program. 1950 external-locker PROG; 1951 } 1952 1953Description 1954----------- 1955 1956This compound statement configures various parameters used when locking 1957UNIX mailboxes in order to prevent simultaneous writes. 1958 1959 It is important to note, that locking applies only to monolithic 1960mailboxes, i.e. mailboxes of 'mbox' and 'dotmail' types (*note mbox::). 1961Other mailbox types don't require locking. 1962 1963 -- Configuration: type STRING 1964 Set locking type. Allowed arguments are: 1965 1966 'default' 1967 Default locking type. As of 'mailutils' version 3.13, this is 1968 equivalent to 'dotlock'. 1969 1970 'dotlock' 1971 A 'dotlock'-style locking. To lock a mailbox named X a "lock 1972 file" named 'X.lock' is created. If 'pid-check yes' is set, 1973 this file will contain the PID of the locking process, so that 1974 another process wishing to acquire the lock could verify if 1975 the lock is still in use. 1976 1977 'external' 1978 Run external program to perform locking/unlocking operations. 1979 The name of the program is given by the 'external-locker' 1980 statement (see below). If it is not given, the built-in 1981 default 'dotlock' is used. 1982 1983 The locker program is invoked as follows: 1984 1985 # To lock MBOX: 1986 LOCKER -fEXPIRE_TIMEOUT -rRETRY_COUNT MBOX 1987 # To unlock it: 1988 LOCKER -u -fEXPIRE_TIMEOUT -rRETRY_COUNT MBOX 1989 1990 Here, EXPIRE_TIMEOUT is the value supplied with the 1991 'expire-timeout' configuration statement, and RETRY_COUNT is 1992 the value supplied with the 'retry-count' statement (see 1993 below). 1994 1995 To properly interact with 'mailutils', the external locker 1996 program must use the following exit codes: 1997 1998 Exit code Meaning 1999 ------------------------------------------------------------------- 2000 0 Success. 2001 1 Failed due to an error. 2002 2 Unlock requested ('-u'), but file is not 2003 locked. 2004 3 Lock requested, but file is already 2005 locked. 2006 4 Insufficient permissions. 2007 2008 *Note dotlock::, for the description of the default external 2009 locker, shipped with mailutils. 2010 2011 'kernel' 2012 Use kernel locking mechanism ('fcntl'(2)). 2013 2014 'null' 2015 No locking at all. The statements below are silently ignored. 2016 2017 -- Configuration: retry-count NUMBER 2018 Number of locking attempts. The default is 10. 2019 2020 -- Configuration: retry-sleep SECONDS 2021 -- Configuration: retry-timeout SECONDS 2022 Time interval, in seconds, between two successive locking attempts. 2023 The default is 1 second. The 'retry-timeout' statement is 2024 deprecated because of its misleading name. 2025 2026 -- Configuration: expire-timeout SECONDS 2027 Sets the expiration timeout. The existing lock file will be 2028 removed, if it was created more than this number of seconds ago. 2029 The default is 600. 2030 2031 -- Configuration: pid-check BOOL 2032 This statement can be used if locking type is set to 'dotlock'. If 2033 set to 'true', it instructs the locking algorithm to check if the 2034 PID of the lock owner is still running by the time when it tries to 2035 acquire the lock. This works as follows. When the lock file is 2036 created, the PID of the creating process is written to it. If 2037 another process tries to acquire the lock and sees that the lock 2038 file already exists, it reads the PID from the file and checks if a 2039 process with that PID still exists in the process table. If it 2040 does not, the process considers the lock file to be stale, removes 2041 it and locks the mailbox. 2042 2043 -- Configuration: external-locker STRING 2044 Sets the name of the external locker program to use, instead of the 2045 default 'dotlock'. 2046 2047 This statement is in effect only when used together with 'type 2048 external'. 2049 2050 2051File: mailutils.info, Node: mailer statement, Next: acl statement, Prev: locking statement, Up: configuration 2052 20533.2.10 The 'mailer' Statement 2054----------------------------- 2055 2056Syntax 2057------ 2058 2059 mailer { 2060 url URL; 2061 } 2062 2063Description 2064----------- 2065 2066A "mailer" is a special logical entity GNU Mailutils uses for sending 2067messages. Its internal representation is discussed in Mailer. The 2068'mailer' statement configures it. 2069 2070 The mailer statement contains a single sub-statement: 2071 2072 -- Configuration: url STR 2073 Set the mailer URL. 2074 2075 GNU Mailutils supports three types of mailer URLs, described in the 2076table below: 2077 2078smtp://[USER[:PASS][;auth=MECH,...]@]HOST[:PORT][;PARAMS] 2079smtps://[USER[:PASS][;auth=MECH,...]@]HOST[:PORT][;PARAMS] 2080 Send messages using SMTP protocol. *Note SMTP Mailboxes::, for a 2081 detailed description of the URL and its parts. 2082 2083sendmail[://PROGNAME] 2084 Use sendmail-compatible program PROGNAME. "Sendmail-compatible" 2085 means that the program must support following command line options: 2086 2087 '-oi' 2088 Do not treat '.' as message terminator. 2089 2090 '-f ADDR' 2091 Use ADDR as the sender address. 2092 2093 '-t' 2094 Get recipient addresses from the message. 2095 2096 *Note sendmail: Program Mailboxes, for details. 2097 2098prog://PROGNAME?QUERY 2099 A "prog" mailer. This is a generalization of 'sendmail' mailer 2100 that allows to use arbitrary external programs as mailers. 2101 2102 It is described in detain in *note prog: Program Mailboxes. 2103 2104 2105File: mailutils.info, Node: acl statement, Next: tcp-wrappers statement, Prev: mailer statement, Up: configuration 2106 21073.2.11 The 'acl' Statement 2108-------------------------- 2109 2110Syntax 2111------ 2112 2113 acl { 2114 # Allow connections from this IP address. 2115 allow [from] IP; 2116 2117 # Deny connections from this IP address. 2118 deny [from] IP; 2119 2120 # Log connections from this IP address. 2121 log [from] IP [STRING]; 2122 2123 /* Execute supplied program if a connection from this 2124 IP address is requested. */ 2125 exec [from] IP PROGRAM; 2126 2127 /* Use PROGRAM to decide whether to allow connection 2128 from IP. */ 2129 ifexec [from] IP PROGRAM; 2130 } 2131 2132Description 2133----------- 2134 2135The ACL statement defines an "Access Control List", a special structure 2136that controls who can access the given Mailutils resource. 2137 2138 The 'acl' block contains a list of access controls. Each control can 2139be regarded as a function that returns a tree-state value: 'True', 2140'False' and 'Don't know'. When a remote party connects to the server, 2141each of controls is tried in turn. If a control returns 'False', access 2142is denied. If it returns 'True', access is allowed. If it returns 2143'Don't know', then the next control is tried. It is unclear whether to 2144allow access if the last control in list returned 'Don't know'. GNU 2145Mailutils 3.13 issues a warning message and allows access. This default 2146may change in future versions. Users are advised to write their ACLs so 2147that the last control returns a definite answer (either 'True' or 2148'False'). 2149 2150 In the discussion below, wherever CIDR appears as an argument, it can 2151be replaced by any of: 2152 2153 * An IPv4 address in dotted-quad notation. 2154 * An IPv6 address in numeric notation 2155 * A CIDR in the form 'IP/MASK', where IP is an IP address (either 2156 IPv4 or IPv6), and MASK is the network mask. 2157 * A symbolic host name. 2158 * A word 'any', which matches any IP address. 2159 2160 The following controls are understood: 2161 2162 -- Configuration: allow [from] CIDR 2163 Allow connections from IP addresses matching this CIDR block. 2164 2165 -- Configuration: deny [from] CIDR 2166 Deny connections from IP addresses matching this CIDR block. 2167 2168 -- Configuration: ifexec [from] CIDR PROGRAM 2169 When a connection from the CIDR block is requested, execute the 2170 program PROGRAM. If its exit code is '0', then allow connection. 2171 Otherwise, deny it. 2172 2173 The PROGRAM argument undergoes variable expansion and word 2174 splitting. The following variables are defined: 2175 2176 'aclno' 2177 Ordinal number of the control in the ACL. Numbers begin from 2178 '1'. 2179 2180 'family' 2181 Connection family. Mailutils version 3.13 supports the 2182 following families: 'AF_INET', 'AF_INET6' and 'AF_UNIX'. 2183 2184 'address' 2185 Remote IP address (for 'AF_INET' and 'AF_INET6') or socket 2186 name (for 'AF_UNIX'). Notice that most Unixes return empty 2187 string instead of the 'AF_UNIX' socket name, so do not rely on 2188 it. 2189 2190 'port' 2191 Remote port number (for 'AF_INET' and 'AF_INET6'). 2192 2193 -- Configuration: exec [from] CIDR PROGRAM 2194 If a connection from the CIDR block is requested, execute the given 2195 PROGRAM. Do not wait for it to terminate, and ignore its exit 2196 code. The PROGRAM is subject for variable expansion as in 2197 'ifexec'. 2198 2199 The following two controls are provided for logging purposes and as a 2200means of extensions. They always return a 'Don't know' answer, and 2201therefore should not be used at the end of an ACL: 2202 2203 -- Configuration: log [from] CIDR [STRING] 2204 Log connections from addresses in this CIDR. The 'MU_DIAG_INFO' 2205 channel is used. If the logging goes to syslog, it is translated 2206 to the 'LOG_INFO' priority. 2207 2208 If STRING is not given, the format of the log entry depends on the 2209 connection family, as described in the table below: 2210 2211 {AF_INET IP:PORT} 2212 For inet IPv4 connections. The variables IP and PORT are 2213 replaced by the remote IP address and port number, 2214 correspondingly. 2215 2216 {AF_UNIX} 2217 For connections over UNIX sockets. The socket name, if 2218 available, may be printed before the closing curly brace. 2219 2220 If STRING is supplied, it undergoes variable expansions as 2221 described for the 'ifexec'. 2222 2223 For example, the following ACL makes a Mailutils server log every 2224 incoming connection: 2225 2226 acl { 2227 log from any "Connect from ${address}"; 2228 ... 2229 } 2230 2231 This was the default behavior for the versions of Mailutils up to 2232 '1.2', so if you got used to its logs you might wish to add the 2233 above in your configuration files. 2234 2235 -- Configuration: exec [from] CIDR PROGRAM 2236 If a connection from the CIDR block is requested, execute the given 2237 PROGRAM. Do not wait for it to terminate, and ignore its exit 2238 code. 2239 2240 2241File: mailutils.info, Node: tcp-wrappers statement, Next: Server Settings, Prev: acl statement, Up: configuration 2242 22433.2.12 The 'tcp-wrappers' Statement 2244----------------------------------- 2245 2246Syntax 2247------ 2248 2249 tcp-wrappers { 2250 # Enable TCP wrapper access control. 2251 enable BOOL; 2252 2253 # Set daemon name for TCP wrapper lookups. 2254 daemon NAME; 2255 2256 # Use FILE for positive client address access control. 2257 allow-table FILE; 2258 2259 # Use file for negative client address access control. 2260 deny-table FILE; 2261 } 2262 2263Description 2264----------- 2265 2266The 'tcp-wrappers' statements provides an alternative way to control 2267accesses to the resources served by GNU Mailutils. This statement is 2268enabled if Mailutils is compiled with TCP wrappers library 'libwrap'. 2269 2270 Access control using TCP wrappers is based on two files, called 2271"tables", containing access rules. There are two tables: the "allow 2272table", usually stored in file '/etc/hosts.allow', and the "deny table", 2273kept in file '/etc/hosts.deny'. The rules in each table begin with an 2274identifier called "daemon name". A utility that wishes to verify a 2275connection, selects the entries having its daemon name from the allow 2276table. A connection is allowed if it matches any of these entries. 2277Otherwise, the utility retrieves all entries with its daemon name from 2278the deny table. If any of these matches the connection, then it is 2279refused. Otherwise, if neither table contains matching entries, the 2280connection is allowed. 2281 2282 The description of a TCP wrapper table format lies outside the scope 2283of this document. Please, see *note ACCESS CONTROL FILES: 2284(hosts_access(5))ACCESS CONTROL FILES, for details. 2285 2286 -- Configuration: enable BOOL 2287 Enable access control using TCP wrappers. It is on by default. 2288 2289 -- Configuration: daemon NAME 2290 Set daemon name for TCP wrapper lookups. By default, the name of 2291 the utility is used. E.g. 'imap4d' uses 'imap4d' as the daemon 2292 name. 2293 2294 -- Configuration: allow-table FILE 2295 Use FILE as allow table. By default, '/etc/hosts.allow' is used. 2296 2297 -- Configuration: deny-table FILE 2298 Use FILE as negative table. By default, '/etc/hosts.deny' is used. 2299 2300 2301File: mailutils.info, Node: Server Settings, Next: auth statement, Prev: tcp-wrappers statement, Up: configuration 2302 23033.2.13 Server Settings 2304---------------------- 2305 2306GNU Mailutils offers several server applications: 'pop3d', 'imap4d', 2307'comsatd', to name a few. Being quite different in their purpose, they 2308are very similar in some aspects of their architecture. First of all, 2309they all support two operating modes: "daemon", where a program 2310disconnects from the controlling terminal and works in background, and 2311"inetd", where it remains in foreground and communicates with the remote 2312party via standard input and output streams. Secondly, when operating 2313as daemons, they listen to a preconfigured set of IP addresses and 2314ports, reacting to requests that arrive. 2315 2316 To configure these aspects of functionality, GNU Mailutils provides 2317"Server Configuration Settings", which is describes in this subsection. 2318 2319* Menu: 2320 2321* General Server Configuration:: 2322* Server Statement:: 2323 2324 2325File: mailutils.info, Node: General Server Configuration, Next: Server Statement, Up: Server Settings 2326 23273.2.13.1 General Server Configuration 2328..................................... 2329 2330 2331Syntax: 2332 # Set daemon mode. 2333 mode 'inetd|daemon'; 2334 2335 # Run in foreground. 2336 foreground BOOL; 2337 2338 # Maximum number of children processes to run simultaneously. 2339 max-children NUMBER; 2340 2341 # Store PID of the master process in FILE. 2342 pidfile FILE; 2343 2344 # Default port number. 2345 port PORTSPEC; 2346 2347 # Set idle timeout. 2348 timeout TIME; 2349 2350 2351 Description: These statements configure general server-related 2352issues. 2353 2354 -- Configuration: mode STRING; 2355 Set operation mode of the server. Two operation modes are 2356 supported: 2357 2358 daemon 2359 Run as a standalone daemon, disconnecting from the controlling 2360 terminal and continuing to run in the background. In this 2361 case, it is the server that controls what IP addresses and 2362 ports to listen on, who is allowed to connect and from where, 2363 how many clients are allowed to connect simultaneously, etc. 2364 Most remaining configuration statements are valid only in the 2365 daemon mode. 2366 2367 This is the preferred mode of operation for GNU Mailutils 2368 servers. 2369 2370 inetd 2371 Operate as a subprocess of UNIX internet super-server program, 2372 'inetd'. *Note (inetd(8))Internet super-server::, for a 2373 detailed description of the operation of 'inetd' and its 2374 configuration. In this case it is 'inetd' that controls all 2375 major connectivity aspects. The Mailutils server program 2376 communicates with it via standard input and output streams. 2377 2378 For historical reasons, this mode is the default, if no 'mode' 2379 statement is specified. This will change in the future. 2380 2381 -- Configuration: foreground BOOL; 2382 2383 [daemon mode only] 2384 Do not disconnect from the controlling terminal and remain in the 2385 foreground. 2386 2387 -- Configuration: max-children NUMBER; 2388 2389 [daemon mode only] 2390 Set maximum number of child processes allowed to run 2391 simultaneously. This equals the number of clients that can use the 2392 server simultaneously. 2393 2394 The default is 20 clients. 2395 2396 -- Configuration: pidfile FILE; 2397 After startup, store the PID of the main server process in FILE. 2398 When the process terminates, the file is removed. As of version 2399 3.13, GNU Mailutils servers make no further use of this file. It 2400 is intended for use by automated startup scripts and controlling 2401 programs (e.g. *note GNU pies: (pies)Top.). 2402 2403 -- Configuration: port PORTSPEC; 2404 2405 [daemon mode only] 2406 Set default port to listen to. The PORTSPEC argument is either a 2407 port number in decimal, or a symbolic service name, as listed in 2408 '/etc/services' (*note (services(5))Internet network services 2409 list::). 2410 2411 -- Configuration: timeout TIME; 2412 Sets maximum idle time out in seconds. If a client does not send 2413 any requests during TIME seconds, the child process terminates. 2414 2415 2416File: mailutils.info, Node: Server Statement, Prev: General Server Configuration, Up: Server Settings 2417 24183.2.13.2 The 'server' Statement 2419............................... 2420 2421 2422Syntax: 2423 server IPADDR[:PORT] { 2424 # Run this server as a single process. 2425 single-process BOOL; 2426 2427 # Log the session transcript. 2428 transcript BOOL; 2429 2430 # Set idle timeout. 2431 timeout TIME; 2432 2433 # Size of the queue of pending connections 2434 backlog <number: callback>; 2435 2436 # Kind of TLS encryption to use for this server. 2437 tls-mode 'no'|'ondemand'|'required'|'connection'; 2438 2439 tls { 2440 # Specify SSL certificate file. 2441 ssl-certificate-file STRING; 2442 # Specify SSL certificate key file. 2443 ssl-key-file FILE; 2444 # Specify trusted CAs file. 2445 ssl-ca-file FILE; 2446 # Set the priorities to use on the ciphers, methods, etc. 2447 ssl-priorities STRING; 2448 } 2449 2450 # Set server specific ACLs. 2451 acl { /* *Note ACL Statement::. */ }; 2452 } 2453 2454 2455 Description: 2456 2457 The 'server' block statement configures a single TCP or UDP server. 2458It takes effect only in daemon mode (*note server mode::). The argument 2459to this statement specifies the IP address, and, optionally, the port, 2460to listen on for requests. The IPADDR part is either an IPv4 address in 2461dotted-quad form, or a IPv6 address enclosed in square brackets, or a 2462symbolic host name which can be resolved to such an address. Specifying 2463'0.0.0.0' as the IPADDR means listen on all available network 2464interfaces. The PORT argument is either a port number in decimal, or a 2465symbolic service name, as listed in '/etc/services' (*note 2466(services(5))Internet network services list::). If PORT is omitted, 2467Mailutils uses the port set by 'port' statement (*note port: General 2468Server Configuration.), or, in its absence, the default port number, 2469which depends on a server being used (e.g. 110, for 'pop3d', 143, for 2470'imap4d', etc.). 2471 2472 Any number of 'server' statements may be specified in a single 2473configuration file, allowing to set up the same service on several IP 2474addresses and/or port numbers, and with different configurations. 2475 2476 Statements within the 'server' block statement configure this 2477particular server. 2478 2479 -- Configuration: single-process BOOL; 2480 If set to true, this server will operate in single-process mode. 2481 This mode is intended for debugging only, do not use it on 2482 production servers. 2483 2484 -- Configuration: transcript BOOL; 2485 Enable transcript of the client-server interaction. This may 2486 generate excessive amounts of logging, which in turn may slow down 2487 the operation considerably. 2488 2489 Session transcripts are useful in fine-tuning your configurations 2490 and in debugging. They should be turned off on most production 2491 servers. 2492 2493 -- Configuration: timeout TIME; 2494 Set idle timeout for this server. This overrides the global 2495 timeout settings (*note timeout: General Server Configuration.). 2496 2497 -- Configuration: backlog NUMBER; 2498 Configures the size of the queue of pending connections 2499 2500 -- Configuration: tls-mode MODE; 2501 Configure the use of TLS encryption. The MODE argument is one of 2502 the following: 2503 2504 no 2505 TLS is not used. The corresponding command ('STLS', for POP3, 2506 'STARTTLS', for 'IMAP4') won't be available even if the TLS 2507 configuration is otherwise complete. 2508 2509 ondemand 2510 TLS is initiated when the user issues the appropriate command. 2511 This is the default when TLS is configured. 2512 2513 required 2514 Same as above, but the use of TLS is mandatory. The 2515 authentication state is entered only after TLS negotiation has 2516 succeeded. 2517 2518 connection 2519 TLS is always forced when the connection is established. For 2520 'pop3d' this means using POP3S protocol (or IMAP4S, for 2521 'imap4d'). 2522 2523 -- Configuration: tls { ... } 2524 The 'tls' statement configures SSL certificate and key files, as 2525 well as other SSL settings for use in this server. It is used when 2526 'tls-mode' is set to any of the following values: 'ondemand', 2527 'required', 'connection'. 2528 2529 If 'tls-mode' is set to any of the values above and 'tls' section 2530 is absent, settings from the global 'tls' section will be used. In 2531 this case, it is an error if the global 'tls' section is not 2532 defined. 2533 2534 *Note tls statement::, for a discussion of its syntax. 2535 2536 -- Configuration: acl 2537 This statement defines a per-server Access Control List. Its 2538 syntax is as described in *note ACL Statement::. Per-server ACLs 2539 complement, but not override, global ACLs, i.e. if both global ACL 2540 and per-server ACL are used, the connection is allowed only if both 2541 of them allow it, and is denied if any one of them denies it. 2542 2543 2544File: mailutils.info, Node: auth statement, Next: pam statement, Prev: Server Settings, Up: configuration 2545 25463.2.14 The 'auth' Statement 2547--------------------------- 2548 2549Syntax 2550------ 2551 2552 auth { 2553 # Set a list of modules for authentication. 2554 authentication MODULE-LIST; 2555 2556 # Set a list of modules for authorization. 2557 authorization MODULE-LIST; 2558 } 2559 2560Description 2561----------- 2562 2563Some mail utilities provide access to their services only after 2564verifying that the user is actually the person he is claiming to be. 2565Such programs are, for example, 'pop3d' and 'imap4d'. The process of 2566the verification is broken down into two stages: "authorization" and 2567"authentication". In "authorization" stage the program retrieves the 2568information about a particular user. In "authentication" stage, this 2569information is compared against the user-supplied credentials. Only if 2570both stages succeed is the user allowed to use the service. 2571 2572 A set of "modules" is involved in performing each stage. For 2573example, the authorization stage can retrieve the user description from 2574various sources: system database, SQL database, virtual domain table, 2575etc. Each module is responsible for retrieving the description from a 2576particular source of information. The modules are arranged in a "module 2577list". The modules from the list are invoked in turn, until one of them 2578succeeds or the list is exhausted. In the latter case the authorization 2579fails. Otherwise, the data returned by the succeeded module are used in 2580authentication. 2581 2582 Similarly, authentication may be performed in several ways. The 2583authentication modules are also grouped in a list. Each module is tried 2584in turn until either a module succeeds, in which case the authentication 2585succeeds, or the end of the list is reached. 2586 2587 For example, the authorization list 2588 2589 (system, sql, virtdomains) 2590 2591means that first the system user database ('/etc/password') is searched 2592for a description of a user in question. If the search fails, the SQL 2593database is searched. Finally, if it also fails, the search is 2594performed in the virtual domain database. 2595 2596 _Note_, that some authentication and/or authorization modules may be 2597disabled when configuring the package before compilation. The names of 2598the disabled modules are nevertheless available for use in runtime 2599configuration options, but they represent a "fail-only" functionality, 2600e.g. if the package was compiled without SQL support then the module 2601'sql' in the above example will always fail, thus passing the execution 2602on to the next module. 2603 2604 The 'auth' statement configures authentication and authorization. 2605 2606 -- Configuration: authorization MODULE-LIST 2607 Define a sequence of modules to use for authorization. Modules 2608 will be tried in the same order as listed in MODULE-LIST. 2609 2610 The modules available for use in authorization list are: 2611 2612 system 2613 User credentials are retrieved from the system user database 2614 ('/etc/password'). 2615 sql 2616 User credentials are retrieved from a SQL database. A 2617 separate configuration statement, 'sql', is used to configure 2618 it (*note sql statement::). 2619 virtdomain 2620 User credentials are retrieved from a "virtual domain" user 2621 database. Virtual domains are configured using 'virtdomain' 2622 statement (*note virtdomain statement::). 2623 radius 2624 User credentials are retrieved using RADIUS. *Note radius 2625 statement::, for a detailed description on how to configure 2626 it. 2627 ldap 2628 User credentials are retrieved from an LDAP database. *Note 2629 ldap statement::, for an information on how to configure it. 2630 2631 Unless overridden by 'authorization' statement, the default list of 2632 authorization modules is: 2633 2634 1. generic 2635 2. system 2636 3. pam 2637 4. sql 2638 5. virtual 2639 6. radius 2640 7. ldap 2641 2642 -- Configuration: authentication MODULE-LIST 2643 Define a sequence of modules to use for authentication. Modules 2644 will be tried in the same order as listed in MODULE-LIST. 2645 2646 The following table lists modules available for use in MODULE-LIST: 2647 2648 generic 2649 The generic authentication type. User password is hashed and 2650 compared against the hash value returned in authorization 2651 stage. 2652 system 2653 The hashed value of the user password is retrieved from 2654 '/etc/shadow' file on systems that support it. 2655 sql 2656 The hashed value of the user password is retrieved from a SQL 2657 database using query supplied by 'getpass' statement (*note 2658 getpass: sql statement.). 2659 pam 2660 The user is authenticated via pluggable authentication module 2661 (PAM). The PAM service name to be used is configured in 'pam' 2662 statement (*note pam statement::). 2663 radius 2664 The user is authenticated on a remote RADIUS server. *Note 2665 radius statement::. 2666 ldap 2667 The user is authenticated using LDAP. *Note ldap statement::. 2668 2669 Unless overridden by 'authentication' statement, the list of 2670 authentication modules is the same as for 'authorization', i.e.: 2671 2672 1. generic 2673 2. system 2674 3. pam 2675 4. sql 2676 5. virtual 2677 6. radius 2678 7. ldap 2679 2680 2681File: mailutils.info, Node: pam statement, Next: virtdomain statement, Prev: auth statement, Up: configuration 2682 26833.2.15 PAM Statement 2684-------------------- 2685 2686Syntax 2687------ 2688 2689 pam { 2690 # Set PAM service name. 2691 service TEXT; 2692 } 2693 2694Description 2695----------- 2696 2697The 'pam' statement configures PAM authentication. It contains a single 2698sub-statement: 2699 2700 -- Configuration: service TEXT 2701 Define service name to look for in PAM configuration. By default, 2702 the base name of the Mailutils binary is used. 2703 2704 This statement takes effect only if 'pam' is listed in 2705'authentication' statement (*note auth statement::). 2706 2707 2708File: mailutils.info, Node: virtdomain statement, Next: radius statement, Prev: pam statement, Up: configuration 2709 27103.2.16 The 'virtdomain' Statement 2711--------------------------------- 2712 2713Syntax 2714------ 2715 2716 virtdomain { 2717 # Name of the virtdomain password directory. 2718 passwd-dir DIR; 2719 } 2720 2721Description 2722----------- 2723 2724"Virtual mail domains" make it possible to handle several mail domains 2725each having a separate set of users, on a single server. The domains 2726are completely independent of each other, i.e. the same user name can 2727be present in several domains and represent different users. 2728 2729 When authenticating to a server with virtual domain support enabled, 2730users must supply their user names with domain parts. The server strips 2731off the domain part and uses it as a name of UNIX-format password 2732database file, located in the "domain password directory". The latter 2733is set using 'passwd-dir' statement. 2734 2735 -- Configuration: passwd-dir DIR 2736 Set virtual domain password directory. 2737 2738 For example, when authenticating user 'smith@example.com', the server 2739will use password file named 'DIR/example.com'. This file must be in 2740UNIX passwd format (*note (passwd(5))password file::), with encrypted 2741passwords stored in it (as of GNU Mailutils version 3.13, there is no 2742support for shadow files in virtual password directories, although this 2743is planned for future versions). Here is an example record from this 2744file: 2745 2746 smith:Wbld/G2Q2Le2w:1000:1000:Email Account:/var/mail/domain/smith:/dev/null 2747 2748 Notice, that it must contain user names without domain parts. 2749 2750 The 'pw_dir' field (the 6th field) is used to determine the location 2751of the maildrop for this user. It is defined as 'PW_DIR/INBOX'. In our 2752example, the maildrop for user 'smith' will be located in file 2753'/var/mail/domain/smith'. 2754 2755 If user did not supply his domain name, or if no matching record was 2756found in the password file, or if the file matching the domain name does 2757not exist, then GNU Mailutils falls back to alternative method. First, 2758it tries to determine the IP address of the remote party. Then the 2759domain name corresponding to that address is looked up in the DNS 2760system. Finally, this domain name is used as a name of the password 2761file. 2762 2763 2764File: mailutils.info, Node: radius statement, Next: sql statement, Prev: virtdomain statement, Up: configuration 2765 27663.2.17 The 'radius' Statement 2767----------------------------- 2768 2769Syntax 2770------ 2771 2772 radius { 2773 # Set radius configuration directory. 2774 directory DIR; 2775 # Radius request for authorization. 2776 auth REQUEST; 2777 # Radius request for getpwnam. 2778 getpwnam REQUEST; 2779 # Radius request for getpwuid. 2780 getpwuid REQUEST; 2781 } 2782 2783Description 2784----------- 2785 2786The 'radius' block statement configures RADIUS authentication and 2787authorization. 2788 2789 Mailutils uses GNU Radius library, which is configured via 2790'raddb/client.conf' file (*note Client Configuration: (radius)client.). 2791Its exact location depends on configuration settings that were used 2792while compiling GNU Radius. Usually it is '/usr/local/etc', or '/etc'. 2793This default can also be changed at run time using 'directory' 2794statement: 2795 2796 -- Configuration: directory DIR 2797 Set full path name to the GNU Radius configuration directory. 2798 2799 It authorization is used, the Radius dictionary file must declare the 2800the following attributes: 2801 2802Attribute Type Description 2803--------------------------------------------------------------------------- 2804GNU-MU-User-Name string User login name 2805GNU-MU-UID integer UID 2806GNU-MU-GID integer GID 2807GNU-MU-GECOS string GECOS 2808GNU-MU-Dir string Home directory 2809GNU-MU-Shell string User shell 2810GNU-MU-Mailbox string User mailbox 2811GNU-MU-Quota integer Mail quota (in bytes) 2812 2813 A dictionary file with appropriate definitions is included in the 2814Mailutils distribution: 'examples/config/mailutils.dict'. This file is 2815not installed by default, you will have to manually copy it to the GNU 2816Radius 'raddb/dict' directory and include it in the main dictionary file 2817'raddb/dictionary' by adding the following statement: 2818 2819 $INCLUDE dict/mailutils.dict 2820 2821 Requests to use for authentication and authorization are configured 2822using three statements: 'auth', 'getpwnam' and 'getpwuid'. Each 2823statement takes a single argument: a string, containing a 2824comma-separated list of assignments. An assignment specifies a 2825particular "attribute-value pair" (*note RADIUS Attributes: 2826(radius)Overview.) to send to the server. The left-hand side of the 2827assignment is a symbolic attribute name, as defined in one of Radius 2828dictionaries (*note Dictionary of Attributes: (radius)dictionary file.). 2829The value is specified by the right-hand side of assignment. For 2830example: 2831 2832 "Service-Type = Authenticate-Only, NAS-Identifier = \"mail\"" 2833 2834 The assignment may contain references to the following variables 2835(*note Variables::): 2836 2837user 2838 The actual user name (for 'auth' and 'getpwnam'), or user ID (for 2839 'getpwuid'). For example: 2840 2841 User-Name = ${user} 2842 2843passwd 2844 User password. For examples: 2845 User-Password = ${passwd} 2846 2847 -- Configuration: auth PAIRLIST 2848 Specifies the request to be sent to authenticate the user. For 2849 example: 2850 2851 auth "User-Name = ${user}, User-Password = ${passwd}"; 2852 2853 The user is authenticated only if this request returns 2854 'Access-Accept' (*note Access-Accept: (radius)Authentication 2855 Requests.). Any returned attribute-value pairs are ignored. 2856 2857 -- Configuration: getpwnam PAIRLIST 2858 Specifies the request that returns user information for the given 2859 user name. For example: 2860 2861 getpwnam "User-Name = ${user}, State = getpwnam, " 2862 "Service-Type = Authenticate-Only"; 2863 2864 If the requested user account exists, the Radius server must return 2865 'Access-Accept' packet with the following attributes: 2866 'GNU-MU-User-Name', 'GNU-MU-UID', 'GNU-MU-GID', 'GNU-MU-GECOS', 2867 'GNU-MU-Dir', 'GNU-MU-Shell'. 2868 2869 The attributes 'GNU-MU-Mailbox' and 'GNU-MU-Quota' are optional. 2870 2871 If 'GNU-MU-Mailbox' is present, it must contain a valid mailbox URL 2872 (*note URL: Mailbox.). If 'GNU-MU-Mailbox' is not present, 2873 Mailutils constructs the mailbox name using the settings from the 2874 'mailbox' configuration statement (*note Mailbox Statement::), or 2875 built-in defaults, if it is not present. 2876 2877 If 'GNU-MU-Quota' is present, it specifies the maximum mailbox size 2878 for this user, in bytes. In the absence of this attribute, mailbox 2879 size is unlimited. 2880 2881 -- Configuration: getpwuid PAIRLIST 2882 Specifies the request that returns user information for the given 2883 user ID. In PAIRLIST, the 'user' macro-variable is expanded to the 2884 numeric value of ID. For example: 2885 2886 getpwuid "User-Name = ${user}, State = getpwuid, " 2887 "Service-Type = Authenticate-Only"; 2888 2889 The reply to 'getpwuid' request is the same as to 'getpwnam' 2890 request (see above). 2891 2892 2893File: mailutils.info, Node: sql statement, Next: ldap statement, Prev: radius statement, Up: configuration 2894 28953.2.18 The 'sql' Statement 2896-------------------------- 2897 2898Syntax 2899------ 2900 2901 sql { 2902 # Set SQL interface to use. 2903 interface 'mysql|odbc|postgres'; 2904 # SQL server host name. 2905 host ARG; 2906 # SQL user name. 2907 user ARG; 2908 # Password for the SQL user. 2909 passwd ARG; 2910 # SQL server port. 2911 port ARG; 2912 # Database name. 2913 db ARG; 2914 # Type of password returned by getpass query. 2915 password-type 'plain | hash | scrambled'; 2916 # Set a field-map for parsing SQL replies. 2917 field-map LIST; 2918 # SQL query returning the user's password. 2919 getpass QUERY; 2920 # SQL query to use for getpwnam requests. 2921 getpwnam QUERY; 2922 # SQL query to use for getpwuid requests. 2923 getpwuid QUERY; 2924 } 2925 2926Description 2927----------- 2928 2929The 'sql' statement configures access credentials to SQL database and 2930the queries for authentication and authorization. 2931 2932 GNU Mailutils supports three types of SQL interfaces: MySQL, 2933PostgreSQL and ODBC. The latter is a standard API for using database 2934management systems, which can be used to communicate with a wide variety 2935of DBMS. 2936 2937 -- Configuration: interface TYPE 2938 Configures type of DBMS interface. Allowed values for TYPE are: 2939 2940 mysql 2941 Interface with a MySQL server (<http://www.mysql.org>). 2942 2943 odbc 2944 Use ODBC interface. See <http://www.unixodbc.org>, for a 2945 detailed description of ODBC configuration. 2946 2947 postgres 2948 Interface with a PostgreSQL server 2949 (<http://www.postgres.org>). 2950 2951 The database and database access credentials are configured using the 2952following statements: 2953 2954 -- Configuration: host ARG 2955 The host running the SQL server. The value can be either a host 2956 name or an IP address in dotted-quad notation, in which case an 2957 INET connection is used, or a full pathname to a file, in which 2958 case a connection to UNIX socket is used. 2959 2960 -- Configuration: port ARG 2961 TCP port the server is listening on (for INET connections). This 2962 parameter is optional. Its default value depends on the type of 2963 database being used. 2964 2965 -- Configuration: db ARG; 2966 Name of the database. 2967 2968 -- Configuration: user ARG 2969 SQL user name. 2970 2971 -- Configuration: passwd ARG; 2972 Password to access the database. 2973 2974 -- Configuration: password-encryption ARG; 2975 Defines type of encryption used by the password returned by 2976 'getpass' query (see below). Possible arguments are: 2977 2978 plain 2979 Password is in plain text. 2980 2981 crypt 2982 hash 2983 Password is encrypted by system 'crypt' function (*note 2984 (crypt(3))crypt::). 2985 2986 scrambled 2987 Password is encrypted by MySQL 'password' function. 2988 2989 -- Configuration: getpwnam QUERY 2990 Defines SQL query that returns information about the given user. 2991 The QUERY is subject to variable expansion (*note Variables::). 2992 The only variable defined is '$user', which expands to the user 2993 name. 2994 2995 The query should return a single row with the following columns: 2996 2997 name 2998 User name. 2999 passwd 3000 User password. 3001 uid 3002 UID of the user. 3003 gid 3004 GID of the primary group. 3005 gecos 3006 Textual description of the user. 3007 dir 3008 User's home directory 3009 shell 3010 User's shell program. 3011 3012 The following columns are optional: 3013 3014 mailbox 3015 Full pathname of the user's mailbox. If not returned or NULL, 3016 the mailbox is determined using the default algorithm (*note 3017 Mailbox::). 3018 quota 3019 Upper limit on the size of the mailbox. The value is either 3020 an integer number optionally followed by one of the usual size 3021 suffixes: 'K', 'M', 'G', or 'T' (case-insensitive). 3022 3023 -- Configuration: getpwuid QUERY 3024 Defines SQL query that returns information about the given UID. The 3025 QUERY is subject to variable expansion (*note Variables::). The 3026 only variable defined is '$user', which expands to the UID. 3027 3028 The query should return a single row, as described for 'getpwnam'. 3029 3030 -- Configuration: getpass QUERY 3031 Defines SQL query that returns the password of the given user. The 3032 QUERY is subject to variable expansion (*note Variables::). The 3033 only variable defined is '$user', which expands to the user name. 3034 3035 The query should return a row with a single column, which gives the 3036 password. The password can be encrypted as specified by the 3037 'password-encryption' statement. 3038 3039 -- Configuration: field-map LIST 3040 Defines a translation map for column names. The LIST is a list of 3041 mappings. Each mapping is a string 'NAME=COLUMN', where NAME is 3042 one of the names described in *note getpw column names::, and 3043 COLUMN is the name of the column in the returned row that should be 3044 used instead. The effect of this statement is similar to that of 3045 SQL 'AS' keyword. E.g. the statement 3046 3047 field-map (uid=user_id); 3048 3049 has the same effect as using 'SELECT user_id AS uid' in the SQL 3050 statement. 3051 3052 3053File: mailutils.info, Node: ldap statement, Next: tls statement, Prev: sql statement, Up: configuration 3054 30553.2.19 The 'ldap' Statement 3056--------------------------- 3057 3058Syntax 3059------ 3060 3061 ldap { 3062 # Enable LDAP lookups. 3063 enable BOOL; 3064 # Set URL of the LDAP server. 3065 url URL; 3066 # Base DN for LDAP lookups. 3067 base STRING; 3068 # DN for accessing LDAP database. 3069 binddn STRING; 3070 # Password for use with binddn. 3071 passwd STRING; 3072 # Use TLS encryption. 3073 tls BOOL; 3074 # Set LDAP debugging level. 3075 debug NUMBER; 3076 # Set a field-map for parsing LDAP replies. 3077 field-map LIST; 3078 # LDAP filter to use for getpwnam requests. 3079 getpwnam STRING; 3080 # LDAP filter to use for getpwuid requests. 3081 getpwuid FILTER; 3082 } 3083 3084Description 3085----------- 3086 3087The 'ldap' statement configures the use of LDAP for authentication. 3088 3089 -- Configuration: enable BOOL 3090 Enables LDAP lookups. If absent, 'enable On' is assumed. 3091 3092 -- Configuration: url URL 3093 Sets the URL of the LDAP server. 3094 3095 -- Configuration: base STRING 3096 Defines base DN for LDAP lookups. 3097 3098 -- Configuration: binddn STRING 3099 Defines the DN for accessing LDAP database. 3100 3101 -- Configuration: passwd STRING 3102 Password for use when binding to the database. 3103 3104 -- Configuration: tls BOOL 3105 Enable the use of TLS when connecting to the server. 3106 3107 -- Configuration: debug NUMBER 3108 Set LDAP debug level. Please refer to the OpenLDAP documentation, 3109 for allowed NUMBER values and their meaning. 3110 3111 -- Configuration: field-map MAP 3112 Defines a map for parsing LDAP replies. The MAP is a list of 3113 mappings(1). Each mapping is 'FIELD=ATTR', where ATTR is the name 3114 of the LDAP attribute and FIELD is a field name that declares what 3115 information that attribute carries. Available values for FIELD 3116 are: 3117 3118 name 3119 User name. 3120 passwd 3121 User password. 3122 uid 3123 UID of the user. 3124 gid 3125 GID of the primary group. 3126 gecos 3127 Textual description of the user. 3128 dir 3129 User's home directory 3130 shell 3131 User's shell program. 3132 3133 The default mapping is 3134 3135 ("name=uid", 3136 "passwd=userPassword", 3137 "uid=uidNumber", 3138 "gid=gidNumber", 3139 "gecos=gecos", 3140 "dir=homeDirectory", 3141 "shell=loginShell") 3142 3143 -- Configuration: getpwnam STRING 3144 Defines the LDAP filter to use for 'getpwnam' requests. The 3145 default is: 3146 3147 (&(objectClass=posixAccount) (uid=$user)) 3148 3149 -- Configuration: getpwuid STRING 3150 Defines the LDAP filter to use for 'getpwuid' requests. The 3151 default filter is: 3152 3153 (&(objectClass=posixAccount) (uidNumber=$user)) 3154 3155 ---------- Footnotes ---------- 3156 3157 (1) For backward compatibility, MAP can be a string containing 3158colon-delimited list of mappings. Such usage is, however, deprecated. 3159 3160 3161File: mailutils.info, Node: tls statement, Next: tls-file-checks statement, Prev: ldap statement, Up: configuration 3162 31633.2.20 The 'tls' Statement 3164-------------------------- 3165 3166Syntax 3167------ 3168 3169 tls { 3170 # Specify SSL certificate file. 3171 ssl-certificate-file STRING; 3172 # Specify SSL certificate key file. 3173 ssl-key-file FILE; 3174 # Specify trusted CAs file. 3175 ssl-ca-file FILE; 3176 # Set the priorities to use on the ciphers, methods, etc. 3177 ssl-priorities STRING; 3178 } 3179 3180Description 3181----------- 3182 3183The 'tls' statement configures TLS parameters to be used by servers. It 3184can appear both in the global scope and in server scope. Global tls 3185settings are applied for servers that are declared as supporting TLS 3186encryption, but lack the 'tls' substatement. 3187 3188 -- Configuration: ssl-certificate-file STRING 3189 Specify SSL certificate file. 3190 3191 -- Configuration: ssl-key-file FILE 3192 Specify SSL certificate key file. 3193 3194 -- Configuration: ssl-ca-file FILE 3195 Specify the trusted certificate authorities file. 3196 3197 -- Configuration: ssl-priorities STRING 3198 Set the priorities to use on the ciphers, key exchange methods, 3199 MACs and compression methods. 3200 3201 3202File: mailutils.info, Node: tls-file-checks statement, Next: gsasl statement, Prev: tls statement, Up: configuration 3203 32043.2.21 The 'tls-file-checks' Statement 3205-------------------------------------- 3206 3207Syntax 3208------ 3209 3210 tls-file-checks { 3211 # Configure safety checks for SSL key file. 3212 key-file LIST; 3213 # Configure safety checks for SSL certificate. 3214 cert-file LIST; 3215 # Configure safety checks for SSL CA file. 3216 ca-file LIST; 3217 } 3218 3219Description 3220----------- 3221 3222This section configures security checks applied to the particular SSL 3223configuration files in order to decide whether it is safe to use them. 3224 3225 -- Configuration: key-file LIST 3226 Configure safety checks for SSL key file. Elements of the LIST are 3227 names of individual checks, optionally prefixed with '+' to enable 3228 or '-' to disable the corresponding check. Valid check names are: 3229 3230 none 3231 Disable all checks. 3232 all 3233 Enable all checks. 3234 gwrfil 3235 Forbid group writable files. 3236 awrfil 3237 Forbid world writable files. 3238 grdfil 3239 Forbid group readable files. 3240 ardfil 3241 Forbid world writable files. 3242 linkwrdir 3243 Forbid symbolic links in group or world writable directories. 3244 gwrdir 3245 Forbid files in group writable directories. 3246 awrdir 3247 Forbid files in world writable directories, 3248 3249 -- Configuration: cert-file LIST 3250 Configure safety checks for SSL certificate. See 'key-file' for a 3251 description of LIST. 3252 3253 -- Configuration: ca-file LIST 3254 Configure safety checks for SSL CA file. See 'key-file' for a 3255 description of LIST. 3256 3257 3258File: mailutils.info, Node: gsasl statement, Prev: tls-file-checks statement, Up: configuration 3259 32603.2.22 The 'gsasl' Statement 3261---------------------------- 3262 3263 ================================================================== 3264 *Editor's note:* 3265 This node is to be written. 3266 ================================================================== 3267 3268Syntax 3269------ 3270 3271 gsasl { 3272 # Name of GSASL password file. 3273 cram-passwd FILE; 3274 # SASL service name. 3275 service STRING; 3276 # SASL realm name. 3277 realm STRING; 3278 # SASL host name. 3279 hostname STRING; 3280 # Anonymous user name. 3281 anonymous-user STRING; 3282 } 3283 3284 3285File: mailutils.info, Node: debugging, Next: frm and from, Prev: configuration, Up: Programs 3286 32873.3 Debugging 3288============= 3289 3290'Mailutils' debugging output is controlled by a set of levels, each of 3291which can be set independently of others. Each debug level consists of 3292a "category name", which identifies the part of 'Mailutils' for which 3293additional debugging is desired, and a level number, which tells 3294'Mailutils' how verbose should its output be. 3295 3296 Valid debug levels are: 3297 3298error 3299 Displays error conditions which are normally not reported, but 3300 passed to the caller layers for handling. 3301trace0 through trace9 3302 Ten levels of verbosity, 'trace0' producing less output, 'trace9' 3303 producing the maximum amount of output. 3304prot 3305 Displays network protocol interaction, where applicable. 3306 3307 Implementation and applicability of each level differs between 3308various categories. The full list of categories is available in file 3309'libmailutils/diag/debcat' in the Mailutils source tree. Most useful 3310categories and levels implemented for them are discussed later in this 3311article. 3312 3313* Menu: 3314 3315* Level Syntax:: 3316* Level BNF:: 3317* Debugging Categories:: 3318 3319 3320File: mailutils.info, Node: Level Syntax, Next: Level BNF, Up: debugging 3321 33223.3.1 Level Syntax 3323------------------ 3324 3325Debug levels can be set either from the command line, by using the 3326'--debug-level' command line option, or from the configuration file, 3327using the '.debug.level' statement. In both cases, the level is 3328specified as a list of individual levels, delimited with semicolons. 3329Each individual level can be specified as: 3330 3331!CATEGORY 3332 Disables all levels for the specified CATEGORY. 3333CATEGORY 3334 Enables all levels for the specified CATEGORY. 3335CATEGORY.LEVEL 3336 For the given CATEGORY, enables all levels from 'error' to LEVEL, 3337 inclusive. 3338CATEGORY.=LEVEL 3339 Enables only the given LEVEL for this CATEGORY. 3340CATEGORY.!LEVEL 3341 Disables all levels from 'error' to LEVEL, inclusive, for this 3342 CATEGORY. 3343CATEGORY.!=LEVEL 3344 Disables only the given LEVEL in this CATEGORY. 3345CATEGORY.LEVELA-LEVELB 3346 Enables all levels in the range from LEVELA to LEVELB, inclusive. 3347CATEGORY.!LEVELA-LEVELB 3348 Disables all levels in the range from LEVELA to LEVELB, inclusive. 3349 3350 Additionally, a comma-separated list of level specifications is 3351allowed after the dot. For example, the following specification: 3352 3353 acl.prot,!=trace9,!trace2 3354 3355 enables in category 'acl' all levels, except 'trace9', 'trace0', 3356'trace1', and 'trace2'. 3357 3358 3359File: mailutils.info, Node: Level BNF, Next: Debugging Categories, Prev: Level Syntax, Up: debugging 3360 33613.3.2 BNF 3362--------- 3363 3364The following specification in Backus-Naur form describes formally the 3365Mailutils debug level: 3366 3367 <debug-spec> ::= <level-spec> | <debug-level-list> 3368 <debug-level-list> ::= <debug-level> | 3369 <debug-level-list> ";" <debug-level> 3370 <debug-level> ::= <category> | "!" <category> | 3371 <category> "." <level-list> 3372 <level-list> ::= <level-spec> | <level-list> "," <level-spec> 3373 <level-spec> ::= <level> | <negate-level> 3374 <negate-level> ::= "!" <level> 3375 <level> ::= <level-number> | "=" <level-number> | 3376 <level-number> "-" <level-number> 3377 <level-number> ::= "error" | "trace0" | "trace1" | "trace2" | "trace3" | 3378 "trace4" | "trace5" | "trace6" | "trace7" | 3379 "trace8" | "trace9" | "prot" 3380 3381 3382File: mailutils.info, Node: Debugging Categories, Prev: Level BNF, Up: debugging 3383 33843.3.3 Debugging Categories 3385-------------------------- 3386 3387acl 3388 This category enables debugging of Access Control Lists. Available 3389 levels are: 3390 3391 error 3392 As usual, displays errors, not directly reported otherwise. 3393 trace0 3394 Basic tracing of ACL processing. 3395 trace9 3396 Traces the process of matching the ACL conditions. 3397 3398config 3399 This category affects configuration parser and/or lexical analyzer. 3400 The following levels are supported: 3401 3402 trace0 3403 Minimal information about configuration statements. 3404 trace2 3405 Trace lexical structure of the configuration files. 3406 trace7 3407 Trace execution of the configuration parser. 3408 3409 Due to its specific nature, this category cannot be enabled from 3410 the configuration file. A special hook is provided to facilitate 3411 debugging the configuration parser, namely, a pragmatic comment in 3412 form: 3413 3414 #debug=DEBUG-LEVEL-LIST 3415 3416 causes DEBUG-LEVEL-LIST to be parsed as described above. Thus, to 3417 force debugging of the configuration parser, one would add the 3418 following line at the very beginning of the configuration file: 3419 3420 #debug=config.trace7 3421 3422mailbox 3423 Operations over mailboxes. This module supports the following 3424 levels: 'error', 'trace0', 'trace1', and 'prot'. The latter is 3425 used by remote mailbox support libraries. 3426 3427auth 3428 Enables debugging information about authentication and 3429 authorization. This category supports the following levels: 3430 'error', 'trace0', 'trace1', and 'trace2'. 3431 3432 In level 'trace0', user data are reported along with the "data 3433 source" they were obtained from. The output may look like this: 3434 3435 pop3d: source=system, name=gray, passwd=x, uid=120, gid=100, 3436 gecos=Sergey Poznyakoff, dir=/home/gray, shell=/bin/bash, 3437 mailbox=/var/mail/gray, quota=0, change_uid=1 3438 3439 In the 'trace1' level, additional flow traces are displayed. 3440 3441 In the level 'trace2', a detailed flow trace is displayed, which 3442 looks like the following: 3443 3444 pop3d: Trying generic... 3445 pop3d: generic yields 38=Function not implemented 3446 pop3d: Trying system... 3447 pop3d: system yields 0=Success 3448 pop3d: Trying generic... 3449 pop3d: generic yields 4135=Authentication failed 3450 pop3d: Trying system... 3451 pop3d: system yields 0=Success 3452 3453mailer 3454 Debugs mailer operations. The following levels are supported: 3455 3456 error 3457 Displays mild error conditions. 3458 trace0 3459 Traces mailer operations in general: displays what part of the 3460 message is being sent, etc. 3461 trace6 3462 When used together with 'prot', displays security-sensitive 3463 information (such as passwords, user keys, etc). in 3464 plaintext. By default, such information is replaced with 3465 asterisks to reduce the possibility of security compromise. 3466 trace7 3467 When used together with 'prot', displays the "payload" 3468 information as it is being sent. The "payload" is the actual 3469 message contents, i.e. the part of SMTP transaction that goes 3470 after the 'DATA' command and which ends with a terminating dot 3471 line. Setting this level can generate huge amounts of 3472 information. 3473 prot 3474 For SMTP mailer: outputs transcripts of SMTP sessions. 3475 3476 _Note:_ Unless in a very secure environment, it is advised to avoid 3477 using level settings such as mailer.prot or mailer (without 3478 explicit level part), because the resulting output tends to be 3479 extremely copious and reveals sender private and security-sensitive 3480 data. If you wish to trace SMTP session flow, use 'mailer.=prot' 3481 or at least 'mailer.prot,!trace6'. 3482 3483server 3484 This category provides debugging information for Mailutils IP 3485 server objects. It supports the 'error' and 'trace0' levels. 3486 3487folder 3488 This category controls debugging information shown for operations 3489 related to Mailutils folders. 3490 3491remote 3492 The remote category is used by 'imap4d' and 'pop3d' servers to 3493 request showing additional information in the session transcripts. 3494 This category takes effect only when the 'transcript' configuration 3495 variable is set. Valid levels are: 3496 3497 trace6 3498 Show security-sensitive information (user passwords, etc.) 3499 trace7 3500 Show payload information 3501 3502 3503File: mailutils.info, Node: frm and from, Next: mail, Prev: debugging, Up: Programs 3504 35053.4 'frm' and 'from' -- List Headers from a Mailbox 3506=================================================== 3507 3508 ================================================================== 3509 *Editor's note:* 3510 The information in this node may be obsolete or otherwise 3511 inaccurate. This message will disappear, once this node revised. 3512 ================================================================== 3513 3514 GNU mailutils provides two commands for listing messages in a 3515mailbox. These are 'from' and 'frm'. 3516 3517 The behavior of both programs is affected by the following 3518configuration file statements: 3519 3520Statement Reference 3521------------------------------------------------------------------- 3522debug *Note debug statement::. 3523tls *Note tls statement::. 3524mailbox *Note mailbox statement::. 3525locking *Note locking statement::. 3526 3527'frm' 3528----- 3529 3530The 'frm' utility outputs a header information of the selected messages 3531in a mailbox. By default, 'frm' reads user's system mailbox and outputs 3532the contents of 'From' and 'Subject' headers for each message. If a 3533folder is specified in the command line, the program reads that folder 3534rather than the default mailbox. 3535 3536 The following command line options alter the behavior of the program: 3537 3538'-d' 3539'--debug' 3540 Enable debugging output. 3541'-f STRING' 3542'--field STRING' 3543 Display the header named by STRING instead of 'From' 'Subject' 3544 pair. 3545'-l' 3546'--to' 3547 Include the contents of 'To' header to the output. The output 3548 field order is then: 'To' 'From' 'Subject'. 3549'-n' 3550'--number' 3551 Prefix each line with corresponding message number. 3552'-Q' 3553'--Quiet' 3554 Be very quiet. Nothing is output except error messages. This is 3555 useful in shell scripts where only the return status of the program 3556 is important. 3557'-q' 3558'--query' 3559 Print a message only if there are unread messages in the mailbox. 3560'-S' 3561'--summary' 3562 Print a summary line. 3563'-s ATTR' 3564'--status ATTR' 3565 Only display headers from messages with the given status. ATTR may 3566 be one of the following: 'new', 'read', 'unread'. It is sufficient 3567 to specify only first letter of an ATTR. Multiple '-s' options are 3568 allowed. 3569'-t' 3570'--align' 3571 Tidy mode. In this mode 'frm' tries to preserve the alignment of 3572 the output fields. It also enables the use of BIDI algorithm for 3573 displaying subject lines that contain text in right-to-left 3574 orientation (such as Arabic or Hebrew). 3575 3576'from' 3577------ 3578 3579The 'from' utility displays sender and subject of each message in a 3580mailbox. By default, it reads the user's system mailbox. If the 3581program is given a single argument, it is interpreted as a name of the 3582user whose mailbox is to be read. Obviously, permissions are required 3583to access that user's mailbox, so such invocations may be used only by 3584superuser. 3585 3586 The option '-f' ('--file') instructs 'from' to read the given 3587mailbox. 3588 3589 The full list of options, supported by 'from' follows: 3590 3591'-c' 3592'--count' 3593 Prints only a count of messages in the mailbox and exit. 3594 3595'-d' 3596'--debug' 3597 Prints additional debugging output. 3598 3599'-s STRING' 3600'--sender=STRING' 3601 Prints only mail with 'From:' header containing the supplied 3602 string. 3603 3604'-f URL' 3605'--file=URL' 3606 Examine mailbox from the given URL. 3607 3608 3609File: mailutils.info, Node: mail, Next: messages, Prev: frm and from, Up: Programs 3610 36113.5 'mail' -- Send and Receive Mail 3612=================================== 3613 3614 ================================================================== 3615 *Editor's note:* 3616 The information in this node may be obsolete or otherwise 3617 inaccurate. This message will disappear, once this node revised. 3618 ================================================================== 3619 3620 'Mail' is an enhanced version of POSIX 'mailx' program. The program 3621operates in two modes: "read" and "send". 3622 3623 'Mail' enters "send" mode when at least one email address was 3624specified in its command line. In this mode the program waits until 3625user finishes composing the message, then attempts to send it to the 3626specified addresses and exits. *Note Composing Mail::, for a detailed 3627description of this behavior. 3628 3629 If the command line contained no email addresses, 'mail' switches to 3630reading mode. In this mode it allows the user to read and manipulate 3631the contents of the user system mailbox. Use the '--file' ('-f') option 3632to specify another mailbox name. For more detail, see *note Reading 3633Mail::. 3634 3635 In addition to the Mailutils configuration file, 'mail' reads the 3636traditional 'mailrc'-style configuration files. *Note Mail 3637Configuration Files::, for a detailed description of their format. 3638 3639* Menu: 3640 3641* Invoking Mail:: Command Line Options. 3642* Reading Mail:: Reading Mail. 3643* Saving and Recording:: Where Mail Messages are Stored. 3644* Composing Mail:: Composing Mail. 3645* MIME:: How to Attach Files. 3646* Scripting:: Scripting. 3647* Mail Variables:: How to Alter the Behavior of 'mail'. 3648* Mail Configuration Files:: Personal and System-wide Configuration Files. 3649 3650 3651File: mailutils.info, Node: Invoking Mail, Next: Reading Mail, Up: mail 3652 36533.5.1 Invoking 'mail' 3654--------------------- 3655 3656General usage of 'mail' program is: 3657 3658 mail [OPTION...] [ADDRESS...] 3659 3660If [ADDRESS...] part is present, 'mail' switches to mail sending mode, 3661otherwise it operates in mail reading mode. 3662 3663 'Mail' understands the following command line options: 3664 3665'-A FILE' 3666'--attach=FILE' 3667 Attach FILE to the composed message. The encoding, content type, 3668 and content description are controlled by the '--encoding', 3669 '--content-type', and '--content-name' options, correspondingly. 3670 3671 The option '--attach=-' instructs 'mail' to read the file to be 3672 attached from the standard input. Interactive shell is disabled in 3673 this case. 3674 3675'--attach-fd=FD' 3676 Read attachment body from the file descriptor FD. The descriptor 3677 must be open for reading. This option is useful when calling 3678 'mail' from another program. 3679 3680 See the options '--encoding', '--content-type', '--content-name', 3681 and '--content-filename'. 3682 3683'-a HEADER:VALUE' 3684'--append=HEADER:VALUE' 3685 Append the given header to the composed message. 3686 3687'--content-type=TYPE' 3688 This options sets the content type to be used by all subsequent 3689 '--attach' options. 3690 3691'--content-filename=NAME' 3692 Set the 'filename' parameter in the 'Content-Disposition' header 3693 for the next '--attach-fd' option. 3694 3695'--content-name=TEXT' 3696 Set the 'name' parameter (description) in the 'Content-Type' header 3697 for the next '--attach' or '--attach-fd' option. 3698 3699'-E COMMAND' 3700'--exec=COMMAND' 3701 Execute COMMAND before opening the mailbox. Any number of '--exec' 3702 options can be given. The commands will be executed after sourcing 3703 configuration files (*note Mail Configuration Files::), but before 3704 opening the mailbox. 3705 3706'-e' 3707'--exist' 3708 Return true if the mailbox contains some messages. Return false 3709 otherwise. 3710 3711 This is useful for writing shell scripts. 3712 3713'--encoding=ENC' 3714 Sets content transfer encoding for use by the subsequent '--attach' 3715 options. 3716 3717'-F' 3718'--byname' 3719 Record outgoing messages in a file named after the first recipient. 3720 The name is the login-name portion of the address found first on 3721 the 'To:' line in the mail header. 3722 3723'-f' 3724'--file' 3725 Operate on the mailbox given by the first non-optional command line 3726 argument. If there is no such argument, read messages from the 3727 user's 'mbox' file. *Note Reading Mail::, for more details about 3728 using this option. 3729 3730'-H' 3731'--headers' 3732 Print header summary to stdout and exit. 3733 3734'-i' 3735'--ignore' 3736 Ignore interrupts when composing the message. 3737 3738'-M' 3739'--mime' 3740'--no-mime' 3741 The '--mime' option instructs 'mail' to compose MIME messages. It 3742 is equivalent for '-E 'set mime'', except that it is processed 3743 after all other options. The '--no-mime' disables the MIME compose 3744 mode, and is a shortcut for '-E 'set nomime'', 3745 3746'-N' 3747'--nosum' 3748 Do not display initial header summary. 3749 3750'-n' 3751'--norc' 3752 Do not read the system-wide mailrc file. *Note Mail Configuration 3753 Files::. 3754 3755'-p' 3756'--print' 3757'--read' 3758 Print all mail to standard output. It is equivalent to issuing 3759 following commands after starting 'mail -N': 3760 print * 3761 quit 3762 except that 'mail --print' does not change status of the messages. 3763 3764'-q' 3765'--quit' 3766 Cause interrupts to terminate program. 3767 3768'-r ADDRESS' 3769'--return-address=ADDRESS' 3770 Sets the return email address for outgoing mail. *Note 3771 return-address::. 3772 3773'--skip-empty-attachments' 3774'--no-skip-empty-attachments' 3775 Don't create attachments that would have zero-size body. This 3776 option affects all attachments created by '--attach' and 3777 '--attach-fd' options appearing after it in the command line, as 3778 well as the body of the original message. 3779 3780 To cancel its effect, use the '--no-skip-empty-attachments' option. 3781 3782'-s SUBJ' 3783'--subject=SUBJ' 3784 Send a message with a Subject of SUBJ. Valid only in sending mode. 3785 3786'-t' 3787'--to' 3788 Read recipients from the message header. Ignore addresses listed 3789 in the command line. 3790 3791'-u USER' 3792'--user=USER' 3793 Operate on USER's mailbox. This is equivalent to: 3794 3795 mail -f/SPOOL_PATH/USER 3796 3797 with SPOOL_PATH being the full path to your mailspool directory 3798 ('/var/spool/mail' or '/var/mail' on most systems). 3799 3800 The program also understands the common mailutils options (*note 3801Common Options::. 3802 3803 3804File: mailutils.info, Node: Reading Mail, Next: Saving and Recording, Prev: Invoking Mail, Up: mail 3805 38063.5.2 Reading Mail 3807------------------ 3808 3809The 'mail' utility operates on three kinds of mailboxes. The "user 3810system mailbox" is the mailbox where the incoming mail for the user is 3811stored. Its location is system-dependent and is determined using the 3812common mailutils rules (*note mailbox statement::). The "personal 3813mailbox" (or "mbox", for short) is the default location for saving 3814messages that have been read. By default it is '$HOME/mbox' or whatever 3815file specified by the 'MBOX' environment variable. Any other mailboxes 3816are called "secondary mailboxes". 3817 3818 When called without arguments, 'mail' opens the system mailbox for 3819the invoking user. The '--file' ('-f') used without arguments instructs 3820'mail' to operate on the personal mailbox instead. When this option and 3821a single command line argument are used together, 'mail' treats the 3822argument as the pathname of the secondary mailbox to operate upon. 3823 3824 Notice that this argument is not an argument to the '--file' ('-f') 3825option itself, but rather the first non-optional argument on the command 3826line. This means that any number of additional options are allowed 3827between the '--file' option and the mailbox file name. For example, the 3828following three invocations are equivalent: 3829 3830 $ mail -fin mymbox 3831 $ mail -f mymbox -in 3832 $ mail --file -in mymbox 3833 $ mail --file -i mymbox -n 3834 3835 Additionally, for conformance to the GNU standards, the following 3836form is also accepted: 3837 3838 $ mail --file=mymbox -i -n 3839 3840 The '--user' ('-u') option allows the system administrator to assume 3841another user identity for operating on this user's mailboxes. 3842Obviously, it is available only to system administrators. For example: 3843 3844 mail --user=tom 3845 3846reads mail from the system mailbox of the user 'tom', and 3847 3848 mail --user=tom --file 3849 3850reads mail from the personal mailbox of this user. 3851 3852 Unless you have started mail with '--norc' command line option, it 3853will read the contents of the system-wide configuration file. Then it 3854will read the contents of user configuration file, if it exists. For 3855detailed description of these files, see *note Mail Configuration 3856Files::. After this initial setup, 'mail' displays the first page of 3857header lines (unless the '-N' option has been given), followed by a 3858prompt, indicating that it is waiting for regular commands. Upon 3859receiving a command, 'mail' parses and executes it, displays the result 3860on the screen, prints the prompt and waits for the next command. This 3861process is continued until 'mail' receives any of the commands 'quit', 3862'exit' or the end-of-file character (ASCII 4, or 'C-D'). 3863 3864 Each message in the mailbox has a state that affects how it is 3865retained or deleted upon closing the mailbox when terminating the 3866program (*note the quit command::) or when switching to another mailbox 3867(*note the file command::). The state is reflected in the header 3868listing and can be changed during the session. The states are: 3869 3870"new" 3871 The message is present in the system mailbox and has not been read 3872 by the user or moved to any other state. When 'mail' terminates, 3873 messages in this state are retained in the system mailbox. If the 3874 mailbox is closed, such messages are moved to the 'unread' state. 3875 3876"unread" 3877 The message has been present in the system mailbox for more than 3878 one invocation of 'mail' and has not been read by the user or moved 3879 to any other state. When 'mail' terminates, messages in this state 3880 are retained in the system mailbox. 3881 3882"read" 3883 The message has been read by the user, i.e. processed by one of 3884 the following commands: 'copy', 'mbox', 'next', 'pipe', 'prev', 3885 'print', 'Print', 'struct', 'top', 'type', 'Type', 'undelete', or 3886 any of the following escapes (in message compose mode): '~f', '~m', 3887 '~F', '~M'. 3888 3889 When 'mail' terminates, messages in this state are handled 3890 depending on the mailbox they are in. 3891 3892 If 'mail' was operating on the user system mailbox, all messages in 3893 state 'read' are preserved. The location where they are preserved 3894 is determined by the 'hold' variable (*note Mail Variables::). If 3895 it is not set (the default), the messages are moved to the user's 3896 'mbox'. If 'hold' is set, the messages are held in the system 3897 mailbox instead. 3898 3899 The 'read' messages in any other mailbox will be retained in their 3900 current location. 3901 3902"deleted" 3903 The message has been processed by one of the following commands: 3904 'delete', 'dp', 'dt'. Messages in this state are ignored by any 3905 command, excepting 'undelete', which changes their state back to 3906 'read'. When closing the mailbox, deleted messages are permanently 3907 removed from the mailbox. 3908 3909"preserved" 3910 The message has been processed by the 'preserve' ('hold') command. 3911 When closing the mailbox, such messages are retained in the 3912 mailbox. 3913 3914"saved" 3915 The message has been processed by one of the following commands: 3916 'save', 'write'. When 'mail' terminates, messages in this state 3917 are handled depending on the mailbox they are in. 3918 3919 If 'mail' was operating on the user system mailbox, the default 3920 behavior for 'saved' messages is to remove them from the system 3921 mailbox. If, however, the 'keepsave' variable is set, they are 3922 preserved using the same rules as for 'read' messages (see above). 3923 3924 Saved messages in non-system mailboxes are retained in their 3925 current location. 3926 3927 Unless the mailbox is empty, exactly one of its messages will be 3928marked as "current message". Upon startup, current message is set to 3929the first new message, if there is any, or the first unread message if 3930there is any, or to the first message in the mailbox. In the header 3931listing, current message is marked with the '>' sign at the beginning of 3932the line. Current message is changed by any of the following commands: 3933'dp', 'prev', 'next'. 3934 3935* Menu: 3936 3937* Command Syntax:: Syntax of mail internal commands. 3938* Quitting the Program:: 3939* Obtaining Online Help:: 3940* Moving Within a Mailbox:: 3941* Changing mailbox/directory:: 3942* Controlling Header Display:: 3943* Displaying Information:: 3944* Displaying Messages:: 3945* Marking Messages:: 3946* Disposing of Messages:: 3947* Saving Messages:: 3948* Editing Messages:: 3949* Aliasing:: 3950* Replying:: 3951* Controlling Sender Fields:: 3952* Incorporating New Mail:: 3953* Shell Escapes:: 3954 3955 3956File: mailutils.info, Node: Command Syntax, Next: Quitting the Program, Up: Reading Mail 3957 39583.5.2.1 Syntax of mail internal commands 3959........................................ 3960 3961Commands have the following syntax: 3962 3963 COMMAND [MSGLIST] [ARGUMENT ...] 3964 3965 A command is terminated by a newline character. Empty command (i.e. 3966a newline character alone) is equivalent to 'next' (*note next: Moving 3967Within a Mailbox.). 3968 3969 In the syntax above, COMMAND is the command verb. Each command has 3970long and short (abbreviated) form. Each of them can be used to invoke 3971the command. 3972 3973 Many mail commands take a list of messages (MSGLIST) to operate upon, 3974which defaults to current message. 3975 3976 The list of messages in its simplest form is one of: 3977 3978. Selects current message. It is equivalent to 3979 empty message list. 3980* Selects all messages in the mailbox. 3981^ Selects first non-deleted message. 3982$ Selects last non-deleted message. 3983 3984 In its complex form, the "message list" is a comma or 3985whitespace-separated list of "message specifiers". A "message 3986specifier" is one of 3987 3988N 3989 (integer number) This specifier addresses the message with the 3990 given ordinal number in the mailbox. 3991 3992N-M 3993 All messages with ordinal numbers between N and M, inclusive. 3994 3995:T 3996 All messages of type T, where T can be any of: 3997 3998 'd' 3999 Deleted messages. 4000 'n' 4001 New messages. 4002 'o' 4003 Old messages (any message not in state 'read' or 'new'). 4004 'r' 4005 Messages in state 'read'. 4006 'u' 4007 Messages in state 'unread'. 4008 't' 4009 Selects all tagged messages. 4010 'T' 4011 Selects all untagged messages. 4012 's' 4013 Selects all messages in state 'saved'. 4014 4015[HEADER:]/STRING[/] 4016 Header match. 4017 4018 Selects all messages that contain header field HEADER matching 4019 given STRING. If the variable 'regex' is set, the STRING is 4020 assumed to be a POSIX regexp. (All comparison is case-insensitive 4021 in either case). 4022 4023 If HEADER: part is omitted, it is assumed to be 'Subject:'. 4024 4025:/STRING[/] 4026 Message body match. 4027 4028 Selects all messages with body matching the STRING. The matching 4029 rules are the same as described above. 4030 4031 A "message specifier" can be followed by "message part specifier", 4032enclosed in a pair of brackets. A "message part specifier" controls 4033which part of a message should be operated upon. It is meaningful only 4034for multipart messages. A "message part specifier" is a comma or 4035whitespace-separated list of part numbers or ranges. Each part number 4036can in turn be "message part specifier", thus allowing for operating 4037upon multiply-encoded messages. 4038 4039 The following are the examples of valid message lists: 4040 40413 4042 Third message. 4043 40441-4 10 4045 Messages from 1 through 4 and message 10. 4046 40474-* 4048 All messages starting from message 4. 4049 4050/watch 4051 All messages with the word 'watch' in the subject. 4052 4053/watch :/watch 4054 All messages with the word 'watch' in the subject or body. 4055 4056/watch :/watch $ 4057 Same as above plus the last message in the mailbox. 4058 405910[2] 4060 Part 2 of the multipart message 10. 4061 4062 4063File: mailutils.info, Node: Quitting the Program, Next: Obtaining Online Help, Prev: Command Syntax, Up: Reading Mail 4064 40653.5.2.2 Quitting the Program 4066............................ 4067 4068Following commands quit the program: 4069 4070 -- Mail command: quit 4071 Terminates the session. The messages, marked with 'delete' are 4072 removed. The messages in state 'read' and 'saved' are processed 4073 depending on the mailbox they are in. 4074 4075 If 'mail' was operating on the user system mailbox, all messages in 4076 state 'read' are preserved. The location where they are preserved 4077 is determined by the 'hold' variable. If it is not set (the 4078 default), the messages are moved to the user's 'mbox'. If 'hold' 4079 is set, the messages are held in the system mailbox instead. 4080 4081 The default behavior for 'saved' messages is to remove them from 4082 the system mailbox. If, however, the 'keepsave' variable is set, 4083 they are preserved using the same rules as for 'read' messages. 4084 4085 For non-system mailboxes, both 'read' and 'saved' messages are 4086 retained in their current location. 4087 4088 The same rules are followed when the mailbox is switched using the 4089 'file' command. 4090 4091 The program exits to the shell, unless saving the mailbox fails, in 4092 which case user can escape with the exit command. 4093 4094 -- Mail command: exit 4095 -- Mail command: ex 4096 -- Mail command: xit 4097 Program exits to the shell without modifying the mailbox it 4098 operates upon. 4099 4100 Typing EOF ('C-D') alone is equivalent to 'quit'. 4101 4102 4103File: mailutils.info, Node: Obtaining Online Help, Next: Moving Within a Mailbox, Prev: Quitting the Program, Up: Reading Mail 4104 41053.5.2.3 Obtaining Online Help 4106............................. 4107 4108Following commands can be used during the session to request online 4109help: 4110 4111 -- Mail command: help [COMMAND] 4112 -- Mail command: hel [COMMAND] 4113 -- Mail command: ? [COMMAND] 4114 Display detailed command synopsis. If no COMMAND is given, help 4115 for all available commands is displayed. 4116 4117 -- Mail command: list 4118 -- Mail command: * 4119 Print a list of available commands. 4120 4121 -- Mail command: version 4122 -- Mail command: ve 4123 Display program version. 4124 4125 -- Mail command: warranty 4126 -- Mail command: wa 4127 Display program warranty statement. 4128 4129 4130File: mailutils.info, Node: Moving Within a Mailbox, Next: Changing mailbox/directory, Prev: Obtaining Online Help, Up: Reading Mail 4131 41323.5.2.4 Moving Within a Mailbox 4133............................... 4134 4135 -- Mail command: ^ 4136 Move to the first undeleted message. 4137 4138 -- Mail command: $ 4139 Move to the last undeleted message. 4140 4141 -- Mail command: next 4142 -- Mail command: n 4143 Move to the next message. 4144 4145 -- Mail command: previous 4146 -- Mail command: prev 4147 Move to the previous message. 4148 4149 4150File: mailutils.info, Node: Changing mailbox/directory, Next: Controlling Header Display, Prev: Moving Within a Mailbox, Up: Reading Mail 4151 41523.5.2.5 Changing Mailbox/Directory 4153.................................. 4154 4155 -- Mail command: cd [DIR] 4156 -- Mail command: chdir [DIR] 4157 -- Mail command: ch [DIR] 4158 Change to the specified directory. If DIR is omitted, '$HOME' is 4159 assumed. 4160 4161 -- Mail command: file [MAILBOX] 4162 -- Mail command: fi [MAILBOX] 4163 -- Mail command: folder [MAILBOX] 4164 -- Mail command: fold [MAILBOX] 4165 When used without argument, prints the information about the 4166 current mailbox: the mailbox file name (or URL), total number of 4167 messages and the number of unread messages, e.g.: 4168 4169 ? fold 4170 "/var/spool/mail/gray": 23 messages 22 unread 4171 4172 Otherwise, closes the current mailbox and opens the mailbox named 4173 by the MAILBOX argument. When closing the current mailbox, its 4174 messages are processed according to their state (*note mail message 4175 states::). 4176 4177 The MAILBOX argument can be the name of the existing file, a 4178 mailbox URL (*note Mailbox::), or any of the following shortcuts: 4179 4180 % 4181 The system mailbox for the invoking user. 4182 4183 %USER 4184 The system mailbox for USER. 4185 4186 # 4187 The previous file. 4188 4189 & 4190 The user's personal mailbox. 4191 4192 @ 4193 Secondary mailbox, given using the '-f' command line option. 4194 4195 +FILE 4196 The named FILE in the folder directory. *Note folder 4197 variable::. 4198 4199 4200File: mailutils.info, Node: Controlling Header Display, Next: Displaying Information, Prev: Changing mailbox/directory, Up: Reading Mail 4201 42023.5.2.6 Controlling Header Display 4203.................................. 4204 4205To control which headers in the message should be displayed, 'mail' 4206keeps two lists: a "retained" header list and an "ignored" header list. 4207If "retained" header list is not empty, only the header fields listed in 4208it are displayed when printing the message. Otherwise, if "ignored" 4209header list is not empty, only the headers _not listed_ in this list are 4210displayed. The uppercase variants of message-displaying commands can be 4211used to print all the headers. 4212 4213 The following commands modify and display the contents of both lists. 4214 4215 -- Mail command: discard [HEADER-FIELD-LIST] 4216 -- Mail command: di [HEADER-FIELD-LIST] 4217 -- Mail command: ignore [HEADER-FIELD-LIST] 4218 -- Mail command: ig [HEADER-FIELD-LIST] 4219 Add HEADER-FIELD-LIST to the ignored list. When used without 4220 arguments, this command prints the contents of ignored list. 4221 4222 -- Mail command: retain [HEADER-FIELD-LIST] 4223 -- Mail command: ret [HEADER-FIELD-LIST] 4224 Add HEADER-FIELD-LIST to the retained list. When used without 4225 arguments, this command prints the contents of retained list. 4226 4227 4228File: mailutils.info, Node: Displaying Information, Next: Displaying Messages, Prev: Controlling Header Display, Up: Reading Mail 4229 42303.5.2.7 Displaying Information 4231.............................. 4232 4233 -- Mail command: = 4234 Displays the current message number. 4235 4236 -- Mail command: headers [MSGLIST] 4237 -- Mail command: h [MSGLIST] 4238 Lists the current pageful of headers. 4239 4240 -- Mail command: from [MSGLIST] 4241 -- Mail command: f [MSGLIST] 4242 Lists the contents of 'From' headers for a given set of messages. 4243 4244 -- Mail command: z [ARG] 4245 Presents message headers in pagefuls as described for 'headers' 4246 command. When ARG is '.', it is generally equivalent to 'headers'. 4247 When ARG is omitted or is '+', the next pageful of headers is 4248 displayed. If ARG is '-', the previous pageful of headers is 4249 displayed. The latter two forms of 'z' command may also take a 4250 numerical argument meaning the number of pages to skip before 4251 displaying the headers. For example: 4252 4253 ? z +2 4254 will skip two pages of messages before displaying the header 4255 summary. 4256 4257 -- Mail command: size [MSGLIST] 4258 -- Mail command: si [MSGLIST] 4259 Lists the message number and message size in bytes for each message 4260 in MSGLIST. 4261 4262 -- Mail command: folders 4263 Displays the value of 'folder' variable. 4264 4265 -- Mail command: summary 4266 -- Mail command: su 4267 Displays current mailbox summary. E.g.: 4268 4269 ? summary 4270 "/var/spool/mail/gray": 23 messages 22 unread 4271 4272 4273File: mailutils.info, Node: Displaying Messages, Next: Marking Messages, Prev: Displaying Information, Up: Reading Mail 4274 42753.5.2.8 Displaying Messages 4276........................... 4277 4278 -- Mail command: print [MSGLIST] 4279 -- Mail command: p [MSGLIST] 4280 -- Mail command: type [MSGLIST] 4281 -- Mail command: t [MSGLIST] 4282 Prints out the messages from MSGLIST. The variable 'crt' 4283 determines the minimum number of lines the body of the message must 4284 contain in order to be piped through pager command specified by 4285 environment variable 'PAGER'. If 'crt' is set to a numeric value, 4286 this value is taken as the minimum number of lines. Otherwise, if 4287 'crt' is set without a value then the height of the terminal screen 4288 is used to compute the threshold. The number of lines on screen is 4289 controlled by 'screen' variable. 4290 4291 -- Mail command: Print [MSGLIST] 4292 -- Mail command: P [MSGLIST] 4293 -- Mail command: Type [MSGLIST] 4294 -- Mail command: T [MSGLIST] 4295 Like print but also prints out ignored header fields. 4296 4297 -- Mail command: decode [MSGLIST] 4298 -- Mail command: dec [MSGLIST] 4299 Print a multipart message. The 'decode' command decodes and prints 4300 out specified message parts. E.g. 4301 4302 ? decode 15[2] 4303 +--------------------------------------- 4304 | Message=15[2] 4305 | Type=message/delivery-status 4306 | encoding=7bit 4307 +--------------------------------------- 4308 Content-Type: message/delivery-status 4309 ... 4310 4311 -- Mail command: top [MSGLIST] 4312 -- Mail command: to [MSGLIST] 4313 Prints the top few lines of each message in MSGLIST. The number of 4314 lines printed is controlled by the variable 'toplines' and defaults 4315 to five. 4316 4317 -- Mail command: pipe [[MSGLIST] SHELL-COMMAND] 4318 -- Mail command: | [[MSGLIST] SHELL-COMMAND] 4319 Pipe the contents of specified messages through SHELL-COMMAND. 4320 Without arguments, pipe the current message through the command 4321 given by the 'cmd' variable (which must be set). 4322 4323 -- Mail command: struct [MSGLIST] 4324 Prints the MIME structure of each message from MSGLIST. Empty 4325 MSGLIST means current message. 4326 4327 Example: 4328 4329 ? struct 2 4330 2 multipart/mixed 14k 4331 2[1] text/plain 296 4332 2[2] application/octet-stream 5k 4333 2[3] text/x-diff 31k 4334 4335 4336File: mailutils.info, Node: Marking Messages, Next: Disposing of Messages, Prev: Displaying Messages, Up: Reading Mail 4337 43383.5.2.9 Marking Messages 4339........................ 4340 4341 -- Mail command: tag [MSGLIST] 4342 -- Mail command: ta [MSGLIST] 4343 Tag messages. The tagged messages can be referred to in message 4344 list using ':t' notation. 4345 4346 -- Mail command: untag [MSGLIST] 4347 -- Mail command: unt [MSGLIST] 4348 Clear tags from specified messages. To untag all messages tagged 4349 so far type 4350 ? untag :t 4351 4352 -- Mail command: hold [MSGLIST] 4353 -- Mail command: ho [MSGLIST] 4354 -- Mail command: preserve [MSGLIST] 4355 -- Mail command: pre [MSGLIST] 4356 Marks each message to be held in user's system mailbox. This 4357 command does not override the effect of 'delete' command. 4358 4359 4360File: mailutils.info, Node: Disposing of Messages, Next: Saving Messages, Prev: Marking Messages, Up: Reading Mail 4361 43623.5.2.10 Disposing of Messages 4363.............................. 4364 4365 -- Mail command: delete [MSGLIST] 4366 -- Mail command: d [MSGLIST] 4367 Mark messages as deleted. Upon exiting with 'quit' command these 4368 messages will be deleted from the mailbox. Until the end of 4369 current session the deleted messages can be referred to in message 4370 lists using :d notation. 4371 4372 -- Mail command: undelete [MSGLIST] 4373 -- Mail command: u [MSGLIST] 4374 Clear delete mark from the specified messages. 4375 4376 -- Mail command: dp [MSGLIST] 4377 -- Mail command: dt [MSGLIST] 4378 Deletes the current message and prints the next message. If 4379 MSGLIST is specified, deletes all messages from the list and prints 4380 the message immediately following last deleted one. 4381 4382 4383File: mailutils.info, Node: Saving Messages, Next: Editing Messages, Prev: Disposing of Messages, Up: Reading Mail 4384 43853.5.2.11 Saving Messages 4386........................ 4387 4388 -- Mail command: save [[MSGLIST] MAILBOX] 4389 -- Mail command: s [[MSGLIST] MAILBOX] 4390 Takes a message list and a file or mailbox name and appends each 4391 message in turn to that file or mailbox. The syntax for MAILBOX is 4392 the same as for the 'file' command (*note Mailbox shortcuts::). 4393 The name of the mailbox and number of lines and characters appended 4394 to it is echoed on the terminal. When writing to file, the numbers 4395 represent exact number of lines and characters appended to the 4396 file. When FILE specifies a mailbox, these numbers may differ by 4397 the amount of lines/characters needed to represent message envelope 4398 for that specific mailbox type. 4399 4400 Each saved message is marked for deletion as if with 'delete' 4401 command, unless the variable 'keepsave' is set. 4402 4403 -- Mail command: Save [MSGLIST] 4404 -- Mail command: S [MSGLIST] 4405 Like 'save', but the file to append messages to is named after the 4406 sender of the first message in MSGLIST. The file name is selected 4407 as described in *note saving mail by name::. For example: 4408 4409 ? from 14 15 4410 U 14 smith@noldor.org Fri Jun 30 18:11 14/358 The Save c 4411 U 15 gray@noldor.org Fri Jun 30 18:30 8/245 Re: The Sa 4412 ? Save 14 15 4413 "smith" 22/603 4414 4415 i.e., 22 lines (603 characters) have been appended to the file 4416 "smith". If the file does not exist, it is created. 4417 4418 -- Mail command: write [[MSGLIST] FILE] 4419 -- Mail command: w [[MSGLIST] FILE] 4420 Similar to 'save', except that only message body (without the 4421 header) is saved. 4422 4423 -- Mail command: Write [MSGLIST] 4424 -- Mail command: W [MSGLIST] 4425 Similar to 'Save', except that only message body (without the 4426 header) is saved. 4427 4428 -- Mail command: mbox [MSGLIST] 4429 -- Mail command: mb [MSGLIST] 4430 Mark list of messages to be saved in the user's personal mailbox 4431 (*note personal mailbox: Reading Mail.) upon exiting via 'quit' 4432 command. This is the default action for all read messages, unless 4433 you have variable 'hold' set. 4434 4435 -- Mail command: touch [MSGLIST] 4436 -- Mail command: tou [MSGLIST] 4437 Touch the specified messages. If any message in MSGLIST is not 4438 specifically deleted nor saved in a file, upon normal termination 4439 it will be acted upon as if it had been read (*note mail message 4440 states::). 4441 4442 -- Mail command: copy [[MSGLIST] FILE] 4443 -- Mail command: c [[MSGLIST] FILE] 4444 Similar to 'save', except that saved messages are not marked as 4445 saved. 4446 4447 -- Mail command: Copy [MSGLIST] 4448 -- Mail command: C [MSGLIST] 4449 Similar to 'Save', except that saved messages are not marked as 4450 saved. 4451 4452 4453File: mailutils.info, Node: Editing Messages, Next: Aliasing, Prev: Saving Messages, Up: Reading Mail 4454 44553.5.2.12 Editing Messages 4456......................... 4457 4458These command allow to edit messages in a mailbox. _Please note_, that 4459modified messages currently do not replace original ones. i.e. you 4460have to save them explicitly using your editor's 'save' command if you 4461do not want the effects of your editing to be lost. 4462 4463 -- Mail command: edit [MSGLIST] 4464 -- Mail command: e [MSGLIST] 4465 Edits each message in MSGLIST with the editor, specified in 4466 'EDITOR' environment variable. 4467 4468 -- Mail command: visual [MSGLIST] 4469 -- Mail command: v [MSGLIST] 4470 Edits each message in MSGLIST with the editor, specified in 4471 'VISUAL' environment variable. 4472 4473 4474File: mailutils.info, Node: Aliasing, Next: Replying, Prev: Editing Messages, Up: Reading Mail 4475 44763.5.2.13 Aliasing 4477................. 4478 4479 -- Mail command: alias [alias [ADDRESS...]] 4480 -- Mail command: a [alias [ADDRESS...]] 4481 -- Mail command: group [alias [ADDRESS...]] 4482 -- Mail command: g [alias [ADDRESS...]] 4483 With no arguments, prints out all currently-defined aliases. With 4484 one argument, prints out that alias. With more than one argument, 4485 creates a new alias or changes an old one. 4486 4487 -- Mail command: unalias [ALIAS...] 4488 -- Mail command: una [ALIAS...] 4489 Takes a list of names defined by alias commands and discards the 4490 remembered groups of users. The alias names no longer have any 4491 significance. 4492 4493 -- Mail command: alternates NAME... 4494 -- Mail command: alt NAME... 4495 The alternates command is useful if you have accounts on several 4496 machines. It can be used to inform mail that the listed addresses 4497 are really you. When you reply to messages, mail will not send a 4498 copy of the message to any of the addresses listed on the 4499 alternates list. If the alternates command is given with no 4500 argument, the current set of alternate names is displayed. 4501 4502 4503File: mailutils.info, Node: Replying, Next: Controlling Sender Fields, Prev: Aliasing, Up: Reading Mail 4504 45053.5.2.14 Replying 4506................. 4507 4508 -- Mail command: mail [ADDRESS...] 4509 -- Mail command: m [ADDRESS...] 4510 Switches to compose mode. After composing the message, sends it to 4511 the specified addresses. 4512 4513 If the 'record' variable is set, the composed message will be saved 4514 in the folder named by it. 4515 4516 -- Mail command: Mail [ADDRESS...] 4517 -- Mail command: M [ADDRESS...] 4518 Same as 'mail', but the name of the file to save the composed 4519 message is derived from its first recipient as outlined below. 4520 4521 If the 'outfolder' variable is set, and has a string value S, the 4522 filename is 'S/RECIPIENT'. If it is a boolean, then the 'folder' 4523 variable is consulted. If it is set, then the filename is 4524 'FOLDER/RECIPIENT'. Otherwise, the message will not be saved. 4525 4526 The value RECIPIENT is derived from the email of the first 4527 recipient of the message. By default it is a local part of that 4528 email. If the 'outfilename' variable has the value 'domain', the 4529 domain part of the email is used. If this variable is set to 4530 'email', then entire email address is used. 4531 4532 *Note saving mail by name::, for a detailed discussion. 4533 4534 -- Mail command: reply [MESSAGE] 4535 -- Mail command: respond [MESSAGE] 4536 -- Mail command: r [MESSAGE] 4537 Mail a reply message to all recipients included in the header of 4538 the MESSAGE. The subject header is formed by concatenating the 4539 value of the 'replyprefix' variable and the subject from the 4540 message. If 'record' is set to a filename, the response is saved 4541 at the end of that file. 4542 4543 -- Mail command: Reply [MSGLIST] 4544 -- Mail command: Respond [MSGLIST] 4545 -- Mail command: R [MSGLIST] 4546 Mail a reply message to the sender of each message in the MSGLIST. 4547 The subject header is formed by concatenating the value of the 4548 'replyprefix' variable and the subject header of from the first 4549 message in MSGLIST. If 'record' is set to a filename, the response 4550 is saved at the end of that file. 4551 4552 Notice, that setting mail variable 'flipr' (*note Mail Variables::) 4553 swaps the meanings of the two above commands 4554 4555 -- Mail command: followup [MESSAGE] 4556 -- Mail command: fo [MESSAGE] 4557 Respond to MESSAGE, recording the response in a file whose name is 4558 derived from the author of the message. *Note saving mail by 4559 name::, for a discussion of how the file name is selected. 4560 4561 -- Mail command: Followup [MSGLIST] 4562 -- Mail command: F [MSGLIST] 4563 Same as 'Reply', but the response is saved in a file whose name is 4564 derived from the author of the first message. *Note saving mail by 4565 name::, for a detailed discussion of how the file name is selected. 4566 4567 By default, 'mail' will preserve personal email parts when forming 4568lists of recipient addresses. If this is not desired, unset the 4569'fullnames' variable (*note fullnames::). 4570 4571 To determine the sender of the message 'mail' uses the list of sender 4572fields (*note Controlling Sender Fields::). The first field from this 4573list is looked up in message headers. If it is found and contains a 4574valid email address, this address is used as the sender address. If 4575not, the second field is searched and so on. This process continues 4576until a field is found in the headers, or the sender field list is 4577exhausted, whichever happens first. 4578 4579 If the previous step did not determine the sender address, the 4580address from SMTP envelope is used. 4581 4582 Let's illustrate this. Suppose your mailbox contains the following: 4583 4584 U 1 block@helsingor.org Fri Jun 30 18:30 8/245 Re: The Sa 4585 ? Print 1 4586 From: Antonius Block <block@helsingor.org> 4587 To: Smeden Plog <plog@helsingor.org> 4588 Date: Tue, 27 Apr 2004 13:23:41 +0300 4589 Reply-To: <root@helsingor.org> 4590 Subject: News 4591 4592 Hi 4593 4594Now, you issue the following commands: 4595 4596 ? sender mail-followup-to reply-to from 4597 ? reply 4598 To: <root@helsingor.org> 4599 Subject: Re: News 4600 4601 4602As you see, the value of 'Reply-To' field was taken as the sender 4603address. 4604 4605 Now, let's try the following command sequence: 4606 4607 # Clear the sender list 4608 ? nosender 4609 # Set new sender list 4610 ? sender From 4611 4612Now, the 'From' address will be taken: 4613 4614 ? reply 4615 To: Antonius Block <block@helsingor.org> 4616 Subject: Re: News 4617 4618 4619 4620File: mailutils.info, Node: Controlling Sender Fields, Next: Incorporating New Mail, Prev: Replying, Up: Reading Mail 4621 46223.5.2.15 Controlling Sender Fields 4623.................................. 4624 4625When 'mail' needs to know the sender of a message, it looks it up in one 4626or more headers of that message. Such headers constitute a "sender 4627list". The first header from the list that is present in the message 4628and has a non-empty value is used. If none is found or if the sender 4629list is empty, the value of the message envelope is used. 4630 4631 The commands 'sender' and 'nosender' manipulate the sender list. 4632 4633 If the command 'sender' is used without arguments, it displays the 4634contents of the sender field list. If arguments are given, each 4635argument is appended to the sender field list. For example: 4636 4637 ? sender 4638 Sender address is obtained from the envelope 4639 ? sender mail-followup-to reply-to 4640 ? sender 4641 mail-followup-to 4642 reply-to 4643 ? sender from 4644 ? sender 4645 mail-followup-to 4646 reply-to 4647 from 4648 4649 Command 'nosender' is used to remove items from the sender field 4650list: 4651 4652 ? sender 4653 mail-followup-to 4654 reply-to 4655 from 4656 ? nosender reply-to 4657 ? sender 4658 mail-followup-to 4659 from 4660 4661 When used without arguments, this command clears the list: 4662 4663 ? nosender 4664 Sender address is obtained from the envelope 4665 4666 4667File: mailutils.info, Node: Incorporating New Mail, Next: Shell Escapes, Prev: Controlling Sender Fields, Up: Reading Mail 4668 46693.5.2.16 Incorporating New Mail 4670............................... 4671 4672The 'incorporate' ('inc') command incorporates newly arrived messages to 4673the displayed list of messages. This is done automatically before 4674returning to 'mail' command prompt if the variable 'autoinc' is set. 4675 4676 4677File: mailutils.info, Node: Shell Escapes, Prev: Incorporating New Mail, Up: Reading Mail 4678 46793.5.2.17 Shell Escapes 4680...................... 4681 4682To run arbitrary shell command from 'mail' command prompt, use 'shell' 4683('sh') command. If no arguments are specified, the command starts the 4684user login shell. Otherwise, it uses its first argument as a file name 4685to execute and all subsequent arguments are passed as positional 4686parameters to this command. The 'shell' command can also be spelled as 4687'!'. 4688 4689 4690File: mailutils.info, Node: Saving and Recording, Next: Composing Mail, Prev: Reading Mail, Up: mail 4691 46923.5.3 Saving and Recording 4693-------------------------- 4694 4695Several commands discussed in the previous section save messages in a 4696disk file. The name of that file is either obtained from the 'record' 4697variable ("recording mail") or is derived from the first recipient of 4698the message ("saving by name"). 4699 4700 The following commands record mails: 4701 4702 * 'mail' 4703 * 'reply' 4704 * 'Reply' 4705 4706 The following commands save mail by name: 4707 4708 * 'Copy' 4709 * 'Save' 4710 * 'Mail' 4711 * 'followup' 4712 * 'Followup' 4713 4714 Saving mail by name is controlled by three mail variables: 4715'outfolder', 'folder', and 'outfilename'. The first, 'outfolder', is a 4716boolean variable which, when set, enables saving mail by name. The 4717'folder' variable defines a directory where mail files are stored. Name 4718of file in that directory where the message will be saved is derived 4719from the message recipient(1). This process is controlled by the 4720'outfilename' variable: if its value is 'local', the file is named by 4721the local part of the email (this is the default). If it is 'domain', 4722the domain part is used instead. Finally, if it's value is 'email', the 4723entire email is used. 4724 4725 As a GNU extension, 'outfolder' can be a string variable. In that 4726case its value names the directory to use instead of 'folder'. 4727 4728 The 'mailx' variable, if set, disables GNU extensions. In this case, 4729'outfolder' is used as a boolean value, and file names are derived from 4730the local part of the email, ignoring the 'outfilename' value. 4731 4732 ---------- Footnotes ---------- 4733 4734 (1) In case of 'Copy' and 'Save', message sender is used instead 4735 4736 4737File: mailutils.info, Node: Composing Mail, Next: MIME, Prev: Saving and Recording, Up: mail 4738 47393.5.4 Composing Mail 4740-------------------- 4741 4742You can compose the message by simply typing the contents of it, line by 4743line. But usually this is not enough, you would need to edit your text, 4744to quote some messages, etc. 'Mail' provides these capabilities through 4745"compose escapes". The "compose escapes" are single-character commands, 4746preceded by special "escape character", which defaults to '~'. The 4747combination 'escape character + command' is recognized as a compose 4748escape only if it occurs at the beginning of a line and the standard 4749input is connected to a terminal. If the escape character must appear 4750at the beginning of a line, enter it twice. 4751 4752 The actual escape character may be changed by setting the value of 4753'escape' mail variable (*note Mail Variables::). 4754 4755* Menu: 4756 4757* Quitting Compose Mode:: 4758* Getting Help on Compose Escapes:: 4759* Editing the Message:: 4760* Modifying the Headers:: 4761* Enclosing Another Message:: 4762* Adding a File to the Message:: 4763* Attaching a File to the Message:: 4764* Printing And Saving the Message:: 4765* Signing the Message:: 4766* Printing Another Message:: 4767* Inserting Value of a Mail Variable:: 4768* Executing Other Mail Commands:: 4769* Executing Shell Commands:: 4770 4771 4772File: mailutils.info, Node: Quitting Compose Mode, Next: Getting Help on Compose Escapes, Up: Composing Mail 4773 47743.5.4.1 Quitting Compose Mode 4775............................. 4776 4777There are several commands allowing you to quit the compose mode. 4778 4779 Typing the end-of-file character ('C-D') on a line alone finishes 4780compose mode and sends the message to its destination. The 'C-D' 4781character looses its special meaning if 'ignoreeof' mail variable is 4782set. 4783 4784 If mail variable 'dot' is set, typing dot ('.') on a line alone 4785achieves the same effect as 'C-D' above. 4786 4787 Finally, using '~.' escape always quits compose mode and sends out 4788the composed message. 4789 4790 To abort composing of a message without sending it, type interrupt 4791character (by default, 'C-C') twice. This behavior is disabled when 4792mail variable 'ignore' is set. In this case, you can use '~x' escape to 4793achieve the same effect. 4794 4795 4796File: mailutils.info, Node: Getting Help on Compose Escapes, Next: Editing the Message, Prev: Quitting Compose Mode, Up: Composing Mail 4797 47983.5.4.2 Getting Help on Compose Escapes: ~? 4799........................................... 4800 4801The '~?' escape prints on screen a brief summary of the available 4802compose escapes. _Please note_, that '~h' escape prompts for changing 4803the header values, and does _not_ give help. 4804 4805 4806File: mailutils.info, Node: Editing the Message, Next: Modifying the Headers, Prev: Getting Help on Compose Escapes, Up: Composing Mail 4807 48083.5.4.3 Editing the Message: ~e and ~v 4809...................................... 4810 4811If you are not satisfied with the message as it is, you can edit it 4812using a text editor specified either by 'EDITOR' or by 'VISUAL' 4813environment variables. The '~e' uses the former, and '~v' uses the 4814latter. 4815 4816 By default both escapes allow you to edit only the body of the 4817message. However, if the 'editheaders' variable is set, 'mail' will 4818load into the editor the complete text of the message with headers 4819included, thus allowing you to change the headers as well. 4820 4821 4822File: mailutils.info, Node: Modifying the Headers, Next: Enclosing Another Message, Prev: Editing the Message, Up: Composing Mail 4823 48243.5.4.4 Modifying the Headers: ~h, ~t, ~c, ~b, ~s 4825................................................. 4826 4827To add new addresses to the list of message recipients, use '~t' 4828command, e.g.: 4829 4830 ~t name1@domain.net name2 4831 4832 To add addresses to 'Cc' or 'Bcc', use '~c' or '~b' escapes 4833respectively. 4834 4835 To change the 'Subject' header, use '~s' escape, e.g.: 4836 4837 ~s "Re: your message" 4838 4839 Finally, to edit all headers, type '~h' escape. This will present 4840you with the values of 'To', 'Cc', 'Bcc', and 'Subject' headers allowing 4841to edit them with normal text editing commands. 4842 4843 4844File: mailutils.info, Node: Enclosing Another Message, Next: Adding a File to the Message, Prev: Modifying the Headers, Up: Composing Mail 4845 48463.5.4.5 Enclosing Another Message: ~m and ~M 4847............................................ 4848 4849If you are sending mail from within mail command mode, you can enclose 4850the contents of any message sent to you by using '~m' or '~M' commands. 4851Typing '~m' alone will enclose the contents of the current message, 4852typing '~m 12' will enclose the contents of message #12 and so on. 4853 4854 The '~m' uses retained and ignored lists when enclosing headers, the 4855'~M' encloses all header fields. 4856 4857 In both cases, the contents of 'indentprefix' mail variable is 4858prepended to each line enclosed. 4859 4860 4861File: mailutils.info, Node: Adding a File to the Message, Next: Attaching a File to the Message, Prev: Enclosing Another Message, Up: Composing Mail 4862 48633.5.4.6 Adding a File to the Message: ~r and ~d 4864............................................... 4865 4866To append the contents of file FILENAME to the message, type 4867 4868 ~r FILENAME 4869or 4870 4871 ~< FILENAME 4872 4873 The '~d' escape is a shorthand for 4874 4875 ~r dead.letter 4876 4877 4878File: mailutils.info, Node: Attaching a File to the Message, Next: Printing And Saving the Message, Prev: Adding a File to the Message, Up: Composing Mail 4879 48803.5.4.7 Attaching a File to the Message 4881....................................... 4882 4883The '~+' escape attaches a file to the message. It takes one to three 4884arguments. The first argument supplies the name of the file to attach: 4885 4886 ~+ myfile.txt 4887 4888 The file will be attached with default content-type 4889'application/octet-stream', and encoding 'base64' (these can be altered 4890by the '--content-type' and '--encoding' command line options, 4891correspondingly). 4892 4893 Optional second argument defines the content type to be used instead 4894of the default one. Optional third argument defines the encoding, e.g.: 4895 4896 ~+ myfile.html text/html base64 4897 4898 To list the files attached so far, use the '~l' escape: 4899 4900 ~l 4901 multipart/mixed 4902 1 myfile.html text/html base64 4903 4904 The first line of the output shows the content type of the message. 4905Each subsequent line contains the ordinal number of the attachment, the 4906name of the file, content-type and transfer encoding used. 4907 4908 The '~/' escape toggles the content type bewteen 'multipart/mixed', 4909and 'multipart/alternative'. The new value of the content type is 4910displayed on the screen. 4911 4912 The '~^' escape removes attachments. Its argument is the number of 4913the attachment to remove, e.g.: 4914 4915 ~^ 1 4916 4917 4918File: mailutils.info, Node: Printing And Saving the Message, Next: Signing the Message, Prev: Attaching a File to the Message, Up: Composing Mail 4919 49203.5.4.8 Printing And Saving the Message 4921....................................... 4922 4923The '~p' escape types the contents of the message entered so far, 4924including headers, on your terminal. You can save the message to an 4925arbitrary file using '~w' escape. It takes the filename as its 4926argument. 4927 4928 4929File: mailutils.info, Node: Signing the Message, Next: Printing Another Message, Prev: Printing And Saving the Message, Up: Composing Mail 4930 49313.5.4.9 Signing the Message: ~a and ~A 4932...................................... 4933 4934To save you the effort of typing your signature at the end of each 4935message, you can use '~a' or '~A' escapes. If your signature occupies 4936one line only, save it to the variable 'sign' and use '~a' escape to 4937insert it. Otherwise, if it is longer than one line, save it to a file, 4938store the name of this file in the variable 'Sign', and use '~A' escape 4939to insert it into the message. 4940 4941 4942File: mailutils.info, Node: Printing Another Message, Next: Inserting Value of a Mail Variable, Prev: Signing the Message, Up: Composing Mail 4943 49443.5.4.10 Printing Another Message: ~f and ~F 4945............................................ 4946 4947Sometimes it is necessary to view the contents of another message, while 4948composing. These two escapes allow it. Both take the message list as 4949their argument. If they are used without argument, the contents of the 4950current message is printed. The difference between '~f' and '~F' is 4951that the former uses ignored and retained lists to select headers to be 4952displayed, whereas the latter prints all headers. 4953 4954 4955File: mailutils.info, Node: Inserting Value of a Mail Variable, Next: Executing Other Mail Commands, Prev: Printing Another Message, Up: Composing Mail 4956 49573.5.4.11 Inserting Value of a Mail Variable: ~i 4958............................................... 4959 4960The '~i' escape enters the value of the named mail variable into the 4961body of the message being composed. 4962 4963 4964File: mailutils.info, Node: Executing Other Mail Commands, Next: Executing Shell Commands, Prev: Inserting Value of a Mail Variable, Up: Composing Mail 4965 49663.5.4.12 Executing Other Mail Commands: ~: and ~- 4967................................................. 4968 4969You can execute a mail command from within compose mode using '~:' or 4970'~-' escapes. For example, typing 4971 4972 ~: from :t 4973 4974 will display the from lines of all tagged messages. Note, that 4975executing mail-sending commands from within the compose mode is not 4976allowed. An attempt to execute such a command will result in diagnostic 4977message "Command not allowed in an escape sequence" being displayed. 4978Also, when starting compose mode immediately from the shell (e.g. 4979running 'mail address@domain'), most mail commands are meaningless, 4980since there is no mailbox to operate upon. In this case, the only 4981commands that can reasonably be used are: 'alias', 'unalias', 4982'alternate', 'set', and 'unset'. 4983 4984 4985File: mailutils.info, Node: Executing Shell Commands, Prev: Executing Other Mail Commands, Up: Composing Mail 4986 49873.5.4.13 Executing Shell Commands: ~! and ~| 4988............................................ 4989 4990The '~!' escape executes specified command and returns you to 'mail' 4991compose mode without altering your message. When used without 4992arguments, it starts your login shell. The '~|' escape pipes the 4993message composed so far through the given shell command and replaces the 4994message with the output the command produced. If the command produced 4995no output, 'mail' assumes that something went wrong and retains the old 4996contents of your message. 4997 4998 4999File: mailutils.info, Node: MIME, Next: Scripting, Prev: Composing Mail, Up: mail 5000 50013.5.5 Composing Multipart Messages 5002---------------------------------- 5003 5004Multipart messages (or MIME, for short) can be used to send text in 5005character sets other than ASCII, attach non-text files, send multiple 5006parts in alternative formats, etc. 5007 5008 Technically speaking, the boolean variable 'mime' controls this 5009feature. If it is set (*note Setting and Unsetting the Variables::), 5010'MIME' will create MIME messages by default. The variable can be set in 5011the global or user configuration file (*note Mail Configuration 5012Files::), using the following command: 5013 5014 set mime 5015 5016 It can also be set from the command line, using the '--mime' option. 5017 5018 GNU 'mail' automatically turns on the MIME mode, when it is requested 5019to send a non-plaintext message, or a message in character set other 5020than ASCII, when the encoding is specified, or when attachments are 5021given. 5022 5023 To send a message in another character set, specify it with the 5024'--content-type' option: 5025 5026 mail --content-type 'text/plain; charset=utf-8' 5027 5028 The '--encoding' specifies the encoding to use: 5029 5030 mail --content-type 'text/plain; charset=utf-8' --encoding=base64 5031 5032 Its argument is any encoding supported by GNU mailutils. The two 5033most often used encodings are 'base64' and 'quoted-printable'. 5034 5035 To specify the charset from 'mail' interactive section, enable the 5036"edit headers" mode ('set editheaders') and add the needed 5037'Content-Type' header manually. 5038 5039 GNU 'mail' also gives you a possibility to attach files to the 5040message being sent. 5041 5042 The simplest way to attach a file from command line is by using the 5043'--attach' ('-A') option. Its argument specifies the file to attach. 5044For example, the following will attach the content of the file 5045'archive.tar': 5046 5047 $ mail --attach=archive.tar 5048 5049 By default, the content type will be set to 5050'application/octet-stream', and the attachment will be encoded using the 5051'base64' encoding. To change the content type, use the '--content-type' 5052option. For example, to send an HTML attachment: 5053 5054 $ mail --content-type=text/html --attach=in.html 5055 5056 The '--content-type' option affects all '--attach' options that 5057follow it, and the message body (if any). To change the content type, 5058simply add another '--content-type' option. For example, to send both 5059the HTML file and the archive: 5060 5061 $ mail --content-type=text/html --attach=in.html \ 5062 --content-type=application/x-tar --attach=archive.tar 5063 5064 To change the content type of the message body when sending a message 5065with attachments, use the trailing '--content-type' option, i.e. the 5066option not followed by another '--attach' option: 5067 5068 $ mail --content-type=text/html --attach=in.html \ 5069 --content-type=application/x-tar --attach=archive.tar \ 5070 --content-type=text/plain 5071 5072This example adds two attachments with different content types and 5073switched back to the 'text/plain' content type for the message body. 5074 5075 The encoding to use is set up by the '--encoding' option. As well as 5076'--content-type', this option affects all attachments supplied after it 5077in the command line as well as the message body read from the standard 5078input, until changed by the eventual next instance of the same option. 5079Extending the above example: 5080 5081 $ mail --content-type=text/html --encoding=quoted-printable \ 5082 --attach=in.html \ 5083 --content-type=application/x-tar --encoding=base64 \ 5084 --attach=archive.tar 5085 5086 A trailing '--encoding' option sets the encoding of the message body. 5087 5088 Each attachment can also be assigned a "description" and a "file 5089name". Normally, these are the same as the file name supplied with the 5090'--attach' option. However, you can change either or both of them using 5091the '--content-name' and '--content-filename', correspondingly. Both of 5092these options affect only the next '--attach' (or '--attach-fd', see 5093below) option. 5094 5095 By default, the message will be assigned the content type 5096'multipart/mixed'. To change it to 'multipart/alternative', use the 5097'--alternative' command line option. Using this option also sets the 5098'Content-Disposition' header of each attached message to 'inline'. 5099 5100 All the examples above will enter the usual interactive shell, 5101allowing you to compose the body of the message. If that's not needed, 5102the non-interactive use can be forced by redirecting '/dev/null' to the 5103standard input, e.g.: 5104 5105 $ mail --attach=archive.tar < /dev/null 5106 5107 This will normally produce a message saying: 5108 5109 mail: Null message body; hope that's ok 5110 5111 To suppress this message, unset the 'nullbodymsg' variable, as shown 5112in the example below: 5113 5114 $ mail -E 'set nonullbodymsg' --attach=archive.tar < /dev/null 5115 5116 The option '--attach=-' forces 'mail' to read the file to be attached 5117from the standard input stream. This option disables the interactive 5118mode and sets 'nonullbodymsg' implicitly, so that the above example can 5119be rewritten as: 5120 5121 $ mail --attach=- < archive.tar 5122 5123 Special option is provided to facilitate the use of 'mail' in 5124scripts. The '--attach-fd=N' instructs the program to read the data to 5125be attached from the file descriptor N. The above example is equivalent 5126to: 5127 5128 $ mail --attach-fd=0 < archive.tar 5129 5130 Attachments created with this option have neither filename nor 5131description set, so normally the use of '--content-name' and/or 5132'--content-filename' is advised. 5133 5134 The option '--skip-empty-attachments' instructs 'mail' to skip 5135creating attachments that would have zero-size body. This option 5136affects all attachments created by '--attach' and '--attach-fd' options 5137appearing after it in the command line. It also affects the handling of 5138the original message body. To cancel its effect, use the 5139'--no-skip-empty-attachments' option. 5140 5141 Here are some examples illustrating how it works. 5142 5143 First, consider the following command line 5144 5145 $ mail --attach=archive.tar </dev/null 5146 5147 Assume that 'archive.tar' is not empty. 5148 5149 This will create a MIME message of two parts: the first part having 5150'text/html' type and empty body, and the second part of type 5151'application/octet-stream', with the content copied from the file 5152'archive.tar'. 5153 5154 Now, if you do: 5155 5156 $ mail --attach=archive.tar --skip-empty-attachments </dev/null 5157 5158then the created MIME message will contain only one part: that 5159containing 'archive.tar'. 5160 5161 If the file 'archive.tar' has zero length, the resulting archive will 5162still contain the 'application/octet-stream' part of zero length. 5163However, if you place the '--skip-empty-attachments' option before 5164'--attach', then the produced message will be empty. 5165 5166 The following Perl program serves as an example of using 'mail' from 5167a script to construct a MIME message on the fly. It scans all mounted 5168file systems for executable files that have setuid or setgid bits set 5169and reports the names of those files in separate attachments. Each 5170attachment is named after the mountpoint it describes. 5171 5172 The script begins with the usual prologue stating the modules that 5173will be used: 5174 5175 #!/usr/bin/perl 5176 5177 use strict; 5178 use autodie; 5179 5180 Then global variables are declared. The '@rcpt' array contains the 5181email addresses of the recipients: 5182 5183 my @rcpt= 'root@example.com'; 5184 5185 The '@cmd' variable holds the 'mail' command line. It will be 5186augmented for each file system. The initial value is set as follows: 5187 5188 my @cmd = ('mail', 5189 '-E set nonullbodymsg', 5190 '--content-type=text/plain'); 5191 5192 The 'find' utility will be used to locate the files. The script will 5193start as many instances as there are mountpoints. Those instances will 5194be run in parallel and their standard output streams will be connected 5195to file descriptors passed to 'mail' invocation in '--attach-fd' 5196options. 5197 5198 The descriptors will be held in '@fds' array. This will prevent them 5199from being wiped out by the garbage collector. Furthermore, care should 5200be taken to ensure that the 'O_CLOEXEC' flag be not set for these 5201descriptors. This sample script takes a simplistic approach: it 5202instructs Perl not to close first 255 descriptors when executing another 5203programs: 5204 5205 my @fds; 5206 $^F = 255; 5207 5208 The following code obtains the list of mount points: 5209 5210 open(my $in, '-|', 'mount -t nonfs,noproc,nosysfs,notmpfs'); 5211 while (<$in>) { 5212 chomp; 5213 if (/^\S+ on (?<mpoint>.+) type (?<fstype>.+) /) { 5214 5215 For each mountpoint, the 'find' command line is constructed and 5216launched. The file descriptor is pushed to the '@fds' array to prevent 5217it from being collected by the garbage collector: 5218 5219 open(my $fd, '-|', 5220 "find $+{mpoint} -xdev -type f" 5221 . " \\( -perm -u+x -o -perm -g+x -o -perm -o+x \\)" 5222 . " \\( -perm -u+s -o -perm -g+s \\) -print"); 5223 push @fds, $fd; 5224 5225 Now, the 'mail' command is instructed to create next attachment from 5226that file descriptor: 5227 5228 my $mpname = $+{mpoint}; 5229 $mpname =~ tr{/}{%}; 5230 push @cmd, 5231 "--content-name=Set[ug]id files on $+{mpoint} (type $+{fstype})", 5232 "--content-filename=$mpname.list", 5233 '--attach-fd=' . fileno($fd); 5234 } 5235 } 5236 close $in; 5237 5238 Finally, the emails of the recipients are added to the command line, 5239the standard input is closed to make sure 'mail' won't enter the 5240interactive mode and the constructed command is executed: 5241 5242 push @cmd, @rcpt; 5243 close STDIN; 5244 system(@cmd); 5245 5246 5247File: mailutils.info, Node: Scripting, Next: Mail Variables, Prev: MIME, Up: mail 5248 52493.5.6 Scripting 5250--------------- 5251 5252Comments 5253........ 5254 5255The '#' character introduces an end-of-line comment. All characters 5256until and including the end of line are ignored. 5257 5258Displaying Arbitrary Text 5259......................... 5260 5261The 'echo' ('ec') command prints its arguments to stdout. 5262 5263Sourcing External Command Files 5264............................... 5265 5266The command 'source FILENAME' reads commands from the named file. Its 5267minimal abbreviation is 'so'. 5268 5269Setting and Unsetting the Variables 5270................................... 5271 5272The mail variables are set using 'set' ('se') command. The command 5273takes a list of assignments. The syntax of an assignment is 5274 5275'NAME=STRING' 5276 Assign a string value to the variable. If STRING contains 5277 whitespace characters it must be enclosed in a pair of double-quote 5278 characters ('"') 5279'NAME=NUMBER' 5280 Assign a numeric value to the variable. 5281'NAME' 5282 Assign boolean 'True' value. 5283'noNAME' 5284 Assign boolean 'False' value. 5285 5286 Example: 5287 5288 ? set askcc nocrt indentprefix="> " 5289 5290 This statement sets 'askcc' to 'True', 'crt' to 'False', and 5291'indentprefix' to "> ". 5292 5293 To unset mail variables use 'unset'('uns') command. The command 5294takes a list of variable names to unset. 5295 5296 To undo the effect of the previous example, do: 5297 5298 ? unset askcc crt indentprefix 5299 5300 When used without arguments, both 'set' or 'unset' list all currently 5301defined variables. The form of this listing is controlled by 5302'variable-pretty-print' ('varpp') variable. If it is set, a description 5303precedes each variable, e.g.: 5304 5305 # prompt user for subject before composing the message 5306 ask 5307 # prompt user for cc before composing the message 5308 askcc 5309 # output character set for decoded header fields 5310 charset="auto" 5311 # number of columns on terminal screen 5312 columns=80 5313 5314 If 'variable-pretty-print' is not set, only the settings are shown, 5315e.g.: 5316 5317 ask 5318 askcc 5319 charset="auto" 5320 columns=80 5321 5322 A special command is provided to list all internal 'mail' variables: 5323 5324 variable [NAMES...] 5325 5326 If used without arguments, it prints all known internal variables. 5327If arguments are given, it displays only those internal variables that 5328are listed in command line. For each variable, this command prints its 5329name, data type, current value and a short description. For example: 5330 5331 ? variable ask datefield 5332 ask, asksub 5333 Type: boolean 5334 Current value: yes 5335 prompt user for subject before composing the message 5336 5337 datefield 5338 Type: boolean 5339 Current value: [not set] 5340 get date from the `Date:' header, instead of the envelope 5341 5342Setting and Unsetting Shell Environment Variables 5343................................................. 5344 5345Shell environment may be modified using 'setenv' ('sete') command. The 5346command takes a list of assignments. The syntax of an assignment is: 5347 5348'NAME=VALUE' 5349 If variable NAME does not already exist in the environment, then it 5350 is added to the environment with the value VALUE. If NAME does 5351 exist, then its value in the environment is changed to VALUE. 5352'NAME' 5353 Delete the variable NAME from the environment ("unset" it). 5354 5355Conditional Statements 5356...................... 5357 5358The conditional statement allows to execute a set of mail commands 5359depending on the mode the 'mail' program is in. The conditional 5360statement is: 5361 5362 if COND 5363 ... 5364 else 5365 ... 5366 endif 5367 5368 where '...' represents the set of commands to be executed in each 5369branch of the statement. COND can be one of the following: 5370 5371's' 5372 True if 'mail' is operating in mail sending mode. 5373'r' 5374 True if 'mail' is operating in mail reading mode. 5375't' 5376 True if stdout is a terminal device (as opposed to a regular file). 5377 5378 The conditional statements can be nested to arbitrary depth. The 5379minimal abbreviations for 'if', 'else' and 'endif' commands are 'i', 5380'el' and 'en'. 5381 5382 Example: 5383 5384 if t 5385 set crt prompt="& " 5386 else 5387 unset prompt 5388 endif 5389 if s 5390 alt gray@example.com gray@example.org 5391 set 5392 5393 5394File: mailutils.info, Node: Mail Variables, Next: Mail Configuration Files, Prev: Scripting, Up: mail 5395 53963.5.7 How to Alter the Behavior of 'mail' 5397----------------------------------------- 5398 5399Following variables control the behavior of GNU 'mail': 5400 5401 -- mail: boolean append 5402 5403 Default: True 5404 Comment: Read-Only 5405 5406 Messages saved in 'mbox' are appended to the end, rather than 5407 prepended. This is the default and cannot be changed. This 5408 variable exists only for compatibility with other 'mailx' 5409 implementations. 5410 5411 -- mail: boolean appenddeadletter 5412 5413 Default: False 5414 5415 If this variable is set, the contents of canceled letter is 5416 appended to the user's 'dead.letter' file. Otherwise it overwrites 5417 its contents. 5418 5419 -- mail: boolean askbcc 5420 5421 Default: False 5422 5423 When set to 'True' the user will be prompted to enter 'Bcc' field 5424 before composing the message. 5425 5426 -- mail: boolean askcc 5427 5428 Default: True 5429 5430 When set to 'True' the user will be prompted to enter 'Cc' field 5431 before composing the message. 5432 5433 -- mail: boolean asksub 5434 5435 Default: True in interactive mode, False otherwise. 5436 5437 When set to 'True' the user will be prompted to enter 'Subject' 5438 field before composing the message. 5439 5440 -- mail: boolean autoinc 5441 5442 Default: True 5443 5444 Automatically incorporate newly arrived messages. 5445 5446 -- mail: boolean autoprint 5447 5448 Default: False 5449 5450 Causes the delete command to behave like 'dp': after deleting a 5451 message, the next one will be typed automatically. 5452 5453 -- mail: boolean bang 5454 5455 Default: False 5456 5457 When set, every occurrence of '!' in arguments to '!' escape is 5458 replaced with the last executed command. 5459 5460 *Note Executing Shell Commands::, for details on the '!' escape. 5461 5462 -- mail: boolean datefield 5463 5464 Default: False 5465 5466 By default the date in a header summary is taken from the SMTP 5467 envelope of the message. Setting this variable tells 'mail' to use 5468 the date from 'Date:' header field, converted to local time. 5469 Notice, that for messages lacking this field 'mail' will fall back 5470 to using SMTP envelope. 5471 5472 *Note fromfield::. 5473 5474 -- mail: string charset 5475 5476 Default: 'auto' 5477 5478 The value of this variable is the character set used for input and 5479 output operations. If the value is 'auto', 'mail' will try to 5480 deduce the name of the character set from the value of 'LC_ALL' 5481 environment variable. If the variable contains the character set 5482 part (e.g. 'nb_NO.utf-8'), it will be used. Otherwise, 'mail' 5483 will look up in its built-in database the value of the character 5484 for this language/territory combination. If 'LC_ALL' is not set, 5485 the 'LANG' environment variable is inspected. 5486 5487 The value of 'charset' controls both input and output operations. 5488 On input, it is used to set the value of the 'charset' parameter in 5489 the 'Content-Type' MIME header, if its value begins with 'text/' 5490 and the 'charset' parameter is not present. 5491 5492 On output, it is used to display values of the header fields 5493 encodied using RFC 2047. If the variable is unset, no decoding is 5494 performed and the fields are printed as they are. Otherwise, they 5495 are recoded to that character set. 5496 5497 -- mail: string cmd 5498 5499 Default: Unset 5500 5501 Contains default shell command for 'pipe'. 5502 5503 -- mail: numeric columns 5504 5505 Default: Detected at startup by querying the terminal device. If 5506 this fails, the value of environment variable 'COLUMNS' is used. 5507 5508 This variable contains the number of columns on terminal screen. 5509 5510 -- mail: numeric crt 5511 -- mail: boolean crt 5512 5513 Default: True in interactive mode, False otherwise. 5514 5515 The variable 'crt' determines the minimum number of lines the body 5516 of the message must contain in order to be piped through pager 5517 command specified by environment variable 'PAGER'. If 'crt' is set 5518 to a numeric value, this value is taken as the threshold. 5519 Otherwise, if 'crt' is set without a value, then the height of the 5520 terminal screen is used to compute the threshold. The number of 5521 lines on screen is controlled by 'screen' variable. 5522 5523 -- mail: boolean debug 5524 -- mail: string debug 5525 5526 Default: Unset 5527 5528 Sets mailutils debug level. If set to string, the value must be a 5529 valid Mailutils debugging specification. *Note Debug Statement::, 5530 for a description. 5531 5532 If unset (i.e. 'set nodebug'), clears and disables all debugging 5533 information. If set to 'true' (i.e. 'set debug'), sets maximum 5534 debugging ('<trace7') on mailbox and its underlying objects. 5535 5536 -- mail: string decode-fallback 5537 5538 Default: 'none' 5539 5540 This variable controls the way to represent characters that cannot 5541 be rendered using current character set. It can have three values: 5542 5543 'none' 5544 Such characters are not printed at all. The conversion 5545 process stops at the first character that cannot be rendered. 5546 5547 'copy-pass' 5548 The characters are displayed 'as is'. Notice, that depending 5549 on your setup, this may screw-up your terminal settings. 5550 5551 'copy-octal' 5552 Unprintable characters are represented by their octal codes. 5553 Printable ones are printed 'as is'. 5554 5555 -- mail: boolean dot 5556 5557 Default: False 5558 5559 If set, causes 'mail' to interpret a period alone on a line as the 5560 terminator of a message you are sending. 5561 5562 -- mail: boolean editheaders 5563 5564 Default: False 5565 5566 When set, 'mail' will include message headers in the text to be the 5567 '~e' and '~v' escapes, thus allowing you to customize the headers. 5568 5569 -- mail: boolean emptystart 5570 5571 Default: False 5572 5573 If the mailbox is empty, 'mail' normally prints 'No mail for user' 5574 and exits immediately. If this option is set, 'mail' will start no 5575 matter is the mailbox empty or not. 5576 5577 -- mail: string escape 5578 5579 Default: '~' 5580 5581 Current value of the command escape character. 5582 5583 -- mail: boolean flipr 5584 5585 Default: Unset 5586 5587 If set, the variable 'flipr' swaps the meanings of 'reply' and 5588 'Reply' commands (*note Replying::). 5589 5590 -- mail: string folder 5591 5592 Default: Unset 5593 5594 The name of the directory to use for storing folders of messages. 5595 If unset, '$HOME' is assumed. 5596 5597 -- mail: boolean fromfield 5598 5599 Default: True 5600 5601 By default the sender address is taken from the 'From' header. 5602 Unsetting this variable tells 'mail' to obtain it from the SMTP 5603 envelope instead. 5604 5605 *Note datefield::. 5606 5607 -- mail: boolean fullnames 5608 5609 Default: True 5610 5611 Preserve personal parts (comments) of recipient addresses when 5612 replying to a message. 5613 5614 When unset, only emails will be used. 5615 5616 *Note Replying::. 5617 5618 -- mail: boolean header 5619 5620 Default: True, unless started with '--nosum' ('-N') option. 5621 5622 Whether to run 'headers' command automatically after entering 5623 interactive mode. 5624 5625 -- mail: string headline 5626 5627 Default: '%>%a%4m %18f %16d %3l/%-5o %s' 5628 5629 Format string to use for the header summary. The '%' character 5630 introduces a "format specifier". The format specifier consists of 5631 optional alignment specifier ('+' or '-' sign), optional output 5632 width and the specifier letter. Format specifiers are replaced on 5633 output with the corresponding piece of information from the message 5634 being described. 5635 5636 The '-' character immediately following '%' indicates that this 5637 field should be left aligned. The '+' character indicates right 5638 alignment. Default alignment depends on the type of the specifier: 5639 the specifiers that produce numeric values ('%l', '%m', and '%o') 5640 are aligned to the right, whereas the ones producing string or 5641 date/time values are aligned to the left. 5642 5643 A number following '%' or the alignment flag, indicates the field 5644 width. 5645 5646 Consider the '%m' specifier as an example: 5647 5648 %m 5649 Print current message number. Take as much screen columns as 5650 necessary for output. 5651 5652 %4m 5653 %+4m 5654 Print current message number. Use exactly 4 screen columns, 5655 truncating the output if it does not fit that width. Align 5656 the output to the right. 5657 5658 %-4m 5659 Same as above, but align to the left. 5660 5661 Valid format specifiers are: 5662 5663 %a 5664 Message attribute. One of the following letters, or a single 5665 horizontal space, if none of them applies: 5666 5667 'M' the message was copied to the mailbox 5668 ('mbox' command) 5669 'P' the message was preserved ('hold' 5670 command) 5671 '*' the message was saved ('save' or 'Save') 5672 'T' the message was tagged ('tag') 5673 'R' the message was read 5674 'N' the message is new (was not seen) 5675 'U' the message was seen, but wasn't read 5676 5677 %d 5678 The date when the message was received. It is determined from 5679 the message header defined by the 'datefield' variable (*note 5680 datefield::). If that variable is not set, or the requested 5681 header is not present in the message, the date from the 5682 envelope is used. 5683 5684 The output is formatted according to the following format 5685 specification (*note Date/time Format String::): 5686 5687 %a %b %e %H:%M 5688 5689 I.e.: abbreviated weekday name, abbreviated month name, day of 5690 the month as a decimal number, followed by hour and minutes. 5691 All names are displayed according to the current locale. 5692 5693 %D{FMT} 5694 Same as '%d', but the date is formatted according to the 5695 date/time format FMT. It is essentially a C 'strftime' format 5696 string, described in detail in *note Date/time Format 5697 String::. 5698 5699 For example: 5700 5701 set headline="%4m %20D{%Y-%m-%dT%H:%M:%S}" 5702 5703 Note, that the opening '{' must follow the format letter 5704 without any intervening whitespace. If FMT contains '{', '}', 5705 or '\', these characters must be escaped with backslash (e.g. 5706 '\{'). 5707 5708 %DF 5709 A simplified form of the '%D' specifier. It is equivalent to 5710 5711 %D{%F} 5712 5713 where F is a single 'strftime' specifier letter. It can be 5714 preceded by 'E' or 'O', if the Single UNIX Specification 5715 allows such usage (*note conversion specs::), e.g. '%DOU'. 5716 5717 Notice, that '%D' not followed by a valid time format in 5718 either of the above forms is treated as unknown specifier. 5719 5720 %f 5721 The email address of the message sender. 5722 5723 %l 5724 The number of lines of the message. 5725 5726 %m 5727 Message number. 5728 5729 %o 5730 The number of octets (bytes) in the message. 5731 5732 %s 5733 Message subject (if any). 5734 5735 %S 5736 Message subject (if any) in double quotes. 5737 5738 %> 5739 A '>' for the current message, otherwise a space. 5740 5741 %< 5742 A '<' for the current message, otherwise a space. 5743 5744 %% 5745 A '%' character. 5746 5747 -- mail: boolean hold 5748 5749 Default: False 5750 5751 Determines the location where to store the messages in state 'read' 5752 and (if the 'keepsave' is also set) 'saved'. When set, these 5753 messages will be retained in the system mailbox. 5754 5755 When not set (the default), such messages will be stored in the 5756 user's personal mailbox. 5757 5758 *Note read messages::, and *Note saved messages::, for a detailed 5759 information on how such messages are processed when the mailbox is 5760 being closed. 5761 5762 *Note keepsave::, for the discussion of the 'keepsave' variable. 5763 5764 -- mail: boolean ignore 5765 5766 Default: False 5767 5768 When set to 'True', 'mail' will ignore keyboard interrupts when 5769 composing messages. Otherwise an interrupt will be taken as a 5770 signal to abort composing. 5771 5772 -- mail: boolean ignoreeof 5773 5774 Default: False 5775 5776 Controls whether typing EOF character terminates the letter being 5777 composed. 5778 5779 -- mail: string indentprefix 5780 5781 Default: "\t" (a tab character). 5782 5783 String used by the '~m' tilde escape for indenting quoted messages. 5784 5785 -- mail: boolean inplacealiases 5786 5787 Default: False 5788 5789 If set, 'mail' will expand aliases in the address header field 5790 before entering send mode (*note Composing Mail::). By default, 5791 the address header fields are left intact while composing, the 5792 alias expansion takes place immediately before sending message. 5793 5794 -- mail: boolean keep 5795 5796 Comment: Read-Only 5797 Default: True 5798 5799 Truncate the user's system mailbox when it is empty, instead of 5800 removing it. This is the default and cannot be changed. This 5801 variable exists only for compatibility with other 'mailx' 5802 implementations. 5803 5804 -- mail: boolean keepsave 5805 5806 Default: False 5807 5808 Controls whether saved messages should be retained. The location 5809 where they will be retained is controlled by the 'hold' variable 5810 (*note the hold variable::). 5811 5812 This variable is in effect only when operating upon the user's 5813 system mailbox. 5814 5815 *Note saved messages::, for a detailed information on how the saved 5816 messages are processed when the mailbox is being closed. 5817 5818 -- mail: boolean mailx 5819 5820 Default: False 5821 5822 When set, enables "mailx compatibility mode". This mode has the 5823 following effects: 5824 5825 * When composing a message 'mail' will ask for 'Cc' and 'Bcc' 5826 addresses after composing the body. The default behavior is 5827 to ask for these values before composing the body. 5828 5829 * In send mode, if the composition was interrupted, 'mail' will 5830 exit with zero status. By default it exits with zero status 5831 only if the message was sent successfully. 5832 5833 * The 'outfolder' variable is treated as boolean. *note 5834 outfolder::. 5835 5836 * The value of 'outfilename' is ignored (assumed to be 'local'). 5837 *note outfilename::. 5838 5839 * The values of 'folder' and 'record' variables are assumed 5840 relative to the home directory, unless they begin with '/', 5841 '~', or '+'. 5842 5843 * If the value of the 'sendmail' variable does not begin with a 5844 scheme specification, 'sendmail:/' is assumed. *Note sendmail 5845 mail variable::. 5846 5847 -- mail: boolean metamail 5848 -- mail: string metamail 5849 5850 Default: True 5851 5852 This variable controls operation of 'decode' command. If it is 5853 unset, 'decode' will not attempt any interpretation of the content 5854 of message parts. Otherwise, if 'metamail' is set to 'true', 5855 'decode' will use internal metamail support to interpret message 5856 parts. Finally, if 'metamail' is assigned a string, this string is 5857 treated as command line of the external 'metamail' command which 5858 will be used to display parts of a multipart message. For example: 5859 5860 # Disable MIME interpretation: 5861 set nometamail 5862 # Enable built-in MIME support: 5863 set metamail 5864 # Use external program to display MIME parts: 5865 set metamail="metamail -m mail -p" 5866 5867 -- mail: string mime 5868 5869 Default: False 5870 5871 If set, this variable instructs 'mail' to compose MIME messages. 5872 5873 It can be set from the command line using '--mime' option. 5874 5875 -- mail: string mimenoask 5876 5877 Default: Unset 5878 5879 By default 'mail' asks for confirmation before running interpreter 5880 to view a part of the multi-part message. If this variable is set, 5881 its value is treated as a comma-separated list of MIME types for 5882 which no confirmation is needed. Elements of this list may include 5883 shell-style globbing patterns, e.g. setting 5884 5885 set mimenoask=text/*,image/jpeg 5886 5887 will disable prompting before displaying any textual files, no 5888 matter what their subtype is, and before displaying files with type 5889 'image/jpeg'. 5890 5891 -- mail: boolean metoo 5892 5893 Default: False 5894 5895 Usually, when an alias is expanded that contains the sender, the 5896 sender is removed from the expansion. Setting this option causes 5897 the sender to be included in the group. 5898 5899 -- mail: string mode 5900 5901 Comment: Read-Only 5902 Default: The name of current operation mode. 5903 5904 This variable keeps the name of the current operation mode. Its 5905 possible values are: 5906 5907 headers 5908 The program is started with the '--headers' ('-H') command 5909 line option (*note Invoking Mail::). 5910 5911 exist 5912 The program is started with the '--exist' ('-e') command line 5913 option (*note Invoking Mail::). 5914 5915 print 5916 The program is started with the '--print' ('-p') command line 5917 option (*note Invoking Mail::). 5918 5919 read 5920 The program operates in read mode. This is the default. 5921 5922 send 5923 The program operates in send mode. This means it was given 5924 one or more recipient addresses in the command line. 5925 5926 -- mail: boolean nullbody 5927 5928 Default: True 5929 5930 Controls whether 'mail' accepts messages with an empty body. The 5931 default value, 'true', means such messages are sent, and a warning 5932 (traditionally saying 'Null message body; hope that's ok') is 5933 displayed. The text of the warning can be set using 'nullbodymsg' 5934 variable (see below). 5935 5936 If 'nullbody' is unset, 'mail' will silently ignore such messages. 5937 This can be useful in 'crontab' files, to avoid sending mails when 5938 nothing important happens. For example, the 'crontab' entry below 5939 will send mail only if the utility 'some-prog' outputs something on 5940 its standard output or error: 5941 5942 */5 * * * * some-prog 2>&1 | \ 5943 /bin/mail -E'set nonullbody' -s 'Periodic synchronization' 5944 5945 -- mail: string nullbodymsg 5946 5947 Default: 'Null message body; hope that's ok' 5948 5949 Text of the warning displayed by 'mail' before sending an empty 5950 message. When available, the translation of this text, in 5951 accordance with the current locale, is displayed. 5952 5953 Unsetting this variable disables the warning. 5954 5955 -- mail: boolean onehop 5956 5957 Default: Unset 5958 5959 This variable is not used. It exists for compatibility with other 5960 'mailx' implementations and for future use. 5961 5962 -- mail: string outfilename 5963 5964 Comment: Three-state: 'local', 'email', 'domain'. 5965 Default: 'local' 5966 5967 Defines the algorithm to convert the recipient email to the name of 5968 the file used to record outgoing messages to that recipient. This 5969 affects the following commands: 'Copy', 'Save', 'Mail', 'followup', 5970 and 'Followup'. The following values are allowed: 5971 5972 'local' 5973 Local part of the email address is taken as the file name. 5974 This is the default. 5975 5976 'email' 5977 Entire email is takes as the file name. 5978 5979 'domain' 5980 Domain part of the email is used as the file name. 5981 5982 -- mail: boolean outfolder 5983 -- mail: string outfolder 5984 5985 Default: Unset 5986 5987 When set as boolean, causes the files used to record outgoing 5988 messages to be located in the directory specified by the 'folder' 5989 variable (unless the pathname is absolute). 5990 5991 If set to a string value, names the directory where to store these 5992 files. 5993 5994 This variable affects the following commands: 'Copy', 'Save', 5995 'Mail', 'followup', and 'Followup'. 5996 5997 In mailx compatibility mode, only boolean value is allowed. *note 5998 mailx mail variable::. 5999 6000 -- mail: boolean page 6001 6002 Default: Unset 6003 6004 If set, the 'pipe' command will emit a linefeed character after 6005 printing each message. 6006 6007 -- mail: string PID 6008 6009 Comment: Read-Only 6010 Default: PID of the process. 6011 6012 PID of the current 'mail' process. 6013 6014 -- mail: string prompt 6015 6016 Default: "? " 6017 6018 Contains the command prompt sequence. 6019 6020 -- mail: boolean quiet 6021 6022 Default: Unset 6023 6024 This variable is not used. It exists for compatibility with other 6025 'mailx' implementations and for future use. 6026 6027 -- mail: boolean quit 6028 6029 Default: False, unless started with '--quit' ('-q') option. 6030 6031 When set, causes keyboard interrupts to terminate the program. 6032 6033 -- mail: boolean rc 6034 6035 Default: True, unless started with '--norc' ('-N') option. 6036 6037 When this variable is set, 'mail' will read the system-wide 6038 configuration file upon startup. *Note Mail Configuration Files::. 6039 6040 -- mail: boolean readonly 6041 6042 Default: False 6043 6044 When set, mailboxes are opened in readonly mode. In this mode, any 6045 'mail' commands that alter the contents of the mailbox are 6046 disabled. These commands include, but are not limited to: 6047 'delete', 'save' and 'mbox'. 6048 6049 -- mail: string record 6050 6051 Default: Unset 6052 6053 When set, outgoing messages produced by the following commmands 6054 will be saved to the named file: 'mail', 'reply', 'Reply'. 6055 6056 See also *note outfolder:: and *note outfilename::. 6057 6058 -- mail: boolean recursivealiases 6059 6060 Default: True 6061 6062 When set, 'mail' will expand aliases recursively. 6063 6064 -- mail: boolean regex 6065 6066 Default: True. 6067 6068 If set, enables the use of regular expressions in '/.../' message 6069 specifications. 6070 6071 -- mail: string replyprefix 6072 6073 Default: 'Re: ' 6074 6075 Sets the prefix that will be used when constructing the subject 6076 line of a reply message. 6077 6078 -- mail: string replyregex 6079 6080 Default: '^re: *' 6081 6082 Sets the regular expression used to recognize subjects of reply 6083 messages. If the 'Subject' header of the message matches this 6084 expression, the value of 'replyprefix' will not be prepended to it 6085 before replying. The value should be a POSIX extended regular 6086 expression. The comparison is case-insensitive. 6087 6088 For example, to recognize usual English, Polish, Norwegian and 6089 German reply subject styles, use: 6090 6091 set replyregex="^(re|odp|aw|ang)(\\[[0-9]+\\])?:[[:blank:]]" 6092 6093 (Notice the quoting of backslash characters). 6094 6095 -- mail: string return-address 6096 6097 Default: unset 6098 6099 Sets the return email address to use when sending messages. If 6100 unset, return address is composed from the current user name and 6101 the host name. 6102 6103 -- mail: boolean save 6104 6105 Default: True. 6106 6107 When set, the aborted messages will be stored in the user's 6108 'dead.file'. See also 'appenddeadletter'. 6109 6110 -- mail: numeric screen 6111 6112 Default: Detected at startup by querying the terminal device. If 6113 this fails, the value of environment variable 'LINES' is used. 6114 6115 This variable contains the number of lines on terminal screen. See 6116 also *note crt::. 6117 6118 -- mail: string sendmail 6119 6120 Default: 'sendmail:/usr/lib/sendmail' 6121 6122 Contains URL of the mail transport agent. If the value begins with 6123 a scheme specifier, it must be one of the mailer URL schemes 6124 supported by mailutils (*note mailer URL::). Otherwise, if not in 6125 mailx compatibility mode, the value starting with directory 6126 separator ('/') is treated as the external command that will be 6127 started as is and the composed message will be piped to its 6128 standard input. 6129 6130 In mailx compatibility mode (*note mailx mail variable::), the 6131 'sendmail:' prefix is assumed. 6132 6133 -- mail: boolean sendwait 6134 6135 Default: Unset 6136 6137 This variable is not used. It exists for compatibility with other 6138 'mailx' implementations and for future use. 6139 6140 -- mail: string Sign 6141 6142 Default: Unset 6143 6144 Contains the filename holding users signature. The contents of 6145 this file is appended to the end of a message being composed by 6146 '~A' escape. 6147 6148 -- mail: string sign 6149 6150 Default: Unset 6151 6152 Contains the user's signature. The contents of this variable is 6153 appended to the end of a message being composed by '~a' escape. 6154 Use 'Sign' variable, if your signature occupies more than one line. 6155 6156 -- mail: boolean showenvelope 6157 6158 Default: Unset 6159 6160 If this variable is set, the 'print' command will include the SMTP 6161 envelope in its output. 6162 6163 -- mail: boolean showto 6164 6165 Default: Unset 6166 6167 If this variable is set, 'mail' will show 'To:' addresses instead 6168 of 'From:' for all messages that come from the user that invoked 6169 the program. 6170 6171 -- mail: string subject 6172 6173 Default: Unset 6174 6175 Contains default subject line. This will be used when 'asksub' is 6176 off. 6177 6178 -- mail: numeric toplines 6179 6180 Default: 5 6181 6182 Number of lines to be displayed by 'top' and 'Top' commands. 6183 6184 -- mail: boolean variable-pretty-print 6185 -- mail: boolean varpp 6186 6187 Default: False 6188 6189 If this variable is set, the listing output by 'set' contains short 6190 descriptions before each variable. *Note Setting and Unsetting the 6191 Variables::. 6192 6193 -- mail: boolean variable-strict 6194 -- mail: boolean varstrict 6195 6196 Default: False 6197 6198 Setting this variable enables strict control over variable 6199 settings. In this mode, 'mail' refuses to set read-only variables. 6200 Also, if the user is trying to set an unknown variable, 'mail' 6201 prints a warning. 6202 6203 *Note Setting and Unsetting the Variables::. 6204 6205 -- mail: boolean verbose 6206 6207 Default: False 6208 6209 When set, the actual delivery of messages is displayed on the 6210 user's terminal. 6211 6212 -- mail: boolean useragent 6213 6214 Default: True 6215 6216 Controls whether the 'User-Agent' header should be added to 6217 outgoing messages. The default value of this header is 6218 6219 User-Agent: mail (GNU Mailutils 3.13) 6220 6221 -- mail: boolean xmailer 6222 This header is retained for compatibility with previous releases of 6223 GNU Mailutils. Since version 3.13 it is an alias for 'useragent'. 6224 6225 6226File: mailutils.info, Node: Mail Configuration Files, Prev: Mail Variables, Up: mail 6227 62283.5.8 Personal and System-wide Configuration Files 6229-------------------------------------------------- 6230 6231After processing the usual Mailutils configuration files (*note 6232configuration::), 'mail' reads the contents of the two command files: 6233the system-wide command file, and the user's command file. Each line 6234read from these files is processed like a usual 'mail' command. 6235 6236 When run with '--norc' ('-N') option, 'mail' does not read the 6237contents of system-wide configuration file. The user's file, if it 6238exists, is always processed. 6239 6240 The user's configuration file is located in the user's home directory 6241and is named '.mailrc'. The location and name of the system-wide 6242configuration file is determined when configuring the package via 6243'--with-mail-rc' option. It defaults to 'SYSCONFDIR/mail.rc'. 6244 6245 6246File: mailutils.info, Node: messages, Next: movemail, Prev: mail, Up: Programs 6247 62483.6 'messages' -- Count the Number of Messages in a Mailbox 6249=========================================================== 6250 6251'Messages' prints on standard output the number of messages contained in 6252each folder specified in command line. If no folders are specified, it 6253operates upon user's system mailbox. For each folder, the following 6254output line is produced: 6255 6256 Number of messages in FOLDER: NUMBER 6257 6258where FOLDER represents the folder name, NUMBER represents the number of 6259messages. 6260 6261 The following configuration file statements affect the behaviour of 6262'messages': 6263 6264Statement Reference 6265------------------------------------------------------------------- 6266debug *Note debug statement::. 6267tls *Note tls statement::. 6268mailbox *Note mailbox statement::. 6269locking *Note locking statement::. 6270 6271 In addition to the common mailutils options (*note Common Options::), 6272the program accepts the following command line options: 6273 6274'-q' 6275'--quiet' 6276'-s' 6277'--silent' 6278 Be quiet. Display only number of messages per mailbox, without 6279 leading text. 6280 6281 6282File: mailutils.info, Node: movemail, Next: readmsg, Prev: messages, Up: Programs 6283 62843.7 'movemail' -- Moves Mail from the User Maildrop to the Local File 6285===================================================================== 6286 6287The purpose of 'movemail', as its name implies, is to move mail from one 6288location to another. For example, the following invocation: 6289 6290 movemail /var/mail/smith INBOX 6291 6292moves messages from file '/var/mail/smith' to file 'INBOX'. 6293 6294 The program was initially intended as a replacement for 'movemail' 6295from GNU Emacs. The 'movemail' program is run by Emacs 'Rmail' module. 6296*Note (emacs)Rmail::, for detailed description of 'Rmail' interface. 6297 6298 Mailutils version of 'movemail' is fully backward-compatible with its 6299Emacs predecessor, so it should run flawlessly with older versions of 6300Emacs. Emacs versions starting from 22.1 contain improved 'Rmail' 6301interface and are able to take advantage of all new features mailutils 6302'movemail' provides. 6303 6304 Apart from that use, 'movemail' proved to be a useful tool for 6305incorporating mail from remote mailboxes into the local one. See 6306Fetching Mail with Movemail 6307(http://mailutils.org/wiki/Fetching_Mail_with_Movemail), for a detailed 6308discussion with usage recipes. 6309 6310* Menu: 6311 6312* Movemail Configuration:: 6313* Ownership:: Setting Destination Mailbox Ownership 6314* Summary:: Short Movemail Invocation Summary 6315 6316 6317File: mailutils.info, Node: Movemail Configuration, Next: Ownership, Up: movemail 6318 63193.7.1 Movemail Configuration 6320---------------------------- 6321 6322The following configuration file statements affect the behavior of 6323'movemail': 6324 6325 -- Movemail Config: preserve BOOL 6326 If BOOL is 'true', do not remove messages from the source mailbox. 6327 6328 -- Movemail Config: reverse BOOL 6329 If BOOL is 'true', reverse message sorting order. 6330 6331 -- Movemail Config: emacs BOOL 6332 If BOOL is 'true', output information used by Emacs rmail 6333 interface. 6334 6335 -- Movemail Config: ignore-errors BOOL 6336 Continue moving messages after errors. By default, 'mailfromd' 6337 exits immediately if it cannot copy a message. 6338 6339 -- Movemail Config: program-id FMT 6340 Set program identifier, i.e. a string which will prefix all 6341 diagnostic messages issued by the program. By default, program 6342 name is used. 6343 6344 The FMT is a format string that may contain references to the 6345 following variables (*note Variables::): 6346 6347 'progname' 6348 The program name. 6349 6350 'source' 6351 URL of the source mailbox. 6352 6353 'source_user' 6354 User part of the source mailbox URL. 6355 6356 'source_host' 6357 Host part of the source mailbox URL. 6358 6359 'source_path' 6360 Path part of the source mailbox URL. 6361 6362 'dest' 6363 URL of the destination mailbox 6364 6365 'dest_user' 6366 User part of the destination mailbox URL. 6367 6368 'dest_host' 6369 Host part of the destination mailbox URL. 6370 6371 'dest_path' 6372 Path part of the destination mailbox URL. 6373 6374 Setting 'program-id' may be necessary if several 'movemail' 6375 instances are run simultaneously (e.g. invoked from a script) to 6376 discern between the instances. For example: 6377 6378 program-id "${progname}: ${source} => ${dest}" 6379 6380 -- Movemail Config: uidl BOOL 6381 Avoid copying the message if a message with the same UIDL already 6382 exists in the destination mailbox. 6383 6384 -- Movemail Config: verbose LEVEL 6385 Set verbosity level. 6386 6387 -- Movemail Config: mailbox-ownership METHOD-LIST 6388 Define list of methods for setting ownership of the destination 6389 mailbox. The METHOD-LIST argument can contain the following 6390 elements: 6391 6392 copy-id 6393 Copy owner UID and GID from the source mailbox. This method 6394 works only with local mailboxes, i.e.: 'mbox' (UNIX mailbox), 6395 'maildir' and 'mh'. 6396 6397 copy-name 6398 Get owner name from the source mailbox URL and obtain UID and 6399 GID for this user using mailutils authorization methods. 6400 6401 set-id=UID[:GID] 6402 Set supplied UID and GID. If GID is not supplied, it is read 6403 from the '/etc/passwd' record for this UID. 6404 6405 set-name=USER 6406 Make destination mailbox owned by USER. 6407 6408 -- Movemail Config: max-messages COUNT 6409 Defines upper limit on the number of moved messages. Movemail will 6410 stop after transferring COUNT messages. 6411 6412 By default, the number of messages is not limited. 6413 6414 -- Movemail Config: onerror ACTIONS 6415 Defines what to do if an error occurs when transferring a message. 6416 ACTIONS is a list of one or more of the following keywords: 6417 6418 abort 6419 Abort the transfer and terminate the program. This is the 6420 default action. 6421 6422 skip 6423 Skip to the next message. 6424 6425 delete 6426 Delete the affected message. 6427 6428 count 6429 Count this message as processed. 6430 6431 Each keyword can be prefixed with 'no' to reverse its meaning. 6432 6433 The following standard Mailutils statements are supported: 6434 6435Statement Reference 6436------------------------------------------------------------------- 6437debug *Note debug statement::. 6438tls *Note tls statement::. 6439mailbox *Note mailbox statement::. 6440locking *Note locking statement::. 6441pam *Note pam statement::. 6442sql *Note sql statement::. 6443virtdomain *Note virtdomain statement::. 6444radius *Note radius statement::. 6445ldap *Note ldap statement::. 6446auth *Note auth statement::. 6447 6448 6449File: mailutils.info, Node: Ownership, Next: Summary, Prev: Movemail Configuration, Up: movemail 6450 64513.7.2 Setting Destination Mailbox Ownership 6452------------------------------------------- 6453 6454 ================================================================== 6455 *Editor's note:* 6456 The information in this node may be obsolete or otherwise 6457 inaccurate. This message will disappear, once this node revised. 6458 ================================================================== 6459 6460 6461File: mailutils.info, Node: Summary, Prev: Ownership, Up: movemail 6462 64633.7.3 Movemail Usage Summary 6464---------------------------- 6465 6466 movemail [OPTION...] INBOX DESTFILE [PASSWORD] 6467 6468 The first argument, INBOX, is the url (*note Mailbox::) of the source 6469mailbox. The second argument, DESTFILE, traditionally means destination 6470file, i.e. the UNIX mailbox to copy messages to. However, mailutils 6471'movemail' extends the meaning of this parameter. You may actually 6472specify any valid url as DESTFILE parameter.(1). 6473 6474 For compatibility with older implementations of 'movemail', the 6475SOURCE argument can also have the form: 6476 6477 po:USERNAME[:POP-SERVER] 6478 6479where POP-SERVER is the IP address or hostname of a POP3 server to 6480connect to and USERNAME is the name of the user on that server. The 6481password is then supplied by the third argument. 6482 6483 It is equivalent to the following URL: 6484 6485 pop://USERNAME[:PASSWORD]@POP-SERVER 6486 6487 In fact, whenever SOURCE refers to a remote mailbox, the PASSWORD 6488argument can be used to pass the password. However, the safer "ticket" 6489method is of course preferred. 6490 6491 Options are one or more of the following: 6492 6493'--emacs' 6494 Output information used by Emacs 'rmail' interface. 6495 6496'--ignore-errors' 6497 Try to continue after errors. 6498 6499'--max-messages=COUNT' 6500 Process at most COUNT messages. 6501 6502'--notify' 6503 Enable biff notification. 6504 6505'--onerror=KW[,KW...]' 6506 What to do on errors. *Note onerror statement: movemail-onerror, 6507 for a description of KW. 6508 6509'-P MODELIST' 6510'--owner=MODELIST' 6511 Control mailbox ownership. MODELIST is a comma-separated list of 6512 one or more ownership change methods. *Note 6513 mailbox-ownership-methods::, for a description of available 6514 methods. 6515 6516 This option is useful only when running 'movemail' as root. 6517 6518'-p' 6519'--preserve' 6520'--keep-messages' 6521 Don't remove transferred messages from the source mailbox. 6522 6523'--program-id=FMT' 6524 Set program identifier for diagnostics (default: the program name). 6525 *Note movemail-program-id::, for a description of its argument. 6526 6527'-r' 6528'--reverse' 6529 Reverse the order of retrieved messages. 6530 6531'-u' 6532'--uidl' 6533 Use UIDLs to avoid downloading the same message twice. 6534 6535'-v' 6536'--verbose' 6537 Increase verbosity level. 6538 6539 The common options are also understood (*note Common Options::). 6540 6541 ---------- Footnotes ---------- 6542 6543 (1) Rmail does not use this feature 6544 6545 6546File: mailutils.info, Node: readmsg, Next: decodemail, Prev: movemail, Up: Programs 6547 65483.8 'readmsg' -- Extract Messages from a Folder 6549=============================================== 6550 6551The 'readmsg' utility extracts messages from a mailbox according to the 6552criteria specified in the command line. These criteria are: 6553 6554 1. A lone '*' means "select all messages in the mailbox". 6555 6556 2. A list of message numbers may be specified. Values of '0' and '$' 6557 in the list both mean the last message in the mailbox. For 6558 example: 6559 6560 readmsg 1 3 0 6561 6562 extracts three messages from the folder: the first, the third, and 6563 the last. 6564 6565 3. Finally, the selection may be some text to match. This will select 6566 a mail message which exactly matches the specified text. For 6567 example, 6568 6569 readmsg staff meeting 6570 6571 extracts the message which contains the words 'staff meeting'. 6572 Note that it will not match a message containing 'Staff Meeting' - 6573 the matching is case sensitive by default. This can changed using 6574 the '-i' ('--ignorecase') option. Two more options are provided to 6575 control the matching algorithm: the '-g' ('--glob') option 6576 instructs 'readmsg' to treat arguments as shell globbing patterns 6577 and the '-r' ('--regex') option instructs it to treat them as POSIX 6578 extended regular expressions. Needless to say, when using any of 6579 the two latter options, you should pay attention to escape the 6580 matching pattern to prevent it from being interpreted by the shell. 6581 E.g.: 6582 6583 readmsg --regex 'staff.*meeting' 6584 6585 Unless requested otherwise, only the first message that matches the 6586pattern is printed. 6587 6588 At least one command line argument or one informational option must 6589be present in 'readmsg' invocation. Informational options are: '--help' 6590('-?'), '--usage', and '--version' ('-V'). 6591 6592* Menu: 6593 6594* Opt-readmsg:: Invocation of 'readmsg'. 6595* Conf-readmsg:: Configuration of 'readmsg'. 6596 6597 6598File: mailutils.info, Node: Opt-readmsg, Next: Conf-readmsg, Up: readmsg 6599 66003.8.1 Invocation of 'readmsg'. 6601------------------------------ 6602 6603'-a' 6604'--show-all' 6605 If a pattern is used for selection, show all messages that match 6606 pattern by default only the first one is presented. 6607 6608'-d' 6609'--debug' 6610 Display mailbox debugging information. 6611 6612'-e' 6613'--exact' 6614 Look for messages containing exactly the words given as arguments. 6615 This is the default. Other options changing this behavior are: 6616 '--glob', '--regex', and '--ignorecase'. 6617 6618'-f MAILBOX' 6619'--folder=MAILBOX' 6620 Specified the default mailbox. 6621 6622'-g' 6623'--glob' 6624 Treat non-option arguments as shell globbing patterns. For 6625 example, to select the first message with words 'morning' and 6626 'coffee' with anything bewteen them: 6627 6628 readmsg --glob 'morning*coffee' 6629 6630 (notice quoting, which prevents the shell from interpreting the '*' 6631 prematurely). 6632 6633'-h' 6634'--header' 6635 Show the entire header and ignore the weedlist. 6636 6637'-i' 6638'--ignorecase' 6639 Ignore the case of letters when looking for matching messages. 6640 E.g.: 6641 6642 readmsg --glob --ignorecase 'morning*coffee' 6643 6644'-n' 6645'--no-header' 6646 Do not print the message header. 6647 6648'-p' 6649'--form-feed' 6650 Put form-feed (Control-L) between messages instead of newline. 6651 6652'-r' 6653'--regex' 6654 Treat non-option arguments as POSIX extended regular expressions. 6655 6656'-w WEEDLIST' 6657'--weedlist=WEEDLIST' 6658 A whitespace or coma separated list of header names to show per 6659 message. Default is '--weedlist="From Subject Date To CC 6660 Apparently-"'. 6661 6662 See also *note Common Options::. 6663 6664 6665File: mailutils.info, Node: Conf-readmsg, Prev: Opt-readmsg, Up: readmsg 6666 66673.8.2 Configuration of 'readmsg'. 6668--------------------------------- 6669 6670Following configuration statements affect the behavior of 'readmsg': 6671 6672 -- Readmsg Conf: header BOOL 6673 If BOOL is 'true', display entire headers. 6674 6675 -- Readmsg Conf: weedlist STR 6676 Set the weedlist. The STR argument is a string, containing a list 6677 of header names, separated by whitespace, commands or colons. This 6678 corresponds to the '--weedlist' command line option (*note 6679 -weedlist: Opt-readmsg.). 6680 6681 -- Readmsg Conf: no-header BOOL 6682 If BOOL is 'true', exclude all headers. 6683 6684 -- Readmsg Conf: form-feeds BOOL 6685 If BOOL is 'true', output formfeed character between messages. 6686 6687 -- Readmsg Conf: folder URL 6688 Set the URL of the mailbox folder to read. 6689 6690 -- Readmsg Conf: show-all-match BOOL 6691 If BOOL is 'true', print all messages matching pattern, not only 6692 the first. 6693 6694Statement Reference 6695------------------------------------------------------------------- 6696debug *Note Debug Statement::. 6697tls *Note TLS Statement::. 6698mailbox *Note Mailbox Statement::. 6699locking *Note Locking Statement::. 6700 6701 6702File: mailutils.info, Node: decodemail, Next: sieve, Prev: readmsg, Up: Programs 6703 67043.9 'decodemail' - Decode multipart messages 6705============================================ 6706 6707The 'decodemail' utility is a filter program that reads messages from 6708the input mailbox, decodes "textual" parts of each multipart message 6709from a base64- or quoted-printable encoding to an 8-bit or 7-bit 6710transfer encoding, and stores the processed messages in the output 6711mailbox. All messages from the input mailbox are stored in the output, 6712regardless of whether a change was made. 6713 6714 The message parts deemed to be textual are those whose 'Content-Type' 6715header matches a predefined, or user-defined, mime type pattern. In 6716addition, encoded pieces of the 'From:', 'To:', 'Subject:', etc., 6717headers are decoded. 6718 6719 For example, 'decodemail' makes this transformation: 6720 6721 Subject: =?utf-8?Q?The=20Baroque=20Enquirer=20|=20July=202020?= 6722 => Subject: The Baroque Enquirer | July 2020 6723 6724 The built-in list of textual content type patterns is: 6725 6726 text/* 6727 application/*shell 6728 application/shellscript 6729 */x-csrc 6730 */x-csource 6731 */x-diff 6732 */x-patch 6733 */x-perl 6734 */x-php 6735 */x-python 6736 */x-sh 6737 6738 These strings are matched as shell globbing patterns (*note 6739(glob(7))glob::). 6740 6741 More patterns can be added to this list using the 'mime.text-type' 6742configuration statement. *Note mime statement::, for a detailed 6743discussion, and the configuration section below for a simple example. 6744 6745 When processing old mesages you may encounter 'Content-Type' headers 6746whose value contains only type, but no subtype. To match such headers, 6747use the pattern without '/whatever' part. E.g. 'text/*' matches 6748'text/plain' and 'text/html', but does not match 'text'. On the other 6749hand, 't*xt' does not match 'text/plain', but does match 'text'. 6750 6751 Optionally, the decoded parts can be converted to another character 6752set. By default, the character set is not changed. 6753 6754* Menu: 6755 6756* Opt-decodemail:: Invocation of 'decodemail'. 6757* Conf-decodemail:: Configuration of 'decodemail'. 6758* Using-decodemail:: Purpose and caveats of 'decodemail'. 6759 6760 6761File: mailutils.info, Node: Opt-decodemail, Next: Conf-decodemail, Up: decodemail 6762 67633.9.1 Invocation of 'decodemail'. 6764--------------------------------- 6765 6766Usually, the utility is invoked as: 6767 6768 decodemail INBOX OUTBOX 6769 6770where INBOX and OUTBOX are file names or URLs of the input and output 6771mailboxes, correspondingly. The input mailbox is opened read-only and 6772will not be modified in any way. In particular, the status of the 6773processed messages will not change. If the output mailbox does not 6774exist, it will be created. If it exists, the messages will be appended 6775to it, preserving any original messages that are already in it. This 6776behavior can be changed using the '-t' ('--truncate') option, described 6777below. 6778 6779 The two mailboxes can be of different types. For example you can 6780read input from an imap server and store it in local 'maildir' box using 6781the following command: 6782 6783 decodemail imap://user@example.com maildir:///var/mail/user 6784 6785 Both arguments can be omitted. If OUTBOX is not supplied, the 6786resulting mailbox will be printed on the standard output in Unix 'mbox' 6787format. If INBOX is not supplied, the utility will open the system 6788inbox for the current user and use it for input. 6789 6790 A consequence of these rules is that there is no simple way to read 6791the input mailbox from standard input (the input must be seekable). If 6792you need to do this, the normal procedure would be to save what would be 6793standard input in a temporary file and then give that file as 6794'decodemail''s input. 6795 6796 The following command line options modify the 'decodemail' behavior: 6797 6798'-c, --charset=CHARSET' 6799 Convert all textual parts from their original character set to the 6800 specified CHARSET. 6801 6802'-R, --recode' 6803 Convert all textual parts from their original character set to the 6804 current character set, as specified by the 'LC_ALL' or 'LANG' 6805 environment variable. 6806 6807'--no-recode' 6808 Do not convert character sets. This is the default. 6809 6810'-t, --truncate' 6811 If the output mailbox exists, truncate it before appending new 6812 messages. 6813 6814'--no-truncate' 6815 Keep the existing messages in the output mailbox intact. This is 6816 the default. 6817 6818 Additionally, the *note Common Options:: are also understood. 6819 6820 6821File: mailutils.info, Node: Conf-decodemail, Next: Using-decodemail, Prev: Opt-decodemail, Up: decodemail 6822 68233.9.2 Configuration of 'decodemail'. 6824------------------------------------ 6825 6826The following common configuration statements affect the behavior of 6827'decodemail': 6828 6829Statement Reference 6830------------------------------------------------------------------- 6831mime *Note mime statement::. 6832debug *Note Debug Statement::. 6833mailbox *Note Mailbox Statement::. 6834locking *Note Locking Statement::. 6835 6836 Notably, the 'mime' statement can be used to extend the list of types 6837which are decoded. For example, in the file '~/.decodemail' (other 6838locations are possible, *note configuration::), you could have: 6839 6840 # base64/qp decode these mime types also: 6841 mime { 6842 text-type "application/x-bibtex"; 6843 text-type "application/x-tex"; 6844 } 6845 6846 Since the list of textual mime types is open-ended, with new types 6847being used at any time, we do not attempt to make the built-in list 6848comprehensive. 6849 6850 6851File: mailutils.info, Node: Using-decodemail, Prev: Conf-decodemail, Up: decodemail 6852 68533.9.3 Purpose and caveats of 'decodemail'. 6854------------------------------------------ 6855 6856The principal use envisioned for this program is to decode messages in 6857batch, after they are received. 6858 6859 Unfortunately, some mailers prefer to encode messages in their 6860entirety in base64 (or quoted-printable), even when the content is 6861entirely human-readable text. This makes straightforward use of 'grep' 6862or other standard commands impossible. The idea is for 'decodemail' to 6863rectify that, by making the message text readable again. 6864 6865 Besides personal mail, mailing list archives are another place where 6866such decoding can be useful, as they are often searched with standard 6867tools. 6868 6869 It is generally not recommended to run 'decodemail' within a mail 6870reader (which should be able to do the decoding itself), or directly in 6871a terminal (since quite possibly there will be 8-bit output not in the 6872current character set). 6873 6874 Although the output message from 'decodemail' should be entirely 6875equivalent to the input message, apart from the decoding, it is 6876generally not identical. Because 'decodemail' parses the input message 6877and reconstructs it for output, there are usually small differences: 6878 6879 * In the envelope 'From ' line, multiple spaces are collapsed to one. 6880 6881 * A 'Content-Transfer-Encoding:' header may be added where not 6882 previously present, or its value changed from '8bit' to '7bit', or 6883 vice versa. This may happen both for the message as a whole, and 6884 for a given mime part. 'decodemail' looks at the actual content of 6885 the text and outputs 'Content-Transfer-Encoding:' accordingly. 6886 6887 * A trailing space is inserted when a long header line is broken to 6888 occupy several lines ("header wrapping"). 6889 6890 SomeHeader: 6891 someextremelylongvaluethatcannotbebroken 6892 6893 * The non-tracing headers may be reordered, notably those that are 6894 mime-related. 6895 6896 * Any material before the first mime part of a mime multipart message 6897 is lost. By the standards, nothing should appear there. Typically 6898 if it does appear, it is a string such as 'This is a multi-part 6899 message in MIME format.'. 6900 6901 * In mime parts, the charset specifications may no longer be quoted 6902 (if quoting is not necessary). For example, 'charset="utf-8"' 6903 becomes 'charset=utf-8'. 6904 6905 * The mime boundary strings will be changed. 6906 6907 If a discrepancy is created which actually affects message parsing or 6908reading, that's most likely a bug, and please report it. Naturally, 6909please send an exact input message to reproduce the problem. 6910 6911 6912File: mailutils.info, Node: sieve, Next: guimb, Prev: decodemail, Up: Programs 6913 69143.10 'sieve' 6915============ 6916 6917 ================================================================== 6918 *Editor's note:* 6919 The information in this node may be obsolete or otherwise 6920 inaccurate. This message will disappear, once this node revised. 6921 ================================================================== 6922 6923 Sieve is a language for filtering e-mail messages at time of final 6924delivery, described in RFC 3028. GNU Mailutils contains stand-alone 6925"sieve interpreter", which is described in detail below. 6926 6927* Menu: 6928 6929* sieve interpreter:: A Sieve Interpreter 6930 6931 6932File: mailutils.info, Node: sieve interpreter, Up: sieve 6933 69343.10.1 A Sieve Interpreter 6935-------------------------- 6936 6937The sieve interpreter 'sieve' allows you to apply Sieve scripts to 6938arbitrary number of mailboxes. GNU 'sieve' implements a superset of the 6939Sieve language as described in RFC 3028. *Note Sieve Language::, for a 6940description of the Sieve language. *Note GNU Extensions::, for a 6941discussion of differences between the GNU implementation of Sieve and 6942its standard. 6943 6944* Menu: 6945 6946* Invoking Sieve:: 6947* Sieve Configuration:: 6948* Logging and Debugging:: 6949* Extending Sieve:: 6950 6951 6952File: mailutils.info, Node: Invoking Sieve, Next: Sieve Configuration, Up: sieve interpreter 6953 69543.10.1.1 Invoking 'sieve' 6955......................... 6956 6957The 'sieve' invocation syntax is: 6958 6959 sieve [OPTIONS] SCRIPT 6960 6961 Normally, SCRIPT is the name of the disk file with the Sieve script. 6962If SCRIPT is a single dash, the script is read from the standard input. 6963If the '-E' ('--expression') option is given, SCRIPT is taken to be the 6964sieve script text. 6965 6966where SCRIPT denotes the filename of the sieve program to parse, and 6967OPTIONS is one or more of the following: 6968 6969'-c' 6970'--compile-only' 6971 Compile script and exit. 6972 6973'--clear-library-path' 6974'--clearpath' 6975 Clear Sieve library path. See also *note clear-library-path: Sieve 6976 Configuration. 6977 6978'--clear-include-path' 6979 Clear Sieve include path. See also *note clear-include-path: Sieve 6980 Configuration. 6981 6982'-d[FLAGS]' 6983'--debug[=FLAGS]' 6984 Specify debug flags. The FLAGS argument is a sequence of one or 6985 more of the following letters: 6986 6987 'g' Enable main parser traces 6988 'T' Enable mailutils traces 6989 'P' Trace network protocols 6990 't' Enable sieve trace 6991 'i' Trace the program instructions 6992 6993'-D' 6994'--dump' 6995 Compile the script, dump disassembled code on standard output and 6996 exit. 6997 6998'--environment=NAME=VALUE' 6999 Set sieve environment variable NAME to the VALUE. 7000 7001'-e ADDRESS' 7002'--email ADDRESS' 7003 Override the user email address. This is useful for 'reject' and 7004 'redirect' actions. By default, the user email address is deduced 7005 from the user name and the full name of the machine where 'sieve' 7006 is executed. See also *note email: Sieve Configuration. 7007 7008'-E,' 7009'--expression' 7010 Treat the SCRIPT argument as Sieve program text. 7011 7012'-I DIR' 7013'--includedir=DIR' 7014 Append directory DIR to the list of directories searched for 7015 include files. See also *note include-path: Sieve Configuration. 7016 7017'-f' 7018'--mbox-url=MBOX' 7019 Mailbox to sieve (defaults to user's system mailbox). See also 7020 *note mbox-url: Sieve Configuration. 7021 7022'-k' 7023'--keep-going' 7024 Keep on going if execution fails on a message. See also *note 7025 keep-going: Sieve Configuration. 7026 7027'-L DIR' 7028'--libdir=DIR' 7029 Append directory DIR to the list of directories searched for 7030 library files. See also *note library-path: Sieve Configuration. 7031 7032'--libdir-prefix=DIR' 7033 Add DIR to the beginning of the list of directories searched for 7034 library files. 7035 7036'--line-info=BOOL' 7037 Print source location along with action logs (default). 7038 7039'-M URL' 7040'--mailer=URL' 7041 Define the URL of the default mailer. 7042 7043'-n' 7044'--no-actions' 7045'--dry-run' 7046 Dry run: do not execute any actions, just print what would be done. 7047 7048'--no-program-name' 7049 Do not prefix diagnostic messages with the program name. 7050 7051'-t TICKET' 7052'--ticket=TICKET' 7053 Ticket file for mailbox authentication. See also *note ticket: 7054 Sieve Configuration. 7055 7056'--variable=NAME=VALUE' 7057 Set Sieve variable NAME. This option automatically inserts 7058 'require "variables"' at the top of the script. 7059 7060'-v' 7061'--verbose' 7062 Log all actions executed. See also *note verbose: Sieve 7063 Configuration. 7064 7065 See also *note Common Options::. 7066 7067 7068File: mailutils.info, Node: Sieve Configuration, Next: Logging and Debugging, Prev: Invoking Sieve, Up: sieve interpreter 7069 70703.10.1.2 Sieve Configuration 7071............................ 7072 7073The behavior of 'sieve' is affected by the following configuration 7074statements: 7075 7076Statement Reference 7077------------------------------------------------------------------- 7078debug *Note debug statement::. 7079tls *Note tls statement::. 7080mailbox *Note mailbox statement::. 7081locking *Note locking statement::. 7082logging *Note logging statement::. 7083mailer *Note mailer statement::. 7084 7085 The following statements configure sieve-specific features: 7086 7087 -- Sieve Conf: sieve { ... } 7088 This block statement configures search paths 'sieve' uses to locate 7089 its loadable modules. *Note Require Statement::, for a detailed 7090 information about loadable modules. 7091 7092 This statement may contain the following sub-statements: 7093 7094 -- Sieve Conf: clear-library-path BOOL 7095 If BOOL is 'true', clear library search path. 7096 7097 -- Sieve Conf: clear-include-path BOOL 7098 If BOOL is 'true', clear include search path. 7099 7100 -- Sieve Conf: library-path PATH 7101 Add directories to 'sieve' library search path. Argument is a 7102 string containing a colon-separated list of directories. 7103 7104 -- Sieve Conf: library-path-prefix PATH 7105 Add directories to the beginning if the library search path. 7106 Argument is a string containing a colon-separated list of 7107 directories. 7108 7109 -- Sieve Conf: include-path PATH 7110 Add directories to the include search path. Argument is a 7111 string containing a colon-separated list of directories. 7112 7113 -- Sieve Conf: keep-going BOOL 7114 If BOOL is 'true', do not abort if execution of a Sieve script 7115 fails on a particular message. 7116 7117 -- Sieve Conf: mbox-url URL 7118 Sets URL of the mailbox to be processed. 7119 7120 -- Sieve Conf: ticket FILE 7121 Sets the name of the ticket file for user authentication. 7122 7123 -- Sieve Conf: debug FLAGS 7124 Sets Sieve debug flags. *Note Logging and Debugging::, for a 7125 detailed description. 7126 7127 -- Sieve Conf: verbose BOOL 7128 If BOOL is 'true', log all executed actions. 7129 7130 -- Sieve Conf: line-info BOOL 7131 If BOOL is 'true', print source locations along with action logs. 7132 This statement takes effect only if 'verbose true' is also set. 7133 7134 -- Sieve Conf: email ADDR 7135 Set user e-mail address. This is useful for 'reject' and 7136 'redirect' actions. By default, the user email address is deduced 7137 from the user name and the full name of the machine where 'sieve' 7138 is executed. 7139 7140 7141File: mailutils.info, Node: Logging and Debugging, Next: Extending Sieve, Prev: Sieve Configuration, Up: sieve interpreter 7142 71433.10.1.3 Logging and debugging 7144.............................. 7145 7146The default behavior of 'sieve' is to remain silent about anything 7147except errors. However, it is sometimes necessary to see which actions 7148are executed and on which messages. This is particularly useful when 7149debugging the sieve scripts. The '--verbose' ('-v') option outputs log 7150of every action executed. 7151 7152 Option '--debug' allows to produce even more detailed debugging 7153information. This option takes an argument specifying the debugging 7154level to be enabled. The argument can consist of the following letters: 7155 7156't' 7157 This flag enables sieve tracing. It means that every test will be 7158 logged when executed. 7159 7160'T' 7161 This flag enables debugging of underlying 'mailutils' library. 7162 7163'P' 7164 Trace network protocols: produces log of network transactions 7165 executed while running the script. 7166 7167'g' 7168 Enable main parser traces. This is useful for debugging the sieve 7169 grammar. 7170 7171'i' 7172 Trace the program instructions. It is the most extensive debugging 7173 level. It produces the full execution log of a sieve program, 7174 showing each instruction and states of the sieve machine. It is 7175 only useful for debugging the code generator. 7176 7177 _Note_, that there should be no whitespace between the short variant 7178of the option ('-d'), and its argument. Similarly, when using long 7179option ('--debug'), its argument must be preceded by equal sign. 7180 7181 If the argument to '--debug' is omitted, it defaults to 'TPt'. 7182 7183 Option '--dump' produces the disassembled dump of the compiled sieve 7184program. 7185 7186 By default 'sieve' outputs all diagnostics on standard error and 7187verbose logs on standard output. This behaviour is changed when 7188'--log-facility' is given in the command line (see logging). This 7189option causes 'sieve' to output its diagnostics to the given syslog 7190facility. 7191 7192 7193File: mailutils.info, Node: Extending Sieve, Prev: Logging and Debugging, Up: sieve interpreter 7194 71953.10.1.4 Extending 'sieve' 7196.......................... 7197 7198The basic set of sieve actions, tests and comparators may be extended 7199using loadable extensions. The usual 'require' mechanism is used for 7200that. 7201 7202 When processing arguments for 'require' statement, 'sieve' uses the 7203following algorithm: 7204 7205 1. Look up the name in a symbol table. If the name begins with 7206 'comparator-' it is looked up in the comparator table. If it 7207 begins with 'test-', the test table is searched instead. Otherwise 7208 the name is looked up in the action table. 7209 7210 2. If the name is found, the search is terminated. 7211 7212 3. Otherwise, transform the name. First, any 'comparator-' or 'test-' 7213 prefix is stripped. Then, any character other than alphanumeric 7214 characters, '.' and ',' is replaced with dash ('-'). The name thus 7215 obtained is used as a file name of an external loadable module. 7216 7217 4. Try to load the module. The module is searched in the following 7218 search paths (in the order given): 7219 7220 1. Mailutils module directory. By default it is 7221 '$prefix/lib/mailutils'. 7222 7223 2. The value of the environment variable 'LTDL_LIBRARY_PATH'. 7224 7225 3. Additional search directories specified with the. 7226 '--libdir-prefix' command line option (*note libdir-prefix: 7227 Invoking Sieve.), or the 'library-path-prefix' configuration 7228 statement (*note library-path-prefix: Sieve Configuration.). 7229 7230 4. Additional search directories specified with the 7231 'library-path' statement (*note library-path: Sieve 7232 Configuration.) in Sieve configuration file. 7233 7234 5. Additional search directories specified with the. '--libdir' 7235 command line option (*note libdir: Invoking Sieve.). 7236 7237 6. Additional search directories specified with the '#searchpath' 7238 Sieve directive (*note #searchpath::). 7239 7240 7. System library search path: The system dependent library 7241 search path (e.g. on Linux it is set by the contents of the 7242 file '/etc/ld.so.conf' and the value of the environment 7243 variable 'LD_LIBRARY_PATH'). 7244 7245 The value of 'LTDL_LIBRARY_PATH' and 'LD_LIBRARY_PATH' must be a 7246 colon-separated list of absolute directories, for example, 7247 '"/usr/lib/mypkg:/lib/foo"'. 7248 7249 In any of these directories, 'sieve' first attempts to find and 7250 load the given filename. If this fails, it tries to append the 7251 following suffixes to the file name: 7252 7253 1. the libtool archive extension '.la' 7254 7255 2. the extension used for native dynamic libraries on the host 7256 platform, e.g., '.so', '.sl', etc. 7257 7258 5. If the module is found, 'sieve' executes its initialization 7259 function (see below) and again looks up the name in the symbol 7260 table. If found, search terminates successfully. 7261 7262 6. If either the module is not found, or the symbol wasn't found after 7263 execution of the module initialization function, search is 7264 terminated with an error status. 'sieve' then displays the 7265 following diagnostic message: 7266 7267 source for the required action NAME is not available 7268 7269 7270File: mailutils.info, Node: guimb, Next: mda, Prev: sieve, Up: Programs 7271 72723.11 'guimb' -- A Mailbox Scanning and Processing Language 7273========================================================== 7274 7275'Guimb' is an experimental tool that iterates over messages in a mailbox 7276(or several mailboxes), applying a Scheme function to each of them. 7277 7278 A user-defined "scheme module" that supplies the function to apply is 7279specified using the '--source' or '--file' option. The module must 7280define at least the following function: 7281 7282 -- User function: guimb-message MSG 7283 Processes message MSG. This function can alter the message using 7284 Guile primitives supplied by mailutils. 7285 7286 The following function definitions are optional: 7287 7288 -- User function: guimb-getopt ARGS 7289 If defined, this function is called after 'guimb' has finished 7290 processing the command line. ARGS is a list of unconsumed command 7291 line arguments. 7292 7293 The function is intended to provide a way of configuring the module 7294 from the command line. 7295 7296 -- User function: guimb-end 7297 If defined, this function is called after all mailboxes have been 7298 processed. 7299 7300 In the following example we define a module that prints information 7301about each message is the input mailbox, in a way similar to 'frm' 7302utility: 7303 7304 (define-module (frm) 7305 :export (guimb-message)) 7306 7307 (use-modules (mailutils mailutils)) 7308 7309 (define (guimb-message msg) 7310 (display (mu-message-get-sender msg)) 7311 (display " ") 7312 (display (mu-message-get-header msg "subject")) 7313 (newline)) 7314 7315 The modules are looked up in directories listed in the global 7316variable '%load-path'. New directories can be added to that variable on 7317the fly using the '-L' ('--load-path') option. For example, if the 7318sample module above was saved in a file 'frm.scm' somewhere in the load 7319path, it can be applied to the current user inbox by running the 7320following command: 7321 7322 guimb --file frm 7323 7324* Menu: 7325 7326* Specifying Scheme Program to Execute:: 7327* Specifying Mailboxes to Operate Upon:: 7328* Passing Options to Scheme:: 7329* Command Line Option Summary:: 7330 7331 7332File: mailutils.info, Node: Specifying Scheme Program to Execute, Next: Specifying Mailboxes to Operate Upon, Up: guimb 7333 7334Specifying Scheme Program to Execute 7335------------------------------------ 7336 7337The Scheme module that defines message processing functions is given via 7338the following options: 7339 7340'-s MODULE' 7341'--source MODULE' 7342 Load Scheme code from MODULE. 7343 7344 This option stops further argument processing, and passes all 7345 remaining arguments as the value of ARGS argument to the 7346 'guimb-getopt' function, if it is defined. 7347 7348'-f MODULE' 7349'--file MODULE' 7350 Load Scheme source code from MODULE. The remaining arguments are 7351 processed in the usual way. When using this option, you can pass 7352 additional options and or arguments to the module by enclosing them 7353 in '-{' and '-}' options (*note Passing Options to Scheme::). 7354 7355 An experimental option is provided, that evaluates a supplied Scheme 7356expression right after loading the module: 7357 7358'-e EXPR' 7359'--expression EXPR' 7360 Evaluate scheme expression. 7361 7362 7363File: mailutils.info, Node: Specifying Mailboxes to Operate Upon, Next: Passing Options to Scheme, Prev: Specifying Scheme Program to Execute, Up: guimb 7364 7365Specifying Mailboxes to Operate Upon 7366------------------------------------ 7367 7368There are four basic ways of passing mailboxes to 'guimb'. 7369 7370'guimb [OPTIONS] [MAILBOX...]' 7371 The resulting mailbox is not saved, unless the user-supplied scheme 7372 program saves it. 7373'guimb [OPTIONS] --mailbox DEFMBOX' 7374 The contents of DEFMBOX is processed and is replaced with the 7375 resulting mailbox contents. Useful for applying filters to user's 7376 mailbox. 7377'guimb [OPTIONS] --mailbox DEFMBOX MAILBOX [MAILBOX...]' 7378 The contents of specified mailboxes is processed, and the resulting 7379 mailbox contents is appended to DEFMBOX. 7380'guimb [OPTIONS] --user USERNAME [MAILBOX...]' 7381 The contents of specified mailboxes is processed, and the resulting 7382 mailbox contents is appended to the user's system mailbox. This 7383 makes it possible to use 'guimb' as a mail delivery agent. 7384 7385 If no mailboxes are specified in the command line, 'guimb' reads and 7386processes the system mailbox of the current user. 7387 7388 7389File: mailutils.info, Node: Passing Options to Scheme, Next: Command Line Option Summary, Prev: Specifying Mailboxes to Operate Upon, Up: guimb 7390 7391Passing Options to Scheme 7392------------------------- 7393 7394Sometimes it is necessary to pass some command line options to the 7395scheme procedure. There are three ways of doing so. 7396 7397 When using '--source' ('-s') option, the rest of the command line 7398following the option's argument is passed as the ARGS argument to the 7399'guimb-getopt' function, if such function is defined. This allows for 7400making guimb scripts executable by the shell. If your system supports 7401'#!' magic at the start of scripts, add the following two lines to the 7402beginning of your script to allow for its immediate execution: 7403 7404 #! /usr/local/bin/guimb -s 7405 !# 7406 7407(replace '/usr/local/bin/' with the actual path to the 'guimb'). 7408 7409 Otherwise, if you use the '--file' option, the additional arguments 7410can be passed to the Scheme program '-g' ('--guile-arg') command line 7411option. For example: 7412 7413 guimb --guile-arg -opt --guile-arg 24 --file PROGFILE 7414 7415 In this example, the 'guimb-getopt' function will get the following 7416argument 7417 7418 ( '-opt' 24 ) 7419 7420 Finally, if there are many arguments to be passed to Scheme, it is 7421more convenient to enclose them in '-{' and '-}' escapes: 7422 7423 guimb -{ -opt 24 -} --file PROGFILE 7424 7425 7426File: mailutils.info, Node: Command Line Option Summary, Prev: Passing Options to Scheme, Up: guimb 7427 7428Command Line Option Summary 7429--------------------------- 7430 7431This is a short summary of the command line options available to 7432'guimb'. 7433 7434'-d' 7435'--debug' 7436 Start with debugging evaluator and backtraces. 7437'-e EXPR' 7438'--expression EXPR' 7439 Execute given Scheme expression. 7440'-L DIR' 7441'--load-path DIR' 7442 Insert DIR at the beginning of the '%load-path' list. The argument 7443 is either a single directory name, or a list of such names, 7444 delimited by ':' characters. 7445'-m PATH' 7446'--mail-spool=PATH' 7447 Set path to the mailspool directory 7448'-f PROGFILE' 7449'--file PROGFILE' 7450 Read Scheme program from PROGFILE. 7451'-g ARG' 7452'--guile-command ARG' 7453 Append ARG to the command line passed to Scheme program. 7454'-{ ... -}' 7455 Pass all command line options enclosed between '-{' and '-}' to 7456 Scheme program. 7457'-m' 7458'--mailbox MBOX' 7459 Set default mailbox name. 7460'-u' 7461'--user NAME' 7462 Act as local MDA for user NAME. 7463'-h' 7464'--help' 7465 Display help message. 7466'-v' 7467'--version' 7468 Display program version. 7469 7470 7471File: mailutils.info, Node: mda, Next: lmtpd, Prev: guimb, Up: Programs 7472 74733.12 mda 7474======== 7475 7476GNU local mail delivery agent reads a message from its standard input 7477and delivers it to one or more local recipients listed in the command 7478line. When we speak about local recipients, we mean that these are 7479system users that are known to the system that runs 'mda'. However, the 7480mailboxes of these users can be local as well as remote ones. 'mda' is 7481able to deliver mail to any mailbox format, supported by GNU Mailutils. 7482These formats, among others, include 'smtp://', 'prog://' and 7483'sendmail://' which are equivalent to forwarding a message over SMTP to 7484a remote node. 7485 7486 'Mda' is also able to process incoming messages using Sieve, Scheme 7487or Python scripts and, based on results of this processing, to take a 7488decision on whether to actually deliver and where to deliver them. Due 7489to its extensive scripting facilities, 'mda' offers much more 7490flexibility than other popular MDAs. 7491 7492* Menu: 7493 7494* Sendmail-mda:: Using 'mda' with Sendmail. 7495* Exim-mda:: Using 'mda' with Exim. 7496* MeTA1-mda:: Using 'mda' with MeTA1. 7497* Mailbox Quotas:: 7498* MDA Scripting:: 7499* Forwarding:: 7500* Conf-mda:: 'mda' Configuration File Summary. 7501* Mailing lists:: How to implement Mailing Lists with 'mda'. 7502 7503 7504File: mailutils.info, Node: Sendmail-mda, Next: Exim-mda, Up: mda 7505 75063.12.1 Using 'mda' with Sendmail. 7507--------------------------------- 7508 7509When used with Sendmail, 'mda' must be invoked from the local mailer 7510definition in the 'sendmail.cf' file. The flags 'lswS' must be set for 7511the mailer. These mean: the mailer is local, quote characters should be 7512stripped off the address before invoking the mailer, the user must have 7513a valid account on this machine and the userid should not be reset 7514before calling the mailer. Additionally, the 'fn' flags may be 7515specified to allow 'mda' to generate the usual 'From ' envelope instead 7516of the one supplied by 'sendmail'. 7517 7518 If you wish to use 'mda' with non-local authentication, such as SQL 7519or LDAP, you also need to remove the 'w' flag, since in that case the 7520user is not required to have a valid account on the machine that runs 7521'sendmail'. 7522 7523 Here is an example of mailer definition in 'sendmail.cf' 7524 7525 Mlocal, P=/usr/local/sbin/mda, 7526 F=lsDFMAw5:/|@qSPfhn9, 7527 S=EnvFromL/HdrFromL, R=EnvToL/HdrToL, 7528 T=DNS/RFC822/X-Unix, 7529 A=mail $u 7530 7531 To define local mailer in 'mc' source file, it will suffice to set: 7532 7533 define(`LOCAL_MAILER_PATH', `/usr/local/sbin/mda') 7534 define(`LOCAL_MAILER_ARGS', `mail $u') 7535 7536 7537File: mailutils.info, Node: Exim-mda, Next: MeTA1-mda, Prev: Sendmail-mda, Up: mda 7538 75393.12.2 Using 'mda' with Exim. 7540----------------------------- 7541 7542Using 'mda' with Exim is quite straightforward. The following example 7543illustrates the definition of the appropriate transport and director in 7544'exim.conf': 7545 7546 # transport 7547 mda_pipe: 7548 driver = pipe 7549 command = /usr/local/sbin/mda $local_part 7550 return_path_add 7551 delivery_date_add 7552 envelope_to_add 7553 7554 # director 7555 mda: 7556 driver = localuser 7557 transport = mda_pipe 7558 7559 7560File: mailutils.info, Node: MeTA1-mda, Next: Mailbox Quotas, Prev: Exim-mda, Up: mda 7561 75623.12.3 Using 'mda' with MeTA1. 7563------------------------------ 7564 7565MeTA1 (<http://meta1.org>) communicates with the delivery agent using 7566LMTP. Instead of using 'mda' you will have to start the LMTP daemon 7567'lmtpd' and configure MeTA1 to communicate with it. *Note 7568MeTA1-lmtpd::, for details. 7569 7570 7571File: mailutils.info, Node: Mailbox Quotas, Next: MDA Scripting, Prev: MeTA1-mda, Up: mda 7572 75733.12.4 Mailbox Quotas 7574--------------------- 7575 7576"Mailbox quota" is a limit on the size of the mailbox. When a mailbox 7577size reaches this limit, 'mda' stops accepting messages for this 7578recipient and returns an error condition to the sender. The error code 7579is accompanied by the following error message: 7580 7581 USER: mailbox quota exceeded for this recipient 7582 7583 Furthermore, if accepting the incoming message would make the mailbox 7584size exceed the quota, such a message will be rejected as well. In this 7585case, the error message is: 7586 7587 USER: message would exceed maximum mailbox size for this recipient 7588 7589 In both cases, the default return code will be 'service unavailable' 7590(corresponding to the SMTP return code '550'), unless the following 7591statement is present in the 'maidag' configuration file: 7592 7593 quota { 7594 exit-tempfail yes; 7595 } 7596 7597in which case a temporary error will be returned. 7598 7599 The mailbox quota can be retrieved from the following sources: 7600 7601 1. Authentication method. 7602 2. DBM file. 7603 3. SQL database. 7604 7605* Menu: 7606 7607* DBM Quotas:: Keeping Quotas in DBM File. 7608* SQL Quotas:: Keeping Quotas in SQL Database. 7609 7610 7611File: mailutils.info, Node: DBM Quotas, Next: SQL Quotas, Up: Mailbox Quotas 7612 76133.12.4.1 Keeping Quotas in DBM File 7614................................... 7615 7616To use DBM quota database, GNU Mailutils must be compiled with one of 7617the following command line options: '--with-gdbm', '--with-berkeley-db', 7618'--with-ndbm', '--with-tokyocabinet', or '--with-kyotocabinet'. Examine 7619the output of 'mda --show-config-options', if not sure. 7620 7621 The quota database should have the following structure: 7622 7623Key 7624 Key represents the user name. Special key 'DEFAULT' means default 7625 quota value, i.e. the one to be used if the user is not explicitly 7626 listed in the database. 7627 7628Value 7629 Mailbox quota for this user. If it is a number, it represents the 7630 maximum mailbox size in bytes. A number may optionally be followed 7631 by 'kb' or 'mb', meaning kilobytes and megabytes, respectively. 7632 7633 A special value 'NONE' means no mailbox size limit for this user. 7634 7635 Here is an example of a quota database in text form: 7636 7637 # Default quota value: 7638 DEFAULT 5mb 7639 7640 # Following users have unlimited mailbox size 7641 root NONE 7642 smith NONE 7643 7644 # Rest of users 7645 plog 26214400 7646 karin 10mB 7647 7648 To use the DBM quota database, specify its absolute name using the 7649'database' configuration statement in the 'quota' section, e.g.: 7650 7651 quota { 7652 database /etc/mail/quota.db; 7653 } 7654 7655 7656File: mailutils.info, Node: SQL Quotas, Prev: DBM Quotas, Up: Mailbox Quotas 7657 76583.12.4.2 Keeping Quotas in SQL Database 7659....................................... 7660 7661User quotas can be kept in an SQL table as well. Currently (as of 7662mailutils version 3.13) it is assumed that this table can be accessed 7663using the credentials set in 'sql' configuration statement (*note SQL 7664Statement::). 7665 7666 For example, suppose you have the following quota table: 7667 7668 create table mailbox_quota ( 7669 user_name varchar(32) binary not null, 7670 quota int, 7671 unique (user_name) 7672 ); 7673 7674 7675 To retrieve user quota the following query can be used: 7676 7677 SELECT quota FROM mailbox_quota WHERE user_name='${user}' 7678 7679 To define this query use the 'sql-query' statement: 7680 7681 quota { 7682 sql-query "SELECT quota " 7683 "FROM mailbox_quota " 7684 "WHERE user_name='${user}'"; 7685 } 7686 7687 There are no special provisions for specifying group quotas, similar 7688to 'DEFAULT' in DBM databases. This is because group quotas can easily 7689be implemented using SQL language. 'Mda' always uses the first tuple 7690from the set returned by mailbox quota query. So, you can add a special 7691entry to the 'mailbox_quota' table that would keep the group quota. In 7692the discussion below we assume that the 'user_name' column for this 7693entry is lexicographically less than any other user name in the table. 7694Let's suppose the group quota name is '00DEFAULT'. Then the following 7695query: 7696 7697 SELECT quota 7698 FROM mailbox_quota 7699 WHERE user_name IN ('${user}','00DEFAULT') 7700 ORDER BY user_name DESC 7701 7702will return two tuples if the user is found in 'mailbox_quota'. Due to 7703'ORDER' statement, the first tuple will contain quota for the user, 7704which will be used by 'mda'. On the other hand, if the requested user 7705name is not present in the table, the above query will return a single 7706tuple containing the group quota. 7707 7708 The following configuration statement instructs 'maidag' to use this 7709query for retrieving the user quota: 7710 7711 quota { 7712 sql-query "SELECT quota " 7713 "FROM mailbox_quota " 7714 "WHERE user_name IN ('${user}','00DEFAULT') " 7715 "ORDER BY user_name DESC"; 7716 } 7717 7718 7719File: mailutils.info, Node: MDA Scripting, Next: Forwarding, Prev: Mailbox Quotas, Up: mda 7720 77213.12.5 Scripting in 'mda' 7722------------------------- 7723 7724'Mda' can use global or per-user "mail filters" to decide whether to 7725deliver the message, and where to deliver it. As of Mailutils version 77263.13, such mail filters may be written in the following languages: 7727 7728 * Sieve *Note Sieve Language::. 7729 7730 * Scheme 7731 * Python 7732 7733 Mail filters to use are specified using 'script' configuration 7734statement. The following meta-symbols can be used in its argument: 7735 7736~ 7737%h 7738 Expands to the recipient home directory. 7739 7740%u 7741 Expands to the recipient user name. 7742 7743 By default, the filename extension decides which scripting language 7744will be used. User can alter the choice using 'language' configuration 7745statement. For example: 7746 7747 script { 7748 language python; 7749 pattern "~/.maidag-py-filter"; 7750 } 7751 7752* Menu: 7753 7754* Sieve MDA Filters:: 7755* Scheme MDA Filters:: 7756* Python MDA Filters:: 7757 7758 7759File: mailutils.info, Node: Sieve MDA Filters, Next: Scheme MDA Filters, Up: MDA Scripting 7760 77613.12.5.1 Sieve MDA Filters 7762.......................... 7763 7764The file name of the Sieve filter to use is specified using 'script' 7765configuration statement. For example, the following configuration 7766statement: 7767 7768 script { 7769 pattern "~/.maidag.sv"; 7770 } 7771 7772instructs 'maidag' to use file '.maidag.sv' in the recipient home 7773directory as a Sieve filter. 7774 7775 Normal message delivery is attempted if execution of the Sieve code 7776ended with 'keep' action (either implicit or explicit). 7777 7778 Other Sieve actions are executed as described in *note Actions::. 7779For example, to deliver message to another mailbox, use the 'fileinto' 7780action. 7781 7782 Any modifications to headers or body of the message performed by the 7783Sieve code will be visible in the delivered message. 7784 7785 7786File: mailutils.info, Node: Scheme MDA Filters, Next: Python MDA Filters, Prev: Sieve MDA Filters, Up: MDA Scripting 7787 77883.12.5.2 Scheme MDA Filters 7789........................... 7790 7791The file name of the Scheme mail filter is specified using 'script' 7792configuration statement. For example, the following configuration 7793statement: 7794 7795 script { 7796 pattern "~/.maidag.scm"; 7797 } 7798 7799instructs 'mda' to use file '.maidag.scm' in the recipient home 7800directory as a Scheme filter. 7801 7802 7803File: mailutils.info, Node: Python MDA Filters, Prev: Scheme MDA Filters, Up: MDA Scripting 7804 78053.12.5.3 Python MDA Filters 7806........................... 7807 7808The file name of the Python mail filter is specified using 'script' 7809configuration statement. For example, the following configuration 7810statement: 7811 7812 script { 7813 pattern "~/.maidag.py"; 7814 } 7815 7816instructs 'mda' to use the file '.maidag.py' in the recipient home 7817directory as a Python filter. 7818 7819A simple example of a mail filter written in Python: 7820 7821 from mailutils import * 7822 import maidag 7823 import re 7824 7825 msg = message.Message (maidag.message) 7826 hdr = msg.header 7827 7828 try: 7829 if 'List-Post' in hdr and 'Received' in hdr \ 7830 and hdr['Received'].find ('fencepost.gnu.org') != -1: 7831 7832 # check envelope's sender address 7833 m = re.search (r'([\w\-]+)-bounces\+([\w]+)=.*', 7834 msg.envelope.get_sender ()) 7835 if m: 7836 lbox = m.group (1) 7837 user = m.group (2) 7838 # open destination mailbox and append message 7839 dst = mailbox.MailboxDefault ('~/Mail/%s' % lbox) 7840 dst.open ('ac') 7841 dst.append_message (msg) 7842 dst.close () 7843 # set deleted flag so maidag will not deliver msg elsewhere 7844 msg.attribute.set_deleted () 7845 except Exception: 7846 pass 7847 7848 7849File: mailutils.info, Node: Forwarding, Next: Conf-mda, Prev: MDA Scripting, Up: mda 7850 78513.12.6 Forwarding 7852----------------- 7853 7854A "forward file" is a special file in the user's home directory that 7855contains the email address of the mailbox where the user wants to 7856forward his mail. Normally, forward files are processed by MTA. 7857However, there are some MTA that lack this feature. One of them is 7858MeTA1. 7859 7860 'Mda' provides a forwarding feature that is useful to compensate the 7861lack of it. This feature is controlled by the 'forward' section in the 7862configuration file: 7863 7864 forward { 7865 # Process forward file. 7866 file NAME; 7867 # Configure safety checks for the forward file. 7868 file-checks (LIST); 7869 } 7870 7871 The name of the forward file is given by the 'file' statement in the 7872'forward' section. A common usage is: 7873 7874 forward { 7875 file .forward; 7876 } 7877 7878 The forward file is always searched in the recipient home directory. 7879 7880 Before actually using the forward file, a number of safety checks are 7881performed on it. If the file fails to pass one of these checks, no 7882forwarding is performed and the message is delivered as usual. These 7883checks are configured using the 'forward.file-checks' statement: 7884 7885 forward { 7886 file .forward; 7887 file-checks (LIST); 7888 } 7889 7890 Its argument is a list of the following keywords: 7891 7892groupwritablefile 7893file_iwgrp 7894 The file must not be group writable. 7895 7896worldwritablefile 7897file_iwoth 7898 The file must not be world writable. 7899 7900linkedfileinwritabledir 7901link 7902 The file cannot be a symlink in a writable directory. 7903 7904fileingroupwritabledir 7905dir_iwgrp 7906 The file cannot reside in a group writable directory. 7907 7908fileinworldwritabledir 7909dir_iwoth 7910 The file cannot reside in a world writable directory. 7911 7912all 7913 All of the above checks. 7914 7915 The default is 'file-checks all'. 7916 7917 Each of these keywords may be prefixed by 'no' to disable this 7918particular check. For example: 7919 7920 forward { 7921 file-checks (nodir_iwoth, nodir_iwgrp); 7922 file .forward; 7923 } 7924 7925 7926File: mailutils.info, Node: Conf-mda, Next: Mailing lists, Prev: Forwarding, Up: mda 7927 79283.12.7 MDA Configuration File Summary 7929------------------------------------- 7930 7931The behavior of 'mda' is affected by the following configuration 7932statements: 7933 7934Statement Reference 7935------------------------------------------------------------------- 7936debug *Note debug statement::. 7937mailbox *Note mailbox statement::. 7938locking *Note locking statement::. 7939pam *Note pam statement::. 7940sql *Note sql statement::. 7941virtdomain *Note virtdomain statement::. 7942radius *Note radius statement::. 7943ldap *Note ldap statement::. 7944auth *Note auth statement::. 7945mailer *Note mailer statement::. 7946 7947 -- MDA Config: stderr BOOL 7948 If BOOL is true, log to standard error instead of syslog. 7949 7950 -- MDA Config: deliver { ... } 7951 This section contains general delivery settings: 7952 7953 deliver { 7954 domain STRING; 7955 exit-multiple-delivery-success ARG; 7956 }; 7957 7958 -- deliver: domain NAME 7959 Default email domain. 7960 7961 -- deliver: exit-multiple-delivery-success ARG; 7962 In case of multiple delivery, exit with code 0 if at least one 7963 delivery succeeded. 7964 7965 -- MDA Config: forward { ... } 7966 Controls the forwarding support: 7967 7968 forward { 7969 file NAME; 7970 file-checks (LIST); 7971 } 7972 7973 -- forward: file NAME 7974 Defines the name of the forward file. E.g.: 7975 7976 forward { 7977 file .forward; 7978 } 7979 7980 *Note Forwarding::, for a detailed description. 7981 7982 -- forward: file-checks (LIST) 7983 Configures safety checks to be performed on the forward file prior 7984 to using it. *Note Forwarding::, for a detailed description. 7985 7986 -- MDA Config: quota { ... } 7987 This section configures mail quota support. *Note Mailbox 7988 Quotas::, for a detailed description. 7989 7990 quota { 7991 database NAME; 7992 sql-query QUERY; 7993 exit-tempfail BOOL; 7994 } 7995 7996 -- quota: database NAME 7997 Sets the name of the quota database in DBM format. *Note DBM 7998 Quotas::. 7999 8000 -- quota: sql-query QUERY 8001 If the quotas are kept in a SQL table, this statement defines the 8002 SQL query to retrieve the quota for a given user name. *Note SQL 8003 Quotas::. 8004 8005 -- quota: exit-tempfail BOOL 8006 By default, if a message cannot be delivered because the user has 8007 exceeded its mail quota, or its delivery would cause it to be 8008 exceeded, 'MDA' exits with the 'service unavailable' status, which 8009 causes MTA to return the 550 code. If 'exit-tempfail' is set to 8010 true, it will return a temporary error instead. 8011 8012 -- MDA Config: script { ... } 8013 Controls scripting. *Note MDA Scripting::. 8014 8015 script { 8016 language LANG; 8017 pattern GLOB; 8018 } 8019 8020 -- script: language LANG 8021 Defines the language that is used for scripting. Allowed values 8022 for LANG are: 'sieve', 'scheme', or 'python'. *Note scripting 8023 language::. 8024 8025 -- script: pattern PAT 8026 Defines the pattern for the script file name. The '~' at the 8027 begiining of the pattern will be replaced with the name of the home 8028 directory of the recipient user. The '%u' in pattern will be 8029 replaced with the recipient user name, and '%h' with the home 8030 directory for that user. 8031 8032 8033File: mailutils.info, Node: Mailing lists, Prev: Conf-mda, Up: mda 8034 80353.12.8 Mailing list implementation 8036---------------------------------- 8037 8038This subsection explains how to implement mailing lists in 'mda' using 8039the 'prog' mailbox scheme. 8040 8041 Delivery to the 'prog' mailbox results in invoking the specified 8042command with the given arguments and passing the message to its standard 8043input. There are two ways to specify a 'prog' mailbox: 8044 8045prog://PROGRAM?ARGS 8046 Here, PROGRAM is the absolute pathname of the program binary, and 8047 ARGS are its arguments, separated by '&' signs. 8048 8049|PROGRAM ARGS 8050 In this notation, ARGS are command line arguments separated by 8051 white space. 8052 8053 In both cases, ARGS do not include 'argv[0]'. 8054 8055 The 'prog' mailbox can be used to implement mailing lists. 8056 8057 For example, suppose that the 'mda' configuration contains: 8058 8059 auth { 8060 authorization (sql, system); 8061 authentication (generic, system); 8062 } 8063 8064 sql { 8065 interface mysql; 8066 db mail; 8067 getpwnam "SELECT user as name, mailbox, " 8068 "'x' as passwd, 500 as uid, 2 as gid, " 8069 "'/nonexistent' as dir, '/sbin/nologin' as shell " 8070 "FROM userdb " 8071 "WHERE user='${user}'"; 8072 } 8073 8074 Then, the following entries in the 'userdb' table implement the 8075<mailman@yourdomain> mailing list: 8076 8077 mysql> select * from userdb; 8078 +---------------------+---------------------------------------+ 8079 | user | mailbox | 8080 +---------------------+---------------------------------------+ 8081 | mailman | |/usr/bin/mailman post mailman | 8082 | mailman-admin | |/usr/bin/mailman admin mailman | 8083 | mailman-bounces | |/usr/bin/mailman bounces mailman | 8084 | mailman-confirm | |/usr/bin/mailman confirm mailman | 8085 | mailman-join | |/usr/bin/mailman join mailman | 8086 | mailman-leave | |/usr/bin/mailman leave mailman | 8087 | mailman-owner | |/usr/bin/mailman owner mailman | 8088 | mailman-request | |/usr/bin/mailman request mailman | 8089 | mailman-subscribe | |/usr/bin/mailman subscribe mailman | 8090 | mailman-unsubscribe | |/usr/bin/mailman unsubscribe mailman | 8091 +---------------------+---------------------------------------+ 8092 8093 8094File: mailutils.info, Node: lmtpd, Next: putmail, Prev: mda, Up: Programs 8095 80963.13 lmtpd 8097========== 8098 8099The LMTP is a local mail transport protocol defined in RFC 2033. GNU 8100Mailutils is shipped with 'lmtpd' - a daemon for delivering messages 8101using this protocol. 8102 8103 The daemon shares most of its codebase and configuration with 'mda' 8104and consequently provides the same features. *Note mda::, for a 8105detailed description of these. 8106 8107 The behavior of 'lmtpd' is affected by the following configuration 8108statements: 8109 8110Statement Reference 8111------------------------------------------------------------------- 8112server *Note Server Settings:: 8113acl *Note acl statement::. 8114tcp-wrappers *Note tcp-wrappers statement::. 8115debug *Note debug statement::. 8116mailbox *Note mailbox statement::. 8117locking *Note locking statement::. 8118pam *Note pam statement::. 8119sql *Note sql statement::. 8120virtdomain *Note virtdomain statement::. 8121radius *Note radius statement::. 8122ldap *Note ldap statement::. 8123auth *Note auth statement::. 8124mailer *Note mailer statement::. 8125 8126* Menu: 8127 8128* MeTA1-lmtpd:: Using 'lmtpd' with MeTA1. 8129 8130 8131File: mailutils.info, Node: MeTA1-lmtpd, Up: lmtpd 8132 81333.13.1 Using 'lmtpd' with MeTA1. 8134-------------------------------- 8135 8136MeTA1 (<http://meta1.org>) communicates with the delivery agent using 8137LMTP. 8138 8139 The socket to listen for LMTP requests must be specified using the 8140'server' statement (*note Server Settings::). For the purposes of this 8141section, let's suppose 'lmtpd' will listen on a UNIX socket 8142'/var/spool/meta1/lmtpsock'. Then, the following (minimal) 'lmtpd' 8143configuration will do the job: 8144 8145 # Run as daemon. 8146 mode daemon; 8147 # Switch to this group after startup. 8148 group meta1c; 8149 # Configure server: 8150 server unix:///var/spool/meta1/lmtpsock { 8151 transcript no; 8152 }; 8153 8154 To configure MeTA1 to use this socket, add the following statement to 8155the 'smtpc' section in '/etc/meta1/meta1.conf': 8156 8157 LMTP_socket="lmtpsock"; 8158 8159 8160File: mailutils.info, Node: putmail, Next: mimeview, Prev: lmtpd, Up: Programs 8161 81623.14 putmail 8163============ 8164 8165The 'putmail' utility reads a message from its standard input and 8166delivers it to the specified mailbox URL. The usage is: 8167 8168 putmail URL 8169 8170 For example, to deliver mail to a local mailbox 8171'/var/spool/mail/test': 8172 8173 putmail /var/spool/mail/test 8174 8175 Of course, this would work only it the 'test' mailbox is writable for 8176the user invoking 'putmail'. 8177 8178 The 'smtp' mailbox scheme can be used for remote delivery. For 8179example: 8180 8181 putmail 'smtp://mail.example.org;to=ovr' 8182 8183 The program will initiate SMTP dialog with the server 8184'mail.example.org' and will send the message from its standard input to 8185the user 'ovr' on that server. 8186 8187* Menu: 8188 8189* putmail options:: 8190* putmail configuration:: 8191 8192 8193File: mailutils.info, Node: putmail options, Next: putmail configuration, Up: putmail 8194 81953.14.1 putmail options 8196---------------------- 8197 8198'-f EMAIL' 8199'-r EMAIL' 8200'--from=EMAIL' 8201 Specify the sender address. If not used, the current user name 8202 will be used. 8203 8204'-l NAME' 8205'--language=NAME' 8206 Define scripting language for the next '--script' option. Valid 8207 arguments are 'sieve', 'scheme' and 'python'. 8208 8209'--message-id-header=HEADER' 8210 Use this header to identify messages when logging Sieve actions 8211 8212'-s NAME' 8213'--script=NAME' 8214 Set the name of the user-defined mail filter. *Note MDA 8215 Scripting::, for a detailed discussion of the scripting feature. 8216 8217 8218File: mailutils.info, Node: putmail configuration, Prev: putmail options, Up: putmail 8219 82203.14.2 putmail configuration 8221---------------------------- 8222 8223The behavior of 'putmail' is affected by the following configuration 8224statements: 8225 8226Statement Reference 8227------------------------------------------------------------------- 8228debug *Note debug statement::. 8229mailbox *Note mailbox statement::. 8230locking *Note locking statement::. 8231pam *Note pam statement::. 8232sql *Note sql statement::. 8233virtdomain *Note virtdomain statement::. 8234radius *Note radius statement::. 8235ldap *Note ldap statement::. 8236auth *Note auth statement::. 8237mailer *Note mailer statement::. 8238 8239 The utility also accepts all MDA configuration statements: *Note 8240Conf-mda::. 8241 8242 8243File: mailutils.info, Node: mimeview, Next: pop3d, Prev: putmail, Up: Programs 8244 82453.15 mimeview 8246============= 8247 8248For each file given in its command line, 'mimeview' attempts to 8249autodetect its type and invoke an appropriate file viewer. 8250 8251 To detect the file type, 'mimeview' uses 'mime.types' file. This 8252file is a part of Common UNIX Printing System, *note 8253(mime.types(5))mime.types::. By default 'mimeview' searches for 8254'mime.types' in '$prefix/etc/cups/'(1), however its exact location can 8255be specified at runtime as well (see '--mimetypes' below). 8256 8257 Once file MIME type is successfully determined, 'mimeview' consults 8258'mailcap' files in order to determine how to display the file. It does 8259so essentially in the same manner as 'metamail' utility, i.e., it scans 8260all files specified in 'METAMAIL' environment variable until it finds an 8261entry describing the desired file format or until the list of files is 8262exhausted. If 'METAMAIL' variable is not set, 'mimeview' uses the 8263following default path instead: 8264 8265 $HOME/.mailcap:/usr/local/etc/mailcap:\ 8266 /usr/etc/mailcap:/etc/mailcap:\ 8267 /etc/mail/mailcap:/usr/public/lib/mailcap 8268 8269* Menu: 8270 8271* Mimeview Invocation:: 8272* Mimeview Config:: 8273 8274 ---------- Footnotes ---------- 8275 8276 (1) The exact location is determined at configuration time by setting 8277environment variable 'DEFAULT_CUPS_CONFDIR'. On most sites running 8278 8279 ./configure DEFAULT_CUPS_CONFDIR=/etc/cups 8280 8281should be recommended. 8282 8283 8284File: mailutils.info, Node: Mimeview Invocation, Next: Mimeview Config, Up: mimeview 8285 82863.15.1 Mimeview Invocation 8287-------------------------- 8288 8289The following table summarizes options specific for 'mimeview': 8290 8291'-a[TYPE-LIST]' 8292'--no-ask[=TYPE-LIST]' 8293 By default 'mimeview' asks for confirmation before running 8294 interpreter to view a message. If this option is used without 8295 argument, it disables the default behavior for all message types. 8296 Otherwise, if argument TYPE-LIST is given, it specifies a 8297 comma-separated list of MIME types for which no questions should be 8298 asked. Elements of this list may include shell-style globbing 8299 patterns, e.g. setting 8300 8301 --no-ask='text/*,image/jpeg' 8302 8303 will disable prompting before displaying any textual files, no 8304 matter what their subtype is, and before displaying files with type 8305 'image/jpeg'. 8306 8307 Notice, that when the long form is used, its argument must be 8308 separated from the option by a single equal sign, as shown in the 8309 example above. When the short form ('-a') is used, its argument 8310 must follow the option immediately, without any intervening 8311 whitespace, e.g. '-a'text/*''). 8312 8313'-d[FLAGS]' 8314'--debug[=FLAGS]' 8315 Enables debugging output. FLAGS is a sequence of characters 8316 specifying the desired debugging level. Following characters are 8317 meaningful in FLAGS: 8318 8319 g 8320 Enables debugging of 'mime.types' parser 8321 8322 l 8323 Enables debugging of 'mime.types' lexical analyzer (warning: 8324 produces _very_ copious output) 8325 8326 0 8327 Prints basic information about actions to be executed and 8328 reports about exit status of executed commands. 8329 8330 1 8331 Additionally displays each file name along with its MIME type 8332 8333 2 8334 Additionally traces the process of looking up the matching 8335 entry in 'mailcap' files. 8336 8337 3 8338 Additionally, enables debugging of 'mime.types' parser ('g'). 8339 8340 4 8341 Additionally, enables debugging of 'mime.types' lexer ('l'). 8342 8343 digits from 5 to 9 8344 The same as 4, currently. 8345 8346 If FLAGS are not given, the default '2' is assumed. 8347 8348'--metamail[=FILE]' 8349 Run 'metamail' to display files, instead of using the internal 8350 mechanisms. If FILE is specified, it is taken as 'metamail' 8351 command line. 8352 8353'-h' 8354'--no-interactive' 8355'--print' 8356 This options tells 'mimeview' that it should run in non-interactive 8357 mode. In this mode prompting is disabled, and the normal mailcap 8358 'command' field is not executed. Instead 'mimeview' will execute 8359 the command specified in the 'print' field. If there is nothing in 8360 the print field, the mailcap entry is ignored and the search 8361 continues for a matching mailcap entry that does have a 'print' 8362 field. 8363 8364 Notice, that unlike in 'metamail -h', this option does not force 8365 'mimeview' to send the output to the printer daemon. 8366 8367 When used with '--metamail' option, this option passes '-h' flag to 8368 the invocation of 'metamail'. 8369 8370 By default 'mimeview' behaves as if given '--no-interactive' option 8371 whenever its standard input is not a tty device. 8372 8373'-i' 8374'--identify' 8375 Identifies and prints the MIME type for each input file. 8376 8377'-n' 8378'--dry-run' 8379 Do not do anything, just print what would be done. Implies 8380 '--debug=1', unless the debugging level is set up explicitly. 8381 8382'-f FILE' 8383'--mimetypes FILE' 8384 Use FILE as 'mime.types' file. If FILE is a directory, use 8385 'FILE/mime.types' 8386 8387'-t' 8388'--lint' 8389 Check syntax of the 'mime.types' file and exit. Command line 8390 arguments are ignored. 8391 8392 8393File: mailutils.info, Node: Mimeview Config, Prev: Mimeview Invocation, Up: mimeview 8394 83953.15.2 Mimeview Config 8396---------------------- 8397 8398The following configuration statements affect the behavior of 8399'mimeview': 8400 8401Statement Reference 8402------------------------------------------------------------------- 8403debug *Note Debug Statement::. 8404 8405 -- Mimeview Config: mimetypes FILE 8406 Read FILE instead of the default 'mime.types'. 8407 8408 -- Mimeview Config: metamail PROGRAM 8409 Use PROGRAM to display files. 8410 8411 8412File: mailutils.info, Node: pop3d, Next: imap4d, Prev: mimeview, Up: Programs 8413 84143.16 POP3 Daemon 8415================ 8416 8417The 'pop3d' daemon implements the Post Office Protocol Version 3 server. 8418 8419 'pop3d' has two operation modes: 8420 8421Inetd 8422 The server is started from '/etc/inetd.conf' file: 8423 8424 pop3 stream tcp nowait root /usr/local/sbin/pop3d pop3d 8425 8426 This is the default operation mode. 8427 8428Standalone 8429 The server runs as daemon, forking a child for each new connection. 8430 8431 The server operation mode is configured using 'mode' statement (*note 8432mode: Server Settings.). 8433 8434* Menu: 8435 8436* Login delay:: 8437* Auto-expire:: 8438* Bulletins:: 8439* Conf-pop3d:: Pop3d Configuration 8440* Command line options:: 8441 8442 8443File: mailutils.info, Node: Login delay, Next: Auto-expire, Up: pop3d 8444 84453.16.1 Login delay 8446------------------ 8447 8448POP3 clients often login frequently to check for new mail. Each new 8449connection implies authenticating the user and opening his maildrop and 8450can be very resource consuming. To reduce server load, it is possible 8451to impose a minimum delay between any two consecutive logins. This is 8452called 'LOGIN-DELAY' capability and is described in RFC 2449. 8453 8454 As of version 3.13, GNU Mailutils 'pop3d' allows to set global login 8455delay, i.e. such enforcement will affect all POP3 users. If a user 8456attempts to log in before the specified login delay expires, he will get 8457the following error message: 8458 8459 -ERR [LOGIN-DELAY] Attempt to log in within the minimum login delay interval 8460 8461 The message will be issued after a valid password is entered. This 8462prevents this feature from being used by malicious clients for account 8463harvesting. 8464 8465 To enable the login delay capability, specify the minimum delay using 8466'login-delay' configuration statement, e.g.: 8467 8468 login-delay 60; 8469 8470 The 'pop3d' utility keeps each user's last login time in a special 8471DBM file, called "login statistics database", so to be able to use this 8472feature, Mailutils must be compiled with DBM support. By default, the 8473login statistics database is called '/var/run/pop3-login.db'. You can 8474change its name using 'stat-file' configuration statement: 8475 8476 login-delay 60; 8477 stat-file /tmp/pop.login.db; 8478 8479 The login delay facility will be enabled only if 'pop3d' is able to 8480access the statistics database for both reading and writing. If it is 8481not, it will report this using 'syslog' and start up without login delay 8482restrictions. A common error message looks like: 8483 8484 Unable to open statistics db: Operation not permitted 8485 8486 You can check whether your 'pop3d' uses login delays by connecting to 8487it and issuing the 'CAPA' command. If login delays are in use, there 8488response will contain the string 'LOGIN-DELAY N', where N is the actual 8489login delay value. 8490 8491 8492File: mailutils.info, Node: Auto-expire, Next: Bulletins, Prev: Login delay, Up: pop3d 8493 84943.16.2 Auto-expire 8495------------------ 8496 8497Automatic expiration of messages allows you to limit the period of time 8498users are permitted to keep their messages on the server. It is enabled 8499by 'expire' configuration statement: 8500 8501'expire N;' 8502 Enable automatic expiration of messages after N days. 8503 8504 The current implementation works as follows. When a message is 8505downloaded by 'RETR' or 'TOP' command, it is marked with 8506'X-Expire-Timestamp: N' header, where N is current value of UNIX 8507timestamp. The exact expiration mechanism depends on you. Mailutils 8508allows you two options: 8509 8510 1. Expired messages are deleted by 'pop3d' upon closing the mailbox. 8511 You specify this mechanism using 'delete-expired' configuration 8512 statement: 8513 8514 'delete-expired BOOL;' 8515 If BOOL is 'true', delete expired messages after receiving the 8516 'QUIT' command. 8517 8518 2. Expired messages remain in the mailbox after closing it. The 8519 system administrator is supposed to run a cron job that purges the 8520 mailboxes. Such a cron job can be easily implemented using 'sieve' 8521 from GNU Mailutils and the following script: 8522 8523 require "timestamp"; 8524 # Replace "5" with the desired expiration period 8525 if timestamp :before "X-Expire-Timestamp" "now - 5 days" 8526 { 8527 discard; 8528 } 8529 8530 This script will remove expired messages 5 days after the 8531 retrieval. Replace '5' with the desired expiration period and make 8532 sure it equals the argument to 'expire' configuration keyword. 8533 8534 The statement 'expire 0' means the client is not permitted to leave 8535mail on the server. It always implies 'delete-expired true'. 8536 8537 8538File: mailutils.info, Node: Bulletins, Next: Conf-pop3d, Prev: Auto-expire, Up: pop3d 8539 85403.16.3 Bulletins 8541---------------- 8542 8543The bulletin feature allows you to send important announcements to all 8544POP3 users without mailing them. It works by creating a "bulletin 8545source mailbox" and sending the announcements to it. 8546 8547 After a user successfully authenticates, 'pop3d' checks the last 8548"bulletin number" the user receives. The bulletin number refers to the 8549number of the bulletin message in the bulletin source mailbox. If the 8550latter contains more messages, these are appended to the user mailbox. 8551 8552 The user last bulletin number can be kept in two places. First, it 8553can be stored in file '.popbull' in his home directory. Secondly, if 8554Mailutils is compiled with DBM support, the numbers can be kept in a DBM 8555file, supplied via 'bulletin-db' configuration statement. If both the 8556database and the '.popbull' file are present, the data from the database 8557take precedence. 8558 8559 To enable this feature, use the following configuration statements: 8560 8561'bulletin-source MBOX' 8562 Set the URL of the bulletin source mailbox. 8563 8564'bulletin-db FILE' 8565 Set the name of the database file to keep last bulletin numbers in. 8566 8567 The following example instructs 'pop3d' to look for the bulletin 8568messages in MH folder '/var/spool/bull/mbox' and to keep the database of 8569last delivered bulletin numbers in '/var/spool/bull/numbers.db': 8570 8571 bulletin-source mh:/var/spool/bull/mbox; 8572 bulletin-db /var/spool/bull/numbers.db; 8573 8574 8575File: mailutils.info, Node: Conf-pop3d, Next: Command line options, Prev: Bulletins, Up: pop3d 8576 85773.16.4 Pop3d Configuration 8578-------------------------- 8579 8580The following configuration file statements affect the behavior of 8581'pop3d'. 8582 8583Statement Reference 8584------------------------------------------------------------------- 8585debug *Note debug statement::. 8586tls *Note tls statement::. 8587tls-file-checks *Note tls-file-checks statement::. 8588mailbox *Note mailbox statement::. 8589locking *Note locking statement::. 8590logging *Note logging statement::. 8591pam *Note pam statement::. 8592sql *Note sql statement::. 8593virtdomain *Note virtdomain statement::. 8594radius *Note radius statement::. 8595ldap *Note ldap statement::. 8596auth *Note auth statement::. 8597server *Note Server Settings::. 8598acl *Note acl statement::. 8599tcp-wrappers *Note tcp-wrappers statement::. 8600 8601 -- Pop3d Conf: tls-mode MODE 8602 Configure the use of TLS encryption for inetd mode. 8603 8604 In daemon mode, this statement sets the type of TLS encryption to 8605 use in all server blocks that lack the 'tls-mode' statement (*note 8606 Server Statement::). 8607 8608 Allowed values for MODE are: 8609 8610 no 8611 TLS is not used. The 'STLS' command won't be available even 8612 if the TLS configuration is otherwise complete. 8613 8614 ondemand 8615 TLS is initiated when the user issues the appropriate command. 8616 This is the default when TLS is configured. 8617 8618 required 8619 Same as above, but the use of TLS is mandatory. The 8620 authentication state is entered only after TLS negotiation has 8621 succeeded. 8622 8623 connection 8624 TLS is always forced when the connection is established (POP3S 8625 protocol). 8626 8627 -- Pop3d Conf: undelete BOOL 8628 On startup, clear deletion marks from all the messages. 8629 8630 -- Pop3d Conf: expire N 8631 Automatically expire read messages after N days. *Note 8632 Auto-expire::, for a detailed description. 8633 8634 -- Pop3d Conf: delete-expired BOOL 8635 Delete expired messages upon closing the mailbox. *Note 8636 Auto-expire::, for a detailed description. 8637 8638 -- Pop3d Conf: login-delay DURATION 8639 Set the minimal allowed delay between two successive logins. *Note 8640 Login delay::, for more information. 8641 8642 -- Pop3d Conf: stat-file FILE 8643 Set the name of login statistics file for the 'login-delay' 8644 facility. *Note Login delay::, for more information. 8645 8646 -- Pop3d Conf: bulletin-source FILE 8647 Get bulletins from the specified mailbox. *Note Bulletins::, for a 8648 detailed description. 8649 8650 -- Pop3d Conf: bulletin-db FILE 8651 Set bulletin database file name. *Note Bulletins::, for a detailed 8652 description. 8653 8654 8655File: mailutils.info, Node: Command line options, Prev: Conf-pop3d, Up: pop3d 8656 86573.16.5 Command line options 8658--------------------------- 8659 8660The following table summarizes all 'pop3d' command line options. 8661 8662'-d[NUMBER]' 8663'--daemon[=NUMBER]' 8664 Run in standalone mode. An optional NUMBER specifies the maximum 8665 number of child processes allowed to run simultaneously. When it 8666 is omitted, it defaults to 10 processes. _Please note_, that there 8667 should be no whitespace between the '-d' and its parameter. 8668 8669'-i' 8670'--inetd' 8671 Run in inetd mode. 8672 8673'--foreground' 8674 Remain in foreground. 8675 8676 The Mailutils common options are also understood. *Note Common 8677Options::. 8678 8679 8680File: mailutils.info, Node: imap4d, Next: comsatd, Prev: pop3d, Up: Programs 8681 86823.17 IMAP4 Daemon 8683================= 8684 8685GNU 'imap4d' is a daemon implementing IMAP4 rev1 protocol for accessing 8686and handling electronic mail messages on a server. It can be run either 8687as a standalone program or from 'inetd.conf' file. 8688 8689* Menu: 8690 8691* Namespace:: Namespace. 8692* Conf-imap4d:: Configuration. 8693* Starting imap4d:: Invocation Options. 8694 8695 8696File: mailutils.info, Node: Namespace, Next: Conf-imap4d, Up: imap4d 8697 86983.17.1 Namespace 8699---------------- 8700 8701GNU 'imap4d' supports a notion of "namespaces" defined in RFC 2342. A 8702namespace can be regarded as a list of entities, defining locations to 8703which the user has certain access rights. Each entity includes the 8704"prefix", under which the mailboxes can be found, "hierarchy delimiter", 8705a character used to delimit parts of a path to a mailbox, and a 8706"directory" on the file system on the server, which actually holds the 8707mailboxes. Among these three values, only first two are visible to the 8708client using the IMAP 'NAMESPACE' command. 8709 8710 There are three namespaces: 8711 8712Personal Namespace 8713 A namespace that is within the personal scope of the authenticated 8714 user on a particular connection. The user has all permissions on 8715 this namespace. 8716 8717 By default, this namespace contains a single prefix: 8718 8719 prefix: "" 8720 delimiter: / 8721 directory: home directory of the user 8722 8723Other Users' Namespace 8724 A namespace that consists of mailboxes from the "Personal 8725 Namespaces" of other users. The user can read and list mailboxes 8726 from this namespace. However, he is not allowed to use '%' and '*' 8727 wildcards with 'LIST' command, that is he can access a mailbox only 8728 if he knows exactly its location. 8729 8730 By default, this namespace is empty. 8731 8732Shared Namespace 8733 A namespace that consists of mailboxes that are intended to be 8734 shared amongst users and do not exist within a user's Personal 8735 Namespace. The user has all permissions on this namespace. 8736 8737 By default, this namespace is empty. 8738 8739 The default values ensure that each user is able to see or otherwise 8740access mailboxes residing in the directories other than his own home. 8741 8742 These defaults can be changed using the 'namespace' block statement: 8743 8744 namespace NAME { 8745 mailbox-mode MODE; 8746 prefix PFX { 8747 directory PATH; 8748 delimiter CHR; 8749 mailbox-type TYPE; 8750 } 8751 } 8752 8753 The NAME argument to the 'namespace' statement declares which 8754namespace is being configured. Allowed values are: 'personal', 'other', 8755and 'shared'. 8756 8757 The 'mailbox-mode' statement configures the file mode for the 8758mailboxes created within that namespace (provided that the directory 8759permissions allow the user to create mailboxes). The MODE argument is a 8760comma-delimited list of symbolic mode settings, similar to that used by 8761'chmod'. Each setting begins with a letter 'g', which means set mode 8762bits for file group, or 'o', which means set mode bits for other users 8763(note, that there is no 'u' specifier, since user ownership of his 8764mailbox cannot be changed). This letter is followed by an '=' (or '+'), 8765and a list of modes to be set. This list can contain only two letters: 8766'r' to set read permission, and 'w' to set write permission. 8767 8768 For example, the following statement sets read and write permissions 8769for the group: 8770 8771 mailbox-mode g=rw; 8772 8773 The 'prefix' statement configures available prefixes and determines 8774their mappings to the server's file system. The PFX argument defines 8775the prefix which will be visible to the IMAP client. 8776 8777 The 'directory' statement defines the directory in the file system to 8778which PFX is mapped. Exactly one 'directory' statement must be present 8779in each 'prefix' block. The inerpretation of its argument depends on 8780the namespace in which it occurs. 8781 8782 When used in the 'namespace shared' block, the argument to this 8783statement is interpreted verbatim, as an absolute pathname. 8784 8785 When used in 'namespace personal' the argument to 'directory' 8786statement can contain references to the following variables (*note 8787Variables::): 8788 8789user 8790 Login name of the user. 8791 8792home 8793 Home directory of the user. 8794 8795 For example, the following statement maps the default personal 8796namespace to the directory 'imap' in the user's home directory: 8797 8798 namespace personal { 8799 prefix ""; 8800 directory "$home/imap"; 8801 } 8802 8803 If the 'directory' statement is used within the 'namespace other' 8804block, its value can contain the '$user' and '$home' variables as well, 8805but their meaning is different. For the 'other' namespace, the '$user' 8806variable is expanded to the part of the actual reference contained 8807between the prefix and first hierarchy delimiter (or the end of the 8808reference, if no delimiter occurs to the right of the prefix). 8809Correspondingly, '$home' expands to the home directory of that user. 8810Consider, for example, the following statement: 8811 8812 namespace other { 8813 prefix "~"; 8814 directory "/var/imap/$user"; 8815 } 8816 8817 If the client issues the following statement: 8818 8819 1 LIST "~smith" "%" 8820 8821then '$user' will expand to the string 'smith' and the server will look 8822for all mailboxes in the directory '/var/imap/smith'. 8823 8824 The 'delimiter' statement defines the folder hierarchy delimiter for 8825that prefix. It is optional, the default value being '"/"'. 8826 8827 The 'mailbox-type' statement declares the type of the mailboxes 8828within that prefix. If present, its argument must be a valid mailbox 8829type (e.g. 'mailbox', 'maildir', or 'mh'). The IMAP 'LIST' command 8830will display only mailboxes of that type. The 'CREATE' command will 8831create mailboxes of that type. 8832 8833 In the absence of the 'mailbox-type' statement, the IMAP 'LIST' 8834command will display mailboxes of any type supported by Mailutils. The 8835type of newly-created mailboxes is then determined by the 'mailbox-type' 8836statement (*note mailbox-type::). 8837 8838 Any number of 'prefix' blocks can be present. 8839 8840 Consider, for example, the following configuration: 8841 8842 namespace personal { 8843 prefix "" { 8844 directory "$home/mailfolder"; 8845 } 8846 prefix "#MH:" { 8847 directory "$home/Mail"; 8848 delimiter "/"; 8849 mailbox-type "mh"; 8850 } 8851 } 8852 8853 It defines the personal namespace containing two prefixes. The empty 8854prefix is mapped to the directory 'mailfolder' in the home directory of 8855the currently authenticated user. Any type of mailboxes is supported 8856within that prefix. 8857 8858 The prefix '#MH:' is mapped to the directory 'Mail' in the home 8859directory of the user, and is limited to contain only mailboxes in MH 8860format. 8861 8862 Note that if the prefixes '""' is not defined in the personal 8863namespace, the following default will be automatically created: 8864 8865 prefix "" { 8866 directory "$home"; 8867 } 8868 8869