Minor README improvements; fix outdated URLs
Change-Id: Ia57f83892471ad85a2301ba4c8ab3df144581000
This commit is contained in:
Davide Pesavento committed
1 parent
3b4ee2f130
commit
db9613e5fd
13 files changed
+115
-108
No files matched your search
+1
-1
@@ -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>
|
||||
|
||||
+5
-7
@@ -4,17 +4,15 @@ This document describes how to build and install ndn-tools.
|
||||
|
||||
## 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:
|
||||
|
||||
|
||||
+29
-27
@@ -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 @@ and placed in the [`manpages`](manpages) directory.
|
||||
## 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 @@ subdirectory.
|
||||
|
||||
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
|
||||
|
||||
|
||||
@@ -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 @@ Please submit any bug reports or feature requests to the
|
||||
|
||||
## 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.
|
||||
+1
-1
@@ -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.
|
||||
|
||||
@@ -15,7 +15,7 @@ and makes it available as NDN Data segments.
|
||||
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
|
||||
-------
|
||||
|
||||
@@ -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 @@ number will be used, without any version discovery process. Otherwise, discovery
|
||||
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 @@ used for version discovery in ndncatchunks, please refer to:
|
||||
* `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`.
|
||||
|
||||
|
||||
@@ -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 @@ On some platforms, it may also be installed in `/usr/share/ndn-dissect-wireshark
|
||||
`/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 @@ Wireshark's `init.lua` script, which located in `/usr/share/wireshark`,
|
||||
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 @@ For more detailed information about how to use Lua refer to [Lua wiki](https://w
|
||||
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
|
||||
|
||||
@@ -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 @@ function getGenericBlockInfo(block)
|
||||
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
|
||||
|
||||
@@ -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 @@ Dissector::printBranches()
|
||||
}
|
||||
}
|
||||
|
||||
// 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"},
|
||||
|
||||
@@ -5,9 +5,10 @@ and displays brief information about captured packets.
|
||||
|
||||
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.
|
||||
@@ -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.
|
||||
+18
-17
@@ -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
|
||||
|
||||
|
||||
Reference in new issue
Block a user