网络 on cyp0633's Blog

ns-3 入门 5：追踪

Tue, 20 Feb 2024 10:52:00 +0800

根据官方教程 Tracing 一章写成。原示例代码¹和文中代码均以GPLv2发布。

大家都知道仿真的目的是得到有价值的输出以进行分析，但对特定的分析目的来说，不同的输出方式可能分析效率不同。比如使用日志输出，其粒度仅为源代码文件和日志等级，对于更细的控制则略显不足，且日志输出的稳定性不作保证，可能随着更新而更改；而输出pcap可以记录每个数据包的细节，使用Wireshark筛选也更加直观简易，但不能体现仿真过程中的逻辑控制，如之前提到的Wi-Fi STA节点的移动轨迹。如果遇到并非自己代码中想要输出的内容，情况就更复杂了。比如开发者在教程中举了一个例子：为TCP socket添加一点输出，而这需要更改ns-3本身（在 tcp-socket-base.cc 中）。虽然加输出确实很简单，但1) 更新ns-3版本时很麻烦，2) 仍需进行进一步日志筛选，3) 要重新编译ns-3。

所以，使用ns-3的追踪工具是更好的选择，因为它可以只输出感兴趣的数据源，免去筛选的麻烦，并且直接从ns-3内部获取数据（而不用改ns-3的代码）。

基本上，追踪接收器就是一个回调，是一个函数指针。将追踪源和接收器相连的操作，就是把接收器对应的回调传入对应追踪源的回调列表中。当追踪源执行的时候，它就依次执行每个接收器对应的回调。另外，被追踪的值采用值语义²传递，这使得它触发的时候是什么样，追踪出来就是什么样。

在不使用回调的情况下，若A要通过B的函数进行通信，A就必须依赖B。由于追踪接收器有很多，又不能逐个添加依赖，所以通过依赖的办法缺乏灵活性。

简单的示例代码

开发者给出了 fourth.cc¹ 作为入门代码示例。略过头文件部分，代码首先定义了一个 Object 的子类，添加了一个追踪源数据，并实现了 GetTypeId 方法：

cpp

class MyObject : public Object
{
  public:
    /**
     * Register this type.
     * \return The TypeId.
     */
    static TypeId GetTypeId()
    {
        static TypeId tid = TypeId("MyObject")
                                .SetParent<Object>()
                                .SetGroupName("Tutorial")
                                .AddConstructor<MyObject>()
                                .AddTraceSource("MyInteger",
                                                "An integer value to trace.",
                                                MakeTraceSourceAccessor(&MyObject::m_myInt),
                                                "ns3::TracedValueCallback::Int32");
        return tid;
    }
    MyObject()
    {
    }
    TracedValue<int32_t> m_myInt; //!< The traced value.
};

如果真的按照官方教程去走，一定会晕头转向，因为官方教程的路线根本没提到ns-3的对象模型。

ns-3提供了三个基类，Object、ObjectBase 和 SimpleRefCount。SimpleRefCount 具有ns-3智能指针（Ptr）的引用计数，ObjectBase 具有类型（即 GetTypeId 这一堆）和属性信息以及对象聚合（目前没用到）。Object 具有以上两者的所有特性，如 NetDevice 和 TcpSocketState 全部是它的子类。

TypeId 是 Object 的子类可选包含的一个属性，用于存放该类的元数据，如：

标识这个类的唯一字符串（MyObject），用于进行运行时类型推导

父类（Object），用于进行向上/向下类型转换

可用的构造函数，用于在不知道对象具体类型的情况下创建对象

可公开访问属性（attribute）列表，需要同时提供访问方法和边界检查

除了以上四条之外，可以看到 AddTraceSource 方法，用于添加一个追踪源。它的用法有点像 AddAttribute，不同的是1) 由于是内部编辑，所以不需要像attribute一样做边界检查；2) 有一个回调函数，用于在触发时执行。

m_myint 就是被追踪的数据，而 TracedValue 类型用于除了包装 int32_t 之外，还具备在值变化时触发回调的功能，并要求回调函数有且仅有两个 int32_t 参数，分别是旧值和新值。至于 MakeTraceSourceAccessor，则用于连接追踪源和追踪接收器，反正加上就行了。

对应的，IntTrace 函数中就是 MyInteger 追踪源对应的接收回调，没有返回值，有且仅有两个 int32_t 参数，代码简单易懂：

cpp

void
IntTrace(int32_t oldValue, int32_t newValue)
{
    std::cout << "Traced " << oldValue << " to " << newValue << std::endl;
}

最后在 main 函数中，就是创建对象和连接的过程了。

cpp

int
main(int argc, char* argv[])
{
    Ptr<MyObject> myObject = CreateObject<MyObject>();
    myObject->TraceConnectWithoutContext("MyInteger", MakeCallback(&IntTrace));

    myObject->m_myInt = 1234;

    return 0;
}

对于 Object 的子类，应该使用 CreateObject() 函数创建对象实例，对应的也会返回一个 Ptr。而对于 SimpleRefCount 的子类，则使用 Create()。

此处连接使用的并不是示例代码3（third.cc）中使用的 Config::Connect() 搭配绝对路径识别符，而是直接使用 MyObject 的 TraceConnectWithoutContext() 成员函数，这样在第一个参数中就只需要写该类下追踪源的名字而非完整路径了。MakeCallback 的作用这里不再赘述。

