[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.10 2008/09/06 14:17:56 swildner Exp $
.\"
.Dd September 2, 2008
.Dt DMA 8
.Os
.Sh NAME
.Nm dma
.Nd DragonFly Mail Agent
.Sh SYNOPSIS
.Nm
.Op Fl DiO
.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 Fl q Ar arg
.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 Ar arg
Process saved messages in the queue.
The argument is required for compatibility with sendmail, and ignored.
.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 of whether 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	.\"
b53f68fc	32	.\" $DragonFly: src/libexec/dma/dma.8,v 1.10 2008/09/06 14:17:56 swildner 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
1b245941	42	.Op Fl DiO
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
1b245941	49	.Op Fl q Ar arg
86e4d161 MS	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
15386ecd	57	authentication.
86e4d161 MS	58	.Pp
	59	.Nm
	60	is not intended as a replacement for real, big MTAs like
	61	.Xr sendmail 8
	62	or
0f215b8d	63	.Xr postfix 1 .
86e4d161 MS	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 Ar mode
	71	.Fl A Ns Ar c
	72	acts as a compatibility option for sendmail.
	73	.It Fl b Ar mode
	74	Specifying
	75	.Fl b Ns Ar p
	76	will list all mails currently stored in the mail queue.
	77	All other modes are are ignored.
	78	.It Fl D
	79	Don't run in the background.
	80	Useful for debugging.
	81	.It Fl f Ar sender
	82	Set sender address to
	83	.Ar sender .
	84	.It Fl i
	85	Ignore dots alone on lines by themselves in incoming messages.
	86	This should be set if you are reading data from a file.
	87	.It Fl L Ar tag
	88	Set the identifier used in syslog messages to the supplied
	89	.Ar tag .
	90	This is a compatibility option for sendmail.
9a0b96be MS	91	.It Fl O
9a0b96be MS	92	This is a compatibility option for sendmail.
86e4d161 MS	93	.It Fl o Ar option
	94	Specifying
	95	.Fl o Ns Ar i
	96	is synonymous to
	97	.Fl i .
	98	All other options are ignored.
1b245941	99	.It Fl q Ar arg
86e4d161	100	Process saved messages in the queue.
1b245941	101	The argument is required for compatibility with sendmail, and ignored.
86e4d161 MS	102	.It Fl r Ar sender
	103	Same as
	104	.Fl f .
	105	.El
	106	.Sh CONFIGURATION
	107	.Nm
	108	can be configured with three config files:
	109	.Pp
	110	.Bl -bullet -compact
	111	.It
	112	auth.conf
	113	.It
	114	dma.conf
	115	.It
	116	virtusertable
	117	.El
	118	.Pp
	119	These three files are stored per default in
	120	.Pa /etc/dma .
86e4d161 MS	121	.Sh FILE FORMAT
	122	Every file contains parameters of the form
	123	.Sq name value .
	124	Lines containing boolean values are set to
	125	.Sq NO
	126	if the line is commented and to
	127	.Sq YES
	128	if the line is uncommented.
	129	Empty lines or lines beginning with a
	130	.Sq #
	131	are ignored.
	132	Parameter names and their values are case sensitive.
	133	.Sh PARAMETERS
	134	.Ss auth.conf
	135	SMTP authentication can be configured in
	136	.Pa auth.conf .
	137	Each line has the format
	138	.Dq Li user\|smarthost:password .
	139	.Ss dma.conf
	140	Most of the behaviour of
	141	.Nm
	142	can be configured in
	143	.Pa dma.conf .
86e4d161 MS	144	.Bl -tag -width 4n
	145	.It Ic SMARTHOST Xo
	146	(string, default=empty)
	147	.Xc
	148	If you want to send outgoing mails via a smarthost, set this variable to
	149	your smarthosts address.
	150	.It Ic PORT Xo
	151	(numeric, default=25)
	152	.Xc
	153	Use this port to deliver remote emails.
	154	Only useful together with the
	155	.Sq SMARTHOST
	156	option, because
	157	.Nm
b53f68fc SW	158	will deliver all mails to this port, regardless of whether a smarthost is set
b53f68fc SW	159	or not.
86e4d161 MS	160	.It Ic ALIASES Xo
	161	(string, default=/etc/mail/aliases)
	162	.Xc
	163	Path to the local aliases file.
	164	Just stick with the default.
	165	.It Ic SPOOLDIR Xo
	166	(string, default=/var/spool/dma)
	167	.Xc
	168	Path to
	169	.Nm Ap s
	170	spool directory.
	171	Just stick with the default.
	172	.It Ic VIRTPATH Xo
	173	(string, default=/etc/dma/virtusertable)
	174	.Xc
	175	Path to the
	176	.Sq virtusertable
	177	file.
86e4d161 MS	178	.It Ic AUTHPATH Xo
	179	(string, default=/etc/dma/auth.conf)
	180	.Xc
	181	Path to the
	182	.Sq auth.conf
	183	file.
86e4d161 MS	184	.It Ic VIRTUAL Xo
	185	(boolean, default=commented)
	186	.Xc
	187	Comment if you want virtual user support.
	188	.It Ic SECURETRANS Xo
	189	(boolean, default=commented)
	190	.Xc
	191	Comment if you want TLS/SSL secured transfer.
	192	.It Ic STARTTLS Xo
	193	(boolean, default=commented)
	194	.Xc
	195	Comment if you want to use STARTTLS.
	196	Only useful together with
	197	.Sq SECURETRANS .
	198	.It Ic CERTFILE Xo
	199	(string, default=empty)
	200	.Xc
	201	Path to your SSL certificate file.
dfce7456 MS	202	.It Ic SECURE Xo
	203	(boolean, default=commented)
	204	.Xc
	205	Change this entry to
	206	.Sq INSECURE
	207	to use plain text SMTP login over an insecure connection.
	208	You have to rename this variable manually to prevent that you send your
5a2a19a6	209	password accidentally over an insecure connection.
86e4d161 MS	210	.It Ic DEFER Xo
	211	(boolean, default=commented)
	212	.Xc
	213	Comment if you want that
	214	.Nm
	215	defers your mail.
	216	You have to flush your mail queue manually with the
	217	.Fl q
	218	option.
	219	This option is handy if you are behind a dialup line.
	220	.El
	221	.Ss virtusertable
	222	The
	223	.Pa virtusertable
	224	file specifies a virtual user table.
	225	Each line has the format
	226	.Dq Li localuser:mail-address .
	227	Some smarthosts do not accept mails from unresolvable email address
b53f68fc	228	(e.g.\& user@localhost) so you have to rewrite your outgoing email
86e4d161 MS	229	address to a valid address.
	230	.Sh SEE ALSO
	231	.Xr mailaddr 7 ,
	232	.Xr mailwrapper 8 ,
	233	.Xr sendmail 8
	234	.Rs
	235	.%A "J. B. Postel"
	236	.%T "Simple Mail Transfer Protocol"
	237	.%O RFC 821
	238	.Re
	239	.Rs
	240	.%A "J. Myers"
	241	.%T "SMTP Service Extension for Authentication"
	242	.%O RFC 2554
	243	.Re
	244	.Rs
	245	.%A "P. Hoffman"
	246	.%T "SMTP Service Extension for Secure SMTP over TLS"
	247	.%O RFC 2487
	248	.Re
	249	.Sh HISTORY
	250	The
	251	.Nm
	252	utility first appeared in
	253	.Dx 1.11 .
	254	.Sh AUTHORS
	255	.Nm
	256	was written by
	257	.An Matthias Schmidt Aq matthias@dragonflybsd.org
	258	and
	259	.An Simon Schubert Aq corecode@dragonflybsd.org .