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
