Update documentation and add new make commands

close #42

Makefile

@@ -12,8 +12,6 @@ PROJECT_DIRECTORY = --project-directory $(BUILD_DIR)
 MAKE = make --no-print-directory
 
 
-.PHONY: default u d t e t l lf clean build test set
-
 $(BCONFIG): default-config.yaml
 	@echo Copying default-config.yaml into $(BCONFIG)
 	@mkdir -p $$(dirname $(BCONFIG))
@@ -24,6 +22,7 @@ $(BCOMPOSE): templates/compose.yaml.j2 scripts/jinja/customize.py $(BCONFIG)
 	@mkdir -p $$(dirname $(BCOMPOSE))
 	@j2 --customize scripts/jinja/customize.py -o $(BCOMPOSE) templates/compose.yaml.j2 $(BCONFIG)
 
+.PHONY: test
 test:
 	@$(MAKE) clean
 	@echo [1/4] Running linter on python scripts
@@ -35,9 +34,11 @@ test:
 	@echo [4/4] Running tests for NextMN/SRv6 config
 	@$(MAKE) test/nextmn-srv6
 
+.PHONY: test/lint/python
 test/lint/python:
 	@find -type f -iname '*.py' -print | parallel '(echo -n Running pylint on {} ; pylint --persistent=false -v -j 0 {})' :::
 
+.PHONY: test/lint/yaml
 test/lint/yaml:
 	@echo "disable_openssl_generation: true" >> $(BCONFIG)
 	@$(MAKE) build
@@ -47,78 +48,139 @@ test/lint/yaml:
 	@docker compose $(PROJECT_DIRECTORY) config >/dev/null
 	@$(MAKE) clean
 
+.PHONY: test/nextmn-srv6
 test/nextmn-srv6:
 	@$(MAKE) set/dataplane/nextmn-srv6
 	@$(MAKE) test/lint/yaml
+.PHONY: test/nextmn-upf
 test/nextmn-upf:
 	@$(MAKE) set/dataplane/nextmn-upf
 	@$(MAKE) test/lint/yaml
+.PHONY: test/nextmn-free5gc
 test/free5gc:
 	@$(MAKE) set/dataplane/free5gc
 	@$(MAKE) test/lint/yaml
 
+.PHONY: set/dataplane
 set/dataplane/%: $(BCONFIG)
 	@echo Set dataplane to $(@F)
 	@./scripts/config_edit.py $(BCONFIG) --dataplane=$(@F)
 
+.PHONY: set/nb-edges
 set/nb-edges/%: $(BCONFIG)
 	@echo Set number of edges to $(@F)
 	@./scripts/config_edit.py $(BCONFIG) --nb-edges=$(@F)
 
+.PHONY: set/nb-ue
 set/nb-ue/%: $(BCONFIG)
 	@echo Set number of ue to $(@F)
 	@./scripts/config_edit.py $(BCONFIG) --nb-ue=$(@F)
 
+.PHONY: clean
 clean:
 	@rm -rf $(BUILD_DIR)
+
+.PHONY: build
 build:
 	@$(MAKE) $(BCOMPOSE)
 
+.PHONY: pull
 pull: $(BCOMPOSE)
 	@echo Pulling Docker images
 	@docker compose $(PROFILES) $(PROJECT_DIRECTORY) pull
 
-u: $(BCOMPOSE)
+.PHONY: pull/all
+pull/all:
+	@echo Pull **all** Docker images
+	@docker compose -f templates/images-list.yaml pull
+
+.PHONY: u
+u:
+	@$(MAKE) up
+
+.PHONY: d
+d:
+	@$(MAKE) down
+
+.PHONY: r
+r:
+	@$(MAKE) restart
+
+.PHONY: up
+up: $(BCOMPOSE)
 	@# set containers up
 	@docker compose $(PROFILES) $(PROJECT_DIRECTORY) up -d
 
-u-fg: $(BCOMPOSE)
+.PHONY: up-fg
+up-fg: $(BCOMPOSE)
 	@# set containers up in foreground
 	@docker compose $(PROFILES) $(PROJECT_DIRECTORY)  up
 
