mirror of
https://gitlab.com/prpl-foundation/prplmesh/stationsniffer.git
synced 2025-12-20 02:20:31 +08:00
Add README.md, CONTRIBUTING.md, and LICENSE
Remove deprecated BUILDING.md Signed-off-by: Tucker Polomik <t.polomik@cablelabs.com>
This commit is contained in:
Tucker Polomik
11
BUILDING.md
11
BUILDING.md
@@ -1,11 +0,0 @@
|
||||
### Build:
|
||||
|
||||
`git submodule update --init --recursive`
|
||||
|
||||
`cd radiotap-library; mkdir -p build; cd build; cmake ..; make`
|
||||
|
||||
`g++ -std=c++17 main.cpp -lpcap -lradiotap -L./radiotap-library/build/ -o pcap`
|
||||
|
||||
### Running:
|
||||
|
||||
`sudo LD_PRELOAD=./radiotap-library/build/libradiotap.so ./pcap <interface> <packet_cadence (mS)>`
|
||||
83
CONTRIBUTING.md
Normal file
83
CONTRIBUTING.md
Normal file
@@ -0,0 +1,83 @@
|
||||
# Introduction
|
||||
|
||||
Thanks for considering making a contribution to this project! Whether it's a code change or a bug report, everything helps!
|
||||
|
||||
[[_TOC_]]
|
||||
|
||||
## How can I contribute?
|
||||
|
||||
### Reporting Bugs
|
||||
|
||||
This section guides you through reporting a bug against StationSniffer.
|
||||
Follow these guidelines to help developers understand your bug report, reproduce the observed behavior, and find related bug reports.
|
||||
|
||||
#### Before Submitting a Bug Report
|
||||
|
||||
First, check the project's [Jira](https://prplfoundationcloud.atlassian.net/jira/software/c/projects/PPM/issues/) bug list to see if the bug you want to report is already being tracked.
|
||||
|
||||
#### Submitting a Good Bug Report
|
||||
|
||||
Either contact the developers directly (see `#contact` in the `README.md`) or [file a bug report on the project's Jira page](https://prplfoundationcloud.atlassian.net/jira/software/c/projects/PPM/issues/)
|
||||
|
||||
Be sure to include as much detail as you can. A list of things to consider including:
|
||||
|
||||
- build tools and versions used to build the project (if you built it from source), OR a link to where you found a pre-compiled binary.
|
||||
- An MD5 checksum of the binary
|
||||
- A thorough description of the behavior you're reporting
|
||||
- Workarounds you tried that either helped or hurt
|
||||
- Backtraces or log files where applicable
|
||||
|
||||
#### An example 'good' bug report
|
||||
|
||||
```
|
||||
BUG: radiotap_parse.cpp: unaligned access leads to garbage data.
|
||||
- Doing a 16 bit unaligned read in the middle of the radiotap buffer causes the channel number information to be read and reported incorrectly
|
||||
We should see channel 1 (2.4GHz) but instead we see channel 2314 (32184821 GHz) -- garbage data.
|
||||
Built from: <source tree link> using <tools> [<versions>]
|
||||
```
|
||||
|
||||
### The Merge Request Process
|
||||
|
||||
All work should be done on feature branches and rebased onto the master branch often. In order to increase transparency and avoid redundant work, developers are encouraged to submit a 'Draft' merge request, which shows everyone what work is being done and allows for real-time feedback while development is happening.
|
||||
|
||||
When implementing a new feature or a bugfix, make commits early and often. When your work is finalized and ready to be reviewed, please rebase and clean up your commits so they are atomic and easy to digest.
|
||||
|
||||
Each commit should do precisely what it's commit message says, and nothing else. Avoiding side-effects makes the review process much easier for everyone and keeps the project's git history clean. This allows reproducible builds of past commit hashes and makes bugfixing easier when developers want to track down the commit that introduced an issue in the code.
|
||||
|
||||
When submitting a merge request, proof of your change working (past unit tests) is appreciated. This can be a screenshot, an inline mp4 on Gitlab, a YouTube link, a live demo, etc...
|
||||
|
||||
#### Commit Messages
|
||||
|
||||
Commit messages should lead with the general synopsis of what the commit as a whole does, followed by a new line, followed by more detail. All lines should be wrapped at 80 characters.
|
||||
|
||||
The title line should be prefixed with the files changes, then the class/struct/method/function
|
||||
|
||||
All commits should be signed by developers (i.e. `git commit -s`) -- bonus points for signing with a known GPG key.
|
||||
|
||||
There is no length limit for commit messages, but brevity is appreciated.
|
||||
|
||||
Example good commit message:
|
||||
```
|
||||
main.cpp: threads: join all threads as the main program exits
|
||||
|
||||
There was a dangling thread that was not caught by SIGTERM or SIGINT.
|
||||
Now, we join on all threads and finish gracefully.
|
||||
|
||||
Signed-off-by: Tucker Polomik <t.polomik@cablelabs.com>
|
||||
```
|
||||
|
||||
#### Coding Guidelines
|
||||
|
||||
This project is written in C++ (C++17) with tidbits of C mixed in. Please prefer C++ wherever possible, especially if it abstracts away machine specific APIs (for example, using `std::thread` instead of `pthread` or `CreateThread(...)`)
|
||||
|
||||
Past that, please format your code using `clang-format`, pointed at the `.clang-format` file in the base of the source tree.
|
||||
|
||||
Do not introduce "format" commits - just make formatting the last thing you do before a commit, but rarely as it's _own_ commit.
|
||||
|
||||
#### Performance Improvement MRs
|
||||
|
||||
Sometimes, you may find an area of the code that is poorly optimized for runtime performance. Whether it be a poorly written algorithm, bad data structure choices, or traversing a 2D matrix in column-major order instead of row-major.
|
||||
|
||||
Any performance improvements are appreciated, but it must not come at the sacrifice of readability. We could trim this code down to just inline assembly, and maybe it would be an order of magnitude faster, but it would also become unmaintainable.
|
||||
|
||||
Additionally, please provide tangible performance metrics (before & after) for optimization MRs.
|
||||
47
LICENSE
Normal file
47
LICENSE
Normal file
@@ -0,0 +1,47 @@
|
||||
Copyright (c) 2022 CableLabs
|
||||
|
||||
Redistribution and use in source and binary forms, with or without modification,
|
||||
are permitted provided that the following conditions are met:
|
||||
|
||||
1. Redistributions of source code must retain the above copyright notice,
|
||||
this list of conditions and the following disclaimer.
|
||||
|
||||
2. Redistributions in binary form must reproduce the above copyright notice,
|
||||
this list of conditions and the following disclaimer in the documentation
|
||||
and/or other materials provided with the distribution.
|
||||
|
||||
Subject to the terms and conditions of this license, each copyright holder
|
||||
and contributor hereby grants to those receiving rights under this license
|
||||
a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
(except for failure to satisfy the conditions of this license) patent license
|
||||
to make, have made, use, offer to sell, sell, import, and otherwise transfer
|
||||
this software, where such license applies only to those patent claims, already
|
||||
acquired or hereafter acquired, licensable by such copyright holder or contributor
|
||||
that are necessarily infringed by:
|
||||
|
||||
(a) their Contribution(s) (the licensed copyrights of copyright holders and
|
||||
non-copyrightable additions of contributors, in source or binary form) alone;
|
||||
or
|
||||
|
||||
(b) combination of their Contribution(s) with the work of authorship to which
|
||||
such Contribution(s) was added by such copyright holder or contributor, if,
|
||||
at the time the Contribution is added, such addition causes such combination
|
||||
to be necessarily infringed. The patent license shall not apply to any other
|
||||
combinations which include the Contribution.
|
||||
|
||||
Except as expressly stated above, no rights or licenses from any copyright
|
||||
holder or contributor is granted under this license, whether expressly, by
|
||||
implication, estoppel or otherwise.
|
||||
|
||||
DISCLAIMER
|
||||
|
||||
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
||||
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||||
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
||||
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
|
||||
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
||||
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
||||
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
|
||||
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
||||
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
|
||||
USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||
63
README.md
Normal file
63
README.md
Normal file
@@ -0,0 +1,63 @@
|
||||
# StationSniffer
|
||||
|
||||
## Userspace process for sniffing and serving Unassociated Station Link Metrics Statistics
|
||||
|
||||
[[_TOC_]]
|
||||
### **Building**
|
||||
|
||||
You'll need a C++ compiler, `libpcap`, and `libradiotap`
|
||||
|
||||
```apt install libpcap-dev```
|
||||
|
||||
To build and install `libradiotap`:
|
||||
|
||||
```
|
||||
git clone git@github.com:radiotap/radiotap-library.git;
|
||||
cd radiotap-library;
|
||||
mkdir -p build;
|
||||
cd build;
|
||||
cmake ..;
|
||||
make && make install
|
||||
```
|
||||
|
||||
Then, to build StationSniffer:
|
||||
|
||||
```make```
|
||||
|
||||
### **Running**
|
||||
|
||||
StationSniffer will take the interface that it is fed and put it into promiscuous mode for the lifetime of the program. If you've got one in mind, use it. If you want to make one, [see "Creating a virtual interface using `iw`"](#creating-a-virtual-interface-using-iw)
|
||||
|
||||
Otherwise, run:
|
||||
|
||||
```./pcap_rt <interface_name> <packet_periodicity> <station_timeout_threshold>```
|
||||
|
||||
|
||||
### **Creating a virtual interface using `iw`**
|
||||
|
||||
```iw phy <your_phy> interface add <virtual_monitor_interface_name> type monitor```
|
||||
|
||||
To find `<your_phy>`, run ```iw dev``` and pick one.
|
||||
|
||||
### **Fetching station statistics**
|
||||
|
||||
StationSniffer has a Unix domain socket server thread running to serve clients. It's found at `/tmp/uslm_socket`
|
||||
|
||||
The client should connect to this (stream) socket and make requests there. Requests are made via a minimal binary protocol, the format of which [can be found in messages.h](https://gitlab.com/prpl-foundation/prplmesh/stationsniffer/-/blob/feature/un_sock_ipc/messages.h)
|
||||
|
||||
There is a reference client implementation in `tools/test.py` (Python) and `tools/uds_client.c` (C)
|
||||
|
||||
### **Contributing**
|
||||
|
||||
See `CONTRIBUTING.md` for more details.
|
||||
|
||||
### **License**
|
||||
|
||||
Distributed under the FreeBSD License. See `LICENSE` for more details.
|
||||
|
||||
### **Contact**
|
||||
|
||||
```
|
||||
t.polomik at cablelabs.com
|
||||
tuckerpo at (buffalo.edu | fsf.org)
|
||||
```
|
||||
Reference in New Issue
Block a user