Remote Commands

Execute fail2ban and system commands on managed servers directly from the Bloqd dashboard.

Overview

Remote commands allow administrators to:

• Manage fail2ban jails (enable, disable, reload)
• Ban/unban specific IPs
• Deploy jail configurations
• Check server status
• Execute custom commands

How It Works

┌────────────┐     Command      ┌────────────┐     Execute     ┌────────────┐
│  Dashboard │────────────────►│   Bloqd    │────────────────►│   Agent    │
│   (User)   │                 │  (Queue)   │                 │  (Server)  │
└────────────┘                 └────────────┘                 └─────┬──────┘
                                                                    │
                                     ◄──────────────────────────────┘
                                          Result callback

1. User initiates command from dashboard
2. Bloqd queues command for target server
3. Agent polls for pending commands
4. Agent executes command locally
5. Agent reports result back to Bloqd
6. Dashboard shows command result

Command Types

fail2ban Commands

Command	Description	Example
jail-status	Get jail status	fail2ban-client status sshd
jail-enable	Enable a jail	fail2ban-client start sshd
jail-disable	Disable a jail	fail2ban-client stop sshd
jail-reload	Reload jail config	fail2ban-client reload sshd
ban-ip	Ban an IP	fail2ban-client set sshd banip 1.2.3.4
unban-ip	Unban an IP	fail2ban-client set sshd unbanip 1.2.3.4
reload-all	Reload fail2ban	fail2ban-client reload

Template Deployment

Command	Description
deploy-template	Write jail config and filter to server
remove-template	Remove jail config from server
verify-template	Check if template is correctly installed

System Commands

Command	Description
service-status	Check fail2ban service status
service-restart	Restart fail2ban service
check-logs	Retrieve recent fail2ban logs

Using Remote Commands

From Jail List

1. Go to Servers → Select a server
2. Navigate to Jails tab
3. Click the action menu (⋮) on any jail
4. Select action:
   • Enable - Start the jail
   • Disable - Stop the jail
   • Reload - Reload configuration

From Ban List

1. Go to Bans page
2. Find a ban entry
3. Click Unban to remove the ban
4. Or click Ban on an IP to manually ban it

From Templates

1. Go to Templates page
2. Select a template
3. Click Deploy to Server
4. Choose target server(s)
5. Confirm deployment

Command Queue

Commands are queued and executed asynchronously.

Queue Status

View pending commands:

1. Go to Servers → Select server
2. Click Command History tab
3. See pending, running, and completed commands

Command States

State	Description
pending	Waiting for agent to pick up
running	Agent is executing
completed	Successfully executed
failed	Execution failed
timeout	Agent didn't respond in time

Timeout Handling

• Default timeout: 60 seconds
• If agent doesn't respond, command marked as timeout
• Timed out commands can be retried

Security

Permission Requirements

Remote commands require appropriate permissions:

Role	Allowed Commands
Viewer	None
Operator	ban-ip, unban-ip, jail-status
Admin	All commands

Command Validation

All commands are validated before execution:

• Only whitelisted commands allowed
• Parameters sanitized
• IP addresses validated
• Jail names checked against known jails

Audit Logging

All commands are logged:

• Who initiated the command
• What command was executed
• When it was executed
• Result of execution

API Usage

Execute Command

curl -X POST "https://bloqd.example.com/api/v1/servers/{serverId}/commands" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "ban-ip",
    "params": {
      "jail": "sshd",
      "ip": "192.168.1.100"
    }
  }'

Check Command Status

curl "https://bloqd.example.com/api/v1/commands/{commandId}" \
  -H "Authorization: Bearer YOUR_API_KEY"

List Command History

curl "https://bloqd.example.com/api/v1/servers/{serverId}/commands" \
  -H "Authorization: Bearer YOUR_API_KEY"

Batch Commands

Execute same command on multiple servers:

1. Go to Servers page
2. Select multiple servers (checkbox)
3. Click Batch Actions
4. Choose command
5. Confirm execution

Via API

curl -X POST "https://bloqd.example.com/api/v1/commands/batch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "serverIds": ["server1-uuid", "server2-uuid"],
    "command": "reload-all"
  }'

Troubleshooting

Command Stuck in Pending

1. Check agent is running on target server
2. Verify agent can reach Bloqd API
3. Check agent logs for errors

Command Failed

1. View error message in command details
2. Check agent logs for full error
3. Verify permissions on target server
4. Ensure fail2ban is installed and running

Permission Denied

1. Verify your user role allows the command
2. Check API key has sufficient permissions
3. Contact admin to upgrade permissions

Best Practices

1. Use templates - Deploy tested configurations
2. Review before executing - Especially for batch commands
3. Monitor results - Check command completed successfully
4. Use appropriate roles - Don't give admin access unnecessarily
5. Test on one server first - Before batch deployment