Add Wake on LAN module

galaxy.yml

@@ -59,6 +59,7 @@ authors:
   - "Manuel Bonk <[email protected]>"
   - "Marcelo Moreira de Mello <[email protected]>"
   - "Marek Czernek <[email protected]>"
+  - "Marek Hulan <[email protected]>"
   - "Mark Hlawatschek <[email protected]>"
   - "Markus Bucher <[email protected]>"
   - "Martin Schlossarek <[email protected]>"

meta/runtime.yml

@@ -38,6 +38,7 @@ action_groups:
     - host_errata_info
     - host_info
     - host_power
+    - host_wake
     - hostgroup
     - hostgroup_info
     - http_proxy

plugins/modules/host_wake.py

@@ -0,0 +1,103 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+# (c) 2025 Marek Hulan
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+
+DOCUMENTATION = '''
+---
+module: host_wake
+version_added: 1.0.0
+short_description: Send Wake-on-LAN request to host
+description:
+  - "Send Wake-on-LAN (WOL) request to a host"
+author:
+  - "Marek Hulan (@ares)"
+options:
+  name:
+    description: Name (FQDN) of the host
+    required: true
+    aliases:
+      - hostname
+    type: str
+  state:
+    description: Wake-on-LAN state
+    default: 'on'
+    choices:
+      - 'on'
+    type: str
+extends_documentation_fragment:
+  - theforeman.foreman.foreman
+'''
+
+EXAMPLES = '''
+- name: "Send Wake-on-LAN request to host"
+  theforeman.foreman.host_wake:
+    username: "admin"
+    password: "changeme"
+    server_url: "https://foreman.example.com"
+    hostname: "test-host.domain.test"
+    state: 'on'
+
+- name: "Wake up multiple hosts"
+  theforeman.foreman.host_wake:
+    username: "admin"
+    password: "changeme"
+    server_url: "https://foreman.example.com"
+    hostname: "{{ item }}"
+    state: 'on'
+  loop:
+    - "host1.domain.test"
+    - "host2.domain.test"
+    - "host3.domain.test"
+'''
+
+RETURN = '''
+wol_result:
+    description: result of the Wake-on-LAN request
+    returned: always
+    type: dict
+    sample: {"wol": true}
+'''
+
+from ansible_collections.theforeman.foreman.plugins.module_utils.foreman_helper import ForemanEntityAnsibleModule
+
+
+def main():
+    module = ForemanEntityAnsibleModule(
+        foreman_spec=dict(
+            name=dict(aliases=['hostname'], required=True),
+        ),
+        argument_spec=dict(
+            state=dict(default='on', choices=['on']),
+        )
+    )
+
+    module_params = module.foreman_params
+
+    with module.api_connection():
+        # Send Wake-on-LAN request using the wol endpoint
+        params = {'id': module_params['name']}
+        wol_result = module.resource_action('hosts', 'wol', params=params)
+
+        # Return the result
+        module.exit_json(wol_result=wol_result)
+
+
+if __name__ == '__main__':
+    main()

tests/test_playbooks/fixtures/host_wake-0.yml

