-
Notifications
You must be signed in to change notification settings - Fork 130
03a Areg SDK Multitarget Router (mtrouter)
The Multitarget Router enables inter-process and networked communication between Service Provider and Consumer nodes in distributed Areg SDK applications.
Tip
For single-process multithreading applications, mtrouter is not required. See Quick Project Setup for creating projects.
- Quick Start
- Overview
- Installation
- Running as Console Application
- Running as System Service
- Configuration
- Command Reference
- Application Integration
- Troubleshooting
Linux/macOS:
cd areg-sdk
./product/build/gnu-g++/linux-64-x86_64-release-shared/bin/mtrouter.elf --consoleWindows:
cd areg-sdk
.\product\build\msvc-v143\windows_nt-x64-release\bin\mtrouter.exe --consoleExpected output:
Areg Multi-target Message Router console application ...
---------------------------------------------------------------------------------------------
Send data with the rate: 0.00 Bytes / sec.
Recv data with the rate: 0.00 Bytes / sec.
Type '-q' or '--quit' to quit the application ...:
Test connection: Run executable of any IPC example, for example 15_pubclient.exe, and type -n in mtrouter console to see connected clients like this:
Areg Multi-target Message Router console application ...
---------------------------------------------------------------------------------------------
Send data with the rate: 0.00 Bytes / sec.
Recv data with the rate: 0.00 Bytes / sec.
Type '-q' or '--quit' to quit the application ...:
---------------------------------------------------------------------------------------------
Nr. | Instance ID | Bitness | Name
---------------------------------------------------------------------------------------------
1. | 256 | 64 | 15_pubclient.exe
2. | 257 | 64 | 15_pubservice.exe
---------------------------------------------------------------------------------------------
Type -q to quit
The Multitarget Message Router (mtrouter) is a message routing service that:
- ✅ Routes messages between distributed processes
- ✅ Enables inter-process communication (IPC)
- ✅ Supports network communication (TCP/IP)
- ✅ Manages service discovery
- ✅ Handles multiple client connections
| Application Type | Requires mtrouter | Communication |
|---|---|---|
| Multithreading (single process) | ❌ No | In-process |
| Multiprocessing (same machine) | ✅ Yes | Inter-process (IPC) |
| Distributed (network) | ✅ Yes | Network (TCP/IP) |
Important
Without mtrouter, multiprocessing applications cannot communicate with each other. They will run as standalone multithreading applications where only internal (local) services work within each process, but external (public) services remain inaccessible to other processes.
Without mtrouter (multithreading):
┌────────────────────────────┐
│ Single Process │
│ ┌──────────┐ ┌──────────┐ │
│ │ Provider │ │ Consumer │ │
│ └──────────┘ └──────────┘ │
└────────────────────────────┘
With mtrouter (multiprocessing/distributed):
┌─────────────┐ ┌──────────┐ ┌─────────────┐
│ Provider │────────►│ mtrouter │◄────────│ Consumer │
│ Process │ │ (Router) │ │ Process │
└─────────────┘ └──────────┘ └─────────────┘
Console Application:
- Run manually for development/testing
- Easy debugging and monitoring
- Stop with
-qor--quit
System Service:
- Automatic startup at boot
- Runs in background
- Managed by OS (systemd/Windows Services)
After building Areg SDK, mtrouter is available in the build output directory.
Default build paths:
Linux:
./product/build/gnu-g++/linux-64-x86_64-release-shared/bin/mtrouter.elfWindows:
.\product\build\msvc-v143\windows_nt-x64-release\bin\mtrouter.exeNote
Build output paths follow pattern: product/build/<compiler>/<platform>-<arch>-<config>/bin/
Install Areg SDK system-wide:
# Configure and build
cmake -B ./build
cmake --build ./build
# Install (requires sudo on Linux)
sudo cmake --install ./buildDefault installation locations:
Linux:
- Executables:
/usr/local/tools/areg/mtrouter - Libraries:
/usr/local/lib/libareg.so - Headers:
/usr/local/include/areg/ - Config:
/usr/local/share/areg/areg.init - Service files:
/usr/local/share/areg/service/
Windows:
- Executables:
C:\Program Files\areg\tools\areg\mtrouter.exe - Libraries:
C:\Program Files\areg\bin\areg.dll - Headers:
C:\Program Files\areg\include\areg\ - Config:
C:\Program Files\areg\share\areg\areg.init - Service files:
C:\Program Files\areg\share\areg\service\
Custom installation prefix:
cmake --install ./build --prefix /opt/aregWhat gets installed:
Libraries:
-
areg- Core framework library -
aregextend- Extended utilities library -
areglogger- Log observer API library
Executables:
-
mtrouter- Message router -
logcollector- Log collector service -
logobserver- Log observer application
Tools:
-
codegen.jar- Service interface code generator -
project-setup.sh/project-setup.bat- Project creation scripts
Configuration:
-
areg.init- Default configuration file - Service installation scripts (Linux/Windows)
Development files:
- Headers (
.h,.hpp) - CMake configuration files
- pkg-config files (
.pc)
From build directory:
Linux/macOS:
./product/build/gnu-g++/linux-64-x86_64-release-shared/bin/mtrouter.elf --consoleWindows:
.\product\build\msvc-v143\windows_nt-x64-release\bin\mtrouter.exe --consoleFrom installed location:
Linux:
/usr/local/tools/areg/mtrouter --consoleWindows:
& "C:\Program Files\areg\tools\areg\mtrouter.exe" --consoleExpected output:
Areg Multi-target Message Router console application ...
---------------------------------------------------------------------------------------------
Send data with the rate: 0.00 Bytes / sec.
Recv data with the rate: 0.00 Bytes / sec.
Type '-q' or '--quit' to quit the application ...:
While mtrouter is running, type commands starting with - (short) or -- (long):
| Command | Alias | Description |
|---|---|---|
--help |
-h |
Display command list |
--instances |
-n |
Show connected clients |
--pause |
-p |
Pause message routing |
--restart |
-r |
Restart all connections |
--quit |
-q |
Stop mtrouter |
--silent |
-t |
Toggle silent mode (hide data rates) |
--verbose |
-v |
Toggle verbose mode (show data rates) |
Example - Check connected clients:
Type --instances or -n:
Areg Multi-target Message Router console application ...
---------------------------------------------------------------------------------------------
Send data with the rate: 0.00 Bytes / sec.
Recv data with the rate: 0.00 Bytes / sec.
Type '-q' or '--quit' to quit the application ...:
---------------------------------------------------------------------------------------------
Nr. | Instance ID | Bitness | Name
---------------------------------------------------------------------------------------------
1. | 256 | 64 | provider.exe
2. | 257 | 64 | consumer.exe
---------------------------------------------------------------------------------------------
Toggle verbose mode:
Type --verbose or -v:
When verbose ON (default):
Send data with the rate: 1.23 Bytes / sec.
Recv data with the rate: 0.87 Bytes / sec.
When verbose OFF (silent):
Type '-q' or '--quit' to quit the application ...:
Note
Verbose mode shows data transfer rates, not individual messages.
Load custom configuration file:
./mtrouter.elf --console --load="./config/custom.init"Option A: Install via CMake (recommended)
# Install Areg SDK system-wide
sudo cmake --install ./build
# Service file location
ls -l /usr/local/share/areg/service/mtrouter.serviceOption B: Manual installation
# Copy executable
sudo cp ./product/build/gnu-g++/linux-64-x86_64-release-shared/bin/mtrouter.elf /usr/local/bin/mtrouter
# Copy library (if shared build)
sudo cp ./product/build/gnu-g++/linux-64-x86_64-release-shared/lib/libareg.so /usr/lib/libareg.so
# Make executable
sudo chmod +x /usr/local/bin/mtrouter
# Update library cache
sudo ldconfigVerify:
/usr/local/bin/mtrouter --helpIf installed via CMake:
sudo cp /usr/local/share/areg/service/mtrouter.service /etc/systemd/system/If manual installation:
sudo cp ./framework/mtrouter/resources/mtrouter.service /etc/systemd/system/Or create manually:
sudo nano /etc/systemd/system/mtrouter.serviceContent:
[Unit]
Description=Areg Multitarget Router Service
After=network.target
[Service]
Type=simple
ExecStart=/usr/local/bin/mtrouter --service
Restart=on-failure
RestartSec=5s
[Install]
WantedBy=multi-user.targetImportant
The --service flag is required for service mode.
Reload systemd:
sudo systemctl daemon-reloadEnable (start at boot):
sudo systemctl enable mtrouter.serviceExpected output:
Created symlink /etc/systemd/system/multi-user.target.wants/mtrouter.service → /etc/systemd/system/mtrouter.service
Start service:
sudo systemctl start mtrouter.serviceVerify status:
sudo systemctl status mtrouter.serviceExpected output:
● mtrouter.service - Areg Multitarget Router Service
Loaded: loaded (/etc/systemd/system/mtrouter.service; enabled)
Active: active (running) since Mon 2026-01-27 10:30:00 UTC; 5s ago
Main PID: 12345 (mtrouter)
Tasks: 3
Memory: 8.5M
CGroup: /system.slice/mtrouter.service
└─12345 /usr/local/bin/mtrouter --service
Stop service:
sudo systemctl stop mtrouter.serviceRestart service:
sudo systemctl restart mtrouter.serviceDisable (don't start at boot):
sudo systemctl disable mtrouter.serviceView logs:
sudo journalctl -u mtrouter.service -fExpected log output:
Jan 27 10:30:00 hostname mtrouter[12345]: Router service started
Jan 27 10:30:01 hostname mtrouter[12345]: Listening on 127.0.0.1:8181
Option A: Install via CMake (recommended)
# Open PowerShell as Administrator
# Install Areg SDK
cmake --install .\build --prefix "C:\Program Files\areg"
# Service installation script location
dir "C:\Program Files\areg\share\areg\service\mtrouter.service.install.bat"Option B: Manual installation
# Create installation directory
New-Item -Path "C:\Program Files\areg\tools\areg" -ItemType Directory -Force
# Copy binaries
Copy-Item .\product\build\msvc-v143\windows_nt-x64-release\bin\mtrouter.exe "C:\Program Files\areg\tools\areg\"
Copy-Item .\product\build\msvc-v143\windows_nt-x64-release\bin\areg.dll "C:\Program Files\areg\tools\areg\"Verify:
& "C:\Program Files\areg\tools\areg\mtrouter.exe" --helpOpen PowerShell as Administrator:
Right-click PowerShell → Run as Administrator
Option A: Using installation script (if CMake installed)
cd "C:\Program Files\areg\share\areg\service"
.\mtrouter.service.install.batOption B: Using mtrouter executable
cd "C:\Program Files\areg\tools\areg"
.\mtrouter.exe --installExpected output:
Service 'Areg Multitarget Router Service' installed successfully
Using Services GUI:
- Press
Win + R, typeservices.msc, press Enter - Find Areg Multitarget Router Service
- Right-click → Start
Using PowerShell:
Start-Service "mtrouter.service"Verify status:
Get-Service "mtrouter.service"Expected output:
Status Name DisplayName
------ ---- -----------
Running mtrouter.service Areg Multitarget Router Service
Automatic startup:
Set-Service "mtrouter.service" -StartupType AutomaticManual startup:
Set-Service "mtrouter.service" -StartupType ManualStop service:
Stop-Service "mtrouter.service"Restart service:
Restart-Service "mtrouter.service"Uninstall service:
Option A: Using uninstall script
cd "C:\Program Files\areg\share\areg\service"
.\mtrouter.service.uninstall.batOption B: Using mtrouter executable
# Stop first
Stop-Service "mtrouter.service"
# Uninstall
cd "C:\Program Files\areg\tools\areg"
.\mtrouter.exe --uninstallExpected output:
Service 'Areg Multitarget Router Service' uninstalled successfully
View service logs:
Open Event Viewer: Win + R → eventvwr.msc
Navigate: Windows Logs → Application
Filter for Source: mtrouter
Default: areg.init in Areg SDK resources directory
Installed location:
- Linux:
/usr/local/share/areg/areg.init - Windows:
C:\Program Files\areg\share\areg\areg.init
Custom location:
mtrouter --load="./path/to/config.init"Settings use key-value pairs:
Syntax:
section::(module|*)::property[::(position|*)] = value
-
section - Configuration section (e.g.,
router,log) -
module - Module name or
*for all modules - property - Property name
- value - Property value
Complete example:
# Router service configuration
router::*::service = mtrouter # Service name
router::*::connect = tcpip # Protocol (tcpip only)
router::*::enable::tcpip = true # Enable TCP/IP
router::*::address::tcpip = 127.0.0.1 # Listen address
router::*::port::tcpip = 8181 # Listen portConfiguration breakdown:
| Property | Default | Description |
|---|---|---|
router::*::service |
mtrouter |
Router process name |
router::*::connect |
tcpip |
Communication protocol |
router::*::enable::tcpip |
true |
Enable/disable TCP/IP |
router::*::address::tcpip |
127.0.0.1 |
IP address to bind |
router::*::port::tcpip |
8181 |
Port number |
1. Local development (default):
router::*::address::tcpip = 127.0.0.1
router::*::port::tcpip = 8181Use case: Single machine development
2. Network access (all interfaces):
router::*::address::tcpip = 0.0.0.0
router::*::port::tcpip = 8181Use case: Accept connections from any network interface
3. Specific network interface:
router::*::address::tcpip = 192.168.1.100
router::*::port::tcpip = 8181Use case: Bind to specific network interface
4. Custom port:
router::*::address::tcpip = 127.0.0.1
router::*::port::tcpip = 9090Use case: Avoid port conflicts
5. Application-specific routing:
# Default for all applications
router::*::address::tcpip = 127.0.0.1
router::*::port::tcpip = 8181
# Specific configuration for 'myapp'
router::myapp::address::tcpip = 192.168.1.50
router::myapp::port::tcpip = 9090Use case: Different applications connect to different routers
Add to configuration:
log::mtrouter::scope::* = NOTSETOr disable all logs:
log::*::scope::* = NOTSETTip
For detailed configuration syntax, see Persistence Syntax Guide.
Options used when starting mtrouter:
| Option | Alias | Platform | Description |
|---|---|---|---|
--console |
-c |
All | Run as console application |
--help |
-h |
All | Display help message |
--install |
-i |
Windows | Install as Windows service |
--load |
-l |
All | Load custom configuration file |
--service |
-s |
Linux | Run as Linux service |
--silent |
-t |
All | Run without showing data rates |
--uninstall |
-u |
Windows | Uninstall Windows service |
--verbose |
-v |
All | Show data transfer rates |
Examples:
# Console with default config
mtrouter --console
# Console with custom config
mtrouter -c -l="./my-config.init"
# Silent console mode (no data rates)
mtrouter -c -t
# Verbose console mode (show data rates)
mtrouter -c -v
# Linux service
mtrouter --service
# Windows service install
mtrouter.exe --installCommands available while mtrouter runs in console mode (must start with - or --):
| Command | Alias | Description |
|---|---|---|
--help |
-h |
Display command list |
--instances |
-n |
Show connected clients |
--pause |
-p |
Pause message routing |
--restart |
-r |
Restart all connections |
--quit |
-q |
Stop mtrouter |
--silent |
-t |
Toggle silent mode (hide data rates) |
--verbose |
-v |
Toggle verbose mode (show data rates) |
Usage: Type the command (e.g., -n or --instances) and press Enter.
Applications connect to mtrouter by initializing the Application class with router client enabled.
Important
For inter-process communication, mtrouter must be running. Start mtrouter before or after starting provider and consumer processes. There is no required startup order - applications will automatically connect when mtrouter becomes available. For network communication, configure mtrouter address in application configuration file (areg.init). By default, applications communicate via localhost.
Minimal setup:
#include "areg/appbase/Application.hpp"
int main()
{
// Initialize with router client enabled
Application::initApplication(
true, // Enable logging
true, // Enable service manager
true, // Enable router client ← Important
true, // Enable timer manager
true // Enable watchdog manager
);
// Load service model
Application::loadModel("MyModel");
// Wait for application quit signal
Application::waitAppQuit(NECommon::WAIT_INFINITE);
// Cleanup
Application::releaseApplication();
return 0;
}Note
The third parameter (true) enables router client connection.
Specify configuration file:
#include "areg/appbase/Application.hpp"
int main()
{
// Initialize with custom configuration
Application::initApplication(
true, // Enable logging
true, // Enable service manager
true, // Enable router client
true, // Enable timer manager
true, // Enable watchdog manager
"./config/myapp.init", // Configuration file
nullptr // Logging configuration (null = use config file)
);
Application::loadModel("MyModel");
Application::waitAppQuit(NECommon::WAIT_INFINITE);
Application::releaseApplication();
return 0;
}Create myapp.init configuration:
# Application router connection settings
router::myapp::service = mtrouter
router::myapp::connect = tcpip
router::myapp::enable::tcpip = true
router::myapp::address::tcpip = 127.0.0.1 # mtrouter address
router::myapp::port::tcpip = 8181 # mtrouter portOr use wildcard for all applications:
# Global router settings (all applications)
router::*::service = mtrouter
router::*::connect = tcpip
router::*::enable::tcpip = true
router::*::address::tcpip = 127.0.0.1
router::*::port::tcpip = 8181Check connection in application code:
#include "areg/appbase/Application.hpp"
#include "areg/base/NEUtilities.hpp"
int main()
{
Application::initApplication(true, true, true, true, true);
// Wait for router connection
NEUtilities::waitTimeout(1000); // Wait 1 second
// Check if connected
if (Application::isRouterConnected())
{
std::cout << "Connected to mtrouter" << std::endl;
}
else
{
std::cout << "Not connected to mtrouter" << std::endl;
}
Application::loadModel("MyModel");
Application::waitAppQuit(NECommon::WAIT_INFINITE);
Application::releaseApplication();
return 0;
}Distributed system setup:
Machine 1 (192.168.1.100) - mtrouter:
# config/router.init
router::*::address::tcpip = 192.168.1.100
router::*::port::tcpip = 8181
# Start router
./mtrouter --console --load="config/router.init"Machine 2 (192.168.1.101) - Provider:
# provider.init
router::provider::address::tcpip = 192.168.1.100
router::provider::port::tcpip = 8181Machine 3 (192.168.1.102) - Consumer:
# consumer.init
router::consumer::address::tcpip = 192.168.1.100
router::consumer::port::tcpip = 8181Problem: mtrouter exits immediately or fails to start.
Solution:
1. Check if port is already in use:
Linux:
sudo netstat -tlnp | grep 8181Windows:
netstat -ano | findstr 8181If port is in use: Kill the process or change port in configuration
2. Check configuration file:
# Verify file exists
ls -l areg.init
# Check syntax
cat areg.init | grep router3. Check permissions:
# Make executable
chmod +x mtrouter.elf
# Check file permissions
ls -l mtrouter.elfProblem: "Error: Address already in use"
Solution:
Find process using port:
Linux:
sudo lsof -i :8181Windows:
netstat -ano | findstr :8181Kill process:
Linux:
sudo kill -9 <PID>Windows:
taskkill /PID <PID> /FOr change port:
Edit areg.init:
router::*::port::tcpip = 9090 # Use different portProblem: Application fails to connect to mtrouter.
Solution:
1. Verify mtrouter is running:
# Check process
ps aux | grep mtrouter # Linux
tasklist | findstr mtrouter # Windows2. Check mtrouter console for connections:
Type --instances or -n in mtrouter console to see connected applications.
3. Verify application configuration:
Check myapp.init:
router::*::address::tcpip = 127.0.0.1 # Must match mtrouter
router::*::port::tcpip = 8181 # Must match mtrouter4. Verify router client is enabled:
Check application code:
Application::initApplication(
true, // logging
true, // service manager
true, // router client ← Must be true
true, // timer
true // watchdog
);5. Test network connectivity:
Same machine:
telnet 127.0.0.1 8181Different machine:
telnet 192.168.1.100 8181If telnet fails: Network/firewall issue
Problem: mtrouter running but remote applications can't connect.
Solution:
Linux (ufw):
# Allow port 8181
sudo ufw allow 8181/tcp
# Check status
sudo ufw statusLinux (firewalld):
# Allow port
sudo firewall-cmd --permanent --add-port=8181/tcp
sudo firewall-cmd --reloadWindows Firewall:
# Add rule
New-NetFirewallRule -DisplayName "Areg mtrouter" -Direction Inbound -Protocol TCP -LocalPort 8181 -Action AllowProblem: systemctl start fails
Solution:
Check service status:
sudo systemctl status mtrouter.serviceCheck logs:
sudo journalctl -u mtrouter.service -n 50Common issues:
1. Executable not found:
# Verify path in service file
grep ExecStart /etc/systemd/system/mtrouter.service
# Verify executable exists
ls -l /usr/local/bin/mtrouter2. Missing library:
# Check dependencies
ldd /usr/local/bin/mtrouter
# Copy missing library
sudo cp ./product/build/gnu-g++/linux-64-x86_64-release-shared/lib/libareg.so /usr/lib/
sudo ldconfig3. Permissions:
# Make executable
sudo chmod +x /usr/local/bin/mtrouterProblem: Service fails to start in Services app
Solution:
Check Event Viewer:
-
Win + R→eventvwr.msc - Windows Logs → Application
- Look for mtrouter errors
Common issues:
1. Missing DLL:
- Ensure
areg.dllis in same directory asmtrouter.exe
2. Permission issues:
- Install must be run as Administrator
3. Service already exists:
# Uninstall first
.\mtrouter.exe --uninstall
# Then reinstall
.\mtrouter.exe --installProblem: Type -n but shows no instances
Cause: No applications connected yet.
Solution:
1. Start an application:
# From multiprocessing project
./build/myapp_provider2. Check connection in mtrouter:
Type -n or --instances in mtrouter console.
3. If still shows 0 instances:
- Check application configuration (mtrouter address/port)
- Verify
Application::initApplication()has router enabled (3rd parameter =true) - Check application logs for connection errors
- Verify mtrouter is listening on correct address/port
Related Guides:
- Quick Project Setup - Create multiprocessing projects
- CMake Integration - Integration methods
- Persistence Syntax - Configuration file format
Configuration Files:
- areg.init - Default configuration
- mtrouter.service - Linux service file
Installation:
- install.cmake - CMake installation script
Source Code:
- mtrouter Module - Router implementation
Help: For questions, open a discussion or issue on GitHub.
Help us to make docs greater: See something is wrong, unclear or need a help? Submit a change, open a discussion or ask AREG SDK community a question.
Copyright © 2026, Aregtech, www.areg.tech, email: info[at]areg.tech