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 4.8.3).
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
.
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:
|
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 }}"
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: “0.0.0.0” |
|
The name of the listening process. Returned: if user permissions allow Sample: “mysqld” |
|
The pid of the listening process. Returned: always Sample: 1223 |
|
The port the server is listening on. Returned: always Sample: 3306 |
|
The network protocol of the server. Returned: always Sample: “tcp” |
|
The start time of the listening process. Returned: always Sample: “Thu Feb 2 13:29:45 2017” |
|
The user who is running the listening process. Returned: always Sample: “mysql” |
|
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: “0.0.0.0” |
|
The name of the listening process. Returned: if user permissions allow Sample: “rsyslogd” |
|
The pid of the listening process. Returned: always Sample: 609 |
|
The port the server is listening on. Returned: always Sample: 514 |
|
The network protocol of the server. Returned: always Sample: “udp” |
|
The start time of the listening process. Returned: always Sample: “Thu Feb 2 13:29:45 2017” |
|
The user who is running the listening process. Returned: always Sample: “root” |
Authors
Nathan Davison (@ndavison)
Collection links
Issue Tracker Repository (Sources) Submit a bug report Request a feature Communication