[people/ms/dma.git] / dma.8

.\"
.\" Copyright (c) 2008
.\"	The DragonFly Project.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in
.\"    the documentation and/or other materials provided with the
.\"    distribution.
.\" 3. Neither the name of The DragonFly Project nor the names of its
.\"    contributors may be used to endorse or promote products derived
.\"    from this software without specific, prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $DragonFly: src/libexec/dma/dma.8,v 1.5 2008/02/04 08:58:54 matthias Exp $
.\"
.Dd February 4, 2008
.Dt DMA 8
.Os
.Sh NAME
.Nm dma
.Nd DragonFly Mail Agent
.Sh SYNOPSIS
.Nm
.Op Fl DiOq
.Op Fl A Ar mode
.Op Fl b Ar mode
.Op Fl f Ar sender
.Op Fl L Ar tag
.Op Fl o Ar option
.Op Fl r Ar sender
.Op Ar recipient ...
.Sh DESCRIPTION
.Nm
is a small Mail Transport Agent (MTA), designed for home and office use.
It accepts mails from locally installed Mail User Agents (MUA) and
delivers the mails either locally or to a remote destination.
Remote delivery includes several features like TLS/SSL support and SMTP
authentication (AUTH LOGIN only).
.Pp
.Nm
is not intended as a replacement for real, big MTAs like
.Xr sendmail 8
or
.Xr postfix 1 .
Consequently,
.Nm
does not listen on port 25 for incoming connections.
.Pp
The options are as follows:
.Bl -tag -width indent
.It Fl A Ar mode
.Fl A Ns Ar c
acts as a compatibility option for sendmail.
.It Fl b Ar mode
Specifying
.Fl b Ns Ar p
will list all mails currently stored in the mail queue.
All other modes are are ignored.
.It Fl D
Don't run in the background.
Useful for debugging.
.It Fl f Ar sender
Set sender address to
.Ar sender .
.It Fl i
Ignore dots alone on lines by themselves in incoming messages.
This should be set if you are reading data from a file.
.It Fl L Ar tag
Set the identifier used in syslog messages to the supplied
.Ar tag .
This is a compatibility option for sendmail.
.It Fl O
This is a compatibility option for sendmail.
.It Fl o Ar option
Specifying
.Fl o Ns Ar i
is synonymous to
.Fl i .
All other options are ignored.
.It Fl q
Process saved messages in the queue.
.It Fl r Ar sender
Same as
.Fl f .
.El
.Sh CONFIGURATION
.Nm
can be configured with three config files:
.Pp
.Bl -bullet -compact
.It
auth.conf
.It
dma.conf
.It
virtusertable
.El
.Pp
These three files are stored per default in
.Pa /etc/dma .
.Sh FILE FORMAT
Every file contains parameters of the form
.Sq name value .
Lines containing boolean values are set to
.Sq NO
if the line is commented and to
.Sq YES
if the line is uncommented.
Empty lines or lines beginning with a
.Sq #
are ignored.
Parameter names and their values are case sensitive.
.Sh PARAMETERS
.Ss auth.conf
SMTP authentication can be configured in
.Pa auth.conf .
Each line has the format
.Dq Li user|smarthost:password .
.Ss dma.conf
Most of the behaviour of
.Nm
can be configured in
.Pa dma.conf .
.Pp
.Bl -tag -width 4n
.It Ic SMARTHOST Xo
(string, default=empty)
.Xc
If you want to send outgoing mails via a smarthost, set this variable to
your smarthosts address.
.It Ic PORT Xo
(numeric, default=25)
.Xc
Use this port to deliver remote emails.
Only useful together with the
.Sq SMARTHOST
option, because
.Nm
will deliver all mails to this port, regardless if a smarthost is set or not.
.It Ic ALIASES Xo
(string, default=/etc/mail/aliases)
.Xc
Path to the local aliases file.
Just stick with the default.
.It Ic SPOOLDIR Xo
(string, default=/var/spool/dma)
.Xc
Path to
.Nm Ap s
spool directory.
Just stick with the default.
.It Ic VIRTPATH Xo
(string, default=/etc/dma/virtusertable)
.Xc
Path to the
.Sq virtusertable
file.
.It Ic AUTHPATH Xo
(string, default=/etc/dma/auth.conf)
.Xc
Path to the
.Sq auth.conf
file.
.It Ic VIRTUAL Xo
(boolean, default=commented)
.Xc
Comment if you want virtual user support.
.It Ic SECURETRANS Xo
(boolean, default=commented)
.Xc
Comment if you want TLS/SSL secured transfer.
.It Ic STARTTLS Xo
(boolean, default=commented)
.Xc
Comment if you want to use STARTTLS.
Only useful together with
.Sq SECURETRANS .
.It Ic CERTFILE Xo
(string, default=empty)
.Xc
Path to your SSL certificate file.
.It Ic DEFER Xo
(boolean, default=commented)
.Xc
Comment if you want that
.Nm
defers your mail.
You have to flush your mail queue manually with the
.Fl q
option.
This option is handy if you are behind a dialup line.
.El
.Ss virtusertable
The
.Pa virtusertable
file specifies a virtual user table.
Each line has the format
.Dq Li localuser:mail-address .
Some smarthosts do not accept mails from unresolvable email address
(e.g. user@localhost) so you have to rewrite your outgoing email
address to a valid address.
.Sh SEE ALSO
.Xr mailaddr 7 ,
.Xr mailwrapper 8 ,
.Xr sendmail 8
.Rs
.%A "J. B. Postel"
.%T "Simple Mail Transfer Protocol"
.%O RFC 821
.Re
.Rs
.%A "J. Myers"
.%T "SMTP Service Extension for Authentication"
.%O RFC 2554
.Re
.Rs
.%A "P. Hoffman"
.%T "SMTP Service Extension for Secure SMTP over TLS"
.%O RFC 2487
.Re
.Sh HISTORY
The
.Nm
utility first appeared in
.Dx 1.11 .
.Sh AUTHORS
.Nm
was written by
.An Matthias Schmidt Aq matthias@dragonflybsd.org
and
.An Simon Schubert Aq corecode@dragonflybsd.org .
Commit	Line	Data
86e4d161 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	.\"
012adf14	32	.\" $DragonFly: src/libexec/dma/dma.8,v 1.5 2008/02/04 08:58:54 matthias Exp $
86e4d161	33	.\"
012adf14	34	.Dd February 4, 2008
86e4d161 MS	35	.Dt DMA 8
	36	.Os
	37	.Sh NAME
	38	.Nm dma
	39	.Nd DragonFly Mail Agent
	40	.Sh SYNOPSIS
	41	.Nm