+.PHONY: ctrl
 ctrl: $(BCONFIG)
 	@# show control plane REST API in firefox
 	@scripts/show_ctrl.py $(BCONFIG)
-d:
+
+.PHONY: down
+down:
 	@# shutdown containers
 	@#> don't depends on build-all because we need the old version to delete all
 	@docker compose $(PROFILES) $(PROJECT_DIRECTORY) down -v
 
-r:
+.PHONY: restart
+restart:
 	@# restart all containers
 	@docker compose $(PROFILES) $(PROJECT_DIRECTORY) restart
 
+.PHONY: e
 e/%:
 	@# enter container
 	docker exec -it $(@F) bash
+
+.PHONY: db
 db/%:
 	@# enter database of a container
 	docker exec -it $(@F)-db psql postgres -U postgres
+
+.PHONY: t
 t/%:
 	@# enter container in debug mode
 	docker exec -it $(@F)-debug bash
+
+.PHONY: l
 l:
 	@# show all logs
 	docker compose $(PROFILES) $(PROJECT_DIRECTORY) logs
 l/%:
 	@# show container's logs
 	docker compose $(PROFILES) $(PROJECT_DIRECTORY) logs $(@F)
+
+.PHONY: lf
 lf:
 	@# show all logs (continuous)
 	docker compose $(PROFILES) $(PROJECT_DIRECTORY) logs -f
 lf/%:
 	@# show container's logs (continuous)
 	docker compose $(PROFILES) $(PROJECT_DIRECTORY) logs $(@F) -f
+
+.PHONY: ps
 ps:
 	@# show container's status
 	docker compose $(PROFILES) $(PROJECT_DIRECTORY) ps
+
+.PHONY: ping
+ping/%:
+	@# ping from a container
+	@docker exec -it $(*D)-debug bash -c "ping $(@F)"
+
+.PHONY: ue/ip
+ue/ip/%:
+	@# show ip of ue
+	@docker exec -it ue$(@F)-debug bash -c "ip --brief address show uesimtun0|awk '{print \"ue$(@F):\", \$$3; exit}'"
+
+.PHONY: ue/ping
+ue/ping/%:
+	@# ping between ues
+	@# ex: `make ue/ping/1/2` pings from ue1 to ue2
+	@TARGET=$(shell docker exec -it ue$(@F)-debug bash -c "ip --brief address show uesimtun0|awk '{print \$$3; exit}'|cut -d"/" -f 1");\
+	docker exec -it ue$(*D)-debug bash -c "ping $$TARGET"

README.md

@@ -11,25 +11,44 @@ The following Debian's packets are required (or their equivalent on your distrib
 - `j2cli`
 - `make`
 