此处与示例代码3中另一个显著的不同是后者使用带context的追踪，TraceConnect() 成员函数中第二个参数为 std::string 类型，用来描述上下文（如对象路径），其会作为第一个参数传入回调，而此处使用的 TraceConnectWithoutContext() 就没有。也就是说，如果使用带context的追踪，那么回调函数应该改为 void IntTrace(std::string context, int32_t oldValue, int32_t newValue)。Config::Connect() 和 Config::ConnectWithoutContext() 则都不需要额外传入上下文信息。

使用 `Config` 子系统

虽然这种 TraceConnect() 很实用，但据开发者声称，一般来说都会使用所谓的配置路径选择追踪源，就像之前在示例代码3中一样。也就是说，以下两个部分的代码是等效的：

cpp

// 使用 Config::Connect
std::ostringstream oss;
oss << "/NodeList/" << wifiStaNodes.Get(nWifi - 1)->GetId()
    << "/$ns3::MobilityModel/CourseChange";
Config::Connect(oss.str(), MakeCallback(&CourseChange););

// 使用 TraceConnect
wifiStaNodes.Get(nWifi - 1)->GetObject<MobilityModel>()
    ->TraceConnect("CourseChange", MakeCallback(&CourseChange));

ns-3 入门 4：构建拓扑

Wed, 14 Feb 2024 16:29:00 +0800

根据官方教程 Building Topologies 一章写成。原示例代码¹²和文中代码均以GPLv2发布。

总线拓扑

第二篇示例代码¹描述了一个简单的例子，默认共有5个节点，$n_0$ 和 $n_1$ 通过点对点链路相连，网段为10.1.1.0/24；$n_1$ 到 $n_{i+1}$ 共 ${i+1}$ 个节点（$i$ 为 nCsma 参数的值，默认为3）通过共享介质的CSMA网络连接（有点类似Ethernet），使用10.1.2.0/24网段。其中 $n_1$ 同时连接了两个网络。之后在 $n_0$ 上设置示例代码1一样的echo client，在 $n_{i+1}$ 上设置对应的echo server。

代码大多跟之前的第一个示例没什么不同，只是有了更多的节点和设备。然而还是有一些需要注意的地方：

一个节点可以同时属于多个 NodeContainer，如 $n_1$，这样就方便在同一个节点上设置多个设备了。
NodeContainer.Create 函数会在当前container的基础上增加指定数量的节点，而非用指定数量初始化。
由于不在同一个网段内，两个网段自然是不互通的，于是需要使用 Ipv4StaticRoutingHelper::PopulateRoutingTables() 让所有节点都能充当路由器的功能，并填充路由表。类似于Linux的 sysctl -w net.ipv4.ip_forward=1。
对于 CsmaChannel 之类可以同时连接多个设备的信道，可以在某一节点上启用混杂（promiscuous）模式（如代码113行），这样就可以监听到所有经过该信道的数据包了。

程序一共录制了三个pcap文件。可以看到，在 second-0-0.pcap 和 second-1-0.pcap 中，只有基于点对点协议的UDP包，但在 second-2-0.pcap 中，不光变成了网段不同、基于Ethernet的UDP包，还出现了ARP包，以进行IP到MAC地址的查找。

为了更高的可自定义度，EnablePcap 不仅可以接受网络设备指针（nd: Ptr<NetDevice>），也可以接受节点 ID（nodeid: uint32_t）和设备ID（deviceid: uint32_t）。换而言之，以下两行代码是等效的：

cpp

1
2

csma.EnablePcap("second",csmaDevices.Get(1),true);
csma.EnablePcap("second",csmaNodes.Get(1)->GetId(),0,true);

Get 中输入的参数为节点在该容器中的索引，而非节点ID。节点ID是全局共享、递增的。

模型、属性和现实

在官方教程的对应章节中，主要是想提醒使用者须清楚认识到建模并不一定能涵盖真实情况的所有方面。比如上一节中 CsmaChannel 相对于真实Ethernet³ 来说并没有碰撞检测特性，而这是很容易被使用者忽略的。

另外作者还提到了不同网络标准中的不同属性。比如Ethernet的常见最大包大小为1518字节，而由于Ethernet II（DIX）标准的封装方式比IEEE 802.2（LLC/SNAP）的协议开销少8个字节⁴，所以前者允许的最大MTU可以高一点。在ns-3的 CsmaNetDevice 中，MTU和封装方式是两个单独的属性，若采用了后者的封装方式而忘了更改默认为1500的MTU，虽然模拟能够正常运行，但可能会偏离实际情况。

这里不是说MTU=1500同时采用LLC/SNAP一定是错的，现代部分网络甚至允许MTU=9000的Jumbo Frame，最终一切还是要看具体情况。

构建无线拓扑

这一段的示例代码²在第二篇代码中增加了一个无线网络，并连接到 $n_0$，Wi-Fi使用802.11a标准（有点远古），网段为10.1.3.0/24。随附示例代码中描述拓扑的字符画：

cpp

// Default Network Topology
//
//   Wifi 10.1.3.0
//                 AP
//  *    *    *    *
//  |    |    |    |    10.1.1.0
// n5   n6   n7   n0 -------------- n1   n2   n3   n4
//                   point-to-point  |    |    |    |
//                                   ================
//                                     LAN 10.1.2.0

在上面总线拓扑的基础上，又添加了 YansWifiChannel，相对来说更复杂一点，但从始至终都是围着链路层和物理层工作。

