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.
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).
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 |
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 sameegiona/ns3-base
tag); andB
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 selectinggfortran
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.
The following instructions should apply to all platforms supported by Docker. However, utility scripts are only provided for UNIX-like systems.
-
Install Docker (please refer to official guidelines w.r.t. your own OS)
-
Select your desired Docker image according to the table above using
docker pull egiona/ns3-woss:<tag>
-
Retrieve the desired image identifier using
docker images
-
Launch a container using the selected image using
docker run -td --name <container name> <image ID>
-
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
, ordocker container ls -a
(the latter also includes containers in any state).
-
You can switch between
debug
andoptimized
builds of ns-3 (see details) using./build-debug.sh
or./build-optimized.sh
respectivelyThe aforementioned utility scripts are placed in the directory
/home
of a container's filesystem (forr2
and later images).Previous images stored them in directory
/home/ns-allinone-3.xx/ns-3.xx/
within a container's filesystem (replacingxx
with your installed version of ns-3). -
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
(orcontrib
) andscratch
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 incontrib
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
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.
-
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
, andtransducers
.For GEBCO databases users only, place the extracted
GEBCO_XXXX.nc
file under thedbs/bathymetry/
sub-directory. It is advisable to store these files outside the container filesystem and using thedocker mount
utility to use them for your simulations. Please see below step 4. -
Copy an arbitrary local file into the container's filesystem using
docker cp <path/to/file> <container ID>:<desired/path/to/file>
-
Copy an arbitrary container's file to local filesystem using
docker cp <container ID>:<path/to/file> <local/path/to/file>
-
Mount a local directory into a container (just once, instead of
docker run
) usingdocker 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.
-
Starting from
r2
images onwards, an environment variableCXX_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.
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.
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.