- Active vs passive FTP — when to use each mode
- Firewall and NAT traversal for residential connections
- Directory structure patterns that prevent half-upload states
- Automated retry and error recovery configuration
- Diagnosing intermittent upload failures
FTP remains the backbone of weather-station publishing for most hobbyist setups. The protocol is defined in RFC 959, but the practical reality of configuring it through home routers, NAT firewalls, and shared hosting accounts requires knowledge that no RFC covers. This guide is built from over a decade of troubleshooting real FTP publishing failures for GraphWeather Publishing setups, and covers the patterns that actually hold up in production.
Active vs Passive FTP
FTP uses two connections: a control channel (port 21 by default) for commands, and a data channel for file transfers. The critical difference between active and passive mode is who initiates the data channel:
- Active mode — the client tells the server “connect back to me on port X for data.” The server opens an outbound connection to the client. This fails through most home routers because the router does not expect an inbound connection on an arbitrary port.
- Passive mode (PASV) — the client asks the server to listen on a port, and the client connects outward to it. Both connections are initiated by the client, which works cleanly through NAT firewalls.
Rule of thumb: if your station computer is behind any kind of router or firewall — and it almost certainly is — use passive mode. Active mode is only appropriate for servers on the same local network with no NAT in between.
Step-by-Step FTP Configuration
- Gather credentials — hostname, username, password, remote directory path, and port (usually 21). Your hosting provider supplies these.
- Set passive mode — in GraphWeather’s publishing settings, enable “Passive FTP” or “PASV mode.”
- Set the remote directory — typically
/public_html/weather/or/htdocs/meteo/. Verify the path exists on the server. - Configure upload order — upload images and data files first, then the HTML page last. This prevents browsers from loading a page that references images still in transit.
- Test manually — use the “Test Connection” button or publish once manually before enabling the scheduler.
- Enable scheduler — set the interval (5–15 minutes is typical) and enable retry on failure.
Troubleshooting Matrix
| Symptom | Likely Cause | Fix |
|---|---|---|
| Connection timeout on port 21 | Firewall blocking, wrong hostname | Verify hostname resolves; check if ISP blocks port 21; try alternate port if hosting supports it |
| Login succeeds, transfer hangs | Active mode through NAT | Switch to passive mode |
| Intermittent “connection reset” | Router NAT table exhaustion | Reduce upload frequency; reboot router to clear NAT table; increase retry delay |
| Permission denied on upload | Wrong remote directory or file permissions | Verify the remote path; check file/directory ownership on the server; contact hosting support |
| File uploads but page shows old data | Browser or CDN caching | Implement cache-busting query parameters; check CDN cache rules. See Image Refresh and Caching |
| Uploads stop after server migration | New server IP, changed FTP settings | Update hostname, verify new credentials, test connection |
| Partial file on server | Connection dropped mid-transfer | Enable atomic upload (write to .tmp, then rename); increase timeout values |
Advanced: Secure FTP Options
For operators whose hosting supports it, consider upgrading from plain FTP to FTPS (FTP over TLS) or SFTP (SSH File Transfer Protocol). Both encrypt the data stream, preventing credential interception. GraphWeather supports FTPS natively; SFTP requires an external tool or plugin.