$n_0$ 作为AP，其他节点作为STA，分到两个 NodeContainer 中。
使用 YansWifiPhyHelper 来设置物理层属性，如频率、速率等。它承担了类似 CsmaHelper 的功能，只不过不能直接包办建立起信道和安装网络设备了。
通过 WifiMacHelper 区分AP和STA，并设置同一个SSID来确保连接同一个网络。
AP和STA的网络设备也有所不同，所以也包含在两个 NetDeviceContainer 中，但可以使用同一个 WifiHelper（用于安装网络设备）。
通过 MobilityHelper 模拟STA节点走来走去，而AP节点则固定在原地。
用同一个 Ipv4AddressHelper 在同一次 Setbase 之后多次 Assign 来保证AP和STA在同一个网段内（相当于使用固定IP，不考虑复杂的DHCP）。

在STA节点的链路层设置中（WifiMacHelper），可以看到设置了 ActiveProbing 属性，这使得STA节点会一直搜寻AP，导致仿真永远不会结束。因此，还需要在开始前手动设置10s结束仿真。

并不需要对Wi-Fi网络启用混杂模式，因为Wi-Fi网络的数据包都是广播的，所以所有节点都能收到。换而言之，混杂模式是自动开启的。

如果加上 --trace 参数，会记录下来4个文件，其中 third-0-1.pcap 对应的是Wi-Fi的流量。使用工具读取，可以看到相比Ethernet，Wi-Fi的通信更加复杂，还有beacon frame之类的控制信息。

记录STA移动轨迹

之前在介绍跟踪时，并未明确跟踪接收器的设计办法，使用的也是helper自带的连接方式。而在这个示例代码中，为了追踪某个STA的移动轨迹并打印到日志中，需要自行设计跟踪接收器（其实就是一个函数），并设置回调。这里的跟踪接收器也只是个函数而已：

cpp

void
CourseChange(std::string context, Ptr<const MobilityModel> model)
{
  Vector position = model->GetPosition();
  NS_LOG_UNCOND(context <<
              " x = " << position.x << ", y = " << position.y);
}

其实功能非常简单，就是当调用这个函数的时候，打印出对应的事件名（context），以及STA节点的位置。为了让节点位置变化时调用这个函数，需要在 Simulator::Run() 之前设置回调：

cpp

std::ostringstream oss;
oss << "/NodeList/" << wifiStaNodes.Get(nWifi - 1)->GetId()
    << "/$ns3::MobilityModel/CourseChange";
auto cb = MakeCallback(&CourseChange);
Config::Connect(oss.str(), cb);

Config::Connect() 的第一个参数就是事件名，也就是跟踪源的路径，这里仅指定了一个STA。第二个参数就是一个回调对象。

MakeCallback 的作用是将函数指针包装成一个 Callback 对象。Callback 类是一个模板类，有一个强制参数（对应返回值，void也算一个）和至多五个可选参数（对应参数列表）。MakeCallback 会根据函数指针的类型自动推断参数列表。这样，就可以直接使用类似 ret = cb(arg1, arg2, ...) 的方法来调用回调了。如果需要设置对象的成员函数回调，或者希望预先设定某几个参数，可以参考手册的对应部分。

这样，当STA位置变化时，就会在日志中打印当前位置，如：

plaintext

/NodeList/7/$ns3::MobilityModel/CourseChange x = 10, y = 0
/NodeList/7/$ns3::MobilityModel/CourseChange x = 9.36083, y = -0.769065
/NodeList/7/$ns3::MobilityModel/CourseChange x = 9.62346, y = 0.195831
/NodeList/7/$ns3::MobilityModel/CourseChange x = 9.42533, y = 1.17601
/NodeList/7/$ns3::MobilityModel/CourseChange x = 8.4854, y = 0.834616
/NodeList/7/$ns3::MobilityModel/CourseChange x = 7.79244, y = 1.55559
/NodeList/7/$ns3::MobilityModel/CourseChange x = 7.85546, y = 2.55361

ns-3中的队列

和很多人理解的不同，数据包并不是排一个队就能直接发出去了，而在实际情况中，有多层队列，排完这个再排下一个，用来处理不同的事情。在ns-3中虽然并没有实际操作系统中那么复杂，但也“将IP层或流量控制层与设备层分开”，前者，即所谓的流量控制层，处理QoS和AQM；而后者在 NetDevice 中，处理设备层的队列，与连接类型有关（Ethernet，Wi-Fi等）。如果设备层的队列并没有被填满，那么流量控制层队列基本等效于透明，毕竟这时并没有控制流量的必要。

官方教程中有 [不同队列类型详解]。在分配IP地址时，流量控制层默认启用 pfifo_fast 队列（容量为1000个包）并可以自行指定，而设备层队列由设备自身决定，不同的网络设备有不同的队列类型。

若要自行指定流量控制层的队列，有两种办法。如果还未安装网络设备，可以借助网络设备的helper实现：

cpp

1
2
3

PointToPointHelper p2p;
p2p.SetQueue("ns3::DropTailQueue", "MaxSize", StringValue("50p"));
NetDeviceContainer devices = p2p.Install(nodes);

如果已经安装了网络设备，可以使用 TrafficControlHelper 来设置根队列：

cpp

1
2
3

TrafficControlHelper tch;
tch.SetRootQueueDisc("ns3::CoDelQueueDisc", "MaxSize", StringValue("1000p"));
tch.Install(devices);

