Skip to content
This repository has been archived by the owner on Feb 14, 2024. It is now read-only.

Commit

Permalink
Merge pull request #1 from emanuelegiona/main
Browse files Browse the repository at this point in the history
ns-3.37 + WOSS 1.12.4 release
  • Loading branch information
emanuelegiona authored Mar 20, 2023
2 parents 9f04707 + b54d82b commit 98b1d53
Show file tree
Hide file tree
Showing 7 changed files with 649 additions and 44 deletions.
101 changes: 62 additions & 39 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,25 +7,27 @@ ns-3 and WOSS library, in order to provide a hassle-free setup process for a
simulation environment.

Images ship with fully-functioning ns-3 and WOSS library installations, also
including the corresponding woss-ns3 module.
ns-3 is provided already built in `debug` and `optimized` profiles, with the
former being the active version on a first run; utility scripts to quickly
including the corresponding [woss-ns3 module][woss-ns3].
ns-3 is provided pre-built in `debug` and `optimized` profiles, with the
*former* being the active version on a first run; utility scripts to quickly
switch between them are provided (see below).
Database configuration is left to the user, mainly for Docker image size
purposes.

## Available configurations
## Available configurations *(latest first)*

| OS | ns-3 | WOSS | Docker image | Dockerfile |
| :---: | :---: | :---: | :---: | :---: |
| Ubuntu 18.04 | [3.33][ns3.33] | [1.12.0][woss-changelog] | [`egiona/ns3-woss:u18.04-n3.33-w1.12.0`][image1] | [link][file1] |
| Ubuntu 18.04 | [3.33][ns3.33] | [1.12.1][woss-changelog] | [`egiona/ns3-woss:u18.04-n3.33-w1.12.1`][image2] | [link][file2] |
| Ubuntu 18.04 | [3.34][ns3.34] | [1.12.1][woss-changelog] | [`egiona/ns3-woss:u18.04-n3.34-w1.12.1`][image3] | [link][file3] |
| Ubuntu 18.04 | [3.34][ns3.34] | [1.12.2][woss-changelog] | [`egiona/ns3-woss:u18.04-n3.34-w1.12.2`][image4] | [link][file4] |
| Ubuntu 18.04 | [3.35][ns3.35] | [1.12.2][woss-changelog] | [`egiona/ns3-woss:u18.04-n3.35-w1.12.2`][image5] | [link][file5] |
<!--- | TBD | TDB | TDB | N/A | N/A | --->
Docker image name: [**`egiona/ns3-woss`**][docker-hub-repo].

All images can be found in the [Docker Hub repository][docker-hub-repo].
| Docker image tag | OS | ns-3 | Build system | WOSS | Dockerfile |
| :---: | :---: | :---: | :---: | :---: | :---: |
| [`u18.04-n3.37-w1.12.4`][image6] | Ubuntu 18.04 | [3.37][ns3.37] | CMake[^ns3-cmake] | [1.12.4][woss-changelog] | [link][file6] |
| [`u18.04-n3.35-w1.12.2`][image5] | Ubuntu 18.04 | [3.35][ns3.35] | Waf | [1.12.2][woss-changelog] | [link][file5] |
| [`u18.04-n3.34-w1.12.2`][image4] | Ubuntu 18.04 | [3.34][ns3.34] | Waf | [1.12.2][woss-changelog] | [link][file4] |
| [`u18.04-n3.34-w1.12.1`][image3] | Ubuntu 18.04 | [3.34][ns3.34] | Waf | [1.12.1][woss-changelog] | [link][file3] |
| [`u18.04-n3.33-w1.12.1`][image2] | Ubuntu 18.04 | [3.33][ns3.33] | Waf | [1.12.1][woss-changelog] | [link][file2] |
| [`u18.04-n3.33-w1.12.0`][image1] | Ubuntu 18.04 | [3.33][ns3.33] | Waf | [1.12.0][woss-changelog] | [link][file1] |

