Update man pages (#137)

KatharaFramework · Dec 19, 2023 · dfcf0a5 · dfcf0a5
1 parent d0c2438
commit dfcf0a5
Show file tree

Hide file tree

Showing 4 changed files with 89 additions and 55 deletions.
diff --git a/docs/Makefile b/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
 

diff --git a/docs/kathara-lab.conf.5.ronn b/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, Kathará 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"
-		LAB_EMAIL=contact@kathara.org
-		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"
+	LAB_EMAIL=contact@kathara.org
+	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)
 

diff --git a/docs/kathara-lconfig.1.ronn b/docs/kathara-lconfig.1.ronn
@@ -24,25 +24,32 @@ 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 of `pc1` (MAC address must be in the format `XX:XX:XX:XX:XX:XX`). If `MAC_ADDR` is not provided, Kathará 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)
 

diff --git a/docs/kathara-vconfig.1.ronn b/docs/kathara-vconfig.1.ronn
@@ -18,26 +18,33 @@ 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 of `pc1` (MAC address must be in the format `XX:XX:XX:XX:XX:XX`). If `MAC_ADDR` is not provided, Kathará 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