https://gitlab.com/nsnam/ns-3-dev/-/blob/2209a5abd18be77c6c865c837368b4e459ae7c8e/examples/tutorial/second.cc ↩︎ ↩︎
https://gitlab.com/nsnam/ns-3-dev/-/blob/5649b4801cc3e06b8d0edc9ea1b18510594dfd35/examples/tutorial/third.cc ↩︎ ↩︎
早期的共享介质Ethernet标准使用CSMA/CD，而非CSMA。 ↩︎
https://en.wikipedia.org/wiki/Ethernet_frame#Types ↩︎

ns-3 入门 3：日志、命令参数和跟踪

Sat, 03 Feb 2024 12:18:00 +0800

根据官方教程 Tweaking 一章写成。

日志

ns-3自带一个日志系统。用日志系统记录输出和错误等是常见的做法，但由于追踪系统的存在（可以使用tcpdump或者Wireshark看），日志系统还是用来记录错误和调试信息为主。

前面讲到ns-3的日志系统粒度为模块，可以对某个模块启用、禁用、设置级别等。

日志级别

日志系统有以下几个级别：

LOG_ERROR：错误
LOG_WARN：警告
LOG_DEBUG：临时的调试信息
LOG_INFO：程序运行进度等信息
LOG_FUNCTION：函数调用信息
LOG_LOGIC：函数内部的逻辑执行
LOG_ALL：包含以上所有

LOG_FUNCTION 等级会在每个函数执行时打印信息，比如下面这样。

log

UdpEchoClientApplication:UdpEchoClient(0xef90d0)
UdpEchoClientApplication:SetDataSize(0xef90d0, 1024)
UdpEchoClientApplication:StartApplication(0xef90d0)
UdpEchoClientApplication:ScheduleTransmit(0xef90d0, +0ns)
UdpEchoClientApplication:Send(0xef90d0)

需要注意以上每种日志级别仅包含其本身。若要包含上级日志，则可使用对应的 LOG_LEVEL。如 LOG_LEVEL_DEBUG 是 LOG_ERROR、LOG_WARN、LOG_DEBUG 三者的并集，皆会打印。

另外还有一种 LOG_UNCOND 级别，会打印任何日志条目，无视等级。

设置级别

有两种办法对模块日志级别进行设置：环境变量和代码。环境变量设置不需要重新编译，所以比较方便。官方教程提到可以用环境变量“提高日志记录级别”，实际测试发现最终输出的日志范围是对两者取并集（包括下文的日志前缀部分）。

如果使用代码，需要使用 LogComponentEnable 函数，若要设置多个模块的日志级别，多次调用该函数即可。比如将 UdpEchoClientApplication 的日志级别设为 INFO：

cpp

`1`	`LogComponentEnable("UdpEchoClientApplication", LOG_LEVEL_INFO);`

如果只想要启用某个模块的自定义等级日志，可以使用并运算：

cpp

`1`	`LogComponentEnable("UdpEchoClientApplication", LogLevel(LOG_INFO \| LOG_FUNCTION));`

而控制日志级别的环境变量是 NS_LOG，虽然只有一个变量，但使用和PATH类似的表示方法，也可以控制多个模块的级别，其值的格式为 Component1=level_1:Component2=level_2。比如：

bash

`1`	`export NS_LOG="UdpEchoClientApplication=level_all:UdpEchoServerApplication=level_all"`

环境变量表示的并运算会更加直观些：

bash

`1`	`export NS_LOG="UdpEchoClientApplication=level_info\|level_function"`

如果需要设置所有模块的日志级别，可以将 * 作为 Component 的值。需注意该选项会导致大量输出。

日志前缀

回想第一个示例代码的输出，前面的日志输出的几乎都只有内容。比如之前那个示例程序，在启用所有日志等级时，输出是这样的：

log

UdpEchoServerApplication:UdpEchoServer(0x55fd771b1b10)
UdpEchoClientApplication:UdpEchoClient(0x55fd771d9570)
UdpEchoClientApplication:SetDataSize(0x55fd771d9570, 1024)
UdpEchoServerApplication:StartApplication(0x55fd771b1b10)
UdpEchoClientApplication:StartApplication(0x55fd771d9570)
UdpEchoClientApplication:ScheduleTransmit(0x55fd771d9570, +0ns)
UdpEchoClientApplication:Send(0x55fd771d9570)
At time +2s client sent 1024 bytes to 10.1.1.2 port 9
UdpEchoServerApplication:HandleRead(0x55fd771b1b10, 0x55fd771e5e70)
At time +2.00369s server received 1024 bytes from 10.1.1.1 port 49153
Echoing packet
......

日志前缀内容可以和日志输出等级一起设定，目前有如下几个选项¹：

PREFIX_FUNC：函数名（格式为 ComponentName:FunctionName）
PREFIX_TIME：仿真已进行的时长
PREFIX_NODE：节点编号（就是之前关键抽象中的那个节点）
PREFIX_LEVEL：日志等级

也可以用 PREFIX_ALL 一次性打开所有前缀。以使用代码的方式为例，可以这样设置：

cpp

    LogComponentEnable("UdpEchoClientApplication",
                       LogLevel(ns3::LOG_LEVEL_ALL | ns3::LOG_PREFIX_ALL));
    LogComponentEnable("UdpEchoServerApplication",
                       LogLevel(ns3::LOG_LEVEL_ALL | ns3::LOG_PREFIX_ALL));

