ns-3 & WOSS Docker images

ns-3 and WOSS bundles using Docker.

The scope of this repository is to automate the installation process of both ns-3 and WOSS library, in order to provide a hassle-free setup process for a simulation environment.

Images are based on egiona/ns3-base, shipping with WOSS library and the corresponding woss-ns3 module installed. Please refer to the ns3-base repository for further details regarding available ns-3 configurations and utilities.

Database configuration is left to the user, mainly for Docker image size purposes.

Available configurations (latest first)

Docker image name: egiona/ns3-woss.

Docker image tag	egiona/ns3-base	WOSS	Dockerfile
u22.04-n3.40-w1.12.6	u22.04-n3.40	1.12.6	link
u20.04-n3.40-w1.12.6	u20.04-n3.40	1.12.6	link
u18.04-n3.35-w1.12.6	u18.04-n3.35	1.12.6	link
u18.04-n3.34-w1.12.6	u18.04-n3.34	1.12.6	link
u18.04-n3.33-w1.12.6	u18.04-n3.33	1.12.6	link

Full changelog can be found at this page.

Previous tags are still available on DockerHub, unless they have been discontinued (see below).

Discontinued images

The following image tags have been discontinued and are not available from the DockerHub repository.

If you are using any of these tags, please consider switching to a different one that is still supported.

Docker image tag	Motivation	Date
u20.04-n3.37-w1.12.5 u18.04-n3.37-w1.12.4-r2 u18.04-n3.37-w1.12.4	GCC compiler issues; not solved by Ubuntu 20.04 upgrade	2023/10/11

Contributing

Any problems should be reported via the GitHub issue tracker.

Users are welcomed to contribute new images (e.g. different base image or other ns-3 versions) via Pull Request and adhering to the following style:

• Directory named <A-B> with: A equal to an arbitrary versioned base image short-hand (i.e. u22.04-n3.40 refers to the same egiona/ns3-base tag); and B equal to the WOSS version bundled (i.e. w1.12.6 refers to WOSS 1.12.6).

  Such directory name will also be used as image tag.

• The directory shall contain a well-commented Dockerfile for the image creation.

  The at sub-directory present in the original images is used to build Acoustic-Toolbox selecting gfortran as FORTRAN compiler; it is advised to stick to it and leave it untouched. In case this compiler is not available to your base image, you should take care of compiling Acoustic-Toolbox on your own (it is among WOSS requirements).

  Other contents may be freely modified, although for uniformity purposes it is advised to maintain the same functionality they provide. The ns3-build directory contains useful scripts to build ns-3 with all WOSS requirements; if modified, you should take care of solving this task.

Usage guidelines

Core instructions

The following instructions should apply to all platforms supported by Docker. However, utility scripts are only provided for UNIX-like systems.

1. Install Docker (please refer to official guidelines w.r.t. your own OS)

2. Select your desired Docker image according to the table above using

   docker pull egiona/ns3-woss:<tag>

3. Retrieve the desired image identifier using

   docker images

4. Launch a container using the selected image using

   docker run -td --name <container name> <image ID>

5. Launch a live terminal from the container using

   docker exec -it <container ID or name> /bin/bash

   You can obtain a running container's ID using  docker ps , or  docker container ls -a (the latter also includes containers in any state).

Utility scripts

1. You can switch between debug and optimized builds of ns-3 (see details) using

   ./build-debug.sh or ./build-optimized.sh respectively

   The aforementioned utility scripts are placed in the directory /home of a container's filesystem (for r2 and later images).

   Previous images stored them in directory  /home/ns-allinone-3.xx/ns-3.xx/ within a container's filesystem (replacing  xx with your installed version of ns-3).

2. Starting from r2 images a utility script in the form of a Makefile is provided.

   Similarly to build scripts, this utility Makefile is placed in the directory /home of a container's filesystem.

   Previous revisions of images had no availability of such utility.

   This script allows for easy decoupling of development directory from ns-3's source directory. Indeed, it is possible to keep novel modules and program driver scripts outside src (or contrib) and scratch directories of the ns-3 installation directory during development, and only copying them afterwards. This is especially useful when paired with mounted directories.

   Multiple targets are present, allowing: ns-3 current version checking, compilation and execution of simulation driver programs (copying them to scratch subdir first), management of ns-3 modules (creation in contrib subdir and copy outside, synchronization of contents, elimination), and debugging (GNU debugger, Valgrind, ns-3 tests).

   Use the following command for all details:

   make help

Optional instructions

As long as you docker restart the same container, any modification to its contents will be preserved. However, it is advisable to keep a local backup copy of your modules and experiment results.

1. Download WOSS databases (required), and optional bathymetry databases such as GEBCO 2020, GEBCO 2022 or GEBCO 2023 locally.

   More specifically, the extracted dbs directory should contain 4 sub-directories, namely: bathymetry, seafloor_sediment, ssp, and transducers.

   For GEBCO databases users only, place the extracted GEBCO_XXXX.nc file under the dbs/bathymetry/ sub-directory. It is advisable to store these files outside the container filesystem and using the docker mount utility to use them for your simulations. Please see below step 4.

2. Copy an arbitrary local file into the container's filesystem using

   docker cp <path/to/file> <container ID>:<desired/path/to/file>

3. Copy an arbitrary container's file to local filesystem using

   docker cp <container ID>:<path/to/file> <local/path/to/file>

4. Mount a local directory into a container (just once, instead of docker run) using

   docker run -td --mount type=bind,source=<local/FS/path>,target=<container/FS/path> --name <container name> <image ID>

   Paths to be mounted must be absolute.

   This is only needed the first time a container is instantiated, subsequent calls to  docker start on the same container will automatically load the mounted directory.

   Warning: existing container contents at the same target path will be overwritten with the ones provided by the local filesystem.

5. Starting from r2 images onwards, an environment variable CXX_CONFIG is available for user-defined scripts to adapt their GCC compilation parameters; by default, such variable holds the following contents:

   CXX_CONFIG="-Wall -Werror -Wno-unused-variable"

   Moreover, build scripts have been updated to provide an exit value reflective of ns-3's configuration and build outcome.

Citing this work

If you use any of the Docker images described in this repository, please cite this work using any of the following methods:

APA

Giona, E. ns-3 and WOSS Docker images [Computer software]. https://doi.org/10.5281/zenodo.5727518

BibTeX

@software{Giona_ns-3_and_WOSS,
author = {Giona, Emanuele},
doi = {10.5281/zenodo.5727518},
license = {MIT},
title = {{ns-3 and WOSS Docker images}},
url = {https://github.com/emanuelegiona/ns3-woss-docker}
}

Bibliography entries generated using Citation File Format described in the CITATION.cff file.

License

Copyright (c) 2024 Emanuele Giona (SENSES Lab, Sapienza University of Rome)

This repository and Docker images themselves are distributed under MIT license.

However, ns-3 and WOSS are distributed under their respective licenses: ns-3 license, WOSS license. All installed packages may also be subject to their own license, and the license chosen for the Docker images does not necessarily apply to them.

Diclaimer: Docker, Ubuntu, ns-3, WOSS and other cited or included software belongs to their respective owners.