Minor README improvements; fix outdated URLs
Change-Id: Ia57f83892471ad85a2301ba4c8ab3df144581000
diff --git a/AUTHORS.md b/AUTHORS.md
index 5754f10..f25a767 100644
--- a/AUTHORS.md
+++ b/AUTHORS.md
@@ -2,7 +2,7 @@
The following lists maintainers, primary developers, and all much-appreciated contributors to ndn-tools in alphabetical order.
The specific contributions of individual authors can be obtained from the git history of the [official ndn-tools repository](https://github.com/named-data/ndn-tools).
-If you would like to become a contributor to the official repository, please follow the recommendations in <https://github.com/named-data/.github/blob/master/CONTRIBUTING.md>.
+If you would like to become a contributor to the official repository, please follow the recommendations in <https://github.com/named-data/.github/blob/main/CONTRIBUTING.md>.
* Jerald Paul Abraham <https://cs.arizona.edu/~jeraldabraham>
* ***(Maintainer)*** Alexander Afanasyev <https://users.cs.fiu.edu/~afanasyev>
diff --git a/INSTALL.md b/INSTALL.md
index 369fd9c..6835f61 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -4,17 +4,15 @@
## Prerequisites
-- Install the [ndn-cxx](https://named-data.net/doc/ndn-cxx/current/) library and its prerequisites.
- Please see [Getting Started with ndn-cxx](https://named-data.net/doc/ndn-cxx/current/INSTALL.html)
- for instructions.
- All operating systems and compilers supported by ndn-cxx are also supported by ndn-tools.
+* Install the [ndn-cxx](https://github.com/named-data/ndn-cxx) library and its dependencies.
+ Check out [the documentation](https://docs.named-data.net/ndn-cxx/current/INSTALL.html) for
+ detailed installation instructions. All platforms supported by ndn-cxx are also supported
+ by ndn-tools.
*Note*: If you have installed ndn-cxx from a binary package, please make sure the development
headers are installed (e.g., if using Ubuntu PPA, the `libndn-cxx-dev` package is needed).
-- `libpcap`
-
- Comes with the base system on macOS.
+* Install `libpcap` (except on macOS where it is provided by the base system).
On Debian and Ubuntu:
diff --git a/README-dev.md b/README-dev.md
index 0a76f22..2a028b8 100644
--- a/README-dev.md
+++ b/README-dev.md
@@ -3,7 +3,7 @@
## Licensing Requirements
Contributions to ndn-tools must be licensed under the GPL 3.0 or a compatible license.
-If you choose GPL 3.0, include the following license boilerplate into all C++ code files:
+If you choose GPL 3.0, insert the following license boilerplate into all C++ source files:
/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
/*
@@ -57,7 +57,7 @@
## Code Guidelines
C++ code should conform to the
-[ndn-cxx code style](https://named-data.net/doc/ndn-cxx/current/code-style.html).
+[ndn-cxx code style](https://docs.named-data.net/ndn-cxx/current/code-style.html).
### Namespace
@@ -83,36 +83,38 @@
Example:
- namespace ndn {
- namespace foo {
+```cpp
+namespace ndn {
+namespace foo {
- class Bar
- {
- public:
- explicit
- Bar(Face& face);
+class Bar
+{
+public:
+ explicit
+ Bar(Face& face);
- void
- run();
- };
+ void
+ run();
+};
- static int
- main(int argc, char* argv[])
- {
- Face face;
- Bar program(face);
- program.run();
- return 0;
- }
+static int
+main(int argc, char* argv[])
+{
+ Face face;
+ Bar program(face);
+ program.run();
+ return 0;
+}
- } // namespace foo
- } // namespace ndn
+} // namespace foo
+} // namespace ndn
- int
- main(int argc, char* argv[])
- {
- return ndn::foo::main(argc, argv);
- }
+int
+main(int argc, char* argv[])
+{
+ return ndn::foo::main(argc, argv);
+}
+```
### Command Line Arguments
diff --git a/README.md b/README.md
index 94dabe6..54a66c5 100644
--- a/README.md
+++ b/README.md
@@ -5,16 +5,16 @@
-**ndn-tools** is a collection of basic tools for [Named Data Networking](https://named-data.net/).
-Tools in this collection include:
+This repository contains a collection of basic tools for [Named Data Networking (NDN)](https://named-data.net/).
+The tools currently included are:
-* [peek](tools/peek): transmit a single Interest/Data packet between a consumer
+* [**peek**](tools/peek): transmit a single Interest/Data packet between a consumer
and a producer
-* [chunks](tools/chunks): segmented file transfer between a consumer and a producer
-* [ping](tools/ping): test reachability between two NDN nodes
-* [dump](tools/dump): capture and analyze live traffic on an NDN network
-* [dissect](tools/dissect): inspect the TLV structure of an NDN packet
-* [dissect-wireshark](tools/dissect-wireshark): Wireshark extension to inspect
+* [**chunks**](tools/chunks): segmented file transfer between a consumer and a producer
+* [**ping**](tools/ping): test reachability between two NDN nodes
+* [**dump**](tools/dump): capture and analyze live traffic on an NDN network
+* [**dissect**](tools/dissect): inspect the TLV structure of an NDN packet
+* [**dissect-wireshark**](tools/dissect-wireshark): Wireshark extension to inspect
the TLV structure of NDN packets
## Installation
@@ -28,12 +28,13 @@
## Contributing
-We greatly appreciate contributions to ndn-tools. If you are new to the NDN
-software community, please read [`README-dev.md`](README-dev.md) and the
-[Contributor's Guide](https://github.com/named-data/.github/blob/master/CONTRIBUTING.md)
-to get started.
+Contributions to ndn-tools are greatly appreciated and can be made through our
+[Gerrit code review site](https://gerrit.named-data.net/).
+If you are new to the NDN software community, please read our
+[Contributor's Guide](https://github.com/named-data/.github/blob/main/CONTRIBUTING.md)
+and [`README-dev.md`](README-dev.md) to get started.
## License
-ndn-tools is an open source project licensed under the GPL version 3.
-See [`COPYING.md`](COPYING.md) for more information.
+ndn-tools is free software distributed under the GNU General Public License version 3.
+See [`COPYING.md`](COPYING.md) for details.
diff --git a/manpages/conf.py b/manpages/conf.py
index 03438b4..a1263b8 100644
--- a/manpages/conf.py
+++ b/manpages/conf.py
@@ -7,7 +7,7 @@
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
project = 'NDN Essential Tools'
-copyright = 'Copyright © 2014-2022 Named Data Networking Project.'
+copyright = 'Copyright © 2014-2023 Named Data Networking Project.'
author = 'Named Data Networking Project'
# The short X.Y version.
diff --git a/manpages/ndnputchunks.rst b/manpages/ndnputchunks.rst
index 441f9eb..f002a78 100644
--- a/manpages/ndnputchunks.rst
+++ b/manpages/ndnputchunks.rst
@@ -15,7 +15,7 @@
Version and segment number components are appended to the specified *name* as needed,
according to the `NDN naming conventions`_.
-.. _NDN naming conventions: https://named-data.net/publications/techreports/ndn-tr-22-2-ndn-memo-naming-conventions/
+.. _NDN naming conventions: https://named-data.net/publications/techreports/ndn-tr-22-3-ndn-memo-naming-conventions/
Options
-------
diff --git a/tools/chunks/README.md b/tools/chunks/README.md
index 8b47eea..3c73bcf 100644
--- a/tools/chunks/README.md
+++ b/tools/chunks/README.md
@@ -4,8 +4,8 @@
* **ndnputchunks** is a producer program that reads a file from the standard input, and makes
it available as a set of NDN Data segments. It appends version and segment number components
- to the specified name as needed, according to the
- [NDN naming conventions](https://named-data.net/publications/techreports/ndn-tr-22-2-ndn-memo-naming-conventions/).
+ to the specified name as needed, according to the [NDN naming conventions](
+ https://named-data.net/publications/techreports/ndn-tr-22-3-ndn-memo-naming-conventions/).
* **ndncatchunks** is a consumer program that fetches Data segments of a file, optionally
discovering the latest version of the file, and writes the content of the retrieved file to
@@ -18,7 +18,7 @@
be sent out to fetch metadata of the solicited content from which the Data version will be resolved.
For more information about the packet format and naming conventions of Interest and Data packets
used for version discovery in ndncatchunks, please refer to:
-[Realtime Data Retrieval (RDR) protocol wiki page](https://redmine.named-data.net/projects/ndn-tlv/wiki/RDR)
+[Realtime Data Retrieval (RDR) protocol](https://redmine.named-data.net/projects/ndn-tlv/wiki/RDR).
## Interest pipeline types in ndncatchunks
@@ -32,7 +32,7 @@
* `cubic`: adjusts the window size similar to the TCP CUBIC algorithm.
For details about both aimd and cubic please refer to:
[A Practical Congestion Control Scheme for Named Data
- Networking](https://conferences2.sigcomm.org/acm-icn/2016/proceedings/p21-schneider.pdf)
+ Networking](https://conferences2.sigcomm.org/acm-icn/2016/proceedings/p21-schneider.pdf).
The default Interest pipeline type is `cubic`.
diff --git a/tools/dissect-wireshark/README.md b/tools/dissect-wireshark/README.md
index d304ce6..805f2e8 100644
--- a/tools/dissect-wireshark/README.md
+++ b/tools/dissect-wireshark/README.md
@@ -1,19 +1,18 @@
-NDN Packet Dissector for Wireshark
-==================================
+# NDN Packet Dissector for Wireshark
-**NDN packet dissector requires at least version 1.12.6 of Wireshark with LUA support enabled**
+*NOTE: The dissector requires at least version 1.12.6 of Wireshark with LUA support enabled.*
-The dissection of [Named Data Networking (NDN) packets](http://named-data.net/doc/ndn-tlv/) is
-supported in the following cases:
+The dissection of [NDN packets](https://docs.named-data.net/NDN-packet-spec/current/)
+is supported in the following cases:
-- NDN packets are encapsulated in IPv4/IPv6 UDP packets with source or destination port
- 6363 or 56363.
+- NDN packets are encapsulated in IPv4/IPv6 UDP datagrams with source or destination
+ port 6363 or 56363.
- NDN packets are encapsulated in IPv4/IPv6 TCP segments with source or destination
port 6363.
-- NDN packets are encapsulated in IPv4/IPv6 TCP/HTTP WebSocket packets with source or
- destination port 9696.
+- NDN packets are encapsulated in IPv4/IPv6 WebSocket packets with source or destination
+ port 9696.
- NDN packets are encapsulated in Ethernet frames with EtherType 0x8624.
@@ -56,11 +55,15 @@
`/opt/local/share/ndn-dissect-wireshark`. To enable the dissector for Wireshark session,
use `-X` command line option, specifying the full path to the `ndn.lua` script:
- wireshark -X lua_script:/usr/local/share/ndn-dissect-wireshark/ndn.lua
+```shell
+wireshark -X lua_script:/usr/local/share/ndn-dissect-wireshark/ndn.lua
+```
Similarly, NDN packets dissector can be enabled when using `tshark`:
- tshark shark -X lua_script:/usr/local/share/ndn-dissect-wireshark/ndn.lua
+```shell
+tshark shark -X lua_script:/usr/local/share/ndn-dissect-wireshark/ndn.lua
+```
To enable NDN packets dissector for all future Wireshark sessions, you can create/edit
Wireshark's `init.lua` script, which located in `/usr/share/wireshark`,
@@ -68,8 +71,9 @@
or similar location depending on the platform and the way Wireshark is installed. The
`dofile` command should be added to the end of `init.lua` file:
- -- dofile("/full/path/to/ndn.lua")
- dofile("/usr/local/share/ndn-dissect-wireshark/ndn.lua")
+```lua
+dofile("/usr/local/share/ndn-dissect-wireshark/ndn.lua")
+```
For more detailed information about how to use Lua refer to [Lua wiki](https://wiki.wireshark.org/Lua).
@@ -78,26 +82,26 @@
Due to security issues, customized lua scripts are not allowed to be loaded when Wireshark
is started with root privileges. There are two workarounds:
-- run Wireshark, `dumpcap`, or `tcpdump` with root privileges to capture traffic to a file, later
- running Wireshark without root privileges and to analyze the captured traffic.
+- Run `dumpcap` or `tcpdump` with root privileges to capture traffic to a file, and later
+ run Wireshark *without* root privileges to analyze the captured traffic.
-- (beware of potential security implications) allow non-root users to capture packets:
+- Allow non-root users to capture packets (beware of potential security implications!)
- * On Linux platform, you can use `setcap`
+ * On Linux, you can use `setcap`:
- sudo setcap cap_net_raw,cap_net_admin=eip /full/path/to/wireshark
+ sudo setcap cap_net_raw,cap_net_admin=eip /full/path/to/wireshark
- You may need to install a package to use setcap (e.g., `sudo apt-get install libcap2-bin` on Ubuntu)
+ You may need to install a package to use `setcap` (e.g., `sudo apt install libcap2-bin` on Ubuntu)
- * On Debian/Ubuntu Linux, capturing traffic with Wireshark by a non-root user can be enabled by adding
- this user to the `wireshark` group.
+ * On Debian/Ubuntu Linux, capturing traffic with Wireshark by a non-root user can be enabled by
+ adding the user to the `wireshark` group.
- See [Wireshark Debian README](http://anonscm.debian.org/viewvc/collab-maint/ext-maint/wireshark/trunk/debian/README.Debian?view=markup)
- for more details.
+ See Debian's [README file](https://salsa.debian.org/debian/wireshark/-/blob/debian/master/debian/README.Debian)
+ for details.
- * On OSX platform, `/dev/bpf*` devices need to be assigned proper permissions
+ * On macOS, `/dev/bpf*` devices need to be assigned proper permissions.
- Automatically using ChmodBPF app
+ Automatically using ChmodBPF app:
curl https://bugs.wireshark.org/bugzilla/attachment.cgi?id=3373 -o ChmodBPF.tar.gz
tar zxvf ChmodBPF.tar.gz
diff --git a/tools/dissect-wireshark/ndn.lua b/tools/dissect-wireshark/ndn.lua
index 2ed49ab..9037b5c 100755
--- a/tools/dissect-wireshark/ndn.lua
+++ b/tools/dissect-wireshark/ndn.lua
@@ -1,4 +1,4 @@
--- Copyright (c) 2015-2019, Regents of the University of California.
+-- Copyright (c) 2015-2023, Regents of the University of California.
--
-- This file is part of ndn-tools (Named Data Networking Essential Tools).
-- See AUTHORS.md for complete list of ndn-tools authors and contributors.
@@ -173,7 +173,7 @@
local name = ""
-- TODO: Properly format informational message based type value reservations
- -- (https://named-data.net/doc/NDN-packet-spec/current/types.html#tlv-type-number-reservations)
+ -- (https://docs.named-data.net/NDN-packet-spec/current/types.html#reserved-ranges)
if (block.type <= AppPrivateBlock1) then
name = "Unrecognized from the reserved range " .. 0 .. "-" .. AppPrivateBlock1 .. ""
elseif (AppPrivateBlock1 < block.type and block.type < AppPrivateBlock2) then
diff --git a/tools/dissect/dissector.cpp b/tools/dissect/dissector.cpp
index f7c464d..9d72998 100644
--- a/tools/dissect/dissector.cpp
+++ b/tools/dissect/dissector.cpp
@@ -1,6 +1,6 @@
/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
/*
- * Copyright (c) 2013-2022, Regents of the University of California.
+ * Copyright (c) 2013-2023, Regents of the University of California.
*
* This file is part of ndn-tools (Named Data Networking Essential Tools).
* See AUTHORS.md for complete list of ndn-tools authors and contributors.
@@ -74,7 +74,7 @@
}
}
-// https://named-data.net/doc/NDN-packet-spec/current/types.html
+// https://docs.named-data.net/NDN-packet-spec/current/types.html
static const std::map<uint32_t, std::string_view> TLV_DICT = {
{tlv::Interest , "Interest"},
{tlv::Data , "Data"},
diff --git a/tools/dump/README.md b/tools/dump/README.md
index cf46ab1..76e1ad1 100644
--- a/tools/dump/README.md
+++ b/tools/dump/README.md
@@ -5,9 +5,10 @@
Usage example:
-1. start NFD on local machine
-2. create an IPv4 UDP tunnel to a remote machine
-3. cause some traffic going on the tunnel
-4. execute `sudo ndndump`
+1. start NFD on the local machine
+2. create a UDP tunnel to a remote machine
+3. run `sudo ndndump`
+4. cause some NDN traffic to be sent/received on the tunnel
+5. observe the output of `ndndump`
For more information, consult the manpage.
diff --git a/tools/peek/README.md b/tools/peek/README.md
index 79e9832..02e6fb1 100644
--- a/tools/peek/README.md
+++ b/tools/peek/README.md
@@ -8,7 +8,7 @@
Usage example:
1. start NFD
-2. execute `echo 'HELLO WORLD' | ndnpoke /localhost/demo/hello`
-3. in another terminal, execute `ndnpeek -p /localhost/demo/hello`
+2. run `echo 'HELLO WORLD' | ndnpoke /localhost/demo/hello`
+3. in another terminal, run `ndnpeek -p /localhost/demo/hello`
-For more information, consult the manpages of these programs.
+For more information on these programs, consult their respective manpages.
diff --git a/tools/ping/README.md b/tools/ping/README.md
index 0bf3150..1e0f02f 100644
--- a/tools/ping/README.md
+++ b/tools/ping/README.md
@@ -2,47 +2,48 @@
## Introduction
-**ndnping** and **ndnpingserver** are reachability testing tools for
-[Named Data Networking](http://named-data.net). They test the reachability between two nodes. The
-client sends an Interest intended for a node running **ndnpingserver**. The ping server then sends
-Data in response. The client then calculates the roundtrip time for the Interest-Data exchange, or
-marks it as a timeout if the Data is not received within the timeout period.
+**ndnping** and **ndnpingserver** are reachability testing tools for NDN. They can be used
+to test the network reachability between two nodes. The client sends an Interest intended
+for a node running **ndnpingserver**. The server then sends Data in response. The client
+then calculates the roundtrip time for the Interest-Data exchange, or marks it as a timeout
+if the Data packet is not received within the timeout period.
-## Using the Client
+## Using the client
-The client can be invoked by calling **ndnping** with a name to ping. For example, to ping
-`/edu/arizona`, one would execute:
+The client can be invoked by calling `ndnping` with a name to ping. For example, to ping
+`/edu/arizona`, one would run:
ndnping /edu/arizona
-There are also a variety of options to control the behavior of the ping client. For example, to
-send only four pings to `/edu/arizona`, displaying a timestamp with each received Data or
+There are also a variety of options to control the behavior of the ping client. For example,
+to send only four pings to `/edu/arizona`, displaying a timestamp with each received Data or
timeout, type:
ndnping -c 4 -t /edu/arizona
A list of the available options can be found with `man ndnping`.
-## Using the Server
+## Using the server
-The server can be invoked by calling **ndnpingserver** with a name to listen for pings to. For
-example, to listen for pings to `/edu/arizona`, one would execute:
+The server can be invoked by calling `ndnpingserver` with a name to listen for pings to. For
+example, to listen for pings to `/edu/arizona`, one would run:
ndnpingserver /edu/arizona
-There are also a variety of options to control the behavior of the ping server. For example, to
-satisfy only 4 ping requests before exiting, execute the following:
+There are also a variety of options to control the behavior of the ping server. For example,
+to satisfy only 4 ping requests before exiting, run the following:
ndnpingserver -p 4 /edu/arizona
A list of the available options can be found with `man ndnpingserver`.
-## ndnping Protocol
+## NDN ping protocol
This section briefly describes ndnping's protocol, in order to allow alternate implementations
to be compatible with this implementation.
+
The current protocol version is **ndnping protocol version 1**.
-This version number will be incremented in case there's an incompatible change.
+This version number will be incremented whenever there is an incompatible change.
### Probe Interests