输出便成了这样：

log

+0.000000000s -1 UdpEchoServerApplication:UdpEchoServer(0x55b8911fcb10)
+0.000000000s -1 UdpEchoClientApplication:UdpEchoClient(0x55b891224570)
+0.000000000s -1 UdpEchoClientApplication:SetDataSize(0x55b891224570, 1024)
+1.000000000s 1 UdpEchoServerApplication:StartApplication(0x55b8911fcb10)
+2.000000000s 0 UdpEchoClientApplication:StartApplication(0x55b891224570)
+2.000000000s 0 UdpEchoClientApplication:ScheduleTransmit(0x55b891224570, +0ns)
+2.000000000s 0 UdpEchoClientApplication:Send(0x55b891224570)
+2.000000000s 0 UdpEchoClientApplication:Send(): [INFO ] At time +2s client sent 1024 bytes to 10.1.1.2 port 9
+2.003686400s 1 UdpEchoServerApplication:HandleRead(0x55b8911fcb10, 0x55b891230e70)
+2.003686400s 1 UdpEchoServerApplication:HandleRead(): [INFO ] At time +2.00369s server received 1024 bytes from 10.1.1.1 port 49153
+2.003686400s 1 UdpEchoServerApplication:HandleRead(): [LOGIC] Echoing packet
......

记录日志

要将某个源文件划入某个模块，可以使用这个宏：

cpp

`1`	`NS_LOG_COMPONENT_DEFINE("ComponentName");`

对于 LOG_FUNCTION 级别的日志，可以使用 NS_LOG_FUNCTION(this)（静态函数使用 NS_LOG_FUNCTION_NOARGS()），它会在函数开始时打印函数名和参数，函数结束时打印函数名和返回值。而对于其他级别的日志，可以使用 NS_LOG_<LEVEL>，如：

cpp

1
2

NS_LOG_INFO("This is an info message");
NS_LOG_DEBUG("This is a debug message");

命令参数

ns-3也有一个自带的命令行参数解析器，从而避免手动解析或使用第三方库的麻烦。在 main 函数传入了 argc 和 argv 的情况下，可以使用 CommandLine 类来解析命令行参数：

cpp

1
2

CommandLine cmd;
cmd.Parse(argc, argv);

要使用 ns3 工具运行时加入命令行参数，可以用下面两种等效的方式：

bash

1
2

./ns3 run examples/tutorial/first.cc -- --PrintHelp
./ns3 run "examples/tutorial/first.cc --PrintHelp"

当然直接加参数也问题不大，会提示更正的。

自带参数

这个参数解析器自带了一些参数，可以通过 --PrintHelp 查看（竟然不是 --help，奇怪）。比如 --PrintAttributes=<TypeId> 可以查看某一类型附带的参数，以及各自的默认值。比如在第一个示例代码中，PointToPointChannel 的默认参数为：

bash

$ ./ns3 run examples/tutorial/first.cc -- --PrintAttributes=ns3::PointToPointChannel
Attributes for TypeId ns3::PointToPointChannel
    --ns3::PointToPointChannel::Delay=[+0ns]
        Propagation delay through the channel
Attributes defined in parent class ns3::Channel
    --ns3::Channel::Id=[0]
        The id (unique integer) of this Channel.

这个和我们在文档中看到的是一致的，默认增加0ns的延迟，但在代码中增加了2ms，覆盖了默认值。但--PrintHelp 并没有提到的是，也可以用命令行参数改变这些默认值。比如，在删除代码中设置链路延迟的部分之后，可以使用以下参数将其值改为100ms：

bash

`1`	`./ns3 run examples/tutorial/first.cc -- --ns3::PointToPointChannel::Delay=100ms`

上面“改变默认值”可以理解为：对于一个属性值，设定的优先级为代码设定值>命令行参数设定值>默认值。更高的优先级会完全覆盖低优先级的值。

自定义参数

当然也可以引入自定义的参数，通过 cmd.AddValue 添加。比如在第一个示例代码中，添加一个 --nPackets 参数，用于设置发送的数据包数量：

cpp

1
2

uint32_t nPackets = 1;
cmd.AddValue("nPackets", "Number of packets to send", nPackets);

然后在后面设置 MaxPackets attribute时传入 nPackets 即可。这样也可以避开命令行参数优先级的问题。

跟踪

模拟的全部目的是生成输出以供进一步研究，而ns-3跟踪系统是实现这一目标的主要机制。

—— ns-3文档

ns-3的跟踪功能，我划分为三个部分：

跟踪源 (trace source)：在仿真的某些阶段触发，并发送某些内部数据（如数据包内容）
跟踪接收器 (trace sink)：接收跟踪源发出的数据
前两者之间的连接

将跟踪源和跟踪接收器分开，可以在不改变跟踪源的情况下，更改接收方式（如新增一个接收器）。在这篇开发者给出的教程中，将会使用一些自带的跟踪源和接收器；后面开发者还写了一篇更加详细的教程，以介绍更加复杂的跟踪用法。

ASCII跟踪

ns-3自带一个ASCII跟踪的helper以帮助设置，在前面第一个示例代码中，可以像这样修改：

cpp

1
2
3

AsciiTraceHelper ascii;
pointToPoint.EnableAsciiAll(ascii.CreateFileStream("myfirst.tr"));
Simulator::Run();

