Layer 2 Shell Documentation

The Layer 2 Shell (l2sh) client and server are provided as a single Python script, l2sh.py. l2sh.py can be run on the command line to either start an l2sh server or initiate a connection to one as a client. As both a server and a client l2sh must be run with root privileges.

l2sh Command Line Help

The l2sh.py script, when executed with no options, will output help on the command line:

$ ./l2sh.py

Error:  At a minimum you must supply -i <interface> '<MAC address>' (client mode connecting to <MAC address>)
        or '-s -i <interface>' (server mode)
Usage: l2sh.py [options] [MAC Address]

Options:
-h, --help            show this help message and exit
-c, --client          Run in client mode connecting to the given host
                        (default).
-i <interface>, --interface=<interface>
                        Bind to the given interface(s) (e.g. '-i eth0,wlan0')
                        or 'all' to bind on all UP interfaces.
-s, --server          Run in server mode.
-u <username>, --username=<username>
                        The username to be used when connecting (uses your
                        logged-in username by default).
-P <password>, --password=<password>
                        The password to be used when connecting (will ask if
                        not provided--recommended)

Running an l2sh server

Running an l2sh server is as simple as executing the following command:

sudo ./l2sh.py -s -i br-lan0
serving on 'br-lan0' (layer 2)...
Started l2sh listener on 'eth0'

Running an l2sh client

Like the server command line above, the client operation is very similar:

sudo ./l2sh.py -c -i eth0 00:11:22:33:44:55
Username: root
Password:
Press control-C to exit (yes, this means you can't use commands that require a SIGINT--working on it!).

Building the l2sh ipk (opkg)

Inside of the l2sh directory is a directory named ‘opkg’ which contains a valid OpenWRT Makefile that can be used to build an ipk package file. To use it just make a symbolic link from your openwrt trunk directory like so:

root@myhost:/path/to/openwrt/trunk # ln -s package/l2sh /path/to/l2sh/okpg

Once the link is created the ipk can be selected in the OpenWRT “make menuconfig” menu under the “Network” category. Once it is selected the package will be built as part of the ‘make’ command. Alternatively, you can build the package directly by executing the following command from within the OpenWRT trunk directory:

make package/l2sh/{clean,compile,install}

Layer 2 Shell API Reference

The documentation below covers the programming API available to Python programmers that import l2sh into their programs.

check_credentials(user, password)

Checks a given user and password against /etc/shadow (or /etc/passwd if /etc/shadow doesn’t exist). Returns None on success and an error message on failure.

counter()

Adds to the count every time it is called.

get_uid(username)

Returns the UID of the given user

interfaces()

Returns a list of all non-alias, UP interfaces on this host

setup_socket(interface)

Returns a socket object bound to the given interface (e.g. ‘eth0’). The socket is created as such: socket(AF_PACKET, SOCK_RAW, PROTO) Note: By default PROTO is set to 0x55aa