win_msg - Sends a message to logged in users on Windows hosts.

New in version 2.3.

Synopsis

  • Wraps the msg.exe command in order to send messages to Windows hosts.

Options

parameter required default choices comments
display_seconds
 no 10
How long to wait for receiver to acknowledge message, in seconds.
msg
 no Hello world!
The text of the message to be displayed.
The message must be less than 256 characters.
to
 no *
Who to send the message to. Can be a username, sessionname or sessionid.
wait
 no no
  • yes
  • no
Whether to wait for users to respond. Module will only wait for the number of seconds specified in display_seconds or 10 seconds if not specified. However, if wait is true, the message is sent to each logged on user in turn, waiting for the user to either press 'ok' or for the timeout to elapse before moving on to the next user.

Examples

- name: Warn logged in users of impending upgrade
  win_msg:
    display_seconds: 60
    msg: Automated upgrade about to start.  Please save your work and log off before {{ deployment_start_time }}

Return Values

Common return values are documented here Return Values, the following are the fields unique to this module:

name description returned type sample
display_seconds
Value of display_seconds module parameter.
 success string 10
msg
Test of the message that was sent.
 changed string Automated upgrade about to start. Please save your work and log off before 22 July 2016 18:00:00
rc
The return code of the API call
 always int 0
runtime_seconds
How long the module took to run on the remote windows host.
 success string 22 July 2016 17:45:51
sent_localtime
local time from windows host when the message was sent.
 success string 22 July 2016 17:45:51
wait
Value of wait module parameter.
 success boolean False

Notes

Note

  • This module must run on a windows host, so ensure your play targets windows hosts, or delegates to a windows host.
  • Messages are only sent to the local host where the module is run.
  • The module does not support sending to users listed in a file.
  • Setting wait to true can result in long run times on systems with many logged in users.

Status

This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Testing Ansible and Developing Modules.

© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.4/win_msg_module.html