[PATCH 1/3] installation.rst: Fix incorrect reference in "HelloWorld" documentation

[Mark Gray]

Signed-off-by: Mark D. Gray 
---
 docs/source/installation.rst | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/docs/source/installation.rst b/docs/source/installation.rst
index 38df777598b3..c19a2c964402 100644
--- a/docs/source/installation.rst
+++ b/docs/source/installation.rst
@@ -62,12 +62,12 @@ A minimal "hello world" example of an executable test script looks like this:
         machine2.nic1 = DeviceReq(label="net1")

def test(self):
-            self.matched.m1.nic1.ip_add("192.168.1.1/24")
-            self.matched.m1.nic1.up()
-            self.matched.m2.nic1.ip_add("192.168.1.2/24")
-            self.matched.m2.nic1.up()
+            self.matched.machine1.nic1.ip_add("192.168.1.1/24")
+            self.matched.machine1.nic1.up()
+            self.matched.machine2.nic1.ip_add("192.168.1.2/24")
+            self.matched.machine2.nic1.up()

-            self.matched.m1.run("ping 192.168.1.2")
+            self.matched.machine1.run("ping 192.168.1.2")

ctl = Controller()
     recipe_instance = HelloWorldRecipe()

[PATCH 2/3] installation.rst: Add note clarifying `ethtool` errors

[Mark Gray]

Signed-off-by: Mark D. Gray 
---
 docs/source/installation.rst | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/docs/source/installation.rst b/docs/source/installation.rst
index c19a2c964402..8fca70c7c4a9 100644
--- a/docs/source/installation.rst
+++ b/docs/source/installation.rst
@@ -131,3 +131,11 @@ the same interface.

After creating your pool, you should now be able to run the ``hello_world.py``
 script successfully and receive back some logs about what happened.
+
+Note: At startup, You may receive some errors of the following form:
+
+``ERROR: Command "ethtool -a virbr0" execution failed (exited with 76)``
+
+LNST probes network devices using `ethtool` on initialization. If those
+network devices do not support the specific `ethtool` command, you may
+receive these benign error messages.

[PATCH 3/3] installation.rst: Add additional HelloWorld tutorial

[Mark Gray]

Signed-off-by: Mark D. Gray 
---
 docs/source/installation.rst | 111 +++++++++++++++++++++++++++++++++++
 1 file changed, 111 insertions(+)

diff --git a/docs/source/installation.rst b/docs/source/installation.rst
index 8fca70c7c4a9..2cd767793622 100644
--- a/docs/source/installation.rst
+++ b/docs/source/installation.rst
@@ -139,3 +139,114 @@ Note: At startup, You may receive some errors of the following form:
 LNST probes network devices using `ethtool` on initialization. If those
 network devices do not support the specific `ethtool` command, you may
 receive these benign error messages.
