dma(8): Upgrade to v0.7.
[dragonfly.git] / libexec / dma / dma.8
CommitLineData
f67beddd
MS
1.\"
2.\" Copyright (c) 2008
3.\" The DragonFly Project. All rights reserved.
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
8.\"
9.\" 1. Redistributions of source code must retain the above copyright
10.\" notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\" notice, this list of conditions and the following disclaimer in
13.\" the documentation and/or other materials provided with the
14.\" distribution.
15.\" 3. Neither the name of The DragonFly Project nor the names of its
16.\" contributors may be used to endorse or promote products derived
17.\" from this software without specific, prior written permission.
18.\"
19.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
22.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
23.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
24.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
25.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
26.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
27.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
28.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
29.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
ffd21410 32.\" $DragonFly: src/libexec/dma/dma.8,v 1.10 2008/09/06 14:17:56 swildner Exp $
f67beddd 33.\"
c8b07ee5 34.Dd April 22, 2010
f67beddd
MS
35.Dt DMA 8
36.Os
37.Sh NAME
38.Nm dma
39.Nd DragonFly Mail Agent
40.Sh SYNOPSIS
41.Nm
ff48fce6 42.Op Fl DiOt
a696990f
SS
43.Op Fl A Ns Ar mode
44.Op Fl b Ns Ar mode
f67beddd
MS
45.Op Fl f Ar sender
46.Op Fl L Ar tag
a696990f 47.Op Fl o Ns Ar option
f67beddd 48.Op Fl r Ar sender
a696990f 49.Op Fl q Ns Op Ar arg
f67beddd
MS
50.Op Ar recipient ...
51.Sh DESCRIPTION
52.Nm
53is a small Mail Transport Agent (MTA), designed for home and office use.
54It accepts mails from locally installed Mail User Agents (MUA) and
55delivers the mails either locally or to a remote destination.
56Remote delivery includes several features like TLS/SSL support and SMTP
9fe4c5f3 57authentication.
f67beddd
MS
58.Pp
59.Nm
60is not intended as a replacement for real, big MTAs like
61.Xr sendmail 8
62or
50bb7f28 63.Xr postfix 1 .
f67beddd
MS
64Consequently,
65.Nm
66does not listen on port 25 for incoming connections.
67.Pp
68The options are as follows:
69.Bl -tag -width indent
a696990f
SS
70.It Fl A Ns Ar mode
71.Fl \&Ac
f67beddd 72acts as a compatibility option for sendmail.
a696990f 73.It Fl b Ns Ar mode
a9337db7
SS
74.Bl -tag -width indent
75.It Fl bp
76List all mails currently stored in the mail queue.
77.It Fl bq
78Queue the mail, but don't attempt to deliver it.
79See also the
80.Sq DEFER
81config file setting below.
82.El
83.Pp
84All other
85.Ar mode Ns
86s are are ignored.
f67beddd
MS
87.It Fl D
88Don't run in the background.
89Useful for debugging.
90.It Fl f Ar sender
c8b07ee5 91Set sender address (envelope-from) to
f67beddd 92.Ar sender .
c8b07ee5
SW
93This overrides the value of the environment variable
94.Ev EMAIL .
f67beddd
MS
95.It Fl i
96Ignore dots alone on lines by themselves in incoming messages.
97This should be set if you are reading data from a file.
98.It Fl L Ar tag
99Set the identifier used in syslog messages to the supplied
100.Ar tag .
101This is a compatibility option for sendmail.
28b8d48f
MS
102.It Fl O
103This is a compatibility option for sendmail.
a696990f 104.It Fl o Ns Ar option
f67beddd 105Specifying
a696990f 106.Fl oi
f67beddd
MS
107is synonymous to
108.Fl i .
109All other options are ignored.
a696990f 110.It Fl q Ns Op Ar arg
f67beddd 111Process saved messages in the queue.
a696990f 112The argument is optional and ignored.
f67beddd
MS
113.It Fl r Ar sender
114Same as
115.Fl f .
ff48fce6
SS
116.It Fl t
117Obtain recipient addresses from the message header.
a696990f
SS
118.Nm
119will parse the
ff48fce6
SS
120.Li To: ,
121.Li Cc: ,
122and
123.Li Bcc:
124headers.
125The
126.Li Bcc:
127header will be removed independent of whether
128.Fl t
129is specified or not.
f67beddd
MS
130.El
131.Sh CONFIGURATION
132.Nm
133can be configured with three config files:
134.Pp
135.Bl -bullet -compact
136.It
137auth.conf
138.It
139dma.conf
f67beddd
MS
140.El
141.Pp
142These three files are stored per default in
143.Pa /etc/dma .
f67beddd
MS
144.Sh FILE FORMAT
145Every file contains parameters of the form
146.Sq name value .
147Lines containing boolean values are set to
148.Sq NO
149if the line is commented and to
150.Sq YES
151if the line is uncommented.
152Empty lines or lines beginning with a
153.Sq #
154are ignored.
155Parameter names and their values are case sensitive.
156.Sh PARAMETERS
157.Ss auth.conf
158SMTP authentication can be configured in
159.Pa auth.conf .
160Each line has the format
161.Dq Li user|smarthost:password .
162.Ss dma.conf
163Most of the behaviour of
164.Nm
165can be configured in
166.Pa dma.conf .
f67beddd
MS
167.Bl -tag -width 4n
168.It Ic SMARTHOST Xo
169(string, default=empty)
170.Xc
171If you want to send outgoing mails via a smarthost, set this variable to
172your smarthosts address.
173.It Ic PORT Xo
174(numeric, default=25)
175.Xc
176Use this port to deliver remote emails.
177Only useful together with the
178.Sq SMARTHOST
179option, because
180.Nm
ffd21410
SW
181will deliver all mails to this port, regardless of whether a smarthost is set
182or not.
f67beddd 183.It Ic ALIASES Xo
c8b07ee5 184(string, default=/etc/aliases)
f67beddd
MS
185.Xc
186Path to the local aliases file.
187Just stick with the default.
c8b07ee5
SW
188The aliases file is of the format
189.Dl nam: dest1 dest2 ...
190In this case, mails to
191.Li nam
192will instead be delivered to
193.Li dest1
194and
195.Li dest2 ,
196which in turn could be entries in
197.Pa /etc/aliases .
198The special name
199.Ql *
200can be used to create a catch-all alias, which gets used if no other
201matching alias is found.
202Use the catch-all alias only if you don't want any local mail to be
203delivered.
f67beddd
MS
204.It Ic SPOOLDIR Xo
205(string, default=/var/spool/dma)
206.Xc
207Path to
208.Nm Ap s
209spool directory.
210Just stick with the default.
f67beddd 211.It Ic AUTHPATH Xo
c8b07ee5 212(string, default=not set)
f67beddd
MS
213.Xc
214Path to the
215.Sq auth.conf
216file.
f67beddd
MS
217.It Ic SECURETRANS Xo
218(boolean, default=commented)
219.Xc
1ec13189 220Uncomment if you want TLS/SSL secured transfer.
f67beddd
MS
221.It Ic STARTTLS Xo
222(boolean, default=commented)
223.Xc
1ec13189 224Uncomment if you want to use STARTTLS.
f67beddd
MS
225Only useful together with
226.Sq SECURETRANS .
c8b07ee5
SW
227.It Ic OPPORTUNISTIC_TLS Xo
228(boolean, default=commented)
229.Xc
230Uncomment if you want to allow the STARTTLS negotiation to fail.
231Most useful when
232.Nm
233is used without a smarthost, delivering remote messages directly to
234the outside mail exchangers; in opportunistic TLS mode, the connection will
235be encrypted if the remote server supports STARTTLS, but an unencrypted
236delivery will still be made if the negotiation fails.
237Only useful together with
238.Sq SECURETRANS
239and
240.Sq STARTTLS .
f67beddd
MS
241.It Ic CERTFILE Xo
242(string, default=empty)
243.Xc
244Path to your SSL certificate file.
b558d098
MS
245.It Ic SECURE Xo
246(boolean, default=commented)
247.Xc
c8b07ee5 248Uncomment this entry and change it to
b558d098
MS
249.Sq INSECURE
250to use plain text SMTP login over an insecure connection.
251You have to rename this variable manually to prevent that you send your
1be1f152 252password accidentally over an insecure connection.
f67beddd
MS
253.It Ic DEFER Xo
254(boolean, default=commented)
255.Xc
1ec13189 256Uncomment if you want that
f67beddd
MS
257.Nm
258defers your mail.
259You have to flush your mail queue manually with the
260.Fl q
261option.
262This option is handy if you are behind a dialup line.
5ca28cf6
SS
263.It Ic FULLBOUNCE Xo
264(boolean, default=commented)
265.Xc
266Uncomment if you want the bounce message to include the complete original
267message, not just the headers.
5754971c
SS
268.It Ic MAILNAME Xo
269(string, default=empty)
270.Xc
c8b07ee5
SW
271The internet hostname
272.Nm
273uses to identify the host.
274If not set or empty, the result of
275.Xr gethostname 2
276is used.
277If
278.Sq MAILNAME
279is an absolute path to a file, the first line of this file will be used
280as the hostname.
281.It Ic MASQUERADE Xo
5754971c
SS
282(string, default=empty)
283.Xc
c8b07ee5
SW
284Masquerade the envelope from addresses with this address/hostname.
285Use this setting if mails are not accepted by destination mail servers
286because your sender domain is invalid.
287This setting is overridden by the
288.Fl f
289flag and the
290.Ev EMAIL
291environment variable.
292.Pp
293If
294.Sq MASQUERADE
295does not contain a
296.Li @
297sign, the string is interpreted as a host name.
298For example, setting
299.Sq MASQUERADE
300to
301.Ql john@
302on host
303.Ql hamlet
304will send all mails as
305.Ql john@hamlet ;
306setting it to
307.Ql percolator
308will send all mails as
309.Ql Sm off Va username @percolator .
310.Sm on
311.El
312.Ss Environment variables
313The behavior of
314.Nm
315can be influenced by some environment variables.
316.Pp
317.Bl -tag -width 4n
318.It Ev EMAIL Xo
319.Xc
320Used to set the sender address (envelope-from).
321Use a plain address, in the form of
322.Li user@example.com .
323This value will be overridden when the
324.Fl f
325flag is used.
f67beddd 326.El
f67beddd
MS
327.Sh SEE ALSO
328.Xr mailaddr 7 ,
329.Xr mailwrapper 8 ,
330.Xr sendmail 8
331.Rs
332.%A "J. B. Postel"
333.%T "Simple Mail Transfer Protocol"
334.%O RFC 821
335.Re
336.Rs
337.%A "J. Myers"
338.%T "SMTP Service Extension for Authentication"
339.%O RFC 2554
340.Re
341.Rs
342.%A "P. Hoffman"
343.%T "SMTP Service Extension for Secure SMTP over TLS"
344.%O RFC 2487
345.Re
346.Sh HISTORY
347The
348.Nm
349utility first appeared in
350.Dx 1.11 .
351.Sh AUTHORS
352.Nm
353was written by
354.An Matthias Schmidt Aq matthias@dragonflybsd.org
355and
356.An Simon Schubert Aq corecode@dragonflybsd.org .