@@ -0,0 +1,106 @@
+interactions:
+- request:
+    body: null
+    headers:
+      Accept:
+      - application/json;version=2
+      Accept-Encoding:
+      - gzip, deflate
+      Connection:
+      - keep-alive
+      User-Agent:
+      - apypie (https://github.com/Apipie/apypie)
+    method: GET
+    uri: http://foreman.example.org/api/status
+  response:
+    body:
+      string: '{"result":"ok","status":200,"version":"3.16.0-develop","api_version":2}'
+    headers:
+      Cache-Control:
+      - max-age=0, private, must-revalidate
+      Content-Length:
+      - '71'
+      Content-Type:
+      - application/json; charset=utf-8
+      Foreman_api_version:
+      - '2'
+      Foreman_current_location:
+      - ; ANY
+      Foreman_current_organization:
+      - ; ANY
+      Foreman_version:
+      - 3.16.0-develop
+      Referrer-Policy:
+      - strict-origin-when-cross-origin
+      content-security-policy:
+      - 'default-src ''self''; child-src ''self''; connect-src ''self'' ws: wss:;
+        img-src ''self'' data:; script-src ''unsafe-eval'' ''unsafe-inline'' ''self'';
+        style-src ''unsafe-inline'' ''self'''
+      x-content-type-options:
+      - nosniff
+      x-download-options:
+      - noopen
+      x-frame-options:
+      - sameorigin
+      x-permitted-cross-domain-policies:
+      - none
+      x-xss-protection:
+      - '0'
+    status:
+      code: 200
+      message: OK
+- request:
+    body: '{}'
+    headers:
+      Accept:
+      - application/json;version=2
+      Accept-Encoding:
+      - gzip, deflate
+      Connection:
+      - keep-alive
+      Content-Length:
+      - '2'
+      Content-Type:
+      - application/json
+      User-Agent:
+      - apypie (https://github.com/Apipie/apypie)
+    method: PUT
+    uri: http://foreman.example.org/api/hosts/tester.hu.lan/wol
+  response:
+    body:
+      string: '{"wol":{"status":"success","message":"Wake-on-LAN packet sent successfully","mac_address":"c8:53:09:27:b8:f1"}}'
+    headers:
+      Cache-Control:
+      - max-age=0, private, must-revalidate
+      Content-Length:
+      - '111'
+      Content-Type:
+      - application/json; charset=utf-8
+      Foreman_api_version:
+      - '2'
+      Foreman_current_location:
+      - ; ANY
+      Foreman_current_organization:
+      - ; ANY
+      Foreman_version:
+      - 3.16.0-develop
+      Referrer-Policy:
+      - strict-origin-when-cross-origin
+      content-security-policy:
+      - 'default-src ''self''; child-src ''self''; connect-src ''self'' ws: wss:;
+        img-src ''self'' data:; script-src ''unsafe-eval'' ''unsafe-inline'' ''self'';
+        style-src ''unsafe-inline'' ''self'''
+      x-content-type-options:
+      - nosniff
+      x-download-options:
+      - noopen
+      x-frame-options:
+      - sameorigin
+      x-permitted-cross-domain-policies:
+      - none
+      x-xss-protection:
+      - '0'
+    status:
+      code: 200
+      message: OK
+version: 1

tests/test_playbooks/fixtures/host_wake-1.yml

@@ -0,0 +1,106 @@
+interactions:
+- request:
+    body: null
+    headers:
+      Accept:
+      - application/json;version=2
+      Accept-Encoding:
+      - gzip, deflate
+      Connection:
+      - keep-alive
+      User-Agent:
+      - apypie (https://github.com/Apipie/apypie)
+    method: GET
+    uri: http://foreman.example.org/api/status
+  response:
+    body:
+      string: '{"result":"ok","status":200,"version":"3.16.0-develop","api_version":2}'
+    headers:
+      Cache-Control:
+      - max-age=0, private, must-revalidate
+      Content-Length:
+      - '71'
+      Content-Type:
+      - application/json; charset=utf-8
+      Foreman_api_version:
+      - '2'
+      Foreman_current_location:
+      - ; ANY
+      Foreman_current_organization:
+      - ; ANY
+      Foreman_version:
+      - 3.16.0-develop
+      Referrer-Policy:
+      - strict-origin-when-cross-origin
+      content-security-policy:
+      - 'default-src ''self''; child-src ''self''; connect-src ''self'' ws: wss:;
+        img-src ''self'' data:; script-src ''unsafe-eval'' ''unsafe-inline'' ''self'';
+        style-src ''unsafe-inline'' ''self'''
+      x-content-type-options:
+      - nosniff
+      x-download-options:
+      - noopen
+      x-frame-options:
+      - sameorigin
+      x-permitted-cross-domain-policies:
+      - none
+      x-xss-protection:
+      - '0'
+    status:
+      code: 200
+      message: OK
+- request:
+    body: '{}'
+    headers:
+      Accept:
+      - application/json;version=2
+      Accept-Encoding:
+      - gzip, deflate
+      Connection:
+      - keep-alive
+      Content-Length:
+      - '2'
+      Content-Type:
+      - application/json
+      User-Agent:
+      - apypie (https://github.com/Apipie/apypie)
+    method: PUT
+    uri: http://foreman.example.org/api/hosts/tester.hu.lan/wol
+  response:
+    body:
+      string: '{"wol":{"status":"success","message":"Wake-on-LAN packet sent successfully","mac_address":"c8:53:09:27:b8:f1"}}'
+    headers:
+      Cache-Control:
+      - max-age=0, private, must-revalidate
+      Content-Length:
+      - '111'
+      Content-Type:
+      - application/json; charset=utf-8
+      Foreman_api_version:
+      - '2'
+      Foreman_current_location:
+      - ; ANY
+      Foreman_current_organization:
+      - ; ANY
+      Foreman_version:
+      - 3.16.0-develop
+      Referrer-Policy:
+      - strict-origin-when-cross-origin
+      content-security-policy:
+      - 'default-src ''self''; child-src ''self''; connect-src ''self'' ws: wss:;
+        img-src ''self'' data:; script-src ''unsafe-eval'' ''unsafe-inline'' ''self'';
+        style-src ''unsafe-inline'' ''self'''
+      x-content-type-options:
+      - nosniff
+      x-download-options:
+      - noopen
+      x-frame-options:
+      - sameorigin
+      x-permitted-cross-domain-policies:
+      - none
+      x-xss-protection:
+      - '0'
+    status:
+      code: 200
+      message: OK
+version: 1

tests/test_playbooks/host_wake.yml

@@ -0,0 +1,35 @@
+---
+- hosts: localhost
+  collections:
+    - theforeman.foreman
+  gather_facts: false
+  vars_files:
+    - vars/server.yml
+  vars:
+    host_name: tester.hu.lan
+  tasks:
+    - include_tasks: tasks/host_wake.yml
+      vars:
+        host_wake_name: "{{ host_name }}"
+        host_wake_state: "on"
+
+- hosts: tests
+  collections:
+    - theforeman.foreman
+  gather_facts: false
+  vars_files:
+    - vars/server.yml
+  vars:
+    host_name: tester.hu.lan
+  tasks:
+    - include_tasks: tasks/host_wake.yml
+      vars:
+        host_wake_name: "{{ host_name }}"
+        host_wake_state: "on"
+        expected_change: true
+
+    - include_tasks: tasks/host_wake.yml
+      vars:
+        host_wake_name: "{{ host_name }}"
+        host_wake_state: "on"
+        expected_change: true 

tests/test_playbooks/tasks/host_wake.yml

@@ -0,0 +1,16 @@
+---
+- name: "Send Wake-on-LAN request to host '{{ host_wake_name }}'"
+  host_wake:
+    username: "{{ foreman_username }}"
+    password: "{{ foreman_password }}"
+    server_url: "{{ foreman_server_url }}"
+    validate_certs: "{{ foreman_validate_certs }}"
+    name: "{{ host_wake_name | default(omit) }}"
+    hostname: "{{ host_wake_hostname | default(omit) }}"
+    state: "{{ host_wake_state | default(omit) }}"
+  register: result
+- assert:
+    fail_msg: "Wake-on-LAN request failed! (expected_change: {{ expected_change | default('unknown') }})"
+    that:
+      - result.changed == expected_change
+  when: expected_change is defined