'\" te
.\" Copyright (c) 2004, Sun Microsystems, Inc.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH ETRN 8 "November 22, 2021"
.SH NAME
etrn \- start mail queue run
.SH SYNOPSIS
.nf
\fBetrn\fR [\fB-b\fR] [\fB-v\fR] \fIserver-host\fR [\fIclient-hosts\fR]
.fi

.SH DESCRIPTION
SMTP's \fBETRN\fR command allows an SMTP client and server to interact, giving
the server an opportunity to start the processing of its queues for messages to
go to a given host. This is meant to be used in start-up conditions, as well as
for mail nodes that have transient connections to their service providers.
.sp
.LP
The \fBetrn\fR utility initiates an SMTP session with the host
\fIserver-host\fR and sends one or more \fBETRN\fR commands as follows: If no
\fIclient-hosts\fR are specified, \fBetrn\fR looks up every host name for which
\fBsendmail\fR(8) accepts email and, for each name, sends an \fBETRN\fR
command with that name as the argument. If any \fIclient-hosts\fR are
specified, \fBetrn\fR uses each of these as arguments for successive \fBETRN\fR
commands.
.SH OPTIONS
The following options are supported:
.sp
.ne 2
.na
\fB\fB-b\fR\fR
.ad
.RS 6n
System boot special case. Make sure localhost is accepting SMTP connections
before initiating the SMTP session with server-host.
.sp
This option is useful because it prevents race conditions between
\fBsendmail\fR(8) accepting connections and \fIserver-host\fR attempting to
deliver queued mail. This check is performed automatically if no
\fIclient-hosts\fR are specified.
.RE

.sp
.ne 2
.na
\fB\fB-v\fR\fR
.ad
.RS 6n
The normal mode of operation for \fBetrn\fR is to do all of its work silently.
The \fB-v\fR option makes it verbose, which causes \fBetrn\fR to display its
conversations with the remote SMTP server.
.RE

.SH ENVIRONMENT VARIABLES
No environment variables are used. However, at system start-up,
\fBsvc:/network/smtp:sendmail\fR reads \fB/etc/default/sendmail\fR. In this
file, if the variable \fBETRN_HOSTS\fR is set, \fBsvc:/network/smtp:sendmail\fR
parses this variable and invokes \fBetrn\fR appropriately. \fBETRN_HOSTS\fR
should be of the form:
.sp
.in +2
.nf
"s1:c1.1,c1.2        s2:c2.1 s3:c3.1,c3.2,c3.3"
.fi
.in -2
.sp

.sp
.LP
That is, white-space separated groups of \fIserver:client\fR where \fIclient\fR
can be one or more comma-separated names. The \fI:client\fR part is optional.
\fIserver\fR is the name of the server to prod; a mail queue run is requested
for each \fIclient\fR name. This is comparable to running:
.sp
.in +2
.nf
/usr/lib/sendmail -qR \fIclient\fR
.fi
.in -2
.sp

.sp
.LP
on the host \fIserver\fR.
.SH EXAMPLES
\fBExample 1 \fRUsing \fBetrn\fR
.sp
.LP
Inserting the line:

.sp
.in +2
.nf
ETRN_HOSTS="s1.example.com:clnt.example.com s2.example.com:clnt.example.com"
.fi
.in -2
.sp

.sp
.LP
in \fB/etc/default/sendmail\fR results in \fBsvc:/network/smtp:sendmail\fR
invoking \fBetrn\fR such that \fBETRN\fR commands are sent to both
\fBs1.example.com\fR and \fBs2.example.com\fR, with both having
\fBclnt.example.com\fR as the \fBETRN\fR argument.

.sp
.LP
The line:

.sp
.in +2
.nf
ETRN_HOSTS="server.example.com:client1.example.com,client2.example.com"
.fi
.in -2
.sp

.sp
.LP
results in two \fBETRN\fR commands being sent to \fBserver.example.com\fR, one
with the argument \fBclient1.example.com\fR, the other with the argument
\fBclient2.example.com\fR.

.sp
.LP
The line:

.sp
.in +2
.nf
ETRN_HOSTS="server1.example.com server2.example.com"
.fi
.in -2
.sp

.sp
.LP
results in set of a \fBETRN\fR commands being sent to both
\fBserver1.example.com\fR and \fBserver2.example.com\fR; each set contains one
\fBETRN\fR command for each host name for which \fBsendmail\fR(8) accepts
email, with that host name as the argument.

.SH FILES
.ne 2
.na
\fB\fB/etc/mail/sendmail.cf\fR\fR
.ad
.RS 25n
\fBsendmail\fR configuration file
.RE

.sp
.ne 2
.na
\fB\fB/etc/default/sendmail\fR\fR
.ad
.RS 25n
Variables used by \fBsvc:/network/smtp:sendmail\fR
.RE

.SH ATTRIBUTES
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Stable
.TE

.SH SEE ALSO
.BR attributes (7),
.BR sendmail (8)
.sp
.LP
RFC 1985
.SH NOTES
Not all SMTP servers support \fBETRN\fR.