libexec/dma/dma.8

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