[^ns3-cmake]: ns-3 adopted the CMake build system starting from 3.36 release. More details can be found at [this page](https://www.nsnam.org/docs/manual/html/working-with-cmake.html).

# Usage guidelines

Expand All @@ -38,32 +40,52 @@ However, _utility scripts_ are only provided for UNIX-like systems.

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

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; `docker pull <image:tag>`
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; `docker pull egiona/ns3-woss:<tag>`

3. Retrieve the desired image identifier using

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; `docker images`

3. Launch a container using the selected image using
4. Launch a container using the selected image using

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; `docker run -t -d --name <container name> <image name>`
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; `docker run -t -d --name <container name> <image ID>`

4. Launch a live terminal from the container using
5. Launch a live terminal from the container using

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; `docker exec -it <container ID> /bin/bash`

&nbsp;&nbsp;&nbsp;&nbsp; _You can obtain a running container's ID using_&nbsp; `docker ps` _, or_&nbsp; `docker container ls -a` _for containers in any state._

## Utility scripts

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

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; `./build-debug.sh` or `./build-optimized.sh` respectively

&nbsp;&nbsp;&nbsp;&nbsp; _The aforementioned utility scripts are placed in the home directory of a container's filesystem (for ns-3.37+ images). Previous images stored them in directory_&nbsp; `/home/ns-allinone-3.xx/ns-3.xx/` _within a container's filesystem (replacing_&nbsp; `xx` _with your installed version of ns-3)._

2. Starting from ns-3.37+ images, a utility script in the form of a [Makefile](./u18.04-n3.37-w1.12.4/ns3-utils/Makefile) is provided. <br/><br/>
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. <br/><br/>
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). <br/><br/>
Use the following command for all details:

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; `make help`

## Optional instructions

> As long as you start 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. Execute the utility script to download [WOSS (3.4 GB -> 8.2 GB)][woss-dbs] and [GEBCO 2020 (4.0 GB -> 7.5 GB)][gebco2020] databases _locally_ using
1. Execute the utility script to download [WOSS (3.4 GB -> 8.2 GB)][woss-dbs], [GEBCO 2020 (4.0 GB -> 7.5 GB)][gebco2020], and [GEBCO 2022 2D 15 arc-seconds (TBD)][gebco2022] databases _locally_ using

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; `./download-databases.sh <DBs directory>`

&nbsp;&nbsp;&nbsp;&nbsp; _Were this utility to fail (or cannot be run due the lack of a UNIX-like system), download both databases via browser and use your favorite decompression tool on them._
<br/>
&nbsp;&nbsp;&nbsp;&nbsp; _More specifically, the extracted_&nbsp; `dbs` _directory should contain 4 sub-directories, namely:_&nbsp; `bathymetry`_,_ `seafloor_sediment`_,_ `ssp`_, and_&nbsp; `transducers`_._
<br/>
&nbsp;&nbsp;&nbsp;&nbsp; _Once extracted, place the_&nbsp; `GEBCO_2020.nc` _file under the_&nbsp; `dbs/bathymetry/` _sub-directory._
&nbsp;&nbsp;&nbsp;&nbsp; _Once extracted, place the_&nbsp; `GEBCO_XXXX.nc` _file under the_&nbsp; `dbs/bathymetry/` _sub-directory._

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

Expand All @@ -75,13 +97,7 @@ However, it is advisable to keep a _local backup copy_ of your modules and exper

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; `docker cp <container ID>:<path/to/file> <local/path/to/file>`

4. You can switch between `debug` and `optimized` builds of ns-3 (see [details][ns3-builds]) using

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; `./build-debug.sh` or `./build-optimized.sh` respectively

&nbsp;&nbsp;&nbsp;&nbsp; _The aforementioned utility scripts are placed in directory_&nbsp; `/home/ns-allinone-3.xx/ns-3.xx/` _within a container's filesystem (replacing_&nbsp; `xx` _with your installed version of ns-3)._

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

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; `./mount.sh <local/path/to/directory> <path/to/directory> <container name> <image name>`