+
+Run additional recipes
+======================
+
+LNST contains a number of recipe classes in ``lnst/Recipes``. These can be run by
+writing an executable python script to create an instance of a Controller class
+and an instance of the Test Recipe that we want to run, and calling the Controller.run()
+method to execute it.
+
+A minimal example of this for the ``NoVirtOvsVxlanRecipe`` recipe can be seen here:
+
+.. code-block:: python
+
+        from lnst.Controller import Controller, HostReq, DeviceReq, BaseRecipe
+        from lnst.Recipes.ENRT import NoVirtOvsVxlanRecipe
+
+        ctl = Controller()
+        recipe_instance = NoVirtOvsVxlanRecipe(driver="lnst")
+        ctl.run(recipe_instance)
+
+It should be noted that some recipes may have some pre-requisites. For example, this
+recipe required the ``iperf3`` package and OVS should be running or startable by
+``systemctl start openvswitch.service``
+
+This test requires that you have 2 test machines that are directly connected to
+each other. This also shows an example of passing the `driver` parameter to the
+test class. The `driver` parameter is used to modify the HW network requirements,
+specifically to request Devices. You can see the corresponding parameter in the
+XML definition of one of the two machines in the pool used in this test:
+
+.. code-block:: xml
+
+    <slavemachine>
+        <params>
+            <param name="hostname" value="HOSTNAME"/>
+            <param name="rpc_port" value="9999"/>
+        </params>
+        <interfaces>
+            <eth label="A" id="1">
+                <params>
+                    <param name="hwaddr" value="MAC_ADDRESS"/>
+                    <param name="driver" value="lnst"/>
+                </params>
+            </eth>
+        </interfaces>
+    </slavemachine>
+
+Additional parameters may be added to a recipe instantiation to configure the
+recipe. Some parameters may be specific for a particular recipe and others may
+apply to all recipes.
+
+For example, for ``NoVirtOvsVxlanRecipe``:
+
+.. code-block:: python
+
+        recipe_instance = NoVirtOvsVxlanRecipe(driver="lnst", perf_tests=["tcp_stream", "udp_stream"], perf_msg_sizes=[1400])
+
+``perf_tests`` specifies a list of perf tests to run for this recipe
+``perf_mesg_sizes`` specifies the message size to send when doing performance tests
+
+Other examples include:
+
+``perf_duration`` specifies the duration of test runs
+``perf_iterations`` specifies the number of iterations of a performance test to run
+
+If you write all of this into a ``hello_world2.py`` file you should now be able to
+execute this script by running::
+
+    python3 hello_world2.py
+
+If you have previously created your machine pool configuration (and added the driver
+parameter as indicated above), the recipe should run to completion.
+
+Debugging when things go wrong
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Additional debug information on the slaves can be seen by running the ``lnst-slave``
+application with the ``-d`` flag. Additional debug information on the controller can
+be seen by adding the ``debug`` paramter to the instantiation of the ``controller``
+class.
+
+.. code-block:: bash
+
+        ctl = Controller(debug=1)
+
+Logs should also be saved in the ``Logs`` directory.
+
+Printing summary information
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can also modify your ``hello_world2.py`` application to print summary information
+at the end of the run:
+
+.. code-block:: xml
+
+        from lnst.Controller import Controller, HostReq, DeviceReq, BaseRecipe
+        from lnst.Recipes.ENRT import NoVirtOvsVxlanRecipe
+
+        from lnst.Controller.RunSummaryFormatter import RunSummaryFormatter
+        from lnst.Controller.RecipeResults import ResultLevel
+        import logging
+
+        ctl = Controller(debug=1)
+        recipe_instance = NoVirtOvsVxlanRecipe(driver="lnst", perf_tests=["tcp_stream", "udp_stream"], perf_msg_sizes=[1400])
+        ctl.run(recipe_instance)
+
+        summary_fmt = RunSummaryFormatter(
+            level=ResultLevel.IMPORTANT + 0, colourize=True
+        )
+        for run in recipe_instance.runs:
+            logging.info(summary_fmt.format_run(run))

[Jan Tluka]

Fri, Mar 26, 2021 at 06:16:03PM CET, [e-mail] wrote:
> Signed-off-by: Mark D. Gray
>
> docs/source/installation.rst | 10 +++++-----
> 1 file changed, 5 insertions(+), 5 deletions(-)
>
> diff --git a/docs/source/installation.rst b/docs/source/installation.rst
> index 38df777598b3..c19a2c964402 100644
> --- a/docs/source/installation.rst
> +++ b/docs/source/installation.rst
> @@ -62,12 +62,12 @@ A minimal "hello world" example of an executable test script looks like this:
>         machine2.nic1 = DeviceReq(label="net1")
>     def test(self):
>        self.matched.m1.nic1.ip_add("192.168.1.1/24")
>        self.matched.m1.nic1.up()
>        self.matched.m2.nic1.ip_add("192.168.1.2/24")
>        self.matched.m2.nic1.up()
>        self.matched.machine1.nic1.ip_add("192.168.1.1/24")
>        self.matched.machine1.nic1.up()
>        self.matched.machine2.nic1.ip_add("192.168.1.2/24")
>        self.matched.machine2.nic1.up()
>
>        self.matched.m1.run("ping 192.168.1.2")
>        self.matched.machine1.run("ping 192.168.1.2")
>
> ctl = Controller()
>   recipe_instance = HelloWorldRecipe()
>
> -- 
> 2.27.0
> _______________________________________________
> LNST-developers mailing list -- [e-mail]
> To unsubscribe send an email to [e-mail]
> Fedora Code of Conduct: https://docs.fedoraproject.org/en-US/project/code-of-conduct/
> List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines
> List Archives: https://lists.fedorahosted.org/archives/list/[e-mail]...
> Do not reply to spam on the list, report it: https://pagure.io/fedora-infrastructure

