 |
bRAWcap 1.0.1
b-plus Technologies - Ethernet Performance Transmitter Receiver
|
|
bRAWcap 1.0.1
b-plus Technologies - Ethernet Performance Transmitter Receiver
|
b-plus technologies GmbH
Ulrichsberger Str. 17
94469 Deggendorf
Phone +49 991 270302-0
Fax +49 991 270302-99
E-Mail servi.nosp@m.ces@.nosp@m.b-plu.nosp@m.s.co.nosp@m.m
www.b-plus.com
Legal Notice
Software Copyright
Bitte beachten Sie, dass die folgenden Informationen in englischer Sprache verfasst wurden. Sofern Sie deutsche Unterstützung benötigen, wenden Sie sich bitte an suppo.nosp@m.rt@b.nosp@m.-plus.nosp@m..com.
The technical experts and engineers of b-plus technologies GmbH (“b-plus”) will be glad to offer technical support. b-plus has set itself the objective to develop products that are easy to use and to support you if you want to integrate the b-plus products in your system.
b-plus reserves the right to implement technical modifications without prior notice.
If you experience problems, errors, or any blue screens due to bRAWcap or NDIS (Network Driver Interface Specification) (while bRAWcap is used), please contact suppo.nosp@m.rt@b.nosp@m.-plus.nosp@m..com and attach your bRAWcap log files.
Default location for the generated log files is C:\ProgramData\bplus\brawcap\. If the environment variable AVETOSYS_CFG_LOG_PATH exists and is set to a valid path, the log files will be stored there. To get a more detailed logging it is possible to adjust the bRAWcap log level and type via API (Application Programming Interface).
In case of a blue screen, we would prefer that you additionally attach a full or at least default memory dump. The type of memory dump can be configured in Windows - please refer to the official Microsoft documentation. Per default, memory dumps are stored at C:\Windows\MEMORY.DMP.
| Symbol | Meaning |
|---|---|
| CAUTION (yellow): Instructions that, if ignored, could result in a injury, failure or crash. |
|
| ATTENTION (blue): Instructions that, if ignored, could result in malfunction. |
|
| NOTE (grey): This symbol refers to a note which can clarify a detail or expand on something mentioned. It provides additional context and more details. |
|
| TIP (green): This symbol refers to a tip which can offer a suggestion or give a best practice to follow. It offers something instructional to the reader. |
|
| List | |
| Task | |
| Cross Reference | |
| Result |
THIS PRODUCT MUST BE USED IN SUITABLE TEST ENVIRONMENTS AND BY TRAINED, QUALIFIED AND EXPERIENCED PERSONS WHO ARE AWARE OF THE POSSIBLE EFFECTS OF THE ACTIONS WHICH MAY BE CAUSED BY THE PRODUCT.
This product potentially can alter, modify or jam operational and security-related data of a networked infrastructure.
This product must be used by trained, qualified and experienced persons who possess the required technical skills and sufficient information about manipulation scenarios to assess the consequences of manipulating network communication. Pay attention to exercise the necessary caution when using this product as well as when using any similar product.
Due to its essential role in network communication, it is recommended to only use official release versions of the product. Pre-release or trial versions should never be used, especially in critical environments. Instead, those should only be used for evaluation under test conditions.
This product is intended to be installed on Windows devices with Ethernet network connections.
| Task | Target Group | Minimum Qualifications |
|---|---|---|
| Integration | C Software Developer | Knowledge in Ethernet communication; networking and experience in C programming. |
| Installation | IT-user | Basic knowledge in configuring and using Windows. |
| Maintenance | IT-specialist | Deeper knowledge in Windows; including filesystem, error handling and monitoring, command line and power shell usage. |
| Deinstallation | IT-user | Basic knowledge in configuring and using Windows. |
As stipulated by law, b-plus provides safety information (in this chapter). Warning messages and advices how to avoid malfunction and crashes to the target machine are in the related chapters. Trained specialists made the manual, the explanatory notes and the documentation for the use of the products.
bRAWcap can be used for low level communication with Ethernet adapters. It makes it possible to send and receive raw Ethernet packets on Windows machines. bRAWcap is optimized for performance. Therefore it tries to consume less CPU (Central Processing Unit) load compared to other drivers. This enables high throughput, which is required for 10G Ethernet adapters, for example. To fit perfectly into user environments, bRAWcap comes with a wide range of configuration options.
For complete functionality bRAWcap requires a license. Such a license can be requested from b-plus.
After requesting a license you will receive an offer of the supported licensing types and their pricing.
To get in touch with bRAWcap, it can also be used without a valid license, but with some limitations (see Demo).
If you want to evaluate or test bRAWcap before ordering a licensed version, it is possible to use bRAWcap without a license but with limitations.
The limitations of the demo version are:
If this restrictions are not acceptable for your tests and you want to test without any limitation, you can contact servi.nosp@m.ces@.nosp@m.b-plu.nosp@m.s.co.nosp@m.m and request a test license. Test licenses are only valid for a short period of time and should be used only for evaluation purposes.
bRAWcap comes with it´s own setup, which should be the preferred tool for installing/updating bRAWcap. In general, it is not allowed to install multiple instances of bRAWcap at the same time. Therefore, previous installations should always be uninstalled before installing a new version. If you use the bRAWcap setup, it takes care of such an update process and no further action is required.
If you still want to install bRAWcap manually (without using the setup), make sure that the previous bRAWcap version is completely removed before deploying a new version.
In general, it is not allowed to mix up driver and library versions of bRAWcap. If this is the case, the communication between driver and library may be incompatible. In the worst case this can lead to a system crash.
It is allowed and supported to install bRAWcap on a device where winpcap, npcap or another similar filter driver is already installed.
First of all the bRAWcap setup checks if bRAWcap is already installed.
If a bRAWcap installation is found, it will ask you if the previous version shall be removed.
When going ahead, the bRAWcap uninstaller of the currently installed bRAWcap version will be started. Follow it´s instructions to uninstall the previous version (see Uninstall for detailed information).
The first installer page will be the welcome page. In the next step you have to accept the license terms for bRAWcap to go ahead. Now the component page will appear, which allows to select specific parts of bRAWcap to be installed or skipped.
Some components are required and have to be installed always. Those are the driver itself, it´s library, the documentation and the Codemeter runtime. The driver and library are the core features of bRAWcap and their versions shall always be equal to each other. Codemeter runtime is required for licensing and always installed if it is not yet available. When the installed Codemeter version is equal or newer, it will be skipped. If an older version of the Codemeter runtime is detected it will be updated. The bRAWcap demo application(s) are only installed if selected, which is the default case. Same applies to the SDK which is only required for developing applications which want to make use of bRAWcap. Therefore the SDK is not installed per default.
After selecting the components you will be asked were to install bRAWcap. The given path will contain bRAWcap components like the documentation, demo(s), SDK and the uninstaller. Some components like the library and the driver instead, are always deployed directly to the system. The next page allows to set some specific settings for bRAWcap, which will be applied during the installation.
Only one setting is currently available. This setting lets you choose whether to enable bRAWcap by default on every supported adapter on the current machine. If this setting is active (default), bRAWcap is enabled on all supported adapters. If it is not active, bRAWcap is not activated on any adapter after installation and must first be activated manually per adapter. In the next step the setup will install all specified components. When the installation has finished the finish page appears.
If the demo was installed you can directly choose to start the demo in receive mode when closing the setup. It is also possible to always open up this documentation directly after closing the setup.
If the setup was corrupted somehow or something during installation went wrong, you can find a generated log file for each install in the bRAWcap logging path. The default logging path is C:\ProgramData\bplus\brawcap\ (see Support & Error Reporting). Setup log files are named with bRAWcap_installer_year_month_day.log.
If you are looking for an older log file have a look into C:\ProgramData\bplus\brawcap\archive.
It is recommended to use the bRAWcap uninstaller to remove bRAWcap. The uninstaller can be started via Control Panel\All Control Panel Items\Programs and Features\bRAWcap. This entry will be linked to the uninstaller location, which is the bRAWcap installation directory which was selected during installation.
After starting the uninstaller it will show up with a component page. Here you can select which parts of bRAWcap shall be removed.
The next page depends on the current usage of bRAWcap. If there is any application which has bRAWcap loaded the uninstaller will display a usage page.
When bRAWcap is not in use by any application this page will be skipped. On the usage page you get a list of all applications which have bRAWcap loaded. This list can be refreshed and you also have the ability to try stopping all applications which use bRAWcap.
To proceed with the uninstall of bRAWcap, you must close all applications that use bRAWcap. The next uninstall step is disabled until then. Now you can start the uninstall on the next page. The uninstaller writes to the same log file where the installer writes to. To check if there are any problems with the uninstall, please have a look into this file.
The bRAWcap setup (installer and uninstaller) supports command line usage. The command line interface allows to configure each option which is available by the guided installation. Therefore the installer/uninstaller has to be called with those command line parameters.
/help. This kind of installation allows you to embed the bRAWcap setup into your own deployment process. With this the bRAWcap setup can be executed completely in the background without any user interaction.
start "" /WAIT bRAWcap_Setup_*.exe /S To get a list of all available command line parameters for the installer use the /help parameter. The installer will then appear with a single dialog showing parameter descriptions and quit after that.
For selecting which components of bRAWcap should be installed use the section switch command line parameters. Section switches are always prefixed with "/" and must be activated/deactivated with "=true/false".
Available section switches are:
/demos=true/false (default: true): Preselects if the bRAWcap demo(s) should be installed./sdk=true/false (default: false): Preselects if the bRAWcap Software Development Kit should be installed.The following command shows how to preselect all components for installation, before showing the installer GUI.
bRAWcap_Setup_*.exe /demos=true /sdk=true
To configure additional settings or change the installer behavior use the command line options. Command line options are always prefixed with "/". If the option requires a value (not only a flag) the value must be set behind a equal sign (=).
Available option(s) are:
/help: Shows the installer command line help./detachAll=true/false (default: false): If true, it detaches bRAWcap driver from each supported interface after installation./uninstallParams="Param1 ... ParamN" (default= " "): If bRAWcap is currently installed (update procedure), this parameter allows to specify the parameters passed to the available bRAWcap uninstaller. It is important that the parameters for the uninstaller must be encapsulated in quotes. For available uninstaller parameters see Uninstalling Automated./S: Use this flag for silent installation, which means that the installer will be executed in the background. This should be the preferred execution if you want to embed bRAWcap into your application setup./D=Absolute Path (default: C:\Program Files\b-plus\brawcap): Allows to change the installation path. It is important that this is the last command line parameter. The path must be given as "absolute path" and should not be placed in any quotes (even if it contains any whitespace). Whats also important is that the path only contains \ and no /.If any of the available command line parameters is not explicitly set, it´s default value will be used.
The following command shows how to install bRAWcap
C:\Program Files\MyAmazingApplication\bRAWcapand wait until installer has finished.
start "" /WAIT "bRAWcap_Setup_*.exe /S /demos=true /sdk=false /detachAll=true /uninstallParams="/cmruntime=true /forceStop=true" /D=C:\Program Files\MyAmazingApplication\bRAWcap"
The uninstaller has the same command line /help parameter for showing a dialog with all it´s supported command line parameters. If set, the uninstaller will exit after showing the help dialog.
For selecting which components shall be removed by the uninstaller use the section switch command line parameters. Section switches are always prefixed with "/" and must be activated/deactivated with "=true/false".
Available section switches are:
/cmruntime=true/false (default: false): Preselects if the Codemeter Runtime shall be uninstalled.The following command shows how to preselect all components for uninstall, before showing the uninstaller GUI.
bRAWcap_Uninstall_*.exe /cmruntime=true
To configure additional settings or change the uninstaller behavior use the command line options. Command line options are always prefixed with "/". If the option requires a value (not only a flag) the value must be set behind a equal sign (=).
Available option(s) are:
/help: Shows the installer command line help./forceStop=true/false (default: false): If true the uninstaller tries to stop all applications which have bRAWcap loaded. This option is only used if the silent flag is set. When the uninstaller fails to stop any application it will abort execution and return an error./S: Use this flag for silent uninstall, which means that the uninstaller will be executed in the background. This should be the preferred execution if you want to embed bRAWcap into your application setup.The following command shows how to uninstall bRAWcap
and wait until uninstaller has finished.
start "" /WAIT "bRAWcap_Uninstall_*.exe /S /cmruntime=true /forceStop=true"
/uninstallParams for passing command line parameters to the currently installed bRAWcap uninstaller. Therefore, in case of an update, it is not required to start the uninstaller on your own. The /S flag for silent uninstall is not required and will be used depending on the installer execution. If the installer is executed in background it will also start the uninstaller in background. To evaluate bRAWcap and familiarize yourself with its features, it is recommended to have a look at the provided command line demo application. The demo application supports different modes, each one for a specific feature of bRAWcap.
A complete list of all available modes will be shown if the demo is called without any parameter or -h/–help/help.
brawcap-demo.exe <mode> [OPTIONS | help]
Example
brawcap-demo.exe help
To select a mode call the bRAWcap demo with one of the supported modes as first argument. Further you can modify each mode with nearly every setting which is provided by the bRAWcap C-API.
To get a list of each setting add a -h/–help behind the selected mode parameter.
brawcap-demo.exe <mode> -h/--help
Example
brawcap-demo.exe receive -h
For integrating bRAWcap into applications use the bRAWcap SDK. The SDK can be selected for installation during the setup and can be copied directly into your project.
The API documentation is grouped into different modules. Each module is describing a specific part of the API.
bRAWcap API is written in C and fully compatible to C99. All header files describing the API can be found in sdk\c\include. bRAWcap has in general four header files. It is recommended to always include the base header sdk\c\include\libbrawcap.h, which will than include all other headers for you.
Here is a list of the other headers and a short description of their content:
sdk\c\include\brawcap.h - Function prototypessdk\c\include\brawcap_types_um.h - User mode definitions and typessdk\c\include\brawcap_types_shared.h - Shared definitions and typesThe bRAWcap library is only available for x64 architectures. For linking against bRAWcap the SDK contains a dynamic library which can be found in sdk\c\lib. Use the sdk\c\lib\libbrawcap64.lib for linking.
Static linking is currently not supported and therefore a static library is not part of the SDK.
On each machine where bRAWcap is installed the sdk\c\lib\libbrawcap64.dll will always be deployed to the system directory. This ensures that it is found for loading and that the driver version always corresponds to the library version. Therefore it is not required and recommended to deploy the DLL (Dynamic Linked Library) again with your application. If you deploy the DLL with your application, your deployed DLL (version) will be loaded, instead of the DLL (version) deployed during bRAWcap installation. This results in a different driver and library version.
bRAWcap requires at least NDIS version 6.50 which was released with Windows 10 build 1507 (July 2015). Therefore bRAWcap can be used with Windows 10 versions higher or equal to the 1507 build.
Demo
cxxopts
PDCursesMod
Setup
NSIS
Doc
doxygen-awesome-css
Per default, bRAWcap will be started during system boot. To see if bRAWcap driver is running or not use the Windows Service Control Manager (SC (Service Control Manager)).
Therefore open a command line and type:
sc query brawcap
This will give you a similar output to the screenshot below.
If you want to stop bRAWcap, close all applications which have loaded the bRAWcap library and then use the following command.
sc stop brawcap
STOP_PENDING state. To manually start bRAWcap the following command can be used.
sc start brawcap
bRAWcap supports all Ethernet adapters and will automatically attach to each detected Ethernet adapter during installation. It is also possible to deactivate bRAWcap for all detected Ethernet adapters per default by using the setup (see setup settings).
To (de)activate bRAWcap after installation on some adapters you can (un)check the bRAWcap entry for each adapter via it´s property page (Control Panel/Network and Internet/Network Connections/Properties).
There is another way of deactivating bRAWcap on specific adapters by using the PowerShell (PS (Power Shell)) NetAdapter cmdlet. The following command lists the activated drivers on the given adapter.
Powershell:
Get-NetAdapterBinding -Name [...]
Example output:
To (de)activate bRAWcap via PowerShell use the following command.
Powershell:
Set-NetAdapterBinding -Name [...] -ComponentID bplus_rawcap -Enabled true/false
Example output:
First of all bRAWcap is handle based, which means that there can be several handles attached to the same adapter. This makes it possible that several processes (applications) can use bRAWcap independent from each other. If several applications use bRAWcap with the same receive filter for example, the CPU load will increase. Especially if the handles use no filtering (all packets are processed) the resulting CPU load have to be multiplied by the number of handles (for example if one handle produces 3% CPU load, than three handles will result in 9% CPU load).
In general it is recommended to set the receive filter very precisely, that only packets which are really required are processed by bRAWcap. Overlapping filters on the same adapter should be avoided, if possible.
bRAWcap also allows to only process a subpart of each packet and not always the hole packet (see brawcap_filter_bytes_to_capture_set API function documentation). So if you are not interested in headers for example, configure bRAWcap to only supply the payload without headers.
Update history of bRAWcap and all of it´s components.
Release Date: 2022-12-15
Highlights
- Initial release - only demo mode supported.
Changes
- Driver & Library
- Adapter
- Possibility to scan the target for supported adapters.
- Translation between several adapter information (GUID, MAC, Description, FriendlyName).
- Reading current adapter properties/states (Speed Rx/Tx, MTU, IPv4/6, Operation, Connection).
- Event notification on adapter changes.
- Receiving
- Single packets without additional buffer handling.
- Multiple packets by configurable API buffer(s), with callback registration.
- VLAN tagging support.
- Filtering packets with user defined byte mask filter.
- (De)activate packet indication - forwarding to network stack.
- Dynamic configuration of driver receive buffers.
- Configuration of adapter/hardware filters (which will be applied directly on the NIC), e. promiscuous mode.
- Choose between several receive timestamp modes (system time, QPC or hardware timestamp), depending on adapter capabilities.
- Direction configuration, which allows to select different receive modes. Only received packets from NIC, only transmitted packets on the NIC - from upper network stack, or both.
- Monitoring
- Multiple receive packet drop counters, for different drop reasons and locations.
- Multiple receive packet counters, for different locations, e.g. at NIC level, driver before/after filtering.
- Receive packet counters, for user space exchange.
- Generic
- Configurable (detailed) file logging, which allows to select log levels for different (sub parts).
- Support of several concurrent bRAWcap handles to the same adapter.
- Demo App
- Added modes for demo application (only receive mode is currently supported).
- Receive demo command line parameters for setting available bRAWcap receive configuration.
- Detailed help command describing each command line parameter.
- Structured console output to get a overall feedback about the current status.
- Setup
- Select between components which you want to install.
- Detailed file logging.
- Choose if bRAWcap should be (de)activated per default, on all supported adapters after installation.
Bugfixes
- Driver & Library
- Demo App
- Setup
Open Issues
- Driver & Library
- Demo App
- Console output formatting issues if running in Windows Terminal.
- Setup
Release Date: 2023-03-31
Highlights
- We are still in a "PRE-RELEASE" state.
- This version supports DEMO mode only. Licensing is still under development.
- Added packet transmission feature.
- A lot of changes to the API. This was required to increase usability and compatibility for later modifications. API should be in a productive state now and we try to keep further changes to a absolute minimum.
- Extended and redesigned documentation.
Changes
- Driver & Library
- Adapter
- Receiving
- A lot of refactoring in receive resource handling.
- Transmitting
- Introduced transmit feature.
- Monitoring
- Restructured statistics to allow extensions in upcoming releases without breaking the compatibility.
- Generic
- Removed own datatype definitions, instead bRAWcap now always includes the required Windows headers.
- Reduced public structures to a absolute minimum, to increase API compatibility.
- Added a lot of API documentation (not yet completely finished).
- Some examples are now available, more will be added with the next version.
- Demo App
- Supports transmit mode now (to get all parameters for this mode use "brawcap-demo.exe transmit -h").
- Improved console output (better readability and highlighting).
- Specified start parameters are now visible during runtime, for each mode.
- Setup
- Added usage check to uninstaller.
- Made setup fully compatible with silent mode (background execution), via command line parameters. This makes it possible to embed the bRAWcap setup into any deployment process.
- Added Codemeter Runtime to setup (for later licensing purposes).
Bugfixes
- Driver & Library
- Generic
- Fixed library unloading.
- Fixed driver crash happening when driver is deactivated on a adapter while IO controls are pending.
- Demo App
- Console output fixed for Windows "Terminal".
- Setup
Open Issues
- Driver & Library
- Demo App
- Setup
Release Date: 2023-06-02
Highlights
- We are still in a "PRE-RELEASE" state.
- Now licensing is supported - unlimited use with all features possible
Changes
- Driver & Library
- Generic
- Added more examples to SDK.
- Improved SDK and manual documentation.
- Added codemeter licensing.
- Demo App
- Setup
Bugfixes
- Driver & Library
- Generic
- Could not apply no timestamp mode.
- Demo App
- Setup
Open Issues
- Driver & Library
- Demo App
- Setup
Release Date: 2024-02-01
Highlights
- This is the first official version of our bRAWcap.
- Stable reception and transmission.
- API is now fixed and will be kept compatible by future minor/patch releases.
Changes
- Driver & Library
- Generic
- Improved driver IO controls to allow asynchronous calls (e.g. for requesting stats while transmitting/receiving).
- Receiving/Filtering
- Filters are now a submodule of receiving (because they are only applicable for reception).
- Monitoring/Statistics
- Checking for supported adapter stats is now possible via macro.
- Time Stamping
- Improved fallback time stamping behavior if selected mode is unavailable.
- Adapter
- 5G uplink speeds are known now - they was reported as "unknown" before.
- Demo App
- Generic
- Improved command line parameter descriptions.
- It is now possible to adjust display refresh rate with +/- during runtime.
- Console output now signals, if demo is going to be stopped (stop pending).
- Demo can be stopped now (gracefully and immediately) by using the ESC key.
- For each mode the displayed adapter statistics will show if the corresponding counter is supported.
- It is now possible to generate a log file for each used adapter containing the statistic counters (–log-stats).
- Improved accuracy of displayed transmit/receive rates.
- Receive
- It is now possible to specify a receive filter via command line parameter (–filter)
- Added column for adapter dropped packets.
- Transmit
- Added new parameter (–dummy-packet-dest-mac) which allows to specify a target Ethernet MAC for the generate dummy packet.
- CPP Wrapper
- Initial release of bRAWcap C++ wrapper for the SDK contained C API (also available at GitHub).
- Setup
- Now supports german language
Bugfixes
- Driver & Library
- Generic
- Could not apply no timestamp mode.
- Receiving/Transmitting
- Fixed possible crash when stopping process while transmission/reception is still active.
- Adapter
- brawcap_adapter_description_by_handle could crash if description pointer was invalid.
- Changed internal Windows API call to support old Windows 10 versions (< 1709).
- Monitoring/Statistics
- Fixed macro BRAWCAP_STATS_RX_ADAPTER_DROPPED_PACKETS_TOTAL_VALID - syntax issue.
- Driver now saves statistics of already closed handles and adds them to the total "driver" stats since driver start.
- Demo App
- Generic
- Improved stop handling when demo is killed with CTRL+C (by resetting the original console attributes, e.g. font size...).
- Transmit
- Time gap for dummy frames was not used anymore if a transmission buffer was transmitted once.
- Setup
- Added required VC re-distributable to installer, will be automatically installed if no supported version is already available.
Open Issues
- Driver & Library
- Demo App
- Setup
Release Date: 2024-11-05
Highlights
- Updated driver signature method to Microsoft Attestation signature. Driver can no be installed and executed on Windows 10 & 11 with Secure Boot activated.
Changes
- Driver & Library
- Generic
- Added new API function for activating several log types and log levels at once (brawcap_log_levels_set)
- Demo App
- Generic
- Command line parameter to adjust demo log levels.
- CPP Wrapper
- Added new API function for activating several log types and log levels at once (BRAWcap::LogLevelsSet)
- Setup
- Improved driver installation-file to isolate driver in Windows driver store depending on Windows version
- All b-plus and third party licenses will be available in installation directory ./licenses subpath
Bugfixes
- Driver & Library
- [none]
- Demo App
- [none]
- Setup
- [none]
Open Issues
- Driver & Library
- [none]
- Demo App
- [none]
- Setup
- [none]
