community.general.listen_ports_facts module – Gather facts on processes listening on TCP and UDP ports
Note
This module is part of the community.general collection (version 9.5.1).
You might already have this collection installed if you are using the ansible
package.
It is not included in ansible-core
.
To check whether it is installed, run ansible-galaxy collection list
.
To install it, use: ansible-galaxy collection install community.general
.
You need further requirements to be able to use this module,
see Requirements for details.
To use it in a playbook, specify: community.general.listen_ports_facts
.
Synopsis
Gather facts on processes listening on TCP and UDP ports using the
netstat
orss
commands.This module currently supports Linux only.
Requirements
The below requirements are needed on the host that executes this module.
netstat or ss
Parameters
Parameter |
Comments |
---|---|
Override which command to use for fetching listen ports. By default module will use first found supported command on the system (in alphanumerical order). Choices:
|
|
Show both listening and non-listening sockets (for TCP this means established connections). Adds the return values Choices:
|
Attributes
Attribute |
Support |
Description |
---|---|---|
Support: full This action does not modify state. |
Can run in |
|
Support: N/A This action does not modify state. |
Will return details on what has changed (or possibly needs changing in |
|
Support: full |
Action returns an |
Notes
Note
ss
returns all processes for each listen address and port. This plugin will return each of them, so multiple entries for the same listen address and port are likely in results.
Examples
- name: Gather facts on listening ports
community.general.listen_ports_facts:
- name: TCP whitelist violation
ansible.builtin.debug:
msg: TCP port {{ item.port }} by pid {{ item.pid }} violates the whitelist
vars:
tcp_listen_violations: "{{ ansible_facts.tcp_listen | selectattr('port', 'in', tcp_whitelist) | list }}"
tcp_whitelist:
- 22
- 25
loop: "{{ tcp_listen_violations }}"
- name: List TCP ports
ansible.builtin.debug:
msg: "{{ ansible_facts.tcp_listen | map(attribute='port') | sort | list }}"
- name: List UDP ports
ansible.builtin.debug:
msg: "{{ ansible_facts.udp_listen | map(attribute='port') | sort | list }}"
- name: List all ports
ansible.builtin.debug:
msg: "{{ (ansible_facts.tcp_listen + ansible_facts.udp_listen) | map(attribute='port') | unique | sort | list }}"
- name: Gather facts on all ports and override which command to use
community.general.listen_ports_facts:
command: 'netstat'
include_non_listening: true
Returned Facts
Facts returned by this module are added/updated in the hostvars
host facts and can be referenced by name just like any other host fact. They do not need to be registered in order to use them.
Key |
Description |
---|---|
A list of processes that are listening on a TCP port. Returned: if TCP servers were found |
|
The address the server is listening on. Returned: always Sample: |
|
The address of the remote end of the socket. Returned: if Sample: |
|
The name of the listening process. Returned: if user permissions allow Sample: |
|
The pid of the listening process. Returned: always Sample: |
|
The port the server is listening on. Returned: always Sample: |
|
The network protocol of the server. Returned: always Sample: |
|
The start time of the listening process. Returned: always Sample: |
|
The user who is running the listening process. Returned: always Sample: |
|
A list of processes that are listening on a UDP port. Returned: if UDP servers were found |
|
The address the server is listening on. Returned: always Sample: |
|
The address of the remote end of the socket. Returned: if Sample: |
|
The name of the listening process. Returned: if user permissions allow Sample: |
|
The pid of the listening process. Returned: always Sample: |
|
The port the server is listening on. Returned: always Sample: |
|
The network protocol of the server. Returned: always Sample: |
|
The state of the socket. UDP is a connectionless protocol. Shows UCONN or ESTAB. Returned: if Sample: |
|
The start time of the listening process. Returned: always Sample: |
|
The user who is running the listening process. Returned: always Sample: |