Hello Mark, thanks for contributing!
I reviewed the patch and it looks good.

Acked-by: Jan Tluka

[Ondrej Lichtner]

On Fri, Mar 26, 2021 at 01:16:03PM -0400, Mark Gray wrote:
> Signed-off-by: Mark D. Gray
>
> docs/source/installation.rst | 10 +++++-----
>  1 file changed, 5 insertions(+), 5 deletions(-)
>
> diff --git a/docs/source/installation.rst b/docs/source/installation.rst
> index 38df777598b3..c19a2c964402 100644
> --- a/docs/source/installation.rst
> +++ b/docs/source/installation.rst
> @@ -62,12 +62,12 @@ A minimal "hello world" example of an executable test script looks like this:
>          machine2.nic1 = DeviceReq(label="net1")
>      def test(self):
>        self.matched.m1.nic1.ip_add("192.168.1.1/24")
>        self.matched.m1.nic1.up()
>        self.matched.m2.nic1.ip_add("192.168.1.2/24")
>        self.matched.m2.nic1.up()
>        self.matched.machine1.nic1.ip_add("192.168.1.1/24")
>        self.matched.machine1.nic1.up()
>        self.matched.machine2.nic1.ip_add("192.168.1.2/24")
>        self.matched.machine2.nic1.up()
>
>        self.matched.m1.run("ping 192.168.1.2")
>        self.matched.machine1.run("ping 192.168.1.2")
>
> ctl = Controller()
>    recipe_instance = HelloWorldRecipe()
>
> -- 
> 2.27.0
> _______________________________________________
> LNST-developers mailing list -- [e-mail]
> To unsubscribe send an email to [e-mail]
> Fedora Code of Conduct: https://docs.fedoraproject.org/en-US/project/code-of-conduct/
> List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines
> List Archives: https://lists.fedorahosted.org/archives/list/[e-mail]...
> Do not reply to spam on the list, report it: https://pagure.io/fedora-infrastructure

thanks mark, looks good to me.

pushed to upstream.

-Ondrej

[Mark Gray]

On 30/03/2021 13:25, Ondrej Lichtner wrote:
> On Fri, Mar 26, 2021 at 01:16:03PM -0400, Mark Gray wrote:
> > Signed-off-by: Mark D. Gray
> >
> > docs/source/installation.rst | 10 +++++-----
> >  1 file changed, 5 insertions(+), 5 deletions(-)
> >
> > diff --git a/docs/source/installation.rst b/docs/source/installation.rst
> > index 38df777598b3..c19a2c964402 100644
> > --- a/docs/source/installation.rst
> > +++ b/docs/source/installation.rst
> > @@ -62,12 +62,12 @@ A minimal "hello world" example of an executable test script looks like this:
> >          machine2.nic1 = DeviceReq(label="net1")
> >      def test(self):
> >        self.matched.m1.nic1.ip_add("192.168.1.1/24")
> >        self.matched.m1.nic1.up()
> >        self.matched.m2.nic1.ip_add("192.168.1.2/24")
> >        self.matched.m2.nic1.up()
> >        self.matched.machine1.nic1.ip_add("192.168.1.1/24")
> >        self.matched.machine1.nic1.up()
> >        self.matched.machine2.nic1.ip_add("192.168.1.2/24")
> >        self.matched.machine2.nic1.up()
> >
> >        self.matched.m1.run("ping 192.168.1.2")
> >        self.matched.machine1.run("ping 192.168.1.2")
> >
> > ctl = Controller()
> >    recipe_instance = HelloWorldRecipe()
> >
> > -- 
> > 2.27.0
> > _______________________________________________
> > LNST-developers mailing list -- [e-mail]
> > To unsubscribe send an email to [e-mail]
> > Fedora Code of Conduct: https://docs.fedoraproject.org/en-US/project/code-of-conduct/
> > List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines
> > List Archives: https://lists.fedorahosted.org/archives/list/[e-mail]...
> > Do not reply to spam on the list, report it: https://pagure.io/fedora-infrastructure
>
> thanks mark, looks good to me.
>
> pushed to upstream.
>
> -Ondrej

Thanks