# VM on Golem Port Checker Server
The Port Checker Server provides a critical network verification service for the Golem Network, ensuring providers have proper port accessibility before joining the network. It verifies both local and external port accessibility through a simple REST API.
## System Architecture
```mermaid
graph TB
subgraph Port Checker
API[FastAPI Service]
Check[Port Checker]
Rate[Rate Limiter]
end
subgraph Providers
P1[Provider 1]
P2[Provider 2]
end
P1 & P2 -->|Verify Ports| API
API --> Check
Rate -->|Protect| API
```
## How It Works
### Port Verification Flow
```mermaid
sequenceDiagram
participant P as Provider
participant PC as Port Checker
P->>PC: Request Port Check
PC->>PC: Verify Local Binding
PC->>PC: Test External Access
PC-->>P: Verification Results
Note over PC: Multiple retries with delay
```
The port checker service verifies port accessibility through:
1. TCP connection attempts to specified ports
2. Retry mechanism with configurable attempts
3. Detailed error reporting
4. Concurrent port checking
## Installation
```bash
# Clone the repository
git clone https://github.com/golem/vm-on-golem.git
cd vm-on-golem/port-checker-server
# Install dependencies
poetry install
```
## Configuration
The server can be configured through environment variables:
```bash
# Server Settings
PORT_CHECKER_HOST="0.0.0.0"
PORT_CHECKER_PORT=9000
PORT_CHECKER_DEBUG=false
# Port Check Settings
PORT_CHECK_RETRIES=3
PORT_CHECK_RETRY_DELAY=1.0
PORT_CHECK_TIMEOUT=5.0
```
## API Reference
### Check Ports
```bash
POST /check-ports
```
Request:
```json
{
"provider_ip": "192.168.1.100",
"ports": [7466, 50800, 50801]
}
```
Response:
```json
{
"success": true,
"results": {
"7466": {
"accessible": true,
"error": null
},
"50800": {
"accessible": true,
"error": null
},
"50801": {
"accessible": false,
"error": "Connection refused"
}
},
"message": "Successfully verified 2 out of 3 ports"
}
```
### Health Check
```bash
GET /health
```
Response:
```json
{
"status": "ok"
}
```
## Technical Details
### Port Verification Process
1. **Request Validation**
- Valid IP address format
- Port numbers within range (1-65535)
- Maximum ports per request
2. **Verification Steps**
- TCP connection attempt
- Configurable timeout
- Multiple retry attempts
- Delay between retries
3. **Response Details**
- Per-port accessibility status
- Detailed error messages
- Overall success indicator
- Summary message
### Error Handling
The API uses standardized error responses:
```json
{
"detail": {
"code": "ERROR_CODE",
"message": "Human readable message"
}
}
```
Common error codes:
- `INVALID_IP`: Invalid IP address format
- `INVALID_PORT`: Port number out of range
- `CHECK_FAILED`: Port check operation failed
## Running the Server
### Manual Start
```bash
# Start the server
poetry run python run.py
# The server will be available at:
# - API: http://localhost:9000
# - Health Check: http://localhost:9000/health
# - OpenAPI Docs: http://localhost:9000/docs
```
### Running as a Systemd Service
The port checker can run as a systemd service for automatic startup and restart:
1. Install the service file:
```bash
sudo cp golem-port-checker.service /etc/systemd/system/
sudo systemctl daemon-reload
```
2. (Optional) Configure environment variables:
```bash
# Create environment file if you need custom settings
sudo mkdir -p /etc/golem
sudo nano /etc/golem/port-checker.env
# Example environment variables:
PORT_CHECKER_HOST=0.0.0.0
PORT_CHECKER_PORT=9000
PORT_CHECKER_DEBUG=false
```
3. Enable and start the service:
```bash
sudo systemctl enable golem-port-checker
sudo systemctl start golem-port-checker
```
4. Check service status:
```bash
sudo systemctl status golem-port-checker
```
5. View service logs:
```bash
# View all logs
sudo journalctl -u golem-port-checker
# Follow new logs
sudo journalctl -u golem-port-checker -f
```
The service is configured to:
- Start automatically on system boot
- Restart automatically if it crashes
- Log output to systemd journal
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run the tests
5. Submit a pull request
Raw data
{
"_id": null,
"home_page": "https://github.com/cryptobench/vm-on-golem",
"name": "golem-port-checker",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "golem, network, port-checker, connectivity, verification",
"author": "Phillip Jensen",
"author_email": "phillip+vm-on-golem@golemgrid.com",
"download_url": "https://files.pythonhosted.org/packages/d9/40/81bf6918867819317e2b028594076582dced8fdcf90fb8c8ed9c957b8d10/golem_port_checker-0.1.21.tar.gz",
"platform": null,
"description": "# VM on Golem Port Checker Server\n\nThe Port Checker Server provides a critical network verification service for the Golem Network, ensuring providers have proper port accessibility before joining the network. It verifies both local and external port accessibility through a simple REST API.\n\n## System Architecture\n\n```mermaid\ngraph TB\n subgraph Port Checker\n API[FastAPI Service]\n Check[Port Checker]\n Rate[Rate Limiter]\n end\n \n subgraph Providers\n P1[Provider 1]\n P2[Provider 2]\n end\n \n P1 & P2 -->|Verify Ports| API\n API --> Check\n Rate -->|Protect| API\n```\n\n## How It Works\n\n### Port Verification Flow\n\n```mermaid\nsequenceDiagram\n participant P as Provider\n participant PC as Port Checker\n \n P->>PC: Request Port Check\n PC->>PC: Verify Local Binding\n PC->>PC: Test External Access\n PC-->>P: Verification Results\n Note over PC: Multiple retries with delay\n```\n\nThe port checker service verifies port accessibility through:\n1. TCP connection attempts to specified ports\n2. Retry mechanism with configurable attempts\n3. Detailed error reporting\n4. Concurrent port checking\n\n## Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/golem/vm-on-golem.git\ncd vm-on-golem/port-checker-server\n\n# Install dependencies\npoetry install\n```\n\n## Configuration\n\nThe server can be configured through environment variables:\n\n```bash\n# Server Settings\nPORT_CHECKER_HOST=\"0.0.0.0\"\nPORT_CHECKER_PORT=9000\nPORT_CHECKER_DEBUG=false\n\n# Port Check Settings\nPORT_CHECK_RETRIES=3\nPORT_CHECK_RETRY_DELAY=1.0\nPORT_CHECK_TIMEOUT=5.0\n```\n\n## API Reference\n\n### Check Ports\n\n```bash\nPOST /check-ports\n```\n\nRequest:\n```json\n{\n \"provider_ip\": \"192.168.1.100\",\n \"ports\": [7466, 50800, 50801]\n}\n```\n\nResponse:\n```json\n{\n \"success\": true,\n \"results\": {\n \"7466\": {\n \"accessible\": true,\n \"error\": null\n },\n \"50800\": {\n \"accessible\": true,\n \"error\": null\n },\n \"50801\": {\n \"accessible\": false,\n \"error\": \"Connection refused\"\n }\n },\n \"message\": \"Successfully verified 2 out of 3 ports\"\n}\n```\n\n### Health Check\n\n```bash\nGET /health\n```\n\nResponse:\n```json\n{\n \"status\": \"ok\"\n}\n```\n\n## Technical Details\n\n### Port Verification Process\n\n1. **Request Validation**\n - Valid IP address format\n - Port numbers within range (1-65535)\n - Maximum ports per request\n\n2. **Verification Steps**\n - TCP connection attempt\n - Configurable timeout\n - Multiple retry attempts\n - Delay between retries\n\n3. **Response Details**\n - Per-port accessibility status\n - Detailed error messages\n - Overall success indicator\n - Summary message\n\n### Error Handling\n\nThe API uses standardized error responses:\n\n```json\n{\n \"detail\": {\n \"code\": \"ERROR_CODE\",\n \"message\": \"Human readable message\"\n }\n}\n```\n\nCommon error codes:\n- `INVALID_IP`: Invalid IP address format\n- `INVALID_PORT`: Port number out of range\n- `CHECK_FAILED`: Port check operation failed\n\n## Running the Server\n\n### Manual Start\n\n```bash\n# Start the server\npoetry run python run.py\n\n# The server will be available at:\n# - API: http://localhost:9000\n# - Health Check: http://localhost:9000/health\n# - OpenAPI Docs: http://localhost:9000/docs\n```\n\n### Running as a Systemd Service\n\nThe port checker can run as a systemd service for automatic startup and restart:\n\n1. Install the service file:\n```bash\nsudo cp golem-port-checker.service /etc/systemd/system/\nsudo systemctl daemon-reload\n```\n\n2. (Optional) Configure environment variables:\n```bash\n# Create environment file if you need custom settings\nsudo mkdir -p /etc/golem\nsudo nano /etc/golem/port-checker.env\n\n# Example environment variables:\nPORT_CHECKER_HOST=0.0.0.0\nPORT_CHECKER_PORT=9000\nPORT_CHECKER_DEBUG=false\n```\n\n3. Enable and start the service:\n```bash\nsudo systemctl enable golem-port-checker\nsudo systemctl start golem-port-checker\n```\n\n4. Check service status:\n```bash\nsudo systemctl status golem-port-checker\n```\n\n5. View service logs:\n```bash\n# View all logs\nsudo journalctl -u golem-port-checker\n\n# Follow new logs\nsudo journalctl -u golem-port-checker -f\n```\n\nThe service is configured to:\n- Start automatically on system boot\n- Restart automatically if it crashes\n- Log output to systemd journal\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Run the tests\n5. Submit a pull request\n",
"bugtrack_url": null,
"license": null,
"summary": "Port checking service for VM on Golem - Verify network connectivity for Golem providers",
"version": "0.1.21",
"project_urls": {
"Homepage": "https://github.com/cryptobench/vm-on-golem",
"Repository": "https://github.com/cryptobench/vm-on-golem"
},
"split_keywords": [
"golem",
" network",
" port-checker",
" connectivity",
" verification"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "656d825633f70921aa3e877ac8c0ede4af51b20c3ef0011318a2841881b7b9f5",
"md5": "94181171cc10381fae70ba109b8b34e1",
"sha256": "fd43a955e9538f7ea7b8bf06bf9fd1c4c6ce6335489dc3c2108288733328c96f"
},
"downloads": -1,
"filename": "golem_port_checker-0.1.21-py3-none-any.whl",
"has_sig": false,
"md5_digest": "94181171cc10381fae70ba109b8b34e1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 5935,
"upload_time": "2025-02-20T23:54:50",
"upload_time_iso_8601": "2025-02-20T23:54:50.277326Z",
"url": "https://files.pythonhosted.org/packages/65/6d/825633f70921aa3e877ac8c0ede4af51b20c3ef0011318a2841881b7b9f5/golem_port_checker-0.1.21-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d94081bf6918867819317e2b028594076582dced8fdcf90fb8c8ed9c957b8d10",
"md5": "3450b650dafd9c211c539dfe67c862c8",
"sha256": "170ac84dea91a95afca39bb0e2feab1a7c09ed8d1b1cefc56467cb77d2f43516"
},
"downloads": -1,
"filename": "golem_port_checker-0.1.21.tar.gz",
"has_sig": false,
"md5_digest": "3450b650dafd9c211c539dfe67c862c8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 5107,
"upload_time": "2025-02-20T23:54:53",
"upload_time_iso_8601": "2025-02-20T23:54:53.749799Z",
"url": "https://files.pythonhosted.org/packages/d9/40/81bf6918867819317e2b028594076582dced8fdcf90fb8c8ed9c957b8d10/golem_port_checker-0.1.21.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-20 23:54:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cryptobench",
"github_project": "vm-on-golem",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "golem-port-checker"
}
JSON
