Merge pull request #262 from KatharaFramework/develop

Kathará v3.7.1

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -22,7 +22,7 @@ body:
     attributes:
       label: Kathará Version
       description: "Please provide the Kathará version you are using (`kathara -v`)."
-      placeholder: "3.7.0"
+      placeholder: "3.7.1"
     validations:
       required: true
   - type: textarea

SECURITY.md

@@ -6,7 +6,7 @@ We release patches for security vulnerabilities only for the last version:
 
 | Version | Supported Versions |
 |---------|--------------------|
-| 3.7.0   | :white_check_mark: |
+| 3.7.1   | :white_check_mark: |
 
 ## Reporting a Vulnerability
 

docs/Makefile

@@ -11,7 +11,8 @@ build-%: docker-build-image
 
 docker-build-image:
 	cp ../scripts/Linux-Deb/Docker-Linux-Build/Dockerfile_template ../scripts/Linux-Deb/Docker-Linux-Build/Dockerfile
-	sed -i -e "s|__DISTRO__|focal|g" ../scripts/Linux-Deb/Docker-Linux-Build/Dockerfile
+	sed -i -e "s|__DISTRO__|jammy|g" ../scripts/Linux-Deb/Docker-Linux-Build/Dockerfile
+	sed -i -e "s|__NOKOGIRI__||g"  ../scripts/Linux-Deb/Docker-Linux-Build/Dockerfile
 	cd ../scripts/Linux-Deb/Docker-Linux-Build/ && docker build -t kathara/linux-build-deb .
 	rm -f ../scripts/Linux-Deb/Docker-Linux-Build/Dockerfile
 

docs/footer.txt

@@ -18,5 +18,5 @@ People involved also include:
 
 ## COPYRIGHT
 
-Copyright © 2017-2021 License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
+Copyright © 2017-2024 License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
 This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

docs/kathara-check.1.ronn

@@ -23,10 +23,11 @@ Should give an output like this:
 
 	*	Current Manager is: `<your_manager_name>`
 	*	Manager version is: `<your_manager_version>`
-	*	Trying to run `Hello World` container...
-	*	Container run successfully.
 	*	Python version is: `<python_version_used>`
 	*	Kathara version is: `<kathara_version>`
+	*	Operating System version is: `<your_os>`
+	*	Trying to run container with `<your_default_image>` image...
+	*	Container run successfully.
 
 **NOTE:** If you are using the released version, the Python version could be different from the one installed in your system because it is packed into the Kathara binary.
 

docs/kathara-lab.conf.5.ronn

@@ -8,41 +8,59 @@ The main network scenario configuration file. In this file you can specify the n
 
 This file is a list of `device[arg]=value` assignments, where `arg` can be an integer value or the name of an option (described below).
 
