# vRouter-agent
[](https://github.com/Unified-Sentinel-Data-Networks/vrouter-agent/actions/workflows/publish-vrouter-agent-s3.yml)
# Overview
vrouter-agent is a custom pip module built by USDN to handle and execute transaction from customer portal to each node.
# Requirements
- [python][python] >= 3.10
- [vpp][vpp] >= v20.06
- [multichain][multichain] > v2.3.1
- [Fast API][fastapi] > v0.115
- [FRR][frr] > v8.3
- [vrouter][vrouter] > v1.0.6
- [poetry][poetry] > v1.6.1
# Development
This project is managed by poetry. Use poetry to install and run script.
```bash
curl -sSL https://install.python-poetry.org | python3 -
poetry install
poetry run server
```
# Deployment
## Building RPM Package
To build an RPM package for AlmaLinux/RHEL deployment:
```bash
# Quick build (from project root)
./build-package.sh
# Or use the build system directly
./build/build.sh
```
The build system automatically:
- Creates a source tarball
- Builds the RPM package
- Handles Python 3.10+ requirements
- Sets up virtual environment for dependencies
- Configures systemd service integration
For detailed build documentation, see [`build/README.md`](build/README.md).
## Installation
```bash
# Install the RPM package
sudo dnf install ./dist/RPMS/noarch/vrouter-agent-*.rpm
# Enable and start the service
sudo systemctl enable vrouter-agent
sudo systemctl start vrouter-agent
```
### Run vrouter-agent as a service
vRouter depends on different services. In order to run vrouter-agent, these services must be up and running:
- VPP
- vRouter
- multichaind@{{chain}}. Chain is what defined in the nodecontrol
- FRR
#### Create service file:
```bash
sudo nano /etc/systemd/system/vrouter_agent.service
```
```ini
[Unit]
Description=VRouter Agent Server - API for VRouter tunnel configuration and telemetry monitoring
Requires=multichaind@{{chain}}
After=network.target multichaind@{{chain}} vpp.service vrouter.service
[Service]
Type=simple
ExecStartPre=/usr/local/bin/poetry/bin/poetry install
ExecStart=/usr/local/bin/poetry/bin/poetry run server
Restart=on-failure
RestartSec=30
WorkingDirectory=/opt/vrouter-agent/bin
# Optional: Set environment variables for configuration
# Environment=VRouterAgentHost=0.0.0.0
# Environment=VRouterAgentPort=8000
# Environment=VRouterAgentLogLevel=INFO
# Environment=VRouterAgentLogFile=/var/log/vrouter-agent.log
[Install]
WantedBy=multi-user.target
```
**Note**: You can configure the service by:
1. Setting environment variables in the service file (as shown above)
2. Modifying the `ExecStart` line to include command-line arguments:
```ini
ExecStart=/usr/local/bin/poetry/bin/poetry run server --host 0.0.0.0 --port 9000 --log-level DEBUG
```
#### Enable service at boot and start service:
```bash
sudo systemctl enable vrouter-agent && sudo systemctl start vrouter-agent
```
# Usage
## Command Line Options
The vrouter-agent supports various command-line options for configuration:
```bash
usage: vrouter-agent [-h] [--version] [--host HOST] [--port PORT]
[--log-file LOG_FILE] [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}]
VRouter Agent Server - API for VRouter tunnel configuration and telemetry monitoring
options:
-h, --help show this help message and exit
--version, -v Show version and exit
--host HOST Host to bind to (default: 127.0.0.1)
--port PORT, -p PORT Port to bind to (default: 8000)
--log-file LOG_FILE, -l LOG_FILE
Log file path (default: /var/log/vrouter-agent.log)
--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
Log level (default: INFO)
```
### Configuration Options
The vrouter-agent can be configured through:
1. **Command-line arguments** (highest priority)
2. **Environment variables** (medium priority)
3. **Default values** (lowest priority)
#### Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `VRouterAgentHost` | Server host address | `127.0.0.1` |
| `VRouterAgentPort` | Server port number | `8000` |
| `VRouterAgentLogFile` | Log file path | `/var/log/vrouter-agent.log` |
| `VRouterAgentLogLevel` | Log level | `INFO` |
### Examples
#### Basic Usage
```bash
# Run with default settings
vrouter-agent
# Show version
vrouter-agent --version
vrouter-agent -v
# Show help
vrouter-agent --help
vrouter-agent -h
```
#### Custom Configuration
```bash
# Run on specific host and port
vrouter-agent --host 0.0.0.0 --port 9000
# Enable debug logging with custom log file
vrouter-agent --log-level DEBUG --log-file /tmp/vrouter-debug.log
# Combine multiple options
vrouter-agent --host 192.168.1.100 --port 8080 --log-level WARNING --log-file /var/log/custom-vrouter.log
# Using short options
vrouter-agent -p 9000 -l /tmp/vrouter.log
```
#### Using Environment Variables
```bash
# Set environment variables
export VRouterAgentHost="0.0.0.0"
export VRouterAgentPort="9000"
export VRouterAgentLogLevel="DEBUG"
export VRouterAgentLogFile="/var/log/vrouter-debug.log"
# Run with environment configuration
vrouter-agent
# Override specific settings with command-line args
vrouter-agent --port 8080 # Uses env vars for other settings, but port 8080
```
### Logging
The vrouter-agent uses structured logging with the following features:
- **Dual output**: Logs to both console (stdout) and file simultaneously
- **Log rotation**: Automatic log file rotation at 1MB with compression
- **Configurable levels**: DEBUG, INFO, WARNING, ERROR, CRITICAL
- **Structured format**: JSON-like format with timestamps, levels, and context
#### Log Levels
| Level | Description | When to Use |
|-------|-------------|-------------|
| `DEBUG` | Detailed diagnostic information | Development and troubleshooting |
| `INFO` | General operational messages | Production monitoring (default) |
| `WARNING` | Warning messages for unusual situations | Production monitoring |
| `ERROR` | Error messages for handled failures | Production monitoring |
| `CRITICAL` | Critical errors that may cause shutdown | Production monitoring |
#### Log File Management
- **Default location**: `/var/log/vrouter-agent.log`
- **Rotation**: Automatic at 1MB file size
- **Compression**: Old logs are compressed as `.zip` files
- **Retention**: Managed by the logging system
- **Permissions**: Ensure the user running vrouter-agent has write access to the log directory
### Run manually
```bash
/usr/local/bin/vrouter-agent
```
## Troubleshooting
### Common Issues
1. **Permission denied for log file**:
```bash
# Ensure log directory exists and has proper permissions
sudo mkdir -p /var/log
sudo chown $(whoami):$(whoami) /var/log/vrouter-agent.log
# Or use a different log file location
vrouter-agent --log-file /tmp/vrouter-agent.log
```
2. **Port already in use**:
```bash
# Check what's using the port
sudo netstat -tulpn | grep :8000
# Use a different port
vrouter-agent --port 8080
```
3. **Service dependencies not running**:
```bash
# Check required services status
sudo systemctl status vpp
sudo systemctl status vrouter
sudo systemctl status multichaind@<chain-name>
# Check logs for more details
vrouter-agent --log-level DEBUG
```
4. **Configuration issues**:
```bash
# Verify configuration with debug logging
vrouter-agent --log-level DEBUG --log-file /tmp/debug.log
# Check environment variables
env | grep VRouterAgent
```
## Contributing
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
Please make sure to update tests as appropriate.
## License
[US Data Networks](https://usdatanetworks.com)
[python]: https://www.python.org/downloads/release/python-380/
[pip]: https://pip.pypa.io/en/stable/installation/
[vpp]: https://s3-docs.fd.io/vpp/22.06/
[multichain]: https://www.multichain.com/download-community/
[fastapi]: https://fastapi.tiangolo.com/
[frr]: https://gallery.ecr.aws/p6l6k3o9/frr
[vrouter]: https://github.com/Unified-Sentinel-Data-Networks/vrouter-pantheon
[poetry]: https://install.python-poetry.org
Raw data
{
"_id": null,
"home_page": "https://github.com/Unified-Sentinel-Data-Networks/vrouter-agent",
"name": "vrouter-agent",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "vrouter, networking, agent, multichain, wireguard",
"author": "Phan Dang",
"author_email": "phan.dang@usdatanetworks.com",
"download_url": "https://files.pythonhosted.org/packages/b4/28/3fdf9ad4c0580dbdb5295f3b7647218f2063962544baa3a29dadfe0e302a/vrouter_agent-1.5.4.tar.gz",
"platform": null,
"description": "# vRouter-agent\n[](https://github.com/Unified-Sentinel-Data-Networks/vrouter-agent/actions/workflows/publish-vrouter-agent-s3.yml)\n\n\n# Overview \nvrouter-agent is a custom pip module built by USDN to handle and execute transaction from customer portal to each node. \n\n\n# Requirements\n\n- [python][python] >= 3.10\n- [vpp][vpp] >= v20.06\n- [multichain][multichain] > v2.3.1\n- [Fast API][fastapi] > v0.115\n- [FRR][frr] > v8.3\n- [vrouter][vrouter] > v1.0.6\n- [poetry][poetry] > v1.6.1\n\n# Development\nThis project is managed by poetry. Use poetry to install and run script.\n \n```bash\ncurl -sSL https://install.python-poetry.org | python3 -\npoetry install \npoetry run server\n```\n\n# Deployment \n\n## Building RPM Package\n\nTo build an RPM package for AlmaLinux/RHEL deployment:\n\n```bash\n# Quick build (from project root)\n./build-package.sh\n\n# Or use the build system directly\n./build/build.sh\n```\n\nThe build system automatically:\n- Creates a source tarball\n- Builds the RPM package\n- Handles Python 3.10+ requirements\n- Sets up virtual environment for dependencies\n- Configures systemd service integration\n\nFor detailed build documentation, see [`build/README.md`](build/README.md).\n\n## Installation\n\n```bash\n# Install the RPM package\nsudo dnf install ./dist/RPMS/noarch/vrouter-agent-*.rpm\n\n# Enable and start the service\nsudo systemctl enable vrouter-agent\nsudo systemctl start vrouter-agent\n```\n\n### Run vrouter-agent as a service\n\nvRouter depends on different services. In order to run vrouter-agent, these services must be up and running:\n- VPP\n- vRouter\n- multichaind@{{chain}}. Chain is what defined in the nodecontrol \n- FRR\n\n#### Create service file: \n\n```bash\nsudo nano /etc/systemd/system/vrouter_agent.service\n```\n\n```ini\n[Unit]\nDescription=VRouter Agent Server - API for VRouter tunnel configuration and telemetry monitoring\nRequires=multichaind@{{chain}}\nAfter=network.target multichaind@{{chain}} vpp.service vrouter.service\n\n[Service]\nType=simple\nExecStartPre=/usr/local/bin/poetry/bin/poetry install \nExecStart=/usr/local/bin/poetry/bin/poetry run server \nRestart=on-failure\nRestartSec=30\nWorkingDirectory=/opt/vrouter-agent/bin\n\n# Optional: Set environment variables for configuration\n# Environment=VRouterAgentHost=0.0.0.0\n# Environment=VRouterAgentPort=8000\n# Environment=VRouterAgentLogLevel=INFO\n# Environment=VRouterAgentLogFile=/var/log/vrouter-agent.log\n\n[Install]\nWantedBy=multi-user.target\n```\n\n**Note**: You can configure the service by:\n1. Setting environment variables in the service file (as shown above)\n2. Modifying the `ExecStart` line to include command-line arguments:\n ```ini\n ExecStart=/usr/local/bin/poetry/bin/poetry run server --host 0.0.0.0 --port 9000 --log-level DEBUG\n ```\n\n#### Enable service at boot and start service:\n\n```bash\nsudo systemctl enable vrouter-agent && sudo systemctl start vrouter-agent \n```\n\n# Usage\n\n## Command Line Options\n\nThe vrouter-agent supports various command-line options for configuration:\n\n```bash\nusage: vrouter-agent [-h] [--version] [--host HOST] [--port PORT] \n [--log-file LOG_FILE] [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}]\n\nVRouter Agent Server - API for VRouter tunnel configuration and telemetry monitoring\n\noptions:\n -h, --help show this help message and exit\n --version, -v Show version and exit\n --host HOST Host to bind to (default: 127.0.0.1)\n --port PORT, -p PORT Port to bind to (default: 8000)\n --log-file LOG_FILE, -l LOG_FILE\n Log file path (default: /var/log/vrouter-agent.log)\n --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}\n Log level (default: INFO)\n```\n\n### Configuration Options\n\nThe vrouter-agent can be configured through:\n1. **Command-line arguments** (highest priority)\n2. **Environment variables** (medium priority)\n3. **Default values** (lowest priority)\n\n#### Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `VRouterAgentHost` | Server host address | `127.0.0.1` |\n| `VRouterAgentPort` | Server port number | `8000` |\n| `VRouterAgentLogFile` | Log file path | `/var/log/vrouter-agent.log` |\n| `VRouterAgentLogLevel` | Log level | `INFO` |\n\n### Examples\n\n#### Basic Usage\n\n```bash\n# Run with default settings\nvrouter-agent\n\n# Show version\nvrouter-agent --version\nvrouter-agent -v\n\n# Show help\nvrouter-agent --help\nvrouter-agent -h\n```\n\n#### Custom Configuration\n\n```bash\n# Run on specific host and port\nvrouter-agent --host 0.0.0.0 --port 9000\n\n# Enable debug logging with custom log file\nvrouter-agent --log-level DEBUG --log-file /tmp/vrouter-debug.log\n\n# Combine multiple options\nvrouter-agent --host 192.168.1.100 --port 8080 --log-level WARNING --log-file /var/log/custom-vrouter.log\n\n# Using short options\nvrouter-agent -p 9000 -l /tmp/vrouter.log\n```\n\n#### Using Environment Variables\n\n```bash\n# Set environment variables\nexport VRouterAgentHost=\"0.0.0.0\"\nexport VRouterAgentPort=\"9000\"\nexport VRouterAgentLogLevel=\"DEBUG\"\nexport VRouterAgentLogFile=\"/var/log/vrouter-debug.log\"\n\n# Run with environment configuration\nvrouter-agent\n\n# Override specific settings with command-line args\nvrouter-agent --port 8080 # Uses env vars for other settings, but port 8080\n```\n\n### Logging\n\nThe vrouter-agent uses structured logging with the following features:\n\n- **Dual output**: Logs to both console (stdout) and file simultaneously\n- **Log rotation**: Automatic log file rotation at 1MB with compression\n- **Configurable levels**: DEBUG, INFO, WARNING, ERROR, CRITICAL\n- **Structured format**: JSON-like format with timestamps, levels, and context\n\n#### Log Levels\n\n| Level | Description | When to Use |\n|-------|-------------|-------------|\n| `DEBUG` | Detailed diagnostic information | Development and troubleshooting |\n| `INFO` | General operational messages | Production monitoring (default) |\n| `WARNING` | Warning messages for unusual situations | Production monitoring |\n| `ERROR` | Error messages for handled failures | Production monitoring |\n| `CRITICAL` | Critical errors that may cause shutdown | Production monitoring |\n\n#### Log File Management\n\n- **Default location**: `/var/log/vrouter-agent.log`\n- **Rotation**: Automatic at 1MB file size\n- **Compression**: Old logs are compressed as `.zip` files\n- **Retention**: Managed by the logging system\n- **Permissions**: Ensure the user running vrouter-agent has write access to the log directory\n\n### Run manually\n\n```bash\n/usr/local/bin/vrouter-agent\n```\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Permission denied for log file**:\n ```bash\n # Ensure log directory exists and has proper permissions\n sudo mkdir -p /var/log\n sudo chown $(whoami):$(whoami) /var/log/vrouter-agent.log\n \n # Or use a different log file location\n vrouter-agent --log-file /tmp/vrouter-agent.log\n ```\n\n2. **Port already in use**:\n ```bash\n # Check what's using the port\n sudo netstat -tulpn | grep :8000\n \n # Use a different port\n vrouter-agent --port 8080\n ```\n\n3. **Service dependencies not running**:\n ```bash\n # Check required services status\n sudo systemctl status vpp\n sudo systemctl status vrouter\n sudo systemctl status multichaind@<chain-name>\n \n # Check logs for more details\n vrouter-agent --log-level DEBUG\n ```\n\n4. **Configuration issues**:\n ```bash\n # Verify configuration with debug logging\n vrouter-agent --log-level DEBUG --log-file /tmp/debug.log\n \n # Check environment variables\n env | grep VRouterAgent\n ```\n\n## Contributing\n\nPull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.\n\nPlease make sure to update tests as appropriate.\n\n## License\n\n[US Data Networks](https://usdatanetworks.com)\n\n[python]: https://www.python.org/downloads/release/python-380/\n[pip]: https://pip.pypa.io/en/stable/installation/\n[vpp]: https://s3-docs.fd.io/vpp/22.06/\n[multichain]: https://www.multichain.com/download-community/\n[fastapi]: https://fastapi.tiangolo.com/\n[frr]: https://gallery.ecr.aws/p6l6k3o9/frr\n[vrouter]: https://github.com/Unified-Sentinel-Data-Networks/vrouter-pantheon\n[poetry]: https://install.python-poetry.org",
"bugtrack_url": null,
"license": "US Data Networks. All rights reserved.",
"summary": "USDN vRouter-agent to execute order on each node",
"version": "1.5.4",
"project_urls": {
"Documentation": "https://github.com/Unified-Sentinel-Data-Networks/vrouter-agent/blob/main/README.md",
"Homepage": "https://github.com/Unified-Sentinel-Data-Networks/vrouter-agent",
"Repository": "https://github.com/Unified-Sentinel-Data-Networks/vrouter-agent"
},
"split_keywords": [
"vrouter",
" networking",
" agent",
" multichain",
" wireguard"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "560bd54feaa3640de513e507f569e8ad6540436e1ca0d44de7cd97d6cadc5a45",
"md5": "8cd4d1ae95197065235e0e084c720d8d",
"sha256": "6b6bac45f2c6bd6bb68ee78b465e4a7035c99c30bf5c9c0b7b0d9012041dd0e7"
},
"downloads": -1,
"filename": "vrouter_agent-1.5.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8cd4d1ae95197065235e0e084c720d8d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 216718,
"upload_time": "2025-09-12T16:39:17",
"upload_time_iso_8601": "2025-09-12T16:39:17.345781Z",
"url": "https://files.pythonhosted.org/packages/56/0b/d54feaa3640de513e507f569e8ad6540436e1ca0d44de7cd97d6cadc5a45/vrouter_agent-1.5.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b4283fdf9ad4c0580dbdb5295f3b7647218f2063962544baa3a29dadfe0e302a",
"md5": "64d0eee95fd4ba1698fe2563ff15ffbe",
"sha256": "8cf8a4252320038cc14e7df40bb2641b71831bb80fa84c837b0f442c0adc1f9b"
},
"downloads": -1,
"filename": "vrouter_agent-1.5.4.tar.gz",
"has_sig": false,
"md5_digest": "64d0eee95fd4ba1698fe2563ff15ffbe",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 162860,
"upload_time": "2025-09-12T16:39:18",
"upload_time_iso_8601": "2025-09-12T16:39:18.819868Z",
"url": "https://files.pythonhosted.org/packages/b4/28/3fdf9ad4c0580dbdb5295f3b7647218f2063962544baa3a29dadfe0e302a/vrouter_agent-1.5.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-12 16:39:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Unified-Sentinel-Data-Networks",
"github_project": "vrouter-agent",
"github_not_found": true,
"lcname": "vrouter-agent"
}
JSON
