.. _param-imdiag-listenportfilename:
.. _imdiag.parameter.module.listenportfilename.listener:

ListenPortFileName
==================

.. index::
   single: imdiag; ListenPortFileName
   single: ListenPortFileName

.. summary-start

Writes the port chosen for the diagnostic listener to the named file.

.. summary-end

This parameter applies to :doc:`../../configuration/modules/imdiag`.

:Name: ListenPortFileName
:Scope: module
:Type: string (filename)
:Default: module=none
:Required?: yes
:Introduced: at least 5.x, possibly earlier

Description
-----------
Specifies a file that receives the TCP port number after the listener starts.
Use :ref:`ServerRun <param-imdiag-serverrun>` to initialize the listener.
The parameter is mandatory and must be provided before the listener is
created.

The file is overwritten each time the listener starts. When the listener is
configured with port ``0`` (ephemeral port selection), this file is the only way
to discover the actual port allocated by the operating system.

Module usage
------------
.. _param-imdiag-module-listenportfilename-listener:
.. _imdiag.parameter.module.listenportfilename.listener-usage:

.. code-block:: rsyslog

   module(load="imdiag"
          listenPortFileName="/var/run/rsyslog/imdiag.port"
          serverRun="0")

Legacy names (for reference)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Historic names/directives for compatibility. Do not use in new configs.

.. _imdiag.parameter.legacy.imdiaglistenportfilename:

- $IMDiagListenPortFileName — maps to ListenPortFileName (status: legacy)

.. index::
   single: imdiag; $IMDiagListenPortFileName
   single: $IMDiagListenPortFileName

See also
--------
See also :doc:`../../configuration/modules/imdiag`.
