[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.9 2008/09/02 15:16:59 matthias Exp $
.\"
.Dd September 2, 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.
.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 .
.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 SECURE Xo
(boolean, default=commented)
.Xc
Change this entry to
.Sq INSECURE
to use plain text SMTP login over an insecure connection.
You have to rename this variable manually to prevent that you send your
password accidentally over an insecure connection.
.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	.\"
15386ecd	32	.\" $DragonFly: src/libexec/dma/dma.8,v 1.9 2008/09/02 15:16:59 matthias Exp $
86e4d161	33	.\"
15386ecd	34	.Dd September 2, 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
15386ecd	56	authentication.
86e4d161 MS	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 .
86e4d161 MS	142	.Bl -tag -width 4n
	143	.It Ic SMARTHOST Xo
	144	(string, default=empty)
	145	.Xc
	146	If you want to send outgoing mails via a smarthost, set this variable to
	147	your smarthosts address.
	148	.It Ic PORT Xo
	149	(numeric, default=25)
	150	.Xc
	151	Use this port to deliver remote emails.
	152	Only useful together with the
	153	.Sq SMARTHOST
	154	option, because
	155	.Nm
	156	will deliver all mails to this port, regardless if a smarthost is set or not.
	157	.It Ic ALIASES Xo
	158	(string, default=/etc/mail/aliases)
	159	.Xc
	160	Path to the local aliases file.
	161	Just stick with the default.
	162	.It Ic SPOOLDIR Xo
	163	(string, default=/var/spool/dma)
	164	.Xc
	165	Path to
	166	.Nm Ap s
	167	spool directory.
	168	Just stick with the default.
	169	.It Ic VIRTPATH Xo
	170	(string, default=/etc/dma/virtusertable)
	171	.Xc
	172	Path to the
	173	.Sq virtusertable
	174	file.
86e4d161 MS	175	.It Ic AUTHPATH Xo
	176	(string, default=/etc/dma/auth.conf)
	177	.Xc
	178	Path to the
	179	.Sq auth.conf
	180	file.
86e4d161 MS	181	.It Ic VIRTUAL Xo
	182	(boolean, default=commented)
	183	.Xc
	184	Comment if you want virtual user support.
	185	.It Ic SECURETRANS Xo
	186	(boolean, default=commented)
	187	.Xc
	188	Comment if you want TLS/SSL secured transfer.
	189	.It Ic STARTTLS Xo
	190	(boolean, default=commented)
	191	.Xc
	192	Comment if you want to use STARTTLS.
	193	Only useful together with
	194	.Sq SECURETRANS .
	195	.It Ic CERTFILE Xo
	196	(string, default=empty)
	197	.Xc
	198	Path to your SSL certificate file.
dfce7456 MS	199	.It Ic SECURE Xo
	200	(boolean, default=commented)
	201	.Xc
	202	Change this entry to
	203	.Sq INSECURE
	204	to use plain text SMTP login over an insecure connection.
	205	You have to rename this variable manually to prevent that you send your
5a2a19a6	206	password accidentally over an insecure connection.
86e4d161 MS	207	.It Ic DEFER Xo
	208	(boolean, default=commented)
	209	.Xc
	210	Comment if you want that
	211	.Nm
	212	defers your mail.
	213	You have to flush your mail queue manually with the
	214	.Fl q
	215	option.
	216	This option is handy if you are behind a dialup line.
	217	.El
	218	.Ss virtusertable
	219	The
	220	.Pa virtusertable
	221	file specifies a virtual user table.
	222	Each line has the format
	223	.Dq Li localuser:mail-address .
	224	Some smarthosts do not accept mails from unresolvable email address
	225	(e.g. user@localhost) so you have to rewrite your outgoing email
	226	address to a valid address.
	227	.Sh SEE ALSO
	228	.Xr mailaddr 7 ,
	229	.Xr mailwrapper 8 ,
	230	.Xr sendmail 8
	231	.Rs
	232	.%A "J. B. Postel"
	233	.%T "Simple Mail Transfer Protocol"
	234	.%O RFC 821
	235	.Re
	236	.Rs
	237	.%A "J. Myers"
	238	.%T "SMTP Service Extension for Authentication"
	239	.%O RFC 2554
	240	.Re
	241	.Rs
	242	.%A "P. Hoffman"
	243	.%T "SMTP Service Extension for Secure SMTP over TLS"
	244	.%O RFC 2487
	245	.Re
	246	.Sh HISTORY
	247	The
	248	.Nm
	249	utility first appeared in
	250	.Dx 1.11 .
	251	.Sh AUTHORS
	252	.Nm
	253	was written by
	254	.An Matthias Schmidt Aq matthias@dragonflybsd.org
	255	and
	256	.An Simon Schubert Aq corecode@dragonflybsd.org .