DOCSEARCHbyAlgolia
Submit Docs

wakeonlan 4.0.0

repository·main·Indexed 43 days ago

https://github.com/remcohaszing/pywakeonlan

A Python module and CLI tool for sending Wake-on-LAN magic packets to power on computers remotely. Features include the wake() high-level API, raw packet generation via create_magic_packet(), and socket management with create_socket(). Supports SecureOn passwords, custom hosts, ports, and specific network interface routing for both IPv4 and IPv6.

Tokens
2K
Snippets
6
Records
7
Agent score
5%

What's inside wakeonlan

  2. Use wakeonlan as a Python module

    main

    You can import wakeonlan to send Wake-on-LAN magic packets programmatically.

    Key Requirements:

    • The target computer must have Wake-on-LAN enabled in its BIOS.
    • The target computer must have a MAC address (it does not need an IP address).
    • Magic packets are sent as broadcast packages.

    Functionality:

    • wake(mac_address, ...): Sends a magic packet to one or more MAC addresses.
    • SecureOn Password: You can append a SecureOn password to the MAC address using the format mac/password (e.g., 'ff.ff.ff.ff.ff.ff/01:23:45:67:89:ab').
    • Custom Host/Port: Specify a target host (defaults to 255.255.255.255) and port (defaults to 9). Note that port forwarding is required if using an external host.
    • Network Interface: Use the interface parameter to specify a local IP address of a network adapter to route the packet through.
    import wakeonlan

# Wake a single computer
wakeonlan.wake('ff.ff.ff.ff.ff.ff')

# Wake a single computer with a SecureOn password
wakeonlan.wake('ff.ff.ff.ff.ff.ff/01:23:45:67:89:ab')

# Wake multiple computers
wakeonlan.wake(
    'ff.ff.ff.ff.ff.ff',
    '00-00-00-00-00-00',
    'FFFFFFFFFFFF'
)

# Wake using a specific host and port
wakeonlan.wake('ff.ff.ff.ff.ff.ff', host='example.com', port=1337)

# Wake using a specific network interface
wakeonlan.wake('ff.ff.ff.ff.ff.ff', interface='192.168.0.2')

  3. Use the wakeonlan CLI

    main

    The wakeonlan command can be used from the terminal to wake one or more computers.

    Usage: wakeonlan [options] mac_address [mac_address ...]

    Arguments:

    • mac address: The MAC address or mac address/secureon password tuple.

    Options:

    • -h, --help: Show help message.
    • -o HOST, --host HOST: Host name to send the magic packet to (default: 255.255.255.255).
    • -p PORT, --port PORT: Port to send the magic packet to (default: 9).
    • -n INTERFACE, --interface INTERFACE: IP address of the network adapter to route through (default: None).
    • -4, --ipv4: Use IPv4.
    • -6, --ipv6: Use IPv6.
    $ wakeonlan --help
usage: wakeonlan [-h] [-4] [-6] [-o HOST] [-p PORT] [-n INTERFACE] mac address [mac address ...]

Wake one or more computers using the wake on lan protocol.

positional arguments:
  mac address           The mac addresses or "mac address/secureon password" tuples of the computers you are trying to wake.

options:
  -h, --help            show this help message and exit
  -o HOST, --host HOST  The host name to send the magic packet to. (default: 255.255.255.255)
  -p PORT, --port PORT  The port of the host to send the magic packet to. (default: 9)
  -n INTERFACE, --interface INTERFACE
                        The ip address of the network adapter to route the magic packet through. (default: None)
  -4, --ipv4            To indicate ipv4 should be used. (default: False)
  -6, --ipv6            To indicate ipv6 should be used. (default: False)

  4. Wake up computers using wake()

    main

    The wake() function is the primary high-level API for sending Wake-on-LAN magic packets to one or more machines. It handles packet creation and socket management automatically.

    Parameters:

    • *macs: One or more MAC addresses or "mac address/secureon password" tuples.
    • host: The IP address/hostname to broadcast to (defaults to BROADCAST_IP / '255.255.255.255').
    • port: The port to send the packet to (defaults to DEFAULT_PORT / 9).
    • interface: The IP address of the specific network adapter to use.
    • family: The socket.AddressFamily (e.g., socket.AF_INET for IPv4, socket.AF_INET6 for IPv6). If not specified, it auto-detects.

    Note: Wake-on-LAN must be enabled on the target device for this to work.

    from wakeonlan import wake
import socket

# Wake a single machine
wake('00:11:22:33:44:55')

# Wake multiple machines with a SecureOn password
wake('00:11:22:33:44:55/password', 'AA:BB:CC:DD:EE:FF/secret')

# Force IPv4 usage
wake('00:11:22:33:44:55', family=socket.AF_INET)

  6. Create a transmission socket with create_socket()

    main

    The create_socket() function returns a configured socket.socket object ready for sending magic packets. It automatically handles address resolution (IPv4/IPv6) and sets the SO_BROADCAST option.

    Arguments:

    • host: The hostname/IP to connect to.
    • port: The target port.
    • interface: (Optional) The IP address of the network adapter to bind to.
    • family: The socket.AddressFamily to use. Defaults to socket.AF_UNSPEC (auto-detect).

    Returns:

    • socket.socket: A connected UDP socket suitable for broadcasting.
    import socket
from wakeonlan import create_socket, create_magic_packet

# Create a socket for a specific interface and IPv4
with create_socket(host='255.255.255.255', port=9, interface='192.168.1.5', family=socket.AF_INET) as sock:
    packet = create_magic_packet('00:11:22:33:44:55')
    sock.send(packet)

  7. Create a magic packet with create_magic_packet()

    main

    Use create_magic_packet() to generate the raw bytes of a Wake-on-LAN magic packet. This is useful if you want to handle the network transmission yourself.

    Arguments:

    • macaddress: A string representing the MAC address (e.g., '00:11:22:33:44:55') or a tuple in the format 'mac address/secureon password'.

    Returns:

    • bytes: The constructed magic packet.

    Errors:

    • Raises ValueError if the MAC address or SecureOn password format is incorrect.
    from wakeonlan import create_magic_packet

# Standard MAC address
packet = create_magic_packet('00:11:22:33:44:55')

# MAC address with SecureOn password
packet_with_password = create_magic_packet('00:11:22:33:44:55/my_password')