mirror of
https://github.com/apache/nuttx.git
synced 2026-10-11 08:10:21 +00:00
f6ecf80ebb
The documentation grew one page at a time, so the tree follows the
history of who wrote what and not the shape of NuttX. Scheduling is
spread over three places, a driver page can sit above the subsystem
that owns it, and the front page lists everything at the same level.
That is a lot to face when all you want to know is where the scheduler
lives.
This change files every page under the code it describes. It is a move,
not a rewrite: outside the ten pages named below, every page keeps the
text that is already in master, and no page's text is deleted.
What it does:
* Groups the table of contents into nine chapters.
* Moves the OS subsystems under os/: scheduling, memory, drivers,
filesystem, networking, IPC, interrupts, libs, time.
* Renames the platform pages to the names the source tree uses, and
derives their tags from the tree instead of by hand.
* Splits guides/ by subject.
* Adds Documentation/redirects.py, with a rule for every page that left
its old path, so old URLs keep working. The redirect page also carries
a link's #anchor across to the new page.
Ten pages have text that is new or rewritten. Nine of them are the
landing page of a chapter, which has to exist for the new structure:
index the front page
os/index OS Design
os/scheduling/index Scheduling
os/interrupts/index Interrupts
os/ipc/index IPC
os/time/index Time and timers
about/index About
developing/index Developing NuttX
ReleaseNotes/index Release notes
The tenth is os/libs/libbuiltin, the only page here with technical
content: libs/libbuiltin/ had no page at all. Five SVG diagrams come
with these pages, hand-written XML with no editor metadata.
Nothing outside Documentation/ is touched.
How it was checked:
* Sphinx builds with -W: no warnings, and no document left outside a
toctree.
* A script, offered in the PR, proves the narrow claim this rests on.
For every page outside the ten named above it erases what a move
touches -- link target, path, tag line, toctree block, table border --
from the whole old text and the whole new text, and requires the two
to be byte for byte identical. It also requires every sentence of a
deleted page to turn up somewhere, and every page that left its old
path to have a redirect, from a URL that existed, to where its content
went. It exits non-zero and names the page if any of that is not true,
and it tests added pages too, so forgetting to declare one cannot make
it pass.
* An independent audit checked 133 factual claims on these ten pages
against the tree, one shell command per claim: 130 confirmed, 1
refuted and fixed here, 2 not checkable.
* tools/checkpatch.sh is clean over the range.
The diff is large because moving a page changes every link that points
to it. Most of it is pure renames, and board pages that gained one tag
line.
Assisted-by: Claude:claude-opus-5
142 lines
4.2 KiB
ReStructuredText
142 lines
4.2 KiB
ReStructuredText
=============================
|
|
Testing TCP/IP Network Stacks
|
|
=============================
|
|
|
|
When working on the network stack there is a need to test and verify the changes
|
|
made. While problems may be discovered by chance, it is hard to reproduce such
|
|
situations. The following sections show some methods to stress the target or
|
|
generate some specific traffic.
|
|
|
|
In the examples the target has the IP address 192.168.2.135
|
|
|
|
SYN Flood Attack
|
|
================
|
|
|
|
Flood the target with SYN packets to exhaust its resources.
|
|
It's a good way to test the network driver's buffer management.
|
|
|
|
.. code-block:: bash
|
|
|
|
sudo hping3 --flood -S -p 80 192.168.2.135
|
|
|
|
Building Packets with Scapy
|
|
===========================
|
|
|
|
A wonderful network testing tool is the Scapy lib.
|
|
It enables you to build pretty much any packet constellation you need for testing.
|
|
|
|
You have to add an iptables rule to prevent outgoing RST packets from the OS's
|
|
networking stack which does nothing know about our test connection.
|
|
|
|
To disable outgoing RST packets:
|
|
|
|
.. code-block:: bash
|
|
|
|
sudo iptables -A OUTPUT -p tcp --tcp-flags RST RST -d 192.168.2.135 -j DROP
|
|
|
|
For removing the rule:
|
|
|
|
.. code-block:: bash
|
|
|
|
sudo iptables -D OUTPUT -p tcp --tcp-flags RST RST -d 192.168.2.135 -j DROP
|
|
|
|
**Testing Re-transmission behavior**
|
|
|
|
When sending a 3-way handshake only, the target should time out and reset the
|
|
connection.
|
|
|
|
The following Python Scapy script starts a HTTP request without further responding.
|
|
The stack should start re-transmit the packets and finally time out.
|
|
|
|
.. code-block:: python
|
|
|
|
#!/usr/bin/env python
|
|
|
|
import logging
|
|
logging.getLogger("scapy.runtime").setLevel(logging.ERROR)
|
|
from scapy.all import *
|
|
|
|
get = 'GET / HTTP/1.1\r\n\r\n'
|
|
|
|
ip = IP(dst="192.168.2.135")
|
|
port = RandNum(1024, 65535)
|
|
|
|
# Create SYN packet
|
|
SYN = ip/TCP(sport=port, dport=80, flags="S", seq=42)
|
|
|
|
# Send SYN and receive SYN,ACK
|
|
SYNACK = sr1(SYN)
|
|
|
|
# Create ACK with GET request
|
|
ACK = ip/TCP(sport=SYNACK.dport, dport=80, flags="A", seq=SYNACK.ack, ack=SYNACK.seq + 1)
|
|
|
|
# SEND our ACK
|
|
send(ACK)
|
|
|
|
reply, err = sr(ip/TCP(sport=SYNACK.dport, dport=80, flags="A", seq=SYNACK.ack, ack=SYNACK.seq + 1) / get)
|
|
|
|
Simulating Packet Loss
|
|
======================
|
|
|
|
With simulating packet loss one can test the re-transmission behavior of the
|
|
target stack.
|
|
|
|
To start packet loss:
|
|
|
|
.. code-block:: bash
|
|
|
|
# for randomly dropping 10% of incoming packets:
|
|
sudo iptables -A INPUT -m statistic --mode random --probability 0.1 -j DROP
|
|
|
|
# and for dropping 10% of outgoing packets:
|
|
sudo iptables -A OUTPUT -m statistic --mode random --probability 0.1 -j DROP
|
|
|
|
To remove the rules:
|
|
|
|
.. code-block:: bash
|
|
|
|
# for the incoming packets:
|
|
sudo iptables -D INPUT -m statistic --mode random --probability 0.1 -j DROP
|
|
|
|
# and for the outgoing packets
|
|
sudo iptables -D OUTPUT -m statistic --mode random --probability 0.1 -j DROP
|
|
|
|
Fuzz-Testing
|
|
============
|
|
|
|
For fuzz testing network applications the excellent
|
|
`SPIKE <https://www.immunitysec.com/resources-freesoftware.shtml>`_ tool can be
|
|
used. To make it compile under Ubuntu 14.04 LTS you have to add
|
|
``-fno-stack-protector`` to CFLAGS.
|
|
|
|
SPIKE complained about missing SSL libs. I simply linked the existing to the needed
|
|
filenames::
|
|
|
|
/lib/i386-linux-gnu$ sudo ln -s ./libssl.so.1.0.0 ./libssl.so.0
|
|
/lib/i386-linux-gnu$ sudo ln -s ./libcrypto.so.1.0.0 ./libcrypto.so.0
|
|
|
|
Maybe those lib versions aren't the expected by SPIKE but if you don't use SSL
|
|
it works fine.
|
|
|
|
SPIKE provides a proxy server to record requests to your web application. Based
|
|
on these requests a application specific fuzz test can be generated.
|
|
|
|
.. code-block:: bash
|
|
|
|
~/SPIKE/src$ mkdir requests && cd requests
|
|
# Record requests to the target at 192.168.2.135 on port 80
|
|
~/SPIKE/src/requests$ ../webmitm -t 192.168.2.135 -p 80
|
|
|
|
Now use your web application through localhost to record some requests. Then you
|
|
can generate your application-specific fuzz test from the recorded requests.
|
|
|
|
.. code-block:: bash
|
|
|
|
~/SPIKE/src$ ./makewebfuzz.pl ./requests/http_request-1.0 > myfuzz.c
|
|
~/SPIKE/src$ gcc ./myfuzz.c -I../include -o myfuzz -L. -ldlrpc -ldl
|
|
|
|
Now you can fuzz your target:
|
|
|
|
.. code-block:: bash
|
|
|
|
~/SPIKE/src$ LD_LIBRARY_PATH=. ./myfuzz 192.168.2.135 80
|