然后重新运行一遍，你就会在shell的工作目录中看到一个 myfirst.tr 文件。里面有6行一长串数据，我们拿出第一行，进行一下换行拆分：

plaintext

+ 
2 
/NodeList/0/DeviceList/0/$ns3::PointToPointNetDevice/TxQueue/Enqueue 
ns3::PppHeader (Point-to-Point Protocol: IP (0x0021)) 
ns3::Ipv4Header (tos 0x0 DSCP Default ECN Not-ECT ttl 64 id 0 protocol 17 offset (bytes) 0 flags [none] length: 1052 10.1.1.1 > 10.1.1.2) 
ns3::UdpHeader (length: 1032 49153 > 9) 
Payload (size=1024)

第一行的 + 代表入队操作。每条跟踪数据的第一个字符会有四种可能：

+：设备队列上入队
-：设备队列上出队
d：丢包（dropped），可能是因为队列满了
r：从外部接收

第二行的 2 代表模拟进行时刻。第三行描述了该行为的发起者，即节点0上的设备0发送队列进行入队，也就是节点0准备发送数据了。后面的几行可以参照Internet的分层模型，分别是链路层的PPP头、网络层的IPv4头、传输层的UDP头和应用层的数据。

PCAP跟踪

PCAP相对上面的ASCII来说就友好多了，毕竟我们可以用Wireshark打开。类似于ASCII跟踪，PCAP跟踪可以这样应用于第一个示例代码：

cpp

1
2

pointToPoint.EnablePcapAll("myfirst");
Simulator::Run();

这次会在shell的工作目录下，对每个节点和网络设备生成一个 pcap 文件。tcpdump的用法这里就不介绍了，Wireshark则可以直接打开，就像用它抓的包一样。

https://www.nsnam.org/docs/doxygen/d7/d2e/namespacens3.html#aa6464a4d69551a9cc968e17a65f39bdb ↩︎

ns-3 入门 2：概念与第一个示例

Sat, 27 Jan 2024 22:57:00 +0800

本文根据官方教程 Conceptual Overview 一章写成。在这章中，教程通过一个代码示例，演示了ns-3的几大基本概念及其基本使用方法。但是个人觉得顺序比较难懂，所以对其进行了一定程度的重新组织。

下文中代码经过一点点修改，原代码见¹，代码均以GPLv2发布。

概念

节点 Node

计算机网络可以抽象为一个图，而一个节点就是其中的一个网络设备。该抽象不考虑网络设备的内部结构与功能，所以路由器（3层）、交换机（2层）、计算机均抽象为节点。因此，节点本身没有任何功能，也不能直接连接任何信道，仅代表一个能收发数据的事物，功能需要作为应用实现，信道通过设备连接。

节点使用 ns3::Node 类表示，并由 ns3::NodeContainer 类管理。要创建指定数量的节点，可以用 Create 实例方法。以下代码创建了两个节点，并将其存储在 nodes 中：

cpp

1
2

NodeContainer nodes;
nodes.Create(2);

要使用下标访问 NodeContainer 中的节点，可以用 Get 实例方法。以下代码访问了第一个节点（下标从0开始）：

cpp

`1`	`Ptr<Node> node = nodes.Get(0);`

上述代码中的 Ptr<T> 是ns-3提供的智能指针，能够自动解引用，效果类似于 std::shared_ptr<T>。类型 T 必须支持 Ref() 和 Unref() 方法。关于ns-3的内存管理机制，请看这一段。

为了使光秃秃的节点具备一些基本的网络通信功能（实际上属于应用），可以使用 ns3::InternetStackHelper 安装网络栈（包含TCP、UDP、IP等）。一个helper可以一次安装一整个 NodeContainer，如以下代码将 nodes 中的所有节点安装网络栈：

cpp

1
2

InternetStackHelper stack;
stack.Install(nodes);

由于并没有变量上的依赖关系，缺少网络栈并不会造成编译失败，但以示例代码为例，缺少网络栈会导致运行时创建更上层的应用失败，从而直接抛出SIGABRT。

网络设备 Net Device

正如电脑要上网就得插网卡（NIC）一样，节点要连接在一起，网络设备是不可或缺的。ns-3中的网络设备抽象包含了网卡的硬件功能和驱动程序功能，每个节点可以连接多个网络设备，用于连接多个不同的信道。

网络设备使用 ns3::NetDevice 类表示，并使用 ns3::NetDeviceContainer 进行管理。同样正如网卡分为有线和无线网卡一样，实际使用时多选择其子类，如以太网使用的 ns3::CsmaNetDevice 类，以及Wi-Fi使用的 ns3::WifiNetDevice 类。在该篇示例代码中，由helper总揽网络设备和信道的创建，此处按下不表。

给网络设备分配IPv4地址后，可以将其看作一个接口。使用 ns3::Ipv4AddressHelper 类，可以为一个网络设备分配一个IPv4地址。以下代码设置了IP地址分配范围和掩码，并将其按顺序分配给一个 NetDeviceContainer 中的设备，返回的是一个接口容器 ns3::Ipv4InterfaceContainer：

cpp

1
2
3

Ipv4AddressHelper address;
address.SetBase("10.1.1.0", "255.255.255.0");
Ipv4InterfaceContainer interfaces = address.Assign(devices);

此处使用了多个隐式转换，从 const char* 即字符串描述的地址到 Ipv4Address 和 Ipv4Mask。如果不希望从10.1.1.1开始分配，可以使用第三个参数 base，如 “0.0.0.3” 表示从10.1.1.3开始分配²。

