Playground Tutorial

Getting Started with Playground

Environment Setup

You will need python3 and the venv module. On Debian-like systems, you may need to apt-get install both python3 and python3-venv.

Once you have these packages, setup a virtual environment for python and playground:

mkdir _some-directory
python3 -m venv <some-directory>

What this does is copy python and the python libraries into the created directory. You can now install packages (such as Playground) without polluting your global namespace.

But you have to activate this python environment to use it. There is a helpful script called activate. But it cannot be run directly, instead it must be sourced.

source <some-directory>/bin/activate

You should see a modification to your prompt indicating that the environment is activated.

Install Playground

I recommend that you clone playground and then install it using pip install -e. The reason is, I am not bumping the version every time I make a fix in Playground. If you install it directly from git, it won't reinstall correctly when I make fixes.

Also, your environment might need the wheel package. Here is the full set of commands. Make sure you are in your activated environment first.

pip install wheel
git clone https://github.com/CrimsonVista/Playground3.git
pip install -e <path_to_playground>

Testing out echo

The first thing to do to use Playground is initialize the overlay networking. The current commands only initialize it for the whole computer or the user. We'll add a manual tweak to confine it to a directory.

To access playground networking, use the pnetworking command. First, initialize the networking for the current user:

pnetworking initialize local

This creates a ~/.playground directory in your home directory that contains playground configuration. Create a playground environment directory and copy these configurations over. (I created my playground directory under my virtual environment directory)

mkdir playground_env
cp -R ~/.playground playground_env
cd playground_env
pnetworking status

The last command, pnetworking status will show you your current networking configuration. It should be empty:

Playground Networking Configuration:
-------------------------------------

Now, it's time to create a playground switch.

pnetworking add test_switch switch local 9876

This tells playground to add a switch named test_switch. It will be local only, meaning it cannot connect to other NICs on other machines. It will use 9876 as the TCP port for listening to connections from VNICs

Next, we need to setup a VNIC (virtual network interface card).

pnetworking add p_eth0 vnic 20184.1.2.3

This command adds a virtual network card into the playground networking system with a playground address of 20184.1.2.3. It is named p_eth0. You can see the status of all your devices by doing pnetworking status again.

Playground Networking Configuration:
-------------------------------------
 
switch test_switch:
        Status: Disabled
        Auto-Enable: True
        PNMS Managed: False
        TCP Location: 127.0.0.1:9876

vnic p_eth0:
        Status: Disabled
        Auto-Enable: True
        Playground Address: 20184.1.2.3
        Connected To: None
        Routes:

Next, we need to connect our VNIC to the switch. This is equivalent, in the real world, to connecting your Ethernet card to a physical switch with an Ethernet cable. There are no cables here, of course. The TCP/IP network connection represents the cable.

pnetworking config p_eth0 connect test_switch

And, because we can have multiple VNICs, we have to tell the system which VNIC is used for which routes. We can designate p_eth0 to be our "default" route.

pnetworking config p_eth0 route add __default__

Let's turn everything on!

pnetworking on

Run pnetworking status again and you should see both devices enabled.

NOTE: This playground networking is only functional within this directory. For example, if you change to a different directory and do pnetworking status, you will see an empty list.

Now that networking is enabled, we can run a test program.

python <path_to_playground3>/src/test/echotest.py server &

This will probably spit out a lot of debug messages. But once it is running, you can run the client side. The ampersand makes it run in the background.

python <path_to_playground3>/src/test/echotest.py 20184.1.2.3

This command tells the echotest to run in client mode and to connect to the server at 20184.1.2.3. Remember, this is the playground address of the VNIC we set up. So both client and server are connected to the same interface. Once the client is up and running, there should be a prompt to enter a message. The message is sent to the other side and received back again (echoed).