9a0b96be	42	.Op Fl DiOq
86e4d161 MS	43	.Op Fl A Ar mode
	44	.Op Fl b Ar mode
	45	.Op Fl f Ar sender
	46	.Op Fl L Ar tag
	47	.Op Fl o Ar option
	48	.Op Fl r Ar sender
	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 (AUTH LOGIN only).
	57	.Pp
	58	.Nm
	59	is not intended as a replacement for real, big MTAs like
	60	.Xr sendmail 8
	61	or
0f215b8d	62	.Xr postfix 1 .
86e4d161 MS	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 Ar mode
	70	.Fl A Ns Ar c
	71	acts as a compatibility option for sendmail.
	72	.It Fl b Ar mode
	73	Specifying
	74	.Fl b Ns Ar p
	75	will list all mails currently stored in the mail queue.
	76	All other modes are are ignored.
	77	.It Fl D
	78	Don't run in the background.
	79	Useful for debugging.
	80	.It Fl f Ar sender
	81	Set sender address to
	82	.Ar sender .
	83	.It Fl i
	84	Ignore dots alone on lines by themselves in incoming messages.
	85	This should be set if you are reading data from a file.
	86	.It Fl L Ar tag
	87	Set the identifier used in syslog messages to the supplied
	88	.Ar tag .
	89	This is a compatibility option for sendmail.
9a0b96be MS	90	.It Fl O
9a0b96be MS	91	This is a compatibility option for sendmail.
86e4d161 MS	92	.It Fl o Ar option
	93	Specifying
	94	.Fl o Ns Ar i
	95	is synonymous to
	96	.Fl i .
	97	All other options are ignored.
	98	.It Fl q
	99	Process saved messages in the queue.
	100	.It Fl r Ar sender
	101	Same as
	102	.Fl f .
	103	.El
	104	.Sh CONFIGURATION
	105	.Nm
	106	can be configured with three config files:
	107	.Pp
	108	.Bl -bullet -compact
	109	.It
	110	auth.conf
	111	.It
	112	dma.conf
	113	.It
	114	virtusertable
	115	.El
	116	.Pp
	117	These three files are stored per default in
	118	.Pa /etc/dma .
86e4d161 MS	119	.Sh FILE FORMAT
	120	Every file contains parameters of the form
	121	.Sq name value .
	122	Lines containing boolean values are set to
	123	.Sq NO
	124	if the line is commented and to
	125	.Sq YES
	126	if the line is uncommented.
	127	Empty lines or lines beginning with a
	128	.Sq #
	129	are ignored.
	130	Parameter names and their values are case sensitive.
	131	.Sh PARAMETERS
	132	.Ss auth.conf
	133	SMTP authentication can be configured in
	134	.Pa auth.conf .
	135	Each line has the format
	136	.Dq Li user\|smarthost:password .
	137	.Ss dma.conf
	138	Most of the behaviour of
	139	.Nm
	140	can be configured in
	141	.Pa dma.conf .
	142	.Pp
	143	.Bl -tag -width 4n
	144	.It Ic SMARTHOST Xo
	145	(string, default=empty)
	146	.Xc
	147	If you want to send outgoing mails via a smarthost, set this variable to
	148	your smarthosts address.
	149	.It Ic PORT Xo
	150	(numeric, default=25)
	151	.Xc
	152	Use this port to deliver remote emails.
	153	Only useful together with the
	154	.Sq SMARTHOST
	155	option, because
	156	.Nm
	157	will deliver all mails to this port, regardless if a smarthost is set or not.
	158	.It Ic ALIASES Xo
	159	(string, default=/etc/mail/aliases)
	160	.Xc
	161	Path to the local aliases file.
	162	Just stick with the default.
	163	.It Ic SPOOLDIR Xo
	164	(string, default=/var/spool/dma)
	165	.Xc
	166	Path to
	167	.Nm Ap s
	168	spool directory.
	169	Just stick with the default.
	170	.It Ic VIRTPATH Xo
	171	(string, default=/etc/dma/virtusertable)
	172	.Xc
	173	Path to the
	174	.Sq virtusertable
	175	file.
86e4d161 MS	176	.It Ic AUTHPATH Xo
	177	(string, default=/etc/dma/auth.conf)
	178	.Xc
	179	Path to the
	180	.Sq auth.conf
	181	file.
86e4d161 MS	182	.It Ic VIRTUAL Xo
	183	(boolean, default=commented)
	184	.Xc
	185	Comment if you want virtual user support.
	186	.It Ic SECURETRANS Xo
	187	(boolean, default=commented)
	188	.Xc
	189	Comment if you want TLS/SSL secured transfer.
	190	.It Ic STARTTLS Xo
	191	(boolean, default=commented)
	192	.Xc
	193	Comment if you want to use STARTTLS.
	194	Only useful together with
	195	.Sq SECURETRANS .
	196	.It Ic CERTFILE Xo
	197	(string, default=empty)
	198	.Xc
	199	Path to your SSL certificate file.
	200	.It Ic DEFER Xo
	201	(boolean, default=commented)
	202	.Xc
	203	Comment if you want that
	204	.Nm
	205	defers your mail.
	206	You have to flush your mail queue manually with the
	207	.Fl q
	208	option.
	209	This option is handy if you are behind a dialup line.
	210	.El
	211	.Ss virtusertable
	212	The
	213	.Pa virtusertable
	214	file specifies a virtual user table.
	215	Each line has the format
	216	.Dq Li localuser:mail-address .
	217	Some smarthosts do not accept mails from unresolvable email address
	218	(e.g. user@localhost) so you have to rewrite your outgoing email
	219	address to a valid address.
	220	.Sh SEE ALSO
	221	.Xr mailaddr 7 ,
	222	.Xr mailwrapper 8 ,
	223	.Xr sendmail 8
	224	.Rs
	225	.%A "J. B. Postel"
	226	.%T "Simple Mail Transfer Protocol"
	227	.%O RFC 821
	228	.Re
	229	.Rs
	230	.%A "J. Myers"
	231	.%T "SMTP Service Extension for Authentication"
	232	.%O RFC 2554
	233	.Re
	234	.Rs
	235	.%A "P. Hoffman"
	236	.%T "SMTP Service Extension for Secure SMTP over TLS"
	237	.%O RFC 2487
	238	.Re
	239	.Sh HISTORY
	240	The
	241	.Nm
	242	utility first appeared in
	243	.Dx 1.11 .
	244	.Sh AUTHORS
	245	.Nm
246	was written by
247	.An Matthias Schmidt Aq matthias@dragonflybsd.org
248	and
249	.An Simon Schubert Aq corecode@dragonflybsd.org .