Expand All @@ -98,7 +114,7 @@ If you use any of the Docker images described in this repository, please cite th
Giona, E. ns-3 and WOSS Docker images [Computer software]. https://doi.org/10.5281/zenodo.5727519
```

**BibTex**
**BibTeX**
```
@software{Giona_ns-3_and_WOSS,
author = {Giona, Emanuele},
Expand All @@ -113,9 +129,9 @@ Bibliography entries generated using [Citation File Format][cff] described in th

# License

Copyright (c) 2021 Emanuele Giona (SENSES Lab, Sapienza University of Rome)
**Copyright (c) 2023 Emanuele Giona ([SENSES Lab][senseslab], Sapienza University of Rome)**

Docker images themselves are distributed under [MIT license][docker-license].
This repository and Docker images themselves are distributed under [MIT license][docker-license].
However, ns-3 and WOSS are distributed under their respective licenses:
[ns-3 license][ns3-license], [WOSS license][woss-license].
All installed packages may also be subject to their own license, and the license
Expand All @@ -126,35 +142,42 @@ chosen for the Docker images does not necessarily apply to them.
[ns3]: https://www.nsnam.org/
[woss]: http://telecom.dei.unipd.it/ns/woss/
[docker]: https://www.docker.com/
[woss-ns3]: https://github.com/MetalKnight/woss-ns3

[docker-hub-repo]: https://hub.docker.com/r/egiona/ns3-woss

[ns3.33]: https://www.nsnam.org/releases/ns-3-33/
[ns3.34]: https://www.nsnam.org/releases/ns-3-34/
[ns3.35]: https://www.nsnam.org/releases/ns-3-35/
[ns3.37]: https://www.nsnam.org/releases/ns-3-37/

[woss-changelog]: http://telecom.dei.unipd.it/ns/woss/doxygen/Changelog.html

[image1]: https://hub.docker.com/r/egiona/ns3-woss/tags?page=1&name=u18.04-n3.33-w1.12.0
[file1]: ./u18.04-n3.33-w1.12.0/Dockerfile
[image2]: https://hub.docker.com/r/egiona/ns3-woss/tags?page=1&name=u18.04-n3.33-w1.12.1
[file2]: ./u18.04-n3.33-w1.12.1/Dockerfile
[image3]: https://hub.docker.com/r/egiona/ns3-woss/tags?page=1&name=u18.04-n3.34-w1.12.1
[file3]: ./u18.04-n3.34-w1.12.1/Dockerfile
[image4]: https://hub.docker.com/r/egiona/ns3-woss/tags?page=1&name=u18.04-n3.34-w1.12.2
[file4]: ./u18.04-n3.34-w1.12.2/Dockerfile
[image6]: https://hub.docker.com/r/egiona/ns3-woss/tags?page=1&name=u18.04-n3.37-w1.12.4
[file6]: ./u18.04-n3.37-w1.12.4/Dockerfile
[image5]: https://hub.docker.com/r/egiona/ns3-woss/tags?page=1&name=u18.04-n3.35-w1.12.2
[file5]: ./u18.04-n3.35-w1.12.2/Dockerfile
[image4]: https://hub.docker.com/r/egiona/ns3-woss/tags?page=1&name=u18.04-n3.34-w1.12.2
[file4]: ./u18.04-n3.34-w1.12.2/Dockerfile
[image3]: https://hub.docker.com/r/egiona/ns3-woss/tags?page=1&name=u18.04-n3.34-w1.12.1
[file3]: ./u18.04-n3.34-w1.12.1/Dockerfile
[image2]: https://hub.docker.com/r/egiona/ns3-woss/tags?page=1&name=u18.04-n3.33-w1.12.1
[file2]: ./u18.04-n3.33-w1.12.1/Dockerfile
[image1]: https://hub.docker.com/r/egiona/ns3-woss/tags?page=1&name=u18.04-n3.33-w1.12.0
[file1]: ./u18.04-n3.33-w1.12.0/Dockerfile

[docker-hub-repo]: https://hub.docker.com/r/egiona/ns3-woss
[docker-install]: https://docs.docker.com/engine/install/

[woss-dbs]: http://telecom.dei.unipd.it/ns/woss/files/WOSS-dbs-v1.6.0.tar.gz
[gebco2020]: https://www.bodc.ac.uk/data/open_download/gebco/gebco_2020/zip/
[gebco2022]: https://www.bodc.ac.uk/data/open_download/gebco/gebco_2022/zip/

[ns3-builds]: https://www.nsnam.org/docs/release/3.35/tutorial/html/getting-started.html#build-profiles
[ns3-builds]: https://www.nsnam.org/docs/release/3.37/tutorial/html/getting-started.html#build-profiles

[cff]: https://citation-file-format.github.io/
[citation]: ./CITATION.cff

[senseslab]: https://senseslab.diag.uniroma1.it/
[docker-license]: ./LICENSE
[ns3-license]: https://www.nsnam.org/develop/contributing-code/licensing/
[woss-license]: http://telecom.dei.unipd.it/ns/woss/doxygen/License.html
86 changes: 81 additions & 5 deletions download-databases.sh
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

# MIT License

# Copyright (c) 2021 Emanuele Giona <[email protected]> (SENSES Lab,
# Copyright (c) 2023 Emanuele Giona <[email protected]> (SENSES Lab,
# Sapienza University of Rome)

# Permission is hereby granted, free of charge, to any person obtaining a copy
Expand All @@ -23,17 +23,93 @@
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
# SOFTWARE.

cd $1
USAGE="Usage: ./$(basename "$0") </path/to/download_dir> </path/to/dbs_dir>
where:
- </path/to/download_dir> is the absolute path to the directory for downloading databases
- </path/to/dbs_dir> is the absolute path to the directory for storing databases"

echo "Downloading databases"
if [[ "$#" -ne 2 ]]; then
echo "Invalid argument number."
echo "${USAGE}"
exit 1
fi

if [ ! -d "${1}" ]; then
echo "Download directory does not exist."
echo "${USAGE}"
exit 1
fi

if [ ! -d "${2}" ]; then
echo "Databse directory does not exist."
echo "${USAGE}"
exit 1
fi

CURR_DIR=`pwd`
WOSS_DBS=0
GEBCO_2020=0
GEBCO_2022=0

echo "Entering ${1}"
cd ${1}

echo "1/3: Downloading WOSS databases..."
wget http://telecom.dei.unipd.it/ns/woss/files/WOSS-dbs-v1.6.0.tar.gz && \
tar -xf WOSS-dbs-v1.6.0.tar.gz && \
rm WOSS-dbs-v1.6.0.tar.gz && \
let WOSS_DBS=1

if [ ${WOSS_DBS} -ne 1 ]; then
echo "FAILED: exiting"
exit 1
fi

echo "2/3: Downloading GEBCO 2020 database..."
curl -L -o gebco_2020_netcdf.zip https://www.bodc.ac.uk/data/open_download/gebco/gebco_2020/zip/ && \
unzip gebco_2020_netcdf.zip && \
rm gebco_2020_netcdf.zip && \
mv GEBCO_2020.nc dbs/bathymetry/
let GEBCO_2020=1

if [ ${GEBCO_2020} -ne 1 ]; then
echo "FAILED: exiting"
exit 1
fi

echo "3/3: Downloading GEBCO 2022 database..."
curl -L -o gebco_2022_netcdf.zip https://www.bodc.ac.uk/data/open_download/gebco/gebco_2022/zip/ && \
unzip gebco_2022_netcdf.zip && \
rm gebco_2022_netcdf.zip && \
let GEBCO_2022=1

if [ ${GEBCO_2022} -ne 1 ]; then
echo "FAILED: exiting"
exit 1
fi

echo "All databases downloaded"
echo "Moving WOSS databases to ${2}..."

cp -r --parents dbs/* ${2}/

if [ ! -d "${2}/dbs" ]; then
echo "FAILED: exiting ('dbs' directory missing)"
exit 1
fi

if [ ! -d "${2}/dbs/bathymetry" ]; then
echo "FAILED: exiting ('dbs/bathymetry' directory missing)."
exit 1
fi

echo "Moving GEBCO 2020 database..."
mv GEBCO_2020.nc ${2}/dbs/bathymetry/

echo "Moving GEBCO 2022 database..."
mv GEBCO_2022.nc ${2}/dbs/bathymetry/

cd ${CURR_DIR}

echo "Databases downloaded at directory: $1/dbs/"
echo "Done"
echo "All databases moved to: ${2}/dbs/"
exit 0
Loading

0 comments on commit 98b1d53

Please sign in to comment.