Swatantra-66 opened a new pull request, #20514:
URL: https://github.com/apache/nuttx/pull/20514
## Summary
Provide a comprehensive documentation guide for the `ftpd` (FTP server)
network utility in `Documentation/applications/netutils/ftpd/index.rst`,
replacing the previous 6-line placeholder stub.
Addresses #11081.
### Key Additions:
1. **Architecture & Multi-Threading Model**:
- Details master server listening socket on port 21, dynamic worker
pthread creation per client connection (`CONFIG_FTPD_WORKERSTACKSIZE`), control
vs. data stream separation, and POSIX VFS mapping.
2. **Security Considerations & Credential Hardening**:
- Highlights unencrypted plaintext FTP credentials risks, network
isolation recommendations, home directory jail enforcement
(`FTPD_ACCOUNTFLAG_GUEST`), mandatory credential hardening advice, and
encrypted password authentication (`CONFIG_FTPD_LOGIN_PASSWD`).
3. **Supported Commands Reference**:
- Complete table covering RFC 959 core commands, RFC 2428 IPv4/IPv6
extensions (`EPRT`, `EPSV`), and RFC 3659 metadata extensions (`SIZE`, `MDTM`).
4. **Configuration Reference**:
- Comprehensive Kconfig table (`CONFIG_NETUTILS_FTPD`, worker stack
sizes, command buffer lengths, data buffer transfer sizing, port options).
5. **NSH CLI & External Client Walkthroughs**:
- Documents `ftpd -4` / `ftpd -6` (address-family options) and
`ftpd_stop` NSH commands with account placeholders.
- Provides interactive `ftp` and `curl` examples that avoid embedding
plaintext passwords in command arguments (prompting securely to avoid shell
history and process table exposure).
6. **Public C API Reference**:
- Covers `ftpd_open()`, `ftpd_adduser()`, `ftpd_session()`, and
`ftpd_close()`.
7. **Runnable Application Example**:
- Demonstrates multi-user server configuration, loop execution, and
clean, thread-safe termination via `sig_atomic_t` signal handling
(`SIGINT`/`SIGTERM`) and companion POSIX `kill` stop routines.
8. **Resource Tuning Guidelines**:
- Guidance on worker stack sizing for flash filesystems, I/O buffer
sizing, and NAT/firewall passive mode operation.
## Impact
- **Documentation**: Fills a blank documentation page identified in #11081.
- **Security**: Warns users against plaintext credential transmission over
untrusted links, documents directory isolation flags, and enforces secure
credential practices.
- **Developer Experience**: Eliminates confusion around mandatory `-4`/`-6`
CLI flags, account management, and thread-safe session termination.
- **Build / ABI**: Documentation-only change. No functional code or ABI
alterations to existing NuttX libraries or apps.
## Testing
- Verified reStructuredText syntax, section underline lengths, and directive
syntax.
- Verified 0 trailing whitespaces (`git diff --check`).
- Validated command-line behavior and options against
`apps/examples/ftpd/ftpd_main.c`.
- Cross-referenced all public C API signatures and account flag constants
against `apps/include/netutils/ftpd.h` and `apps/netutils/ftpd/ftpd.c`.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