信道 Channel

信道代表节点之间的连接，比如RJ45双绞线，比如Wi-Fi，都可以抽象为信道。

信道使用 ns3::Channel 类表示，并由 ns3::ChannelContainer 类管理。同样，信道也有多种类型，如以太网使用的 ns3::CsmaChannel 类，Wi-Fi使用的 ns3::WifiChannel 类。但是在本篇示例代码中，并没有明确地使用 Channel，而是借助了网络设备和信道的紧密联系，由helper类统一创建。比如在下面的代码中，新建了一个点对点信道，设置两端网络设备传输速率为5 Mbps，信道延迟2 ms，并将其安装到一个 NodeContainer 中，最终返回创建完成的网络设备 NetDeviceContainer：

cpp

PointToPointHelper pointToPoint;
pointToPoint.SetDeviceAttribute("DataRate", StringValue("5Mbps"));
pointToPoint.SetChannelAttribute("Delay", StringValue("2ms"));
auto devices = pointToPoint.Install(nodes);

属性（attribute）相比于普通的成员变量，具有更多的控制，如可以设置默认值（包括编译期和运行期）、边界检查等。关于更多属性信息，请看这一段。

点对点信道限制输入的 NodeContainer 必须有且仅有两个节点，否则运行时会抛出异常。

这里设置的网络设备属性和信道属性，应该参考具体的网络设备³和信道类⁴的文档。

信道的延迟，就是propagation delay。

应用 Application

节点的实际功能均由应用实现。这是一个庞大的概念，不仅仅包含应用层的内容，也同时包含了传输层、网络层等内容。它描述了某个节点的行为。

应用使用 ns3::Application 类表示，并由 ApplicationContainer 类管理。该container的具体创建由具体的应用程序实现。使用 Start 和 Stop 实例方法，可以控制应用的开始结束时间，仿真程序在所有应用运行结束之前不会主动停止：

cpp

1
2
3

ApplicationContainer serverApps = xxx;
serverApps.Start(Seconds(1.0));
serverApps.Stop(Seconds(10.0));

在示例代码中，具体使用了 ns3::UdpEchoClientApplication 和 ns3::UdpEchoServerApplication 类，作用应该不言而喻。UdpEchoServerApplication 使用 ns3::UdpEchoServerHelper 类创建，如以下代码在第二个节点上安装，设置端口为9，并在1-10s运行：

cpp

UdpEchoServerHelper echoServer(9);
ApplicationContainer serverApps = echoServer.Install(nodes.Get(1));
serverApps.Start(Seconds(1.0));
serverApps.Stop(Seconds(10.0));

这里包含一个隐式转换。nodes.Get(1) 返回的是 Ptr<Node>，而 Install 方法接受的是 NodeContainer，但是 Ptr<Node> 可以隐式转换为 NodeContainer。

负责主动发送数据的 UdpEchoClientApplication 与上文的helper类似，但有更多的参数可供自定义。如以下代码，将第二个节点的端口9作为目标，设置发送间隔为1s、包大小为1024B、发送总数为1⁵，安装到第一个节点上，并在2-10s运行：

cpp

UdpEchoClientHelper echoClient(interfaces.GetAddress(1), 9);
echoClient.SetAttribute("MaxPackets", UintegerValue(1));
echoClient.SetAttribute("Interval", TimeValue(Seconds(1.0)));
echoClient.SetAttribute("PacketSize", UintegerValue(1024));
ApplicationContainer clientApps = echoClient.Install(nodes.Get(0));
clientApps.Start(Seconds(2.0));
clientApps.Stop(Seconds(10.0));

代码示例

使用ns-3编写的仿真器程序是声明式而非命令式的，这有点类似于前端工程中兴起的类似概念。

头文件

ns-3提供了一些大粒度的头文件，可以一定程度上免去繁琐的找头文件过程。下面头文件的内容，基本就是示例代码中用到的模块。

cpp

#include "ns3/core-module.h"
#include "ns3/network-module.h"
#include "ns3/internet-module.h"
#include "ns3/point-to-point-module.h"
#include "ns3/applications-module.h"

日志

ns-3的日志是可以按照模块自定义的，当然这也需要自行为代码划分模块。如示例代码中的这一行macro就是将当前源文件划分到 FirstScriptExample 模块：

cpp

`1`	`ns3::NS_LOG_COMPONENT_DEFINE("FirstScriptExample");`

如果需要控制日志的详细程度，可以使用（如将 UdpEchoClientApplication 的日志级别设为 INFO）

cpp

`1`	`ns3::LogComponentEnable("UdpEchoClientApplication", LOG_LEVEL_INFO);`

命名空间

正如上文提到的，本代码示例中使用的类几乎均在 ns3 命名空间下。

模拟器

当上文模拟器所需执行的行为全部描述完毕后，就需要调用模拟器进行模拟了。这个示例代码的模拟是有穷尽的，所以可以等待模拟自行结束，然后直接销毁：

cpp

1
2

Simulator::Run();
Simulator::Destroy();

但是，如果模拟永远不会结束，或是希望自定义一个结束时间，则需要在 Run() 之前调用 Stop()，如以下代码将模拟时间限制在10s：

cpp

1
2
3

Simulator::Stop(Seconds(10.0));
Simulator::Run();
Simulator::Destroy();

编译

