qb transfer - Inter-Instance Transfer Peers
Transfer Peer Allowlist
Exempt your paired instances from fail2ban on the transfer data port
Inter-Instance Transfer is driven from the dashboard at System → Inter-Instance Transfer, where you create, approve, and monitor transfers. The dashboard also manages the peer allowlist for you automatically — it whitelists each paired server the moment a transfer is accepted. The qb transfer commands below expose that same allowlist for manual inspection and adjustment from the terminal.
The qb transfer command manages the peer allowlist used by Inter-Instance Transfer. When two of your QuickBox instances move data between each other, the traffic hits a dedicated data port. A long or frequently-retried transfer can look like abuse to Fail2Ban and get the peer server banned mid-flight, breaking the transfer. The allowlist exempts a peer’s address from fail2ban on that port so paired servers never lock each other out.
The dashboard adds each peer to this allowlist automatically when a transfer is accepted, and the entry is persistent — the peer stays allowlisted until an administrator removes it, so servers that transfer regularly never trip each other again. The commands below let an administrator inspect and adjust the list directly.
Quick Reference
| Command | Description |
|---|---|
qb transfer peer-allow <ip> | Add a peer server address to the transfer allowlist |
qb transfer peer-deny <ip> | Remove a peer server address from the allowlist |
qb transfer peer-list | List every allowlisted peer address |
The peer allowlist is implemented on top of Fail2Ban. The commands are safe to run on any server — on a box without Fail2Ban they never hard-fail; they simply report that peer-allowlist support is unavailable or make no change. Install Fail2Ban from the Applications catalog to maintain an allowlist.
Commands
qb transfer subcommands
peer-allow <ip>Add a peer server address to the transfer allowlist so it is exempt from fail2ban on the transfer data port. The address must be a single valid IPv4 or IPv6 address — CIDR ranges are not accepted. Re-adding an address that is already allowlisted is a safe no-op.
qb transfer peer-allow 198.51.100.10peer-deny <ip>Remove a peer server address from the allowlist. Removing an address that is not on the list is a safe no-op.
qb transfer peer-deny 198.51.100.10peer-listPrint every allowlisted peer address, one per line. Prints nothing when the list is empty.
qb transfer peer-listAdd a peer
qb transfer peer-allow 198.51.100.10Adds the address to the allowlist and confirms with peer 198.51.100.10 added to the transfer allowlist. Use the address of your other QuickBox instance — the server that connects to this one during a transfer.
Remove a peer
qb transfer peer-deny 198.51.100.10Removes the address and confirms with peer 198.51.100.10 removed from the transfer allowlist. Do this when you retire a paired server or want to stop exempting it.
List allowlisted peers
qb transfer peer-listPrints each allowlisted address on its own line, or reports that no peers are allowlisted when the list is empty.
Only add addresses of servers you own and trust. An allowlisted address is exempt from fail2ban on the transfer data port. The data path is still protected by signed, single-use transfer authorization regardless of the allowlist — the allowlist only affects fail2ban, never the transfer authorization itself — but there is no reason to exempt an address that is not one of your paired instances.
Data port
The transfer data leg uses a dedicated port. The default is 45876. It can be changed by an operator, and the dashboard shows the active value under System → Inter-Instance Transfer → Settings → Transfer engine → Data port. The allowlist applies to whichever port the data leg terminates on.
Best practices
Do
- Prefer the dashboard at System → Inter-Instance Transfer for day-to-day transfers — it manages the allowlist for you automatically on accept.
- Use
qb transfer peer-listto confirm which peers are exempt when troubleshooting a transfer that keeps getting cut off. - Only allowlist the addresses of servers you own — the allowlist is meant for your own paired instances.
- Remove a peer with
qb transfer peer-denywhen you retire or repurpose one of your servers.
Don't
- Do not allowlist an address that is not one of your paired QuickBox instances.
- Do not rely on the allowlist for transfer security — the data path is authorized by signed, single-use, expiring credentials independently of fail2ban.
- Do not expect these commands to start or approve a transfer — they only manage the fail2ban peer allowlist.
Frequently asked questions
Related documentation
Join the Community
Media server operators sharing configs, getting support, and shaping the future of QuickBox Pro.