{"id":38806048,"url":"https://github.com/radiusmethod/socketzero-marketplace-offering","last_synced_at":"2026-01-17T12:50:38.730Z","repository":{"id":305975152,"uuid":"1020402585","full_name":"radiusmethod/socketzero-marketplace-offering","owner":"radiusmethod","description":"Deploy SocketZero on AWS with Terraform - includes VPC, load balancer, SSL, and test server","archived":false,"fork":false,"pushed_at":"2025-07-22T23:51:40.000Z","size":19,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-23T01:22:01.418Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"HCL","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/radiusmethod.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-15T20:14:41.000Z","updated_at":"2025-07-22T23:51:44.000Z","dependencies_parsed_at":"2025-07-23T01:34:23.841Z","dependency_job_id":null,"html_url":"https://github.com/radiusmethod/socketzero-marketplace-offering","commit_stats":null,"previous_names":["radiusmethod/socketzero-marketplace-offering"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/radiusmethod/socketzero-marketplace-offering","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/radiusmethod%2Fsocketzero-marketplace-offering","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/radiusmethod%2Fsocketzero-marketplace-offering/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/radiusmethod%2Fsocketzero-marketplace-offering/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/radiusmethod%2Fsocketzero-marketplace-offering/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/radiusmethod","download_url":"https://codeload.github.com/radiusmethod/socketzero-marketplace-offering/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/radiusmethod%2Fsocketzero-marketplace-offering/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28508638,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T11:50:55.898Z","status":"ssl_error","status_checked_at":"2026-01-17T11:50:55.569Z","response_time":85,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-17T12:50:38.177Z","updated_at":"2026-01-17T12:50:38.717Z","avatar_url":"https://github.com/radiusmethod.png","language":"HCL","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SocketZero AWS Marketplace Terraform Examples\n\nThis guide provides complete instructions to setup the SocketZero Receiver EC2 instance from the [AWS Marketplace SocketZero AMI](https://aws.amazon.com/marketplace/pp/prodview-qjqz3izsnofoo), all of the supporting AWS infrastructure, and a sample tunnel using a basic webserver. It also provides examples to implement new tunnels and tear down the example tunnel.\n\nDeploy SocketZero on AWS using Terraform with best practices for security and production readiness.\n\n## Table of Contents\n\n- [Important Notes](#important-notes)\n  - [SocketZero Client Application Requirement](#socketzero-client-application-requirement)\n  - [Subscription Benefits](#subscription-benefits)\n  - [Internet Connection Requirement](#internet-connection-requirement)\n  - [SSH Access](#ssh-access)\n- [Quick Start Guide](#quick-start-guide)\n  - [Prerequisites](#prerequisites)\n  - [3-Step Deployment](#3-step-deployment)\n  - [Finding Your AMI ID](#finding-your-ami-id)\n- [Security \u0026 Encryption](#security--encryption)\n- [Architecture](#architecture)\n- [Project Structure](#project-structure)\n- [Configuration Options](#configuration-options)\n- [Example Configuration](#example-configuration)\n- [SocketZero Configuration](#socketzero-configuration)\n- [Load Balancer \u0026 DNS](#load-balancer--dns)\n- [Testing Your Deployment](#testing-your-deployment)\n- [Install SocketZero client application](#install-socketzero-client-application)\n  - [SocketZero client application](#socketzero-client-application)\n  - [Linux Installation](#linux-installation)\n- [Testing Your Setup](#testing-your-setup)\n  - [Security Notes](#security-notes)\n  - [Verification Steps](#verification-steps)\n- [Adding Additional Tunnels](#adding-additional-tunnels)\n  - [Requirements for Additional Tunnels](#requirements-for-additional-tunnels)\n  - [Common Tunnel Examples](#common-tunnel-examples)\n  - [Troubleshooting Additional Tunnels](#troubleshooting-additional-tunnels)\n- [Updates \u0026 Management](#updates--management)\n- [Troubleshooting](#troubleshooting)\n- [Support](#support)\n\n---\n\n## Important Notes\n\n### SocketZero Client Application Requirement\nThis SocketZero AMI extends the functionality of the SocketZero Client Application and without it, this product has very limited utility. Please note that the SocketZero Client Application does not require its own licensing and is provided **free of charge** with the subscription to this SocketZero AMI offering. Client installation instructions are provided in the **[Install SocketZero client application](#install-socketzero-client-application)** section below.\n\n### Subscription Benefits\nCustomers receive full access to SocketZero after subscribing to the AMI and up to **5 free connections**. Additional connections may require separate licensing arrangements.\n\n### Internet Connection Requirement\nThis product requires an internet connection to deploy properly. Terraform will download and install nginx for the test web server during deployment.\n\n\u003e ⚠️ **Important**: Ensure your deployment environment has outbound internet access for package downloads and AWS service communications.\n\n### SSH Access\nThe SocketZero AMI uses **`ubuntu`** as the SSH username.\n\n## Quick Start Guide\n\n### Prerequisites\n- **Subscribe to SocketZero on AWS Marketplace**: [Get SocketZero AMI](https://aws.amazon.com/marketplace/pp/prodview-qjqz3izsnofoo)\n- AWS CLI configured with appropriate permissions\n- Terraform installed (\u003e= 1.0)\n- Existing Route53 public hosted zone with a registered domain using Route53 nameservers\n- IP addresses for security group access\n\n### 3-Step Deployment\n\n#### Step 1: Clone and Configure\n```bash\n# Navigate to the terraform examples\ncd socketzero-marketplace-offerings\n\n# Copy and edit the configuration\ncp terraform.tfvars.example terraform.tfvars\n```\n\n#### Step 2: Update Configuration\nEdit `terraform.tfvars` with your values:\n```hcl\n# Your existing Route53 hosted zone (required)\naws_route53_zone = \"your-domain.com\"\n\n# Port that SocketZero receiver listens on\nreceiver_port = 9997\n\n# IP addresses/CIDRs allowed to access the load balancer\ntrusted_ip_cidrs = [\"YOUR.IP.ADDRESS/32\"]\n\n# SocketZero version and AMI configuration\nsocketzero_version = \"stable-1.0.0\"\nsocketzero_ami_id  = \"ami-REPLACE_WITH_YOUR_AMI_ID\"  # See \"Finding Your AMI ID\" below\n\n# Optional: Custom KMS key ID for EBS encryption (if not set, uses AWS-managed key)\n# kms_key_id = \"arn:aws:kms:us-east-1:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab\"\n```\n\n#### Step 2.5: Finding Your AMI ID\n\n**Important**: SocketZero provides a unique AMI ID for each subscription. You need to find your specific AMI ID:\n\n**Method 1: AWS Console**\n1. Go to [SocketZero on AWS Marketplace](https://aws.amazon.com/marketplace/pp/prodview-qjqz3izsnofoo)\n2. Click \"Continue to Subscribe\" (if not already subscribed)\n3. Click \"Continue to Configuration\"\n4. Your unique AMI ID will be displayed (e.g., `ami-08245aa9e252ea9f2`)\n5. Copy this AMI ID and update your `terraform.tfvars` file\n\n**Method 2: AWS CLI**\n```bash\n# Find your SocketZero AMI (after subscribing)\naws ec2 describe-images \\\n  --owners aws-marketplace \\\n  --filters \"Name=product-code,Values=SOCKETZERO_PRODUCT_CODE\" \\\n  --query 'Images[0].ImageId' \\\n  --output text\n```\n\n**Method 3: EC2 Console**\n1. Go to EC2 → Launch Instance\n2. Browse more AMIs → AWS Marketplace AMIs\n3. Search for \"SocketZero\"\n4. Your subscribed AMI will show with its unique ID\n\n#### Step 3: Deploy\n```bash\n# Initialize and deploy\nterraform init\nterraform plan\nterraform apply\n```\n\n**That's it!** Your SocketZero receiver will be available at `https://ami.your-domain.com`\n\n## Security \u0026 Encryption\n\n### Important Security Information\n\n⚠️ **CRITICAL**: The SocketZero AMI is **unencrypted per AWS Marketplace requirements**, but **EBS encryption is automatically enabled** in these Terraform examples for production security.\n\n#### Why is the AMI unencrypted?\n\nAWS Marketplace requires AMIs to be distributed unencrypted to ensure compatibility across all AWS accounts and regions. This does not compromise SocketZero's security capabilities.\n\n#### How Encryption is Enabled\n\n**Our Terraform examples automatically enable encryption:**\n```hcl\nroot_block_device {\n  encrypted   = true\n  volume_type = \"gp3\"\n  volume_size = 8\n  kms_key_id  = var.kms_key_id  # Optional: use your own KMS key\n}\n```\n\n**Alternative encryption methods:**\n\n\u003cdetails\u003e\n\u003csummary\u003eAWS Console Method\u003c/summary\u003e\n\nIn the EC2 launch wizard:\n1. Expand \"Configure Storage\"\n2. Check \"Encrypted\" \n3. Select your KMS key\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eAWS CLI Method\u003c/summary\u003e\n\n```bash\naws ec2 run-instances \\\n  --image-id ami-08a1c83424ca22b36 \\\n  --instance-type t3.small \\\n  --block-device-mappings '[{\"DeviceName\":\"/dev/sda1\",\"Ebs\":{\"Encrypted\":true,\"VolumeType\":\"gp3\"}}]'\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eEnable Account-Wide Encryption\u003c/summary\u003e\n\n```bash\naws ec2 enable-ebs-encryption-by-default --region us-east-1\n```\n\u003c/details\u003e\n\n#### Security Features\n\nAll SocketZero security features work perfectly with encrypted storage:\n- ✅ **Zero-trust networking**\n- ✅ **Post-quantum cryptography**  \n- ✅ **End-to-end encryption**\n- ✅ **Identity-based access controls**\n- ✅ **Certificate-based authentication**\n- ✅ **EBS encryption enabled** by default\n- ✅ **Security groups** restricting access to trusted IPs\n- ✅ **Private subnets** for internal resources\n- ✅ **TLS/SSL** termination at load balancer\n\n#### Security Best Practices\n\n1. **Always encrypt in production** (done automatically in our examples)\n2. **Use customer-managed KMS keys** for enhanced control\n3. **Enable encryption by default** in your AWS account\n4. **Regularly rotate encryption keys** per your security policy\n\n## Architecture\n\nThis Terraform configuration creates:\n- **VPC** with public/private subnets across multiple AZs\n- **Application Load Balancer** with TLS termination\n- **SocketZero Receiver** instance (encrypted EBS)\n- **Test Web Server** for demonstration\n- **Route53 DNS** record\n- **Security Groups** with minimal required access\n- **IAM Roles** for instance permissions\n\nAll infrastructure is defined in easy-to-read `.tf` files in the root directory.\n\n## Project Structure\n\n```\nsocketzero-marketplace-offering/\n├── README.md                    # Complete documentation and setup guide\n├── main.tf                     # Terraform provider and requirements\n├── variables.tf                # Input variables and configuration\n├── outputs.tf                  # Deployment outputs and endpoints\n├── locals.tf                   # Local values and computed config\n├── terraform.tfvars.example    # Example configuration file\n├── validate.sh                 # Validation script for deployment\n├── vpc.tf                      # VPC and networking configuration\n├── iam.tf                      # IAM roles and policies\n├── receiver-ec2.tf             # SocketZero receiver instance\n├── test-webserver-ec2.tf       # Test web server for demonstration\n├── lb.tf                       # Application Load Balancer configuration\n├── dns.tf                      # Route53 DNS records\n└── templates/\n    └── config.json.tmpl        # SocketZero receiver configuration template\n```\n\n## Configuration Options\n\n| Variable | Description | Default | Required |\n|----------|-------------|---------|----------|\n| `aws_route53_zone` | Existing Route53 zone | - | ✅ |\n| `receiver_port` | SocketZero receiver port | `9997` | ✅ |\n| `trusted_ip_cidrs` | IPs allowed to access ALB | `[]` | ✅ |\n| `socketzero_version` | SocketZero version identifier | `stable-1.0.0` | ❌ |\n| `socketzero_ami_id` | Your unique SocketZero AMI ID | See Step 2.5 | ✅ |\n| `kms_key_id` | KMS key for encryption | AWS managed | ❌ |\n\n\u003e 💡 **Important**: Each SocketZero subscription receives a unique AMI ID. You must subscribe at [AWS Marketplace](https://aws.amazon.com/marketplace/pp/prodview-qjqz3izsnofoo) and find your specific AMI ID (see Step 2.5 above).\n\n## Example Configuration\n\n```hcl\n# terraform.tfvars\naws_route53_zone = \"example.com\"\nreceiver_port    = 9997\ntrusted_ip_cidrs = [\n  \"203.0.113.1/32\",    # Your IP\n  \"198.51.100.0/24\",   # Office network\n]\nsocketzero_version = \"stable-1.0.0\"\nsocketzero_ami_id  = \"ami-08245aa9e252ea9f2\"  # Your unique AMI ID from Marketplace\n```\n\n## SocketZero Configuration\n\n### Configuration File Location\n- **Path:** `/opt/socketzero/config.json`\n- **Generated:** From Terraform template at instance launch\n- **Updates:** Edit file directly on instance for immediate changes\n\n### Example Configuration\n```json\n{\n  \"authz\": false,\n  \"cookie\": \"__Host-socketzero-authservice-session-id-cookie\",\n  \"redisHost\": \"localhost:6379\",\n  \"redisPassword\": \"\",\n  \"upgraderDisabled\": true,\n  \"tunnels\": [\n    {\n      \"hostname\": \"web-server.apps.socketzero.com\",\n      \"listenPort\": 80,\n      \"targetPort\": 80,\n      \"transport\": \"tcp\",\n      \"targetHost\": \"10.10.128.10\",\n      \"friendlyName\": \"Web Server Tunnel\",\n      \"roles\": [\"admin\"]\n    }\n  ]\n}\n```\n\n### Updating Configuration\n\n**For immediate changes on existing instance:**\n```bash\n# Edit the config file\nsudo vi /opt/socketzero/config.json\n\n# Restart the service to apply changes\nsudo systemctl restart socketzero-receiver\n\n# Check service status\nsudo systemctl status socketzero-receiver\n```\n\n**For persistent changes across redeployments:**\n- Update the template in `templates/config.json.tmpl`\n- Modify variables in `terraform.tfvars`\n- Re-apply Terraform: `terraform apply`\n\n## Load Balancer \u0026 DNS\n\n### How it Works\n- The SocketZero receiver is deployed behind an AWS Application Load Balancer (ALB)\n- ALB listens on **port 443 (HTTPS)** and forwards to receiver on configured port (default: 9997)\n- Only IPs in `trusted_ip_cidrs` can access the ALB\n- A CNAME record (e.g., `ami.your-domain.com`) points to the ALB in Route53\n\n### After Deployment\n- Connect using: `https://ami.your-domain.com`\n- Add this hostname in your SocketZero client configuration\n- Use **port 443** for the connection\n\n## Testing Your Deployment\n\n## Install SocketZero client application\n\nTo connect to your SocketZero receiver and access the tunneled services, you need to install the SocketZero client:\n\n### SocketZero client application\n\n| | | |\n|----------|-----|-----|\n| **macOS** | [AMD64](https://radiusmethod-public-downloads.s3.us-east-1.amazonaws.com/socketzero/installer/v0.5.9/SocketZero-0.5.9-x64.pkg) | [ARM64](https://radiusmethod-public-downloads.s3.us-east-1.amazonaws.com/socketzero/installer/v0.5.9/SocketZero-0.5.9-arm64.pkg) |\n| **Linux** | [AMD64](https://radiusmethod-public-downloads.s3.us-east-1.amazonaws.com/socketzero/installer/v0.5.9/SocketZero-0.5.9-x86_64.AppImage) | [ARM64](https://radiusmethod-public-downloads.s3.us-east-1.amazonaws.com/socketzero/installer/v0.5.9/SocketZero-0.5.9-arm64.AppImage) |\n| **Windows** | [AMD64](https://radiusmethod-public-downloads.s3.us-east-1.amazonaws.com/socketzero/installer/v0.5.9/SocketZero-0.5.9-x64.exe) | [ARM64](https://radiusmethod-public-downloads.s3.us-east-1.amazonaws.com/socketzero/installer/v0.5.9/SocketZero-0.5.9-arm64.exe) |\n\n#### Linux Installation\n\nLinux installation requires a few additional steps:\n\n1. Download the AppImage from the table above\n2. Make it executable: `chmod +x SocketZero.AppImage`\n3. Run it: `./SocketZero.AppImage`\n4. Linux will prompt for sudo password to install the service (on first launch)\n5. The app launches normally\n\n## Testing Your Setup\n\n1. **Connect with SocketZero Client**\n   - Open the SocketZero client application and select the \"+\" symbol\n   - Enter a **Name** such as Test-Web-Server\n   - Enter the following **Host name / address**: `ami.your-domain.com`\n2. **Open browser** and navigate to: `http://web-server.apps.socketzero.com`\n3. **Expected result**: You should see \"Hello World from [hostname]\"\n4. **Verify tunnel**: The traffic is flowing through your SocketZero receiver to the private web server\n\nIf you see the web page, congratulations! Your SocketZero deployment is working correctly.\n\n### Security Notes\n\n- **Client Authentication**: The client connects securely to your receiver using HTTPS\n- **Zero Trust**: No direct access to private resources without going through SocketZero\n- **Encrypted Tunnels**: All traffic between client and receiver is encrypted\n\n### Verification Steps\n\n- **Check EC2 console**: Confirm encrypted volumes are enabled\n- **Verify security groups**: Only trusted IPs can access the load balancer  \n- **Test tunnel access**: Private web server accessible only through SocketZero\n\n## Adding Additional Tunnels\n\nAfter your SocketZero deployment is working, you can add tunnels to other applications and services.\n\n### Requirements for Additional Tunnels\n\n**Network Accessibility:**\n- Target applications/assets must be accessible from the SocketZero receiver instance\n- This means they should be in the same VPC, connected VPCs, or accessible via VPN/Transit Gateway\n- Security groups must allow traffic from the SocketZero receiver to the target service\n\n**Common Scenarios:**\n- **Same VPC**: Applications in private subnets of the `socketzero-ami` VPC\n- **Connected VPCs**: Applications in peered VPCs or Transit Gateway connected networks\n- **On-premises**: Applications accessible via VPN or Direct Connect\n- **Public services**: Internet-accessible applications (with proper security)\n\n### Adding a New Tunnel\n\n1. **Verify Network Connectivity**:\n   Test connectivity from the SocketZero receiver to your target service:\n   ```bash\n   # Connect to SocketZero receiver via SSH or Session Manager\n   ssh -i your-key.pem ubuntu@\u003creceiver-public-ip\u003e\n   # OR: EC2 → Instances → socketzero-receiver → Connect → Session Manager\n   \n   # Test connectivity (replace with your target IP/hostname and port)\n   telnet 10.0.1.100 3306  # Example: MySQL database\n   curl -I http://10.0.2.50:8080  # Example: Web application\n   ```\n\n2. **Update Security Groups** (if needed):\n   - Ensure target service security groups allow traffic from SocketZero receiver\n   - Update receiver security group if additional outbound rules are needed\n\n3. **Update SocketZero Configuration**:\n   ```bash\n   # Connect to SocketZero receiver\n   # Backup current configuration\n   sudo cp /opt/socketzero/config.json /opt/socketzero/config.json.backup\n   \n   # Edit configuration to add new tunnel\n   sudo nano /opt/socketzero/config.json\n   ```\n\n4. **Example Updated Configuration**:\n   ```json\n   {\n     \"authz\": false,\n     \"cookie\": \"__Host-socketzero-authservice-session-id-cookie\",\n     \"redisHost\": \"localhost:6379\",\n     \"redisPassword\": \"\",\n     \"upgraderDisabled\": true,\n     \"tunnels\": [\n       {\n         \"hostname\": \"web-server.apps.socketzero.com\",\n         \"listenPort\": 80,\n         \"targetPort\": 80,\n         \"transport\": \"tcp\",\n         \"targetHost\": \"10.10.128.45\",\n         \"friendlyName\": \"Web Server Tunnel\",\n         \"roles\": [\"admin\"]\n       },\n       {\n         \"hostname\": \"database.apps.socketzero.com\",\n         \"listenPort\": 3306,\n         \"targetPort\": 3306,\n         \"transport\": \"tcp\",\n         \"targetHost\": \"10.0.1.100\",\n         \"friendlyName\": \"MySQL Database\",\n         \"roles\": [\"admin\"]\n       },\n       {\n         \"hostname\": \"api.apps.socketzero.com\",\n         \"listenPort\": 8080,\n         \"targetPort\": 8080,\n         \"transport\": \"tcp\",\n         \"targetHost\": \"internal-api.company.local\",\n         \"friendlyName\": \"Internal API\",\n         \"roles\": [\"admin\"]\n       }\n     ]\n   }\n   ```\n\n5. **Apply Configuration Changes**:\n   ```bash\n   # Validate JSON syntax\n   cat /opt/socketzero/config.json | jq\n   \n   # Restart SocketZero service\n   sudo systemctl restart socketzero-receiver\n   \n   # Verify service is running\n   sudo systemctl status socketzero-receiver\n   \n   # Check logs for any errors\n   sudo journalctl -u socketzero-receiver -f\n   ```\n\n6. **Test New Tunnels**:\n   - Connect with your SocketZero client\n   - Access the new tunnel endpoints:\n     - `http://database.apps.socketzero.com`\n     - `http://api.apps.socketzero.com`\n\n### Tunnel Configuration Parameters\n\n| Parameter | Description | Example |\n|-----------|-------------|---------|\n| `hostname` | Client-side hostname for accessing the tunnel | `myapp.apps.socketzero.com` |\n| `listenPort` | Port the tunnel listens on (client-side) | `8080` |\n| `targetPort` | Port on the target service | `80` |\n| `transport` | Protocol (usually `tcp`) | `tcp` |\n| `targetHost` | IP or hostname of target service | `10.0.1.50` or `myservice.local` |\n| `friendlyName` | Display name in SocketZero client | `My Application` |\n| `roles` | Access control (typically `[\"admin\"]`) | `[\"admin\"]` |\n\n### Common Tunnel Examples\n\n**Database Access:**\n```json\n{\n  \"hostname\": \"postgres.apps.socketzero.com\",\n  \"listenPort\": 5432,\n  \"targetPort\": 5432,\n  \"transport\": \"tcp\",\n  \"targetHost\": \"10.0.1.200\",\n  \"friendlyName\": \"PostgreSQL Database\",\n  \"roles\": [\"admin\"]\n}\n```\n\n**SSH Access:**\n```json\n{\n  \"hostname\": \"server.apps.socketzero.com\",\n  \"listenPort\": 22,\n  \"targetPort\": 22,\n  \"transport\": \"tcp\",\n  \"targetHost\": \"10.0.2.100\",\n  \"friendlyName\": \"Internal Server SSH\",\n  \"roles\": [\"admin\"]\n}\n```\n\n**Web Applications:**\n```json\n{\n  \"hostname\": \"grafana.apps.socketzero.com\",\n  \"listenPort\": 3000,\n  \"targetPort\": 3000,\n  \"transport\": \"tcp\",\n  \"targetHost\": \"monitoring.internal.company.com\",\n  \"friendlyName\": \"Grafana Dashboard\",\n  \"roles\": [\"admin\"]\n}\n```\n\n### Troubleshooting Additional Tunnels\n\n**Connection Issues:**\n- Verify network connectivity from receiver to target\n- Check security group rules allow required ports\n- Ensure target service is running and accessible\n- Test with `telnet` or `curl` from receiver instance\n\n**Configuration Issues:**\n- Validate JSON syntax with `jq`\n- Check SocketZero service logs: `sudo journalctl -u socketzero-receiver -f`\n- Ensure no port conflicts between tunnels\n- Verify hostname uniqueness for each tunnel\n\n### Persistent Configuration (via Terraform)\n\n**For changes that persist across redeployments:**\n- Update the template in `templates/config.json.tmpl`\n- Modify variables in `terraform.tfvars`\n- Re-apply Terraform: `terraform apply`\n\n**For immediate changes on existing instance:**\n- Edit the config file directly: `sudo nano /opt/socketzero/config.json`\n- Restart the service: `sudo systemctl restart socketzero-receiver`\n\n## Updates \u0026 Management\n\n### Update to New SocketZero Version\n```bash\n# Update variables in terraform.tfvars\n# socketzero_version = \"stable-1.1.0\"\n# socketzero_ami_id  = \"ami-NEW_AMI_ID\"\n\n# Re-apply Terraform\nterraform apply\n```\n\n### Manual Instance Management\nIf you want to use the SocketZero receiver on a different EC2 instance (not managed by Terraform):\n\n1. Launch your EC2 instance using the SocketZero Receiver AMI\n2. Copy your desired `config.json` to `/opt/socketzero/config.json`\n3. Ensure proper IAM permissions and security group rules\n4. Restart the service: `sudo systemctl restart socketzero-receiver`\n5. Update DNS/load balancer configuration if needed\n\n### SSM Parameter Store\nThe AMI ID can be stored in AWS SSM Parameter Store under `/socketzero/receiver/latest-ami` for automated version management.\n\n## Troubleshooting\n\n### Common Issues\n\n**Can't connect to receiver:**\n- Check security group allows your IP in `trusted_ip_cidrs`\n- Verify Route53 DNS record exists and points to ALB\n- Confirm SSL certificate is valid\n- Test ALB health checks are passing\n\n**Config changes not applied:**\n- Restart service: `sudo systemctl restart socketzero-receiver`\n- Check logs: `sudo journalctl -u socketzero-receiver -f`\n- Verify config file syntax: `cat /opt/socketzero/config.json | jq`\n\n**Encryption not working:**\n- Verify `encrypted = true` in `root_block_device` configuration\n- Check instance shows encrypted volumes in EC2 console\n- Confirm KMS key permissions if using custom key\n\n**Service not starting:**\n- Check service status: `sudo systemctl status socketzero-receiver`\n- Review logs: `sudo journalctl -u socketzero-receiver -f`\n- Verify config file permissions: `ls -la /opt/socketzero/config.json`\n\n### Health Checks\n```bash\n# Check if SocketZero service is running\nsudo systemctl status socketzero-receiver\n\n# View recent logs\nsudo journalctl -u socketzero-receiver --since \"10 minutes ago\"\n\n# Test local connectivity\ncurl -k https://localhost:9997/health\n```\n\n## Support\n\nFor issues with:\n- **Terraform examples**: Check this repository's issues\n- **SocketZero product**: Contact support@radiusmethod.com\n- **Client installation**: See [SocketZero Client Repository](https://github.com/radiusmethod/socketzero-client)\n- **AWS resources**: Consult AWS documentation\n- **Security/Encryption**: Review the security section above\n\n---\n\n**Ready to get started?** Follow the [Quick Start Guide](#-quick-start-guide) above! ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fradiusmethod%2Fsocketzero-marketplace-offering","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fradiusmethod%2Fsocketzero-marketplace-offering","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fradiusmethod%2Fsocketzero-marketplace-offering/lists"}