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.

.. automodule:: l2sh
    :members: