dma: add TODO
[dragonfly.git] / libexec / dma / dma.8
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 .\"
32 .\" $DragonFly: src/libexec/dma/dma.8,v 1.10 2008/09/06 14:17:56 swildner Exp $
33 .\"
34 .Dd August 27, 2009
35 .Dt DMA 8
36 .Os
37 .Sh NAME
38 .Nm dma
39 .Nd DragonFly Mail Agent
40 .Sh SYNOPSIS
41 .Nm
42 .Op Fl DiOt
43 .Op Fl A Ns Ar mode
44 .Op Fl b Ns Ar mode
45 .Op Fl f Ar sender
46 .Op Fl L Ar tag
47 .Op Fl o Ns Ar option
48 .Op Fl r Ar sender
49 .Op Fl q Ns Op Ar arg
50 .Op Ar recipient ...
51 .Sh DESCRIPTION
52 .Nm
53 is a small Mail Transport Agent (MTA), designed for home and office use.
54 It accepts mails from locally installed Mail User Agents (MUA) and
55 delivers the mails either locally or to a remote destination.
56 Remote delivery includes several features like TLS/SSL support and SMTP
57 authentication.
58 .Pp
59 .Nm
60 is not intended as a replacement for real, big MTAs like
61 .Xr sendmail 8
62 or
63 .Xr postfix 1 .
64 Consequently,
65 .Nm
66 does not listen on port 25 for incoming connections.
67 .Pp
68 The options are as follows:
69 .Bl -tag -width indent
70 .It Fl A Ns Ar mode
71 .Fl \&Ac
72 acts as a compatibility option for sendmail.
73 .It Fl b Ns Ar mode
74 .Bl -tag -width indent
75 .It Fl bp
76 List all mails currently stored in the mail queue.
77 .It Fl bq
78 Queue the mail, but don't attempt to deliver it.
79 See also the
80 .Sq DEFER
81 config file setting below.
82 .El
83 .Pp
84 All other
85 .Ar mode Ns
86 s are are ignored.
87 .It Fl D
88 Don't run in the background.
89 Useful for debugging.
90 .It Fl f Ar sender
91 Set sender address to
92 .Ar sender .
93 .It Fl i
94 Ignore dots alone on lines by themselves in incoming messages.
95 This should be set if you are reading data from a file.
96 .It Fl L Ar tag
97 Set the identifier used in syslog messages to the supplied
98 .Ar tag .
99 This is a compatibility option for sendmail.
100 .It Fl O
101 This is a compatibility option for sendmail.
102 .It Fl o Ns Ar option
103 Specifying
104 .Fl oi
105 is synonymous to
106 .Fl i .
107 All other options are ignored.
108 .It Fl q Ns Op Ar arg
109 Process saved messages in the queue.
110 The argument is optional and ignored.
111 .It Fl r Ar sender
112 Same as
113 .Fl f .
114 .It Fl t
115 Obtain recipient addresses from the message header.
116 .Nm
117 will parse the
118 .Li To: ,
119 .Li Cc: ,
120 and
121 .Li Bcc:
122 headers.
123 The
124 .Li Bcc:
125 header will be removed independent of whether
126 .Fl t
127 is specified or not.
128 .El
129 .Sh CONFIGURATION
130 .Nm
131 can be configured with three config files:
132 .Pp
133 .Bl -bullet -compact
134 .It
135 auth.conf
136 .It
137 dma.conf
138 .It
139 virtusertable
140 .El
141 .Pp
142 These three files are stored per default in
143 .Pa /etc/dma .
144 .Sh FILE FORMAT
145 Every file contains parameters of the form
146 .Sq name value .
147 Lines containing boolean values are set to
148 .Sq NO
149 if the line is commented and to
150 .Sq YES
151 if the line is uncommented.
152 Empty lines or lines beginning with a
153 .Sq #
154 are ignored.
155 Parameter names and their values are case sensitive.
156 .Sh PARAMETERS
157 .Ss auth.conf
158 SMTP authentication can be configured in
159 .Pa auth.conf .
160 Each line has the format
161 .Dq Li user|smarthost:password .
162 .Ss dma.conf
163 Most of the behaviour of
164 .Nm
165 can be configured in
166 .Pa dma.conf .
167 .Bl -tag -width 4n
168 .It Ic SMARTHOST Xo
169 (string, default=empty)
170 .Xc
171 If you want to send outgoing mails via a smarthost, set this variable to
172 your smarthosts address.
173 .It Ic PORT Xo
174 (numeric, default=25)
175 .Xc
176 Use this port to deliver remote emails.
177 Only useful together with the
178 .Sq SMARTHOST
179 option, because
180 .Nm
181 will deliver all mails to this port, regardless of whether a smarthost is set
182 or not.
183 .It Ic ALIASES Xo
184 (string, default=/etc/mail/aliases)
185 .Xc
186 Path to the local aliases file.
187 Just stick with the default.
188 .It Ic SPOOLDIR Xo
189 (string, default=/var/spool/dma)
190 .Xc
191 Path to
192 .Nm Ap s
193 spool directory.
194 Just stick with the default.
195 .It Ic VIRTPATH Xo
196 (string, default=/etc/dma/virtusertable)
197 .Xc
198 Path to the
199 .Sq virtusertable
200 file.
201 .It Ic AUTHPATH Xo
202 (string, default=/etc/dma/auth.conf)
203 .Xc
204 Path to the
205 .Sq auth.conf
206 file.
207 .It Ic VIRTUAL Xo
208 (boolean, default=commented)
209 .Xc
210 Comment if you want virtual user support.
211 .It Ic SECURETRANS Xo
212 (boolean, default=commented)
213 .Xc
214 Comment if you want TLS/SSL secured transfer.
215 .It Ic STARTTLS Xo
216 (boolean, default=commented)
217 .Xc
218 Comment if you want to use STARTTLS.
219 Only useful together with
220 .Sq SECURETRANS .
221 .It Ic CERTFILE Xo
222 (string, default=empty)
223 .Xc
224 Path to your SSL certificate file.
225 .It Ic SECURE Xo
226 (boolean, default=commented)
227 .Xc
228 Change this entry to
229 .Sq INSECURE
230 to use plain text SMTP login over an insecure connection.
231 You have to rename this variable manually to prevent that you send your
232 password accidentally over an insecure connection.
233 .It Ic DEFER Xo
234 (boolean, default=commented)
235 .Xc
236 Comment if you want that
237 .Nm
238 defers your mail.
239 You have to flush your mail queue manually with the
240 .Fl q
241 option.
242 This option is handy if you are behind a dialup line.
243 .It Ic FULLBOUNCE Xo
244 (boolean, default=commented)
245 .Xc
246 Uncomment if you want the bounce message to include the complete original
247 message, not just the headers.
248 .It Ic MAILNAME Xo
249 (string, default=empty)
250 .Xc
251 The name to be used when introducing this host, if different from
252 the result of
253 .Xr hostname 1 .
254 If specified, this option overrides
255 .Sq MAILNAMEFILE .
256 .It Ic MAILNAMEFILE Xo
257 (string, default=empty)
258 .Xc
259 The name of the file to read the
260 .Sq MAILNAME
261 from.
262 .El
263 .Ss virtusertable
264 The
265 .Pa virtusertable
266 file specifies a virtual user table.
267 Each line has the format
268 .Dq Li localuser:mail-address .
269 Some smarthosts do not accept mails from unresolvable email address
270 (e.g.\& user@localhost) so you have to rewrite your outgoing email
271 address to a valid address.
272 .Sh SEE ALSO
273 .Xr mailaddr 7 ,
274 .Xr mailwrapper 8 ,
275 .Xr sendmail 8
276 .Rs
277 .%A "J. B. Postel"
278 .%T "Simple Mail Transfer Protocol"
279 .%O RFC 821
280 .Re
281 .Rs
282 .%A "J. Myers"
283 .%T "SMTP Service Extension for Authentication"
284 .%O RFC 2554
285 .Re
286 .Rs
287 .%A "P. Hoffman"
288 .%T "SMTP Service Extension for Secure SMTP over TLS"
289 .%O RFC 2487
290 .Re
291 .Sh HISTORY
292 The
293 .Nm
294 utility first appeared in
295 .Dx 1.11 .
296 .Sh AUTHORS
297 .Nm
298 was written by
299 .An Matthias Schmidt Aq matthias@dragonflybsd.org
300 and
301 .An Simon Schubert Aq corecode@dragonflybsd.org .