From c43f6ed97544191ca804a8885caa3af8906e7f65 Mon Sep 17 00:00:00 2001 From: Andy Fingerhut Date: Wed, 16 Oct 2024 18:55:00 -0400 Subject: [PATCH 1/3] Move optional steps for testing VMs out of README.md file This may help avoid new users being confused that they must follow those instructions. Signed-off-by: Andy Fingerhut --- vm-ubuntu-20.04/README.md | 217 +--------------- vm-ubuntu-20.04/create-vm-image-for-others.md | 210 ++++++++++++++++ vm-ubuntu-24.04/README.md | 235 +----------------- vm-ubuntu-24.04/create-vm-image-for-others.md | 214 ++++++++++++++++ 4 files changed, 435 insertions(+), 441 deletions(-) create mode 100644 vm-ubuntu-20.04/create-vm-image-for-others.md create mode 100644 vm-ubuntu-24.04/create-vm-image-for-others.md diff --git a/vm-ubuntu-20.04/README.md b/vm-ubuntu-20.04/README.md index ade3084c..6a1eb7ff 100644 --- a/vm-ubuntu-20.04/README.md +++ b/vm-ubuntu-20.04/README.md @@ -1,10 +1,12 @@ # Creating the VM + + Below are the steps to create a brand new VM using Vagrant: + Install [Vagrant](https://developer.hashicorp.com/vagrant/docs/installation) on your system if it's not already installed. - + Navigate to the directory where you want to create the new VM. + + In a shell/terminal window, change to this `vm-ubuntu-20.04` + directory inside the `tutorials` directory. + Run the below command in the terminal. - ``` + ```bash vagrant up ``` @@ -13,214 +15,9 @@ - You can update these packages using `apt upgrade` within the VM. + Alternatively, a development VM can be created by running - ``` + ```bash vagrant up dev ``` -*Note* : that creating a development VM can take one to several -hours, depending upon the speed of your computer and Internet -connection. - -Below are steps that were performed _after_ one of the commands above -was run on the host OS, before creating the VM images. Some of these -steps could probably be automated with programs, and changes to the -`vagrant` scripts that can do so are welcome. I performed these steps -manually to create a VM image, simply to avoid the experimentation and -time required to automate them. I typically only create new VM images -once per month. - -+ Log in as user p4 (password p4) -+ Click "Upgrade" in the pop-up window asking if you want to upgrade - the system, if asked. This will download the latest Linux kernel - version released for Ubuntu 20.04, and other updated packages. -+ Reboot the system. -+ This is optional, but if you want to save a little disk space, use - - ``` - sudo apt purge - ``` - - to remove older version of Linux - kernel, if the upgrade installed a newer one. -+ Clean the local repository of retrieved package files to free up disk space - - ``` - sudo apt clean - ``` - -+ Log in as user p4 (password p4) -+ Start menu -> Preferences -> LXQt settings -> Monitor settings - + Change resolution from initial 800x600 to 1024x768. Apply the changes. - + Close monitor settings window - + *Note*: For some reason I do not know, these settings seem to be - undone, even if I use the "Save" button. They are temporarily in - effect if I shut down the system and log back in, but then in a few - seconds it switches back to 800x600. Strange. -+ Start menu -> Preferences -> LXQt settings -> Desktop - + In "Wallpaper mode" popup menu, choose "Center on the screen". - + Click Apply button - + Close "Desktop preferences" window -+ Several of the icons on the desktop have an exclamation mark on - them. If you try double-clicking those icons, it pops up a window - saying "This file 'Wireshark' seems to be a desktop entry. What do - you want to do with it?" with buttons for "Open", "Execute", and - "Cancel". Clicking "Execute" executes the associated command. - If you do a mouse middle click on one of these desktop icons, a - popup menu appears where the second-to-bottom choice is "Trust this - executable". Selecting that causes the exclamation mark to go away, - and future double-clicks of the icon execute the program without - first popping up a window to choose between Open/Execute/Cancel. I - did that for each of these desktop icons: - + Terminal - + Wireshark -+ Log off - -+ Log in as user vagrant (password vagrant) -+ Change monitor settings and wallpaper mode as described above for - user p4. -+ Open a terminal. - + Run the command - - ``` - ./clean.sh - ``` - which removes about 6 to 7 GBytes of - files created while building the projects. -+ Log off - - -# Notes on test results for the VM - -I have run the tests below on every VM image I release, before -releasing it. You need not run them again, unless you are curious how -to do so. - - -## p4c testing results - -Steps to run the p4c tests: - -+ Log in as user vagrant (password vagrant) -+ In a new terminal, execute these commands: - -If you are testing on a Release VM image, first get a copy of the p4c -source code using the following command. This is unnecessary with a -Development VM image, as there is already a `p4c` directory with the -version of source code used to create that image already included in -the home directory of the `vagrant` user account: - -```bash -# for Release VM image only -git clone --recursive https://github.com/p4lang/p4c -``` - -The following steps are common for both Release and Development VM -images: - -```bash -# Compile p4c again from source, since the clean.sh step reduced disk -# space by deleting the p4c/build directory. -git clone https://github.com/jafingerhut/p4-guide -cd p4c -~/p4-guide/bin/build-p4c.sh - -# Run the p4c tests -cd build -make -j2 check |& tee make-check-out.txt -``` - -As of 2024-08-01, the p4c compiler passes all of its included tests, -except for some of the p4testgen tests (if those are enabled). - - -## Send ping packets in the solution to `basic` exercise of `p4lang/tutorials` repository - -With the version of the [tutorials](https://github.com/p4lang/tutorials) repository -that comes pre-installed in the `p4` user account of this VM, the -following tests pass. - -First log in as the user `p4` (password `p4`) and open a terminal -window. -```bash -$ cd tutorials/exercises/basic -$ cp solution/basic.p4 basic.p4 -$ make run -``` - -If at the end of many lines of logging output you see a prompt -`mininet>`, you can try entering the command `h1 ping h2` to ping from -virtual host `h1` in the exercise to `h2`, and it should report a -successful ping every second. It will not stop on its own. You can -type Control-C to stop it and return to the `mininet>` prompt, and you -can type Control-D to exit from mininet and get back to the original -shell prompt. To ensure that any processes started by the above steps -are terminated, you can run this command: -```bash -$ make stop -``` - - -# Creating a single file image of the VM - -These notes are primarily here as a reminder for people creating VM -images for distribution. If you downloaded a VM image, these steps -were already performed, and there is no reason you need to perform -them again. - -For the particular case of creating the VM named: - -+ 'P4 Tutorial Development 2024-08-01' -+ created on August 1, 2024 - -here were the host OS details, in case it turns out that matters to -the finished VM image for some reason: - -+ Windows 10 Enterprise -+ VirtualBox 6.1.30 r148432 -+ Vagrant 2.2.18 - -In the VirtualBox GUI interface: - -+ Choose menu item File -> Export Appliance ... -+ Select the VM named 'P4 Tutorial Development 2024-08-01' and click - Continue button - -+ Format - + I used: Open Virtualization Format 1.0 - + Other available options were: - + Open Virtualization Format 0.9 - + Open Virtualization Format 2.0 -+ Target file - + I used: /Users/andy/Documents/P4 Tutorials Development 2024-08-01.ova -+ Mac Address Policy - + I used: Include only NAT network adapter MAC addresses - + Other available options were: - + Include all network adapter MAC addresses - + Strip all network adapter MAC addresses -+ Additionally - + Write Manifest file: checked - + Include ISO image files: unchecked - -Clicked "Continue" button. - -Virtual system settings: - -+ Name: P4 Tutorial 2024-08-01 -+ Product: I left this blank -+ Product-URL: I left this blank -+ Vendor: P4.org - P4 Language Consortium -+ Vendor-URL: https://p4.org -+ Version: 2024-08-01 -+ Description: - -``` -Open source P4 development tools built from latest source code as of 2024-Aug-01 and packaged into an Ubuntu 20.04 Desktop Linux VM for the AMD64 architecture. -``` - -+ License - -``` -Open source code available hosted at https://github.com/p4lang is released under the Apache 2.0 license. Libraries it depends upon, such as Protobuf, Thrift, gRPC, Ubuntu Linux, etc. are released under their own licenses. -``` - -Clicked "Export" button. +*Note* that creating a development VM can take several hours, +depending upon the speed of your computer and Internet connection. diff --git a/vm-ubuntu-20.04/create-vm-image-for-others.md b/vm-ubuntu-20.04/create-vm-image-for-others.md new file mode 100644 index 00000000..6f050d1f --- /dev/null +++ b/vm-ubuntu-20.04/create-vm-image-for-others.md @@ -0,0 +1,210 @@ +# Creating a VM image for distribution to others + +If you want to run `p4c` tests, see the next section on how to do so, +_before_ running the commands in this section, since the commands in +this section will delete files that take one to several hours to +create while compiling p4c, needed for running p4c tests. + +Below are steps that were performed _after_ the commands in the +README.md file were run on the host OS, before creating the VM images. +Some of these steps could probably be automated with programs, and +changes to the `vagrant` scripts that can do so are welcome. I +performed these steps manually to create a VM image, simply to avoid +the experimentation and time required to automate them. I typically +only create new VM images once per month. + ++ Log in as user p4 (password p4) ++ Click "Upgrade" in the pop-up window asking if you want to upgrade + the system, if asked. This will download the latest Linux kernel + version released for Ubuntu 20.04, and other updated packages. ++ Reboot the system. ++ This is optional, but if you want to save a little disk space, use + + ``` + sudo apt purge + ``` + + to remove older version of Linux + kernel, if the upgrade installed a newer one. ++ Clean the local repository of retrieved package files to free up disk space + + ``` + sudo apt clean + ``` + ++ Log in as user p4 (password p4) ++ Start menu -> Preferences -> LXQt settings -> Monitor settings + + Change resolution from initial 800x600 to 1024x768. Apply the changes. + + Close monitor settings window + + *Note*: For some reason I do not know, these settings seem to be + undone, even if I use the "Save" button. They are temporarily in + effect if I shut down the system and log back in, but then in a few + seconds it switches back to 800x600. Strange. ++ Start menu -> Preferences -> LXQt settings -> Desktop + + In "Wallpaper mode" popup menu, choose "Center on the screen". + + Click Apply button + + Close "Desktop preferences" window ++ Several of the icons on the desktop have an exclamation mark on + them. If you try double-clicking those icons, it pops up a window + saying "This file 'Wireshark' seems to be a desktop entry. What do + you want to do with it?" with buttons for "Open", "Execute", and + "Cancel". Clicking "Execute" executes the associated command. + If you do a mouse middle click on one of these desktop icons, a + popup menu appears where the second-to-bottom choice is "Trust this + executable". Selecting that causes the exclamation mark to go away, + and future double-clicks of the icon execute the program without + first popping up a window to choose between Open/Execute/Cancel. I + did that for each of these desktop icons: + + Terminal + + Wireshark ++ Log off + ++ Log in as user vagrant (password vagrant) ++ Change monitor settings and wallpaper mode as described above for + user p4. ++ Open a terminal. + + Run the command + + ``` + ./clean.sh + ``` + which removes about 6 to 7 GBytes of + files created while building the projects. ++ Log off + + +# Notes on test results for the VM + +I have run the tests below on every VM image I release, before +releasing it. You need not run them again, unless you are curious how +to do so. + + +## p4c testing results + +Steps to run the p4c tests: + ++ Log in as user vagrant (password vagrant) ++ In a new terminal, execute these commands: + +If you are testing on a Release VM image, first get a copy of the p4c +source code using the following command. This is unnecessary with a +Development VM image, as there is already a `p4c` directory with the +version of source code used to create that image already included in +the home directory of the `vagrant` user account: + +```bash +# for Release VM image only +git clone --recursive https://github.com/p4lang/p4c +``` + +The following steps are common for both Release and Development VM +images: + +```bash +# Compile p4c again from source, since the clean.sh step reduced disk +# space by deleting the p4c/build directory. +git clone https://github.com/jafingerhut/p4-guide +cd p4c +~/p4-guide/bin/build-p4c.sh + +# Run the p4c tests +cd build +make -j2 check |& tee make-check-out.txt +``` + +As of 2024-08-01, the p4c compiler passes all of its included tests, +except for some of the p4testgen tests (if those are enabled). + + +## Send ping packets in the solution to `basic` exercise of `p4lang/tutorials` repository + +With the version of the [tutorials](https://github.com/p4lang/tutorials) repository +that comes pre-installed in the `p4` user account of this VM, the +following tests pass. + +First log in as the user `p4` (password `p4`) and open a terminal +window. +```bash +$ cd tutorials/exercises/basic +$ cp solution/basic.p4 basic.p4 +$ make run +``` + +If at the end of many lines of logging output you see a prompt +`mininet>`, you can try entering the command `h1 ping h2` to ping from +virtual host `h1` in the exercise to `h2`, and it should report a +successful ping every second. It will not stop on its own. You can +type Control-C to stop it and return to the `mininet>` prompt, and you +can type Control-D to exit from mininet and get back to the original +shell prompt. To ensure that any processes started by the above steps +are terminated, you can run this command: +```bash +$ make stop +``` + + +# Creating a single file image of the VM + +These notes are primarily here as a reminder for people creating VM +images for distribution. If you downloaded a VM image, these steps +were already performed, and there is no reason you need to perform +them again. + +For the particular case of creating the VM named: + ++ 'P4 Tutorial Development 2024-08-01' ++ created on August 1, 2024 + +here were the host OS details, in case it turns out that matters to +the finished VM image for some reason: + ++ Windows 10 Enterprise ++ VirtualBox 6.1.30 r148432 ++ Vagrant 2.2.18 + +In the VirtualBox GUI interface: + ++ Choose menu item File -> Export Appliance ... ++ Select the VM named 'P4 Tutorial Development 2024-08-01' and click + Continue button + ++ Format + + I used: Open Virtualization Format 1.0 + + Other available options were: + + Open Virtualization Format 0.9 + + Open Virtualization Format 2.0 ++ Target file + + I used: /Users/andy/Documents/P4 Tutorials Development 2024-08-01.ova ++ Mac Address Policy + + I used: Include only NAT network adapter MAC addresses + + Other available options were: + + Include all network adapter MAC addresses + + Strip all network adapter MAC addresses ++ Additionally + + Write Manifest file: checked + + Include ISO image files: unchecked + +Clicked "Continue" button. + +Virtual system settings: + ++ Name: P4 Tutorial 2024-08-01 ++ Product: I left this blank ++ Product-URL: I left this blank ++ Vendor: P4.org - P4 Language Consortium ++ Vendor-URL: https://p4.org ++ Version: 2024-08-01 ++ Description: + +``` +Open source P4 development tools built from latest source code as of 2024-Aug-01 and packaged into an Ubuntu 20.04 Desktop Linux VM for the AMD64 architecture. +``` + ++ License + +``` +Open source code available hosted at https://github.com/p4lang is released under the Apache 2.0 license. Libraries it depends upon, such as Protobuf, Thrift, gRPC, Ubuntu Linux, etc. are released under their own licenses. +``` + +Clicked "Export" button. diff --git a/vm-ubuntu-24.04/README.md b/vm-ubuntu-24.04/README.md index 31466a58..9a2fb11c 100644 --- a/vm-ubuntu-24.04/README.md +++ b/vm-ubuntu-24.04/README.md @@ -1,10 +1,7 @@ # Introduction -This directory is still new and a bit experimental at this point. -Feel free to try it out and report problems if you find any. - -Known issues that anyone who knows how to fix is welcome to suggest -improvements: +Known minor issues that anyone who knows how to fix is welcome to +suggest improvements: + The desktop icon for the Wireshark application does not seem to exist, at least not under the name that worked for Ubuntu 20.04, so @@ -15,7 +12,8 @@ improvements: + Below are the steps to create a brand new VM using Vagrant: + Install [Vagrant](https://developer.hashicorp.com/vagrant/docs/installation) on your system if it's not already installed. - + Navigate to the directory where you want to create the new VM. + + In a shell/terminal window, change to this `vm-ubuntu-24.04` + directory inside the `tutorials` directory. + Run the below command in the terminal. ```bash @@ -30,228 +28,3 @@ improvements: *Note* that creating a development VM can take several hours, depending upon the speed of your computer and Internet connection. - - -# Creating a VM image for distribution to others - -If you are creating the VM for your own use, there is no need to read -further below. All later instructions are for those who wish to -create a VM image for others to download and use. - -Some of these steps could probably be automated with programs, and -changes to the `vagrant` scripts that can do so are welcome. I -perform these steps manually to create a VM image, simply to avoid the -experimentation and time required to automate them. I typically only -create new VM images once per month. - -+ Log in as user p4 (password p4) -+ Upgrade Ubuntu packages if newer ones are available: - - ```bash - sudo apt update - sudo apt upgrade - ``` - -+ Reboot the system. -+ This is optional, but if you want to save a little disk space, use - - ```bash - sudo apt purge - ``` - - to remove older version of Linux - kernel, if the upgrade installed a newer one. -+ Clean the local repository of retrieved package files to free up disk space - - ```bash - sudo apt clean - ``` - -+ Log in as user p4 (password p4) -+ Start menu -> Preferences -> LXQt settings -> Monitor settings - + Change resolution from initial 800x600 to 1024x768. Apply the changes. - + Close monitor settings window - + *Note*: For some reason I do not know, these settings seem to be - undone, even if I use the "Save" button. They are temporarily in - effect if I shut down the system and log back in, but then in a few - seconds it switches back to 800x600. Strange. -+ Start menu -> Preferences -> LXQt settings -> Desktop - + Click "Background" tab - + To the right of "Wallpaper image file" name, click "Browse" - button. Find and choose "lxqt-default-wallpaper.png" from the - list and click "Open". - + In "Wallpaper mode" popup menu, choose "Center on the screen". - + Click Apply button - + Close "Desktop preferences" window -+ Start menu -> Preferences -> LXQt settings -> Appearance - + Click "Icons Theme" in left column - + Click "Ubuntu-Mono-Light ..." in right column. - + Click "Apply" button, then "Close" button. -+ Several of the icons on the desktop have an exclamation mark on - them. If you try double-clicking those icons, it pops up a window - saying "This file 'Wireshark' seems to be a desktop entry. What do - you want to do with it?" with buttons for "Open", "Execute", and - "Cancel". Clicking "Execute" executes the associated command. - If you do a mouse middle click on one of these desktop icons, a - popup menu appears where the second-to-bottom choice is "Trust this - executable". Selecting that causes the exclamation mark to go away, - and future double-clicks of the icon execute the program without - first popping up a window to choose between Open/Execute/Cancel. I - did that for each of these desktop icons: - + Terminal - + Wireshark -+ Log off - -+ Log in as user vagrant (password vagrant) -+ Change monitor settings and wallpaper mode as described above for - user p4. -+ Open a terminal. - + Run the command - - ```bash - ./clean.sh - ``` - which removes about 6 to 7 GBytes of - files created while building the projects. -+ Log off - - -# Notes on test results for the VM - -I have run the tests below on every VM image I release, before -releasing it. You need not run them again, unless you are curious how -to do so. - - -## p4c testing results - -Steps to run the p4c tests: - -+ Log in as user vagrant (password vagrant) -+ In a new terminal, execute these commands: - -If you are testing on a Release VM image, first get a copy of the p4c -source code using the following command. This is unnecessary with a -Development VM image, as there is already a `p4c` directory with the -version of source code used to create that image already included in -the home directory of the `vagrant` user account: - -```bash -# for Release VM image only -git clone --recursive https://github.com/p4lang/p4c -``` - -The following steps are common for both Release and Development VM -images: - -```bash -# Compile p4c again from source, since the clean.sh step reduced disk -# space by deleting the p4c/build directory. -git clone https://github.com/jafingerhut/p4-guide -cd p4c -~/p4-guide/bin/build-p4c.sh - -# Run the p4c tests -cd build -make -j2 check |& tee out1.txt - -# The above fails about 500 tests that require root. Re-run those tests -# as root using the next command. -sudo PATH=${PATH} VIRTUAL_ENV=${VIRTUAL_ENV} ${P4GUIDE_SUDO_OPTS} make -j2 recheck |& tee out2.txt -``` - -As of 2024-08-01, the p4c compiler passes all but about 15 of its -included tests when built using the steps above. - - -## Send ping packets in the solution to `basic` exercise of `p4lang/tutorials` repository - -With the version of the [tutorials](https://github.com/p4lang/tutorials) repository -that comes pre-installed in the `p4` user account of this VM, the -following tests pass. - -First log in as the user `p4` (password `p4`) and open a terminal -window. -```bash -$ cd tutorials/exercises/basic -$ cp solution/basic.p4 basic.p4 -$ make run -``` - -If at the end of many lines of logging output you see a prompt -`mininet>`, you can try entering the command `h1 ping h2` to ping from -virtual host `h1` in the exercise to `h2`, and it should report a -successful ping every second. It will not stop on its own. You can -type Control-C to stop it and return to the `mininet>` prompt, and you -can type Control-D to exit from mininet and get back to the original -shell prompt. To ensure that any processes started by the above steps -are terminated, you can run this command: -```bash -$ make stop -``` - - -# Creating a single file image of the VM - -These notes are primarily here as a reminder for people creating VM -images for distribution. If you downloaded a VM image, these steps -were already performed, and there is no reason you need to perform -them again. - -For the particular case of creating the VM named: - -+ 'P4 Tutorial Development 2024-08-01' -+ created on August 1, 2024 - -here were the host OS details, in case it turns out that matters to -the finished VM image for some reason: - -+ Windows 10 Enterprise -+ VirtualBox 6.1.30 r148432 -+ Vagrant 2.2.18 - -In the VirtualBox GUI interface: - -+ Choose menu item File -> Export Appliance ... -+ Select the VM named 'P4 Tutorial Development 2024-08-01' and click - Continue button - -+ Format - + I used: Open Virtualization Format 1.0 - + Other available options were: - + Open Virtualization Format 0.9 - + Open Virtualization Format 2.0 -+ Target file - + I used: /Users/andy/Documents/P4 Tutorials Development 2024-08-01.ova -+ Mac Address Policy - + I used: Include only NAT network adapter MAC addresses - + Other available options were: - + Include all network adapter MAC addresses - + Strip all network adapter MAC addresses -+ Additionally - + Write Manifest file: checked - + Include ISO image files: unchecked - -Clicked "Continue" button. - -Virtual system settings: - -+ Name: P4 Tutorial 2024-08-01 -+ Product: I left this blank -+ Product-URL: I left this blank -+ Vendor: P4.org - P4 Language Consortium -+ Vendor-URL: https://p4.org -+ Version: 2024-08-01 -+ Description: - -``` -Open source P4 development tools built from latest source code as of 2024-Aug-01 and packaged into an Ubuntu 24.04 Desktop Linux VM for the AMD64 architecture. -``` - -+ License - -``` -Open source code available hosted at https://github.com/p4lang is released under the Apache 2.0 license. Libraries it depends upon, such as Protobuf, Thrift, gRPC, Ubuntu Linux, etc. are released under their own licenses. -``` - -Clicked "Export" button. diff --git a/vm-ubuntu-24.04/create-vm-image-for-others.md b/vm-ubuntu-24.04/create-vm-image-for-others.md new file mode 100644 index 00000000..2e38ca84 --- /dev/null +++ b/vm-ubuntu-24.04/create-vm-image-for-others.md @@ -0,0 +1,214 @@ +# Creating a VM image for distribution to others + +If you want to run `p4c` tests, see the next section on how to do so, +_before_ running the commands in this section, since the commands in +this section will delete files that take one to several hours to +create while compiling p4c, needed for running p4c tests. + +If you are creating the VM for your own use, there is no need to read +further below. All later instructions are for those who wish to +create a VM image for others to download and use. + +Some of these steps could probably be automated with programs, and +changes to the `vagrant` scripts that can do so are welcome. I +perform these steps manually to create a VM image, simply to avoid the +experimentation and time required to automate them. I typically only +create new VM images once per month. + ++ Log in as user p4 (password p4) ++ Upgrade Ubuntu packages if newer ones are available: + + ```bash + sudo apt update + sudo apt upgrade + ``` + ++ Reboot the system. ++ This is optional, but if you want to save a little disk space, use + + ```bash + sudo apt purge + ``` + + to remove older version of Linux + kernel, if the upgrade installed a newer one. ++ Clean the local repository of retrieved package files to free up disk space + + ```bash + sudo apt clean + ``` + ++ Log in as user p4 (password p4) ++ Start menu -> Preferences -> LXQt settings -> Monitor settings + + Change resolution from initial 800x600 to 1024x768. Apply the changes. + + Close monitor settings window + + *Note*: For some reason I do not know, these settings seem to be + undone, even if I use the "Save" button. They are temporarily in + effect if I shut down the system and log back in, but then in a few + seconds it switches back to 800x600. Strange. ++ Start menu -> Preferences -> LXQt settings -> Desktop + + Click "Background" tab + + To the right of "Wallpaper image file" name, click "Browse" + button. Find and choose "lxqt-default-wallpaper.png" from the + list and click "Open". + + In "Wallpaper mode" popup menu, choose "Center on the screen". + + Click Apply button + + Close "Desktop preferences" window ++ Start menu -> Preferences -> LXQt settings -> Appearance + + Click "Icons Theme" in left column + + Click "Ubuntu-Mono-Light ..." in right column. + + Click "Apply" button, then "Close" button. ++ Several of the icons on the desktop have an exclamation mark on + them. If you try double-clicking those icons, it pops up a window + saying "This file 'Wireshark' seems to be a desktop entry. What do + you want to do with it?" with buttons for "Open", "Execute", and + "Cancel". Clicking "Execute" executes the associated command. + If you do a mouse middle click on one of these desktop icons, a + popup menu appears where the second-to-bottom choice is "Trust this + executable". Selecting that causes the exclamation mark to go away, + and future double-clicks of the icon execute the program without + first popping up a window to choose between Open/Execute/Cancel. I + did that for each of these desktop icons: + + Terminal + + Wireshark ++ Log off + ++ Log in as user vagrant (password vagrant) ++ Change monitor settings and wallpaper mode as described above for + user p4. ++ Open a terminal. + + Run the command + + ```bash + ./clean.sh + ``` + which removes about 6 to 7 GBytes of + files created while building the projects. ++ Log off + + +# Notes on test results for the VM + +I have run the tests below on every VM image I release, before +releasing it. You need not run them again, unless you are curious how +to do so. + + +## p4c testing results + +Steps to run the p4c tests: + ++ Log in as user vagrant (password vagrant) ++ In a new terminal, execute these commands: + +```bash +# Compile p4c again from source, since the clean.sh step reduced disk +# space by deleting the p4c/build directory. +git clone https://github.com/jafingerhut/p4-guide +cd p4c +~/p4-guide/bin/build-p4c.sh + +# Run the p4c tests +cd build +make -j2 check |& tee out1.txt + +# The above fails about 500 tests that require root. Re-run those tests +# as root using the next command. +sudo PATH=${PATH} VIRTUAL_ENV=${VIRTUAL_ENV} ${P4GUIDE_SUDO_OPTS} make -j2 recheck |& tee out2.txt +``` + +As of 2024-08-01, the p4c compiler passes all but about 15 of its +included tests when built using the steps above. + + +## Send ping packets in the solution to `basic` exercise of `p4lang/tutorials` repository + +With the version of the [tutorials](https://github.com/p4lang/tutorials) repository +that comes pre-installed in the `p4` user account of this VM, the +following tests pass. + +First log in as the user `p4` (password `p4`) and open a terminal +window. +```bash +$ cd tutorials/exercises/basic +$ cp solution/basic.p4 basic.p4 +$ make run +``` + +If at the end of many lines of logging output you see a prompt +`mininet>`, you can try entering the command `h1 ping h2` to ping from +virtual host `h1` in the exercise to `h2`, and it should report a +successful ping every second. It will not stop on its own. You can +type Control-C to stop it and return to the `mininet>` prompt, and you +can type Control-D to exit from mininet and get back to the original +shell prompt. To ensure that any processes started by the above steps +are terminated, you can run this command: +```bash +$ make stop +``` + + +# Creating a single file image of the VM + +These notes are primarily here as a reminder for people creating VM +images for distribution. If you downloaded a VM image, these steps +were already performed, and there is no reason you need to perform +them again. + +For the particular case of creating the VM named: + ++ 'P4 Tutorial Development 2024-08-01' ++ created on August 1, 2024 + +here were the host OS details, in case it turns out that matters to +the finished VM image for some reason: + ++ Windows 10 Enterprise ++ VirtualBox 6.1.30 r148432 ++ Vagrant 2.2.18 + +In the VirtualBox GUI interface: + ++ Choose menu item File -> Export Appliance ... ++ Select the VM named 'P4 Tutorial Development 2024-08-01' and click + Continue button + ++ Format + + I used: Open Virtualization Format 1.0 + + Other available options were: + + Open Virtualization Format 0.9 + + Open Virtualization Format 2.0 ++ Target file + + I used: /Users/andy/Documents/P4 Tutorials Development 2024-08-01.ova ++ Mac Address Policy + + I used: Include only NAT network adapter MAC addresses + + Other available options were: + + Include all network adapter MAC addresses + + Strip all network adapter MAC addresses ++ Additionally + + Write Manifest file: checked + + Include ISO image files: unchecked + +Clicked "Continue" button. + +Virtual system settings: + ++ Name: P4 Tutorial 2024-08-01 ++ Product: I left this blank ++ Product-URL: I left this blank ++ Vendor: P4.org - P4 Language Consortium ++ Vendor-URL: https://p4.org ++ Version: 2024-08-01 ++ Description: + +``` +Open source P4 development tools built from latest source code as of 2024-Aug-01 and packaged into an Ubuntu 24.04 Desktop Linux VM for the AMD64 architecture. +``` + ++ License + +``` +Open source code available hosted at https://github.com/p4lang is released under the Apache 2.0 license. Libraries it depends upon, such as Protobuf, Thrift, gRPC, Ubuntu Linux, etc. are released under their own licenses. +``` + +Clicked "Export" button. From 322494984d045d085562715f3e7fb3fece7ff1d5 Mon Sep 17 00:00:00 2001 From: Andy Fingerhut Date: Thu, 30 Jan 2025 21:17:19 +0000 Subject: [PATCH 2/3] Add 2025-Jan-30 versions of source code for install.sh Signed-off-by: Andy Fingerhut --- vm-ubuntu-24.04/install.sh | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/vm-ubuntu-24.04/install.sh b/vm-ubuntu-24.04/install.sh index ccc7728f..a7eae56b 100755 --- a/vm-ubuntu-24.04/install.sh +++ b/vm-ubuntu-24.04/install.sh @@ -27,11 +27,12 @@ print_usage() { 1>&2 echo "" 1>&2 echo "Dates supported:" 1>&2 echo " 2025-Jan-01" + 1>&2 echo " 2025-Jan-30" } if [ $# -eq 0 ] then - VERSION="2025-Jan-01" + VERSION="2025-Jan-30" echo "No version specified. Defaulting to ${VERSION}" elif [ $# -eq 1 ] then @@ -49,6 +50,13 @@ case ${VERSION} in export INSTALL_P4C_SOURCE_VERSION="1dc0afae2207f4bb9f5ab45f105ed569cc1ac89b" export INSTALL_PTF_SOURCE_VERSION="c554f83685186be4cfa9387eb5d6d700d2bbd7c0" ;; + 2025-Jan-30) + # 2025-Jan-01 versions: + export INSTALL_BEHAVIORAL_MODEL_SOURCE_VERSION="892c42198082d3252f4c6facc7363c02ca1d71d2" + export INSTALL_PI_SOURCE_VERSION="2bb40f7ab800b91b26f3aed174bbbfc739a37ffa" + export INSTALL_P4C_SOURCE_VERSION="2776b1948529bc7e8ccfb2f6ea2a9c1ab1f68796" + export INSTALL_PTF_SOURCE_VERSION="c554f83685186be4cfa9387eb5d6d700d2bbd7c0" + ;; latest) echo "Using the latest version of all p4lang repository source code." ;; From 57155581abda41ee8e52bc5e36f64becbe282eef Mon Sep 17 00:00:00 2001 From: Andy Fingerhut Date: Sat, 21 Feb 2026 13:01:27 -0500 Subject: [PATCH 3/3] Update the README to mention P4sim as a newer alternative with recommendations not to use it yet if your primary goal is to learn from the existing exercises. Signed-off-by: Andy Fingerhut --- README.md | 70 ++++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 49 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 16dba45d..6a5a299b 100644 --- a/README.md +++ b/README.md @@ -84,23 +84,6 @@ All exercises in this repository use the v1model architecture, the documentation 1. The BMv2 Simple Switch target document accessible [here](https://github.com/p4lang/behavioral-model/blob/master/docs/simple_switch.md) talks mainly about the v1model architecture. 2. The include file `v1model.p4` has extensive comments and can be accessed [here](https://github.com/p4lang/p4c/blob/master/p4include/v1model.p4). -## P4sim – A Simple P4 Behavioral Simulator - -**P4sim** is a lightweight, dependency-free P4 packet-processing simulator designed for learning and experimentation. -Unlike BMv2 or P4-DPDK, P4sim does **not** emulate a full switch pipeline. Instead, it provides a minimal execution environment that evaluates P4 parser, control, and deparser logic on user-provided packets. - -P4sim is intended for: - -* Running P4 programs without installing large data plane frameworks -* Quickly testing parser and control-flow behavior -* Understanding how P4 programs process packets step-by-step - -P4sim is **not** a performance model and does not aim to replicate full-featured switch behavior (such as multitable pipelines, extern objects, or architecture-specific metadata). -It is mainly a **teaching and debugging tool**. - -To learn more or try P4sim examples, see: -[`P4sim/README.md`](./doc/P4sim/README.md) - ## Obtaining required software If you are starting this tutorial at one of the proctored tutorial events, @@ -118,12 +101,27 @@ you will need to do one of the following: tools within it. + Install the P4 development tools on an existing system with a supported version of Ubuntu Linux. ++ Install P4 development tools and also + [P4sim](https://github.com/HapCommSys/p4sim). + + Note: No instructions have been written yet on how to run the + tutorials exercises using P4sim. If your goal is to learn from + doing the exercises, we recommend you ignore P4sim for now. + +See the appropriate section below for more details on your choice. + +If you have a Windows, Mac, or Linux system with a 64-bit Intel/AMD +processor architecture, or an Apple Silicon Mac, and are willing to +install and use VirtualBox to run a Linux virtual machine, then the +first option above is the quickest way to get started, followed by the +second option. If you prefer not to use VirtualBox for some reason, +or prefer to use an existing system with a supported version of Ubuntu +Linux installed, the third option may be best for you. ### Download a virtual machine with the P4 development tools already installed -You will need a system with a 64-bit Intel/AMD processor architecture, -with [VirtualBox](https://virtualbox.org) installed on it. See the -table +You will need a Windows, Mac, or Linux system with a 64-bit Intel/AMD +processor architecture, or an Apple Silicon Mac, with +[VirtualBox](https://virtualbox.org) installed on it. See the table [here](https://github.com/jafingerhut/p4-guide/blob/master/bin/README-install-troubleshooting.md) for a list of virtual machine images that you can download, then use VirtualBox's File->Import Appliance menu item to add the virtual @@ -138,7 +136,37 @@ See the instructions [here](vm-ubuntu-24.04/README.md). ### To install P4 development tools on an existing system -There are instructions and scripts in another Github repository that can, starting from a freshly installed Ubuntu 20.04, 22.04, or 24.04 Linux system with enough RAM and free disk space, install all of the necessary P4 development tools to run the exercises in this repository. You can find those instructions and scripts [here](https://github.com/jafingerhut/p4-guide/blob/master/bin/README-install-troubleshooting.md) (note that you must clone a copy of that entire repository in order for its install scripts to work). +There are instructions and scripts in another Github repository that +can, starting from a freshly installed Ubuntu 22.04, or 24.04 Linux +system with enough RAM and free disk space, install all of the +necessary P4 development tools to run the exercises in this +repository. You can find those instructions and scripts +[here](https://github.com/jafingerhut/p4-guide/blob/master/bin/README-install-troubleshooting.md) +(note that you must clone a copy of that entire repository in order +for its install scripts to work). + +### Install P4 development tools and also P4sim + +[P4sim](https://github.com/HapCommSys/p4sim) is a lightweight, +dependency-free P4 packet-processing simulator designed for learning +and experimentation. Unlike BMv2 or P4-DPDK, P4sim does **not** +emulate a full switch pipeline. Instead, it provides a minimal +execution environment that evaluates P4 parser, control, and deparser +logic on user-provided packets. + +P4sim is intended for: + +* Running P4 programs without installing large data plane frameworks +* Quickly testing parser and control-flow behavior +* Understanding how P4 programs process packets step-by-step + +P4sim is **not** a performance model and does not aim to replicate +full-featured switch behavior (such as multitable pipelines, extern +objects, or architecture-specific metadata). It is mainly a +**teaching and debugging tool**. + +To learn more or try P4sim examples, see: +[`P4sim/README.md`](./doc/P4sim/README.md) # How to Contribute