Awake ====== *Command and library to "wake on lan" a remote host.* If you want to know something more about the WoL stuff check `the wikipedia page`_. :: Usage: awake [options] MAC1 [MAC2 MAC3 MAC...] Options: --version show program's version number and exit -h, --help show this help message and exit -p PORT, --port=PORT Destination port. (Default 9) -b BROADCAST, --broadcast=BROADCAST Broadcast ip of the network. (Default 255.255.255.255) -d DESTINATION, --destination=DESTINATION Destination ip/domain to connect and send the packet, by default use broadcast. -f FILE, --file=FILE Use a file with the list of macs, separated with -s, by default \n. If any mac (line where -s \n), have the "#" character, any following character is considered a comment. Can be used multiple times for multiple files. -s SEPARATOR, --separator=SEPARATOR Pattern to be use as a separator with the -f option. (Default \n) -q, --quiet Do not output informative messages. Requirements ------------- Any cpython (common python) implementation from 2.4 to 3.X. Probably it also works with jython, ironpython and pypy but I haven't personally tested on those implementations. Installation ------------ :: pip install awake Or with the old `easy_install` :: easy_install awake Or with the source :: python setup.py install Upgrading from 0.X to 1.0 -------------------------- Make sure the previous CLI script `awake.py` gets removed from the script installation path after the upgrading, e.g. in linux `/usr/bin/` the new cli interface is just `awake` and if the file `awake.py` exists at the same level of the script then the new `awake` going to try to fetch the required modules from the old cli script `awake.py`. CLI Examples ------------ **Wake-on-lan a group of computers in the current network**:: awake 1c:6f:65:31:aa:5f 1c6c2531e051 3f.6c.25.31.e0.55 3b-6c-21-31-e0-41 which is equivalent to:: awake -f ~/list_of_macs and in the file ``list_of_macs`` have one MAC per line or use the ``-s`` option. ``list_of_macs`` content:: 1c:6f:65:31:aa:5f # web1 1c6c2531e051 # web2 # The rest 3f.6c.25.31.e0.55 3b-6c-21-31-e0-41 The format of the MAC is flexible in the sense that can use any character to group the digits of the MAC, except for the reserved character *#* for comments. **Wake-on-lan a computer or group of computers in a external network** For this situation, you need to forward a port in your router, for example to forward 9999 to 9 in the local network o 7777 to 7, check the documentation if your router or modem. After the port has been configured you can use `DDNS`_ to have a reference to the current ip address of your router/modem and use awake in this way:: awake -a myhouse.homedns.com -p 9999 -f ~/file_with_my_macs or use any other option, the important here is to use the ``-a`` and ``-p`` options to specify the destination to send the magic packet. **Alternative method to invoke awake** Awake can be used calling the module directly from python:: python -m awake Is the same interface as the installed script ``awake``, this is very useful in platforms like windows, when the `PythonXX/Scripts` is not set in the `PATH`. As a library ------------ The real functionality of the wake-on-lan is provided from a small function that is implemented in the provided module ``awake.wol``:: send_magic_packet(mac, broadcast='255.255.255.255', dest=None, port=9) Send a "magic packet" to the given destination mac to wake up the host, if `dest` is not specified then the packed is broadcasted. Apart from the awake script the WOL functionality can be easily integrated in your python programs with a simple call to the function like:: from awake import wol def sysadmin_function_x(mac, *args): # some stuff... wol.send_magic_packet(mac) # some more stuff... Tests ----- The tests are designed to be executed with the python unittest module, you can run the tests from the folder `test`:: cd test python -m unittest discover In case that you want to run the tests in python < 2.7, you will need the `unittest2`_ module. The general recommended process to develop is using `virtualenv`_ and after creating the environ just run:: ./environ/bin/python setup.py install ./environ/bin/python -m unittest discover Improvements, bugs? ------------------- For any improvement or bug, feel free to create an `issue`_ in the github project. .. _the wikipedia page: http://en.wikipedia.org/wiki/Wake-on-LAN .. _DDNS: http://en.wikipedia.org/wiki/DDNS .. _issue: http://github.com/cyraxjoe/awake/issues .. _pypi: http://pypi.python.org/pypi/awake .. _unittest2: http://pypi.python.org/pypi/unittest2 .. _virtualenv: http://pypi.python.org/pypi/virtualenv