+>[!NOTE]
+> If you intend to use Free5GC’s UPF (with `make set/dataplane/free5gc`),
+> install [Free5CG's GTP5G kernel module](https://github.com/free5gc/gtp5g) on your host.
+> Until [upstream issue](https://github.com/free5gc/go-upf/issues/53) is fixed, and this repository updated, use version v0.8.10 of the driver.
+> Please note that you need to have Linux headers installed on the host to be able to install the module
+> (for example, the package linux-headers-amd64 on Debian if you are on an amd64 architecture).
+
+
 ### Usage
+> [!IMPORTANT]
+> Make sure to enable IPv6.
+This can be done by adding the following in `/etc/docker/daemon.json`:
+ ```json
+{
+	"ipv6": true,
+}
+```
+
 ```text
-make j # build
+make build # build
 make pull # update docker images
-make u # run containers
-make d # stop containers
+make up # run containers
+make down # stop containers
 ```
 
+The Makefile provides some other commands you might want to use. They are described in [`doc/commands.md`](doc/commands.md)
+
 #### Configuration
-Configuration is done in the file `config.yaml`. Currently, it only contains a list of IP addresses.
+Configuration is done in the file [`default-config.yaml`](./default-config.yaml). Currently, it only contains a list of IP addresses.
 
 #### Documentation
-Documentation is available in the `doc` directory.
+Documentation is available in the [`doc`](./doc) directory.
 
 ![edge intance access through SRv6](./doc/img/edge-instance-access-through-srv6.svg)
 
 ### Contributing
 #### Syntax coloration
-To enable syntax coloration in vim, you can use the following plugin: [`nextmn/vim-yaml-jinja`](https://github.com/nextmn/vim-yaml-jinja).
+To enable syntax coloration in Vim, you can use the following plugin: [`nextmn/vim-yaml-jinja`](https://github.com/nextmn/vim-yaml-jinja).
 
 #### PCAP analysis
 To analyse RAN traffic, you can install the following Wireshark/Tshark plugin : [`nextmn/RLS-wireshark-dissector`](https://github.com/nextmn/RLS-wireshark-dissector).

doc/commands.md

@@ -0,0 +1,36 @@
+# Available commands
+## Set
+- dataplane
+  - `make set/dataplane/nextmn-srv6`: use NextMN SRv6 (default)
+  - `make set/dataplane/nextmn-upf`: use NextMN UPFs
+  - `make set/dataplane/free5gc`: use Free5GC's UPFs
+- number of UEs: `make set/nb-ue/<number>` (max: 2)
+- number of Edges: `make set/nb-edges/<number>` (max: 2)
+
+## Pull
+When you update the git repository, please ensure to update Docker images as well.
+- `make pull` pulls required images to run the project with the current configuration.
+- `make pull/all` pulls all images used by the project.
+
+## Running the testbed
+- `make build`: build the testbed, without running it
+- `make clean`: clean the build directory
+- `make up`: equivalent of `docker compose up -d`
+- `make up-fg`: equivalent of `docker compose up`
+- `make down`: equivalent of `docker compose down`
+- `make restart`: equivalent of `docker compose restart`
+- `make ps`: equivalent of `docker compose ps`
+- `make l`: equivalent of `docker compose logs`
+- `make lf`: equivalent of `docker compose logs -f`
+- `make ctrl`: open in your browser the control API URLs of NextMN SRv6 nodes
+
+## Using containers
+- `make e/<container-name>`: enter the base container
+- `make t/<container-name>`: enter the container with debug tools
+- `make db/<container-name>`: enter the database associated with a container (for NextMN-SRv6)
+- `make l/<container-name>`: show logs of a container
+- `make lf/<container-name>`: show logs of a container (continuous)
+
+## Using UEs
+- `make ue/ip/<ue-number>`: show IP Address of the UE within the Mobile Network
+- `make ue/ping/<ue-source-number>/<ue-target-number>`

templates/images-list.yaml

@@ -0,0 +1,44 @@
+name: "nextmn-testbed-pull-images"
+services:
+  mongo:
+    image: mongo
+  postgres:
+    image: postgres
+  nginx:
+    image: nginx
+  ue:
+    image: louisroyer/ueransim-ue
+  gnb:
+    image: louisroyer/ueransim-gnb
+  debug:
+    image: louisroyer/network-debug
+  docker-setup:
+    image: louisroyer/docker-setup
+  free5gc-upf:
+    image: louisroyer/dev-free5gc-upf
+  nextmn-upf:
+    image: louisroyer/dev-nextmn-upf
+  nextmn-srv6:
+    image: louisroyer/dev-nextmn-srv6
+  nextmn-srv6-ctrl:
+    image: louisroyer/dev-nextmn-srv6-ctrl
+  amf:
+    image: louisroyer/dev-free5gc-amf
+  ausf:
+    image: louisroyer/dev-free5gc-ausf
+  chf:
+    image: louisroyer/dev-free5gc-chf
+  nrf:
+    image: louisroyer/dev-free5gc-nrf
+  nssf:
+    image: louisroyer/dev-free5gc-nssf
+  pcf:
+    image: louisroyer/dev-free5gc-pcf
+  smf:
+    image: louisroyer/dev-free5gc-smf
+  udm:
+    image: louisroyer/dev-free5gc-udm
+  udr:
+    image: louisroyer/dev-free5gc-udr
+  webconsole:
+    image: louisroyer/dev-free5gc-webconsole