<!DOCTYPE varlistentry [
	<!ENTITY from-version21 SYSTEM "version-2.1.xml">
]>
<varlistentry>
	<term><option>--retain-handling</option> always | new | never</term>
	<listitem>
		&from-version21;
		<para>
			Use this option to control the retain handling option when making a
			subscription. This controls under what circumstances an existing
			retained message is sent to the client when the subscription is
			made.
		</para>

		<itemizedlist mark="circle">
			<listitem><para><option>always</option> - always deliver retained messages</para></listitem>
			<listitem><para>
				<option>new</option> - deliver retained messages the first time
				a subscription is made, but not on subsequent subscriptions. This
				is useful for the case where you have a long running client using
				a non-clean session. If the connection is dropped briefly, when the
				client reconnects you will not receive the retained messages again.
			</para></listitem>
			<listitem><para><option>never</option> - never deliver retained messages</para></listitem>
		</itemizedlist>
	</listitem>
</varlistentry>