-If `arg` is an integer value, then `value` is the name of the collision domain to which interface eth`arg` of device `device` must be connected (note that the name of the collision domain must not contain spaces (" "), commas (",") and dots ("."). For example, `pc1[0]=CD1` means that interface eth0 of device pc1 will be connected to collision domain CD1.
+In order to establish a uniform convention, comment lines should always start with a hash character (`#`).
 
-If `arg` is an option name, then `device` will be launched with option `arg` set to value `value`.
+## DEVICE INTERFACES
 
-In order to establish a uniform convention, comment lines should always start with a hash character (`#`).
+If `arg` is an integer value, then `value` is the name of the collision domain to which interface eth`arg` of device `device` must be connected. The syntax is as follows:
+
+- `arg`: An integer value representing the interface number (e.g., 0).
+- `CD1`: The name of the collision domain to which the specified interface must be connected. Note that the name of the collision domain must not contain spaces (" "), commas (",") and dots (".").
+- `/MAC_ADDR`: An optional parameter to specify the MAC address of the interface of `device` (MAC address must be in the format `XX:XX:XX:XX:XX:XX`). If `MAC_ADDR` is not provided, Kathara will assign a random one.
+
+### EXAMPLES
+
+1. Connect eth0 of `pc1` to collision domain `CD1` with a random MAC address:
+	```
+	pc1[0]="CD1"
+	```
+
+2. Connect eth1 of `pc1` to collision domain `CD2` with the specified MAC address:
+	```
+	pc1[1]="CD2/02:42:ac:11:00:02"
+	```
 
 ## DEVICE OPTIONS
 
+If `arg` is an option name, then `device` will be launched with option `arg` set to value `value`.
+
 * `image` (string):
-    Docker image used for this device.
+	Docker image used for this device.
 
 * `mem` (string):
-    Set the amount of available RAM inside the device. If you set this option, the minimum allowed value is 4m (4 megabyte).
+	Set the amount of available RAM inside the device. If you set this option, the minimum allowed value is 4m (4 megabyte).
 
-    This option takes a positive integer, followed by a suffix of "b", "k", "m", "g", to indicate bytes, kilobytes, megabytes, or gigabytes.
+	This option takes a positive integer, followed by a suffix of "b", "k", "m", "g", to indicate bytes, kilobytes, megabytes, or gigabytes.
 
 * `cpus` (float):
-    Limit the amount of CPU available for this device.
+	Limit the amount of CPU available for this device.
 
-    This option takes a positive float, ranging from 0 to max number of host logical CPUs. For instance, if the host device has two CPUs and you set `device[cpus]=1.5`, the device is guaranteed at most one and a half of the CPUs.
+	This option takes a positive float, ranging from 0 to max number of host logical CPUs. For instance, if the host device has two CPUs and you set `device[cpus]=1.5`, the device is guaranteed at most one and a half of the CPUs.
 
 * `port` (string):
-    Map localhost port HOST to the internal port GUEST of the device for the specified PROTOCOL. The syntax is [HOST:]GUEST[/PROTOCOL].
+	Map localhost port HOST to the internal port GUEST of the device for the specified PROTOCOL. The syntax is [HOST:]GUEST[/PROTOCOL].
 
-    If HOST port is not specified, default is 3000. If PROTOCOL is not specified, default is `tcp`. Supported PROTOCOL values are: tcp, udp, or sctp.
-    For instance, with this command you can map host's port 8080 to device's port 80 with TCP protocol: `device[port]="8080:80/tcp"`.
+	If HOST port is not specified, default is 3000. If PROTOCOL is not specified, default is `tcp`. Supported PROTOCOL values are: tcp, udp, or sctp.
+	For instance, with this command you can map host's port 8080 to device's port 80 with TCP protocol: `device[port]="8080:80/tcp"`.
 
 * `bridged` (boolean):
-    Connect the device to the host network by adding an additional network interface. This interface will be connected to the host network through a NAT connection.
+	Connect the device to the host network by adding an additional network interface. This interface will be connected to the host network through a NAT connection.
 
 * `ipv6` (boolean):
-    Enable or disable IPv6 on this device.
+	Enable or disable IPv6 on this device.
 
 * `exec` (string):
-    Run a specific shell command inside the device during the startup phase.
+	Run a specific shell command inside the device during the startup phase.
 
 * `sysctl` (string):
 	Set a sysctl option for this device. Only the `net.` namespace is allowed to be set. Can be set multiple times per device, each will add a new entry (unless the same config item is used again).
@@ -51,10 +69,10 @@ In order to establish a uniform convention, comment lines should always start wi
 	Set an environment variable for the device. Can be set multiple times per device, each will add a new entry (unless the same variable is used again). The format is: ENV_NAME=ENV_VALUE.
 
 * `shell` (string):
-    Use the specified shell to connect to the device, e.g., when `kathara connect` is called.
+	Use the specified shell to connect to the device, e.g., when `kathara connect` is called.
 
 * `num_terms` (integer):
-    Choose the number of terminals to open for this device.
+	Choose the number of terminals to open for this device.
 
 ## NETWORK SCENARIO META INFORMATION
 
@@ -69,32 +87,33 @@ It is also possible to provide descriptive information about a network scenario
 
 ## EXAMPLE
 
-        LAB_NAME="Example"
-		LAB_DESCRIPTION="A simple example of lab.conf"
-		LAB_VERSION=1.0
-		LAB_AUTHOR="Kathara Authors"
-		[email protected]
-		LAB_WEB=http://www.kathara.org/
+Example of a `lab.conf`(5) file.
 
-		r1[0]="A"
-		r1[1]="B"
-		r1[port]="32000"
-		r1[image]="namespace/image_name"
-		r1[sysctl]="net.ipv6.conf.all.forwarding=1"
+	LAB_NAME="Example" 
+	LAB_DESCRIPTION="A simple example of lab.conf"
+	LAB_VERSION=1.0
+	LAB_AUTHOR="Kathara Authors"
+	[email protected]
+	LAB_WEB=http://www.kathara.org/
 
-		r2[0]="C"
-		r2[1]="B"
-		r2[port]="2000:500/udp"
-		r2[exec]="echo Hi"
+	r1[0]="A"
+	r1[1]="B/02:42:ac:11:00:02" # Specify the MAC address assigned to interface eth1 of r1
+	r1[port]="32000"
+	r1[image]="namespace/image_name"
+	r1[sysctl]="net.ipv6.conf.all.forwarding=1"
 
-		pc1[0]="A"
-		pc1[bridged]="true"
+	r2[0]="C"
+	r2[1]="B"
+	r2[port]="2000:500/udp"
+	r2[exec]="echo Hi"
 
-		pc2[0]="C"
-		pc2[mem]="128m"
-        pc2[shell]="/bin/sh"
+	pc1[0]="A"
+	pc1[bridged]="true"
+
+	pc2[0]="C"
+	pc2[mem]="128m"
+	pc2[shell]="/bin/sh" 
 
-Example of a `lab.conf`(5) file.
 
 m4_include(footer.txt)
 

docs/kathara-lconfig.1.ronn

@@ -4,7 +4,7 @@ kathara-lconfig(1) -- Attach network interfaces to a running Kathara device of a
 
 ## SYNOPSIS
 
-`kathara lconfig` [`-h`] [`-d` <DIRECTORY>] `-n` <DEVICE_NAME> (`--add` <CD> [<CD> ...] \| `--rm` <CD> [<CD> ...])  
+`kathara lconfig` [`-h`] [`-d` <DIRECTORY>] `-n` <DEVICE_NAME> (`--add` <CD[/MAC_ADDR]> [<CD[/MAC_ADDR]> ...] \| `--rm` <CD> [<CD> ...])
 
 ## DESCRIPTION
 
@@ -24,25 +24,34 @@ Manage the network interfaces of a running Kathara device in a network scenario.
 * `-n` <DEVICE_NAME>, `--name` <DEVICE_NAME>:
     Name of the device to configure.
 
-* `--add` <CD> [<CD> ...]:
-	Specify the collision domain to add.
-
-    Equip the device with an additional network interface attached to a (virtual) collision domain whose name is <CD>. The number of the resulting network interface is generated incrementing the number of the last network interface used by the device.
+* `--add` <CD[/MAC_ADDR]> [<CD[/MAC_ADDR]> ...]:
+	Specify the collision domain to be connected to the device:
+
+    `CD`: The name of the collision domain to which the specified interface must be connected. Note that the name of the collision domain must not contain spaces (" "), commas (",") and dots (".").
+
+    `/MAC_ADDR`: An optional parameter to specify the MAC address of the interface (MAC address must be in the format `XX:XX:XX:XX:XX:XX`). If `MAC_ADDR` is not provided, Kathara will assign a random one. 
+
+    Equip the device with an additional network interface attached to a (virtual) collision domain whose name is <CD>. 
+    The number of the resulting network interface is generated incrementing the number of the last network interface used by the device.
 
 * `--rm` <CD> [<CD> ...]:
-	Specify the collision domain to remove.
+	Specify the collision domain to be disconnected from the device.
 
     Disconnect the device from the collision domain whose name is <CD> and remove the corresponding interface.
 
 ## EXAMPLES
 
+Connect `pc1` to collision domain `X` and `Y` (with random MAC addresses):
+
     kathara lconfig -d path/to/network_scenario -n pc1 --add X Y
 
-Two new interfaces will be added to the device pc1 in the network scenario located in "path/to/network_scenario": the first one will be attached to the collision domain named X, while the other one to the collision domain named Y. Both the interfaces will have to be configured by hand inside the device (for example, by using ifconfig).
-
-    kathara vconfig -n pc1 --rm X
+Connect `pc1` to collision domain `X` with the specified MAC address:
+    
+    kathara lconfig -d path/to/network_scenario -n pc1 --add X/00:00:00:00:00:01
 
-pc1, in the network scenario located in "path/to/network_scenario", will be disconnected from the collision domain named X and the corresponding network interface will be removed.
+Disconnect `pc1` from collision domain `X` and remove the corresponding interface:
+
+    kathara lconfig -d path/to/network_scenario -n pc1 --rm X
 
 m4_include(footer.txt)
 

docs/kathara-vconfig.1.ronn

@@ -4,7 +4,7 @@ kathara-vconfig(1) -- Attach network interfaces to a running Kathara device
 
 ## SYNOPSIS
 
-`kathara vconfig` [`-h`] `-n` <DEVICE_NAME> (`--add` <CD> [<CD> ...] \| `--rm` <CD> [<CD> ...])  
+`kathara vconfig` [`-h`] `-n` <DEVICE_NAME> (`--add` <CD[/MAC_ADDR]> [<CD[/MAC_ADDR]> ...] \| `--rm` <CD> [<CD> ...])  
 
 ## DESCRIPTION
 
@@ -18,26 +18,35 @@ Manage the network interfaces of a running Kathara device. The affected device i
 * `-n` <DEVICE_NAME>, `--name` <DEVICE_NAME>:
     Name of the device to manage.
 
-* `--add` <CD> [<CD> ...]:
-	Specify the collision domain to add.
-
-    Equip the device with an additional network interface attached to a (virtual) collision domain whose name is <CD>. The number of the resulting network interface is generated incrementing the number of the last network interface used by the device.
+* `--add` <CD[/MAC_ADDR]> [<CD[/MAC_ADDR]> ...]:
+	Specify the collision domain to be connected to the device:
+
+    `CD`: The name of the collision domain to which the specified interface must be connected. Note that the name of the collision domain must not contain spaces (" "), commas (",") and dots (".").
+
+    `/MAC_ADDR`: An optional parameter to specify the MAC address of the interface (MAC address must be in the format `XX:XX:XX:XX:XX:XX`). If `MAC_ADDR` is not provided, Kathara will assign a random one. 
+
+    Equip the device with an additional network interface attached to a (virtual) collision domain whose name is <CD>. 
+    The number of the resulting network interface is generated incrementing the number of the last network interface used by the device.
 
 * `--rm` <CD> [<CD> ...]:
-	Specify the collision domain to remove.
+	Specify the collision domain to be disconnected from the device.
 
     Disconnect the device from the collision domain whose name is <CD> and remove the corresponding interface.
 
 ## EXAMPLES
 
+Connect `pc1` to collision domain `X` and `Y` (with random MAC addresses):
+
     kathara vconfig -n pc1 --add X Y
 
-Two new interfaces will be added to the device pc1: the first one will be attached to the collision domain named X, while the other one to the collision domain named Y. Both the interfaces will have to be configured by hand inside the device (for example, by using ifconfig).
+Connect `pc1` to collision domain `X` with the specified MAC address:
+
+    kathara vconfig -n pc1 --add X/00:00:00:00:00:01
 
+Disconnect `pc1` from collision domain `X` and remove the corresponding interface:
+
     kathara vconfig -n pc1 --rm X
 
-pc1 will be disconnected from the collision domain named X and the corresponding network interface will be removed.
-
 m4_include(footer.txt)
 
 ## SEE ALSO

docs/kathara-vstart.1.ronn

@@ -6,7 +6,7 @@ kathara-vstart(1) -- Start a new Kathara device
 
 `kathara vstart` `-n` <DEVICE_NAME>  
 [`-h`] [`--noterminals` | `--terminals` | `--privileged` | `--num_terms` <NUM_TERMS>]  
-[`--eth` <N\:CD> [<N\:CD> ...]]  
+[`--eth` <N:CD[/MAC_ADDR]> [<N:CD[/MAC_ADDR]> ...]]  
 [`-e` [<EXEC_COMMANDS> [<EXEC_COMMANDS> ...]]] [`--mem` <MEM>]  
 [`--cpus` <CPUS>] [`-i` <IMAGE>] [`--no-hosthome` \| `--hosthome`]
 [`--xterm` <XTERM>] [`--print`] [`--bridged`]  
@@ -42,9 +42,13 @@ Notice: unless differently stated, command line arguments (DEVICE_NAME) and opti
 * `-n` <DEVICE_NAME>, `--name` <DEVICE_NAME>:
     Name of the device to be started.
 
-* `--eth` <N\:CD> [<N\:CD> ...]:
+* `--eth` <N:CD[/MAC_ADDR]> [<N:CD[/MAC_ADDR]> ...]:
     Set a specific interface on a collision domain.
-
+
+    `CD`: The name of the collision domain to which the specified interface must be connected. Note that the name of the collision domain must not contain spaces (" "), commas (",") and dots (".").
+
+    `/MAC_ADDR`: An optional parameter to specify the MAC address of the interface (MAC address must be in the format `XX:XX:XX:XX:XX:XX`). If `MAC_ADDR` is not provided, Kathara will assign a random one. 
+
     Equip the device with a network interface. `N` is a positive integer starting from 0.
     The network interface will be attached to a (virtual) collision domain whose name is `CD`. Attaching interfaces of different devices to the same collision domain allows them to exchange network traffic. <N> should be declared as a sequential number, starting from 0; if any intermediate number is missing an exception is raised.
 

docs/kathara.conf.5.ronn

@@ -97,10 +97,10 @@ Each Manager specifies additional parameters which are used only when the Manage
 
     Default to `Prompt`.
 
-* `shared_cd` (boolean):
-    This parameter allows to connect devices of different users to the same collision domains.
+* `shared_cds` (integer):
+    This parameter allows to connect devices of different network scenarios and users to the same collision domains.
 
-    Default to `false`.
+    Default to `1` (enum value for `Not Shared`).
 
 * `remote_url` (string):
     This parameter specifies a Remote Docker daemon URL to connect to, instead of a local one.
@@ -154,7 +154,7 @@ Each Manager specifies additional parameters which are used only when the Manage
             "hosthome_mount": false,
             "shared_mount": true,
             "image_update_policy": "Prompt",
-            "shared_cd": false,
+            "shared_cds": 1,
             "remote_url": null,
             "cert_path": null,
             "network_plugin": "kathara/katharanp_vde"

pyproject.toml

@@ -1,19 +1,19 @@
 [project]
 name = "kathara"
-version = "3.7.0"
-description = "A lightweight container-based emulation system."
+version = "3.7.1"
+description = "A lightweight container-based network emulation tool."
 readme = "README.md"
 requires-python = ">=3.9"
 license = { file = "LICENSE" }
 keywords = ["NETWORK-EMULATION", "CONTAINERS", "NFV"]
 authors = [
-    { name = "Kathara Framework", email = "[email protected]" } # Optional
+    { name = "Kathara Framework", email = "[email protected]" }
 ]
 
 maintainers = [
-    { name = "Tommaso Caiazzi", email = "[email protected]" }, # Optional
-    { name = "Mariano Scazzariello", email = "[email protected]" }, # Optional
-    { name = "Lorenzo Ariemma", email = "[email protected]" }, # Optional
+    { name = "Tommaso Caiazzi", email = "[email protected]" },
+    { name = "Mariano Scazzariello", email = "[email protected]" },
+    { name = "Lorenzo Ariemma", email = "[email protected]" },
 ]
 
 classifiers = [
@@ -30,7 +30,7 @@ classifiers = [
 
 dependencies = [
     "binaryornot>=0.4.4",
-    "docker>=6.0.1",
+    "docker>=7.0.0",
     "kubernetes>=23.3.0",
     "requests>=2.22.0",
     "coloredlogs>=10.0",