教程中提到的 ./ns3 build 大概率是错的，个人猜测是之前 ./waf 直接查找替换后的产物⁶。现在不必将文件移至 scratch/ 中，如本例子可以直接执行：

bash

`1`	`./ns3 run examples/tutorial/first.cc`

ns-3 入门 1：介绍与安装

Fri, 26 Jan 2024 22:57:00 +0800

根据官方教程 Getting Started 一章写成。

介绍

ns-3是一个离散网络事件模拟器。不难理解这个描述：比如改变拥塞窗口大小，发出数据包，都是离散事件。将这些离散事件按发生时间顺序模拟，就能得到这个系统在一段时间内的运行过程。因为计算机网络（也有其他一些类似系统）的运行过程是离散的，而不像往水池里倒水那样连续的，所以这种模拟方法是合理的。

ns-3本质上是一组库，可以在C++（或Python，但之后忽略）程序中导入，也就是自己写代码把ns-3提供的工具串成一个完整的模拟程序。通过手动导入头文件和链接库，当然也可以直接利用ns-3编译出需要的程序，但ns-3也提供了 ns3 命令行工具，以构建并运行模拟源代码。

下载

ns-3的分发形式是源代码，无论发行版是否有打包，都推荐使用源代码安装。以下仅以Linux为例，Windows用户自觉去装WSL2。

如果你使用Ubuntu，则可以参考官方文档的对应部分¹先按需安装好依赖；如果你和我一样使用的是Arch Linux，那么有一个 PROTECTED_0 AUR 包。但个人不建议你直接装它，因为上文提到的 ns3 命令行工具会留在源代码目录里，无法直接引用。所以可以利用AUR装依赖。Arch Linux的cppyy（用于写Python仿真程序）已更新至3.x，ns-3还没跟上支持，如有需要请注意。

然后从官网下载最新源码包，解压，进入里面的 ns-3.xx 目录。下文均基于3.40版本，此处暂时不提另外两种使用Bake和Git的方法。

编译

官方在文档里给了三种编译方式：

使用 build.py：比较简单，但不太自由
使用CMake：能自定义编译的模块，以及一些额外的选项
使用Bake：好处就是可以包揽从下载到安装

个人需要在之后将ns-3安装至系统目录，而其限定只能用第二种方法，所以下面只写第二种。

ns3 命令行工具也可以作为CMake的一个wrapper。在 ns-allinone-3.xx/ns-3.xx 目录中，运行以下命令：

bash

1
2
3

./ns3 clean
./ns3 configure --enable-tests --enable-examples --prefix=/usr/local
./ns3 build

其中 configure 的前两个参数是一起编译测试和示例，--prefix 指定之后的安装路径。完整的参数列表可以使用 ./ns3 configure --help 查看。

还需要注意configure完成后显示的build profile。如果在之后使用时需要使用GDB调试，则需确保其为 debug （加入 -d debug参数并重新编译），如不需调试，则可以使用默认的 optimized。

只要不是缺少非必需的依赖，编译都会正常进行。CMake也会输出各个模块是否会被编译，以及不被编译的原因（如果有；如缺少依赖，或用户指定不编译）。官方文档中有示例的编译输出，可以结合来看。

编译完成后，可以运行测试：

bash

`1`	`./test.py`

到这里编译过程就结束了。由于 ns3 命令行工具的存在，写程序时不需要太关注库和头文件的位置，同时为了防止多个ns-3版本共存冲突，开发者声称大部分人并不需要安装了：

Most users do not install ns-3 libraries to typical system library directories; they instead just leave the libraries in the build directory, and the ns3 Python program will find these libraries.

安装

虽然 ns3 命令行工具能够帮助构建系统找到头文件和链接库，但麻烦的是IDE并不这么认为（clangd自定义就比较麻烦），所以我决定将其安装到系统目录中。前面提到我添加了 --prefix=/usr/local，在这一步ns-3的头文件和链接库就会被分别安装到 /usr/local/include/ns3 和 /usr/local/lib。

根据文档，安装也需使用 ns3 命令行。但是 ns3 命令行工具会故意阻止以root权限执行，确有需要的可以编辑其约1400行处，删掉对 refuse_run_as_root() 的调用²。但也有副作用，比如之后每次构建运行仿真程序都要输入密码。在此希望读者也能够对自己的目的和行为有明确的认知。

然后，执行 ./ns3 install 即可将ns-3的头文件和链接库安装至prefix指定的位置。

如果只是为了IDE识别，当然也有另外一种方法，仅把头文件复制到系统目录中。头文件就在 build/include/ns3 目录中。

安装完成后，下一篇将顺着官方教程的脉络，认识一个仿真程序的示例。

网络 on cyp0633's Blog

ns-3 入门 5：追踪

简单的示例代码

使用 Config 子系统

ns-3 入门 4：构建拓扑

总线拓扑

模型、属性和现实

构建无线拓扑

记录STA移动轨迹

ns-3中的队列

ns-3 入门 3：日志、命令参数和跟踪

日志

日志级别

设置级别

日志前缀

记录日志

命令参数

自带参数

自定义参数

跟踪

ASCII跟踪

PCAP跟踪

ns-3 入门 2：概念与第一个示例

概念

节点 Node

网络设备 Net Device

信道 Channel

应用 Application

代码示例

头文件

日志

命名空间

模拟器

编译

ns-3 入门 1：介绍与安装

介绍

下载

编译

安装

使用 `Config` 子系统