You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@nuttx.apache.org by "Swatantra-66 (via GitHub)" <gi...@apache.org> on 2026/10/08 12:51:05 UTC
[PR] Documentation/netutils: add comprehensive guide for ftpd [nuttx]
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: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Documentation/netutils: add comprehensive guide for ftpd [nuttx]
Posted by "acassis (via GitHub)" <gi...@apache.org>.
acassis commented on PR #20514:
URL: https://github.com/apache/nuttx/pull/20514#issuecomment-6062468992
> Hmm, the CI complains there is unexpected indentation on line 42, but I don't see an indentation problem there. Does anyone know why it complains?
Good point. @Swatantra-66 if you are using AI to write the documentation (because its very well designed and formatted), please indicate it using: Assisted-by: AI Vendor and Model
--
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: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Documentation/netutils: add comprehensive guide for ftpd [nuttx]
Posted by "Swatantra-66 (via GitHub)" <gi...@apache.org>.
Swatantra-66 commented on PR #20514:
URL: https://github.com/apache/nuttx/pull/20514#issuecomment-6063849152
@hartmannathan @acassis Thank you for the reviews!
Regarding the line 42 indentation error: in Sphinx / Docutils, when sub-bullets are nested under an enumerated list (`1.`, `2.`, `3.`) without an intervening blank line, the reST state machine treats subsequent indented lines as an ambiguous blockquote, throwing an `Unexpected indentation` error on the very next numbered item (`4.`).
I have flattened those sub-items into clean inline text and verified locally with Docutils (0 warnings, 0 errors). I have also added the requested `Assisted-by: Google Gemini` tag to the commit message.
--
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: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Documentation/netutils: add comprehensive guide for ftpd [nuttx]
Posted by "acassis (via GitHub)" <gi...@apache.org>.
acassis commented on PR #20514:
URL: https://github.com/apache/nuttx/pull/20514#issuecomment-6062483248
> Well written doc! Thank you for helping to improve NuttX documentation!
Good point. @Swatantra-66 if you are using AI to write the documentation (because its very well designed and formatted), please indicate it using: Assisted-by: AI Vendor and Model
--
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: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Documentation/netutils: add comprehensive guide for ftpd [nuttx]
Posted by "hartmannathan (via GitHub)" <gi...@apache.org>.
hartmannathan commented on PR #20514:
URL: https://github.com/apache/nuttx/pull/20514#issuecomment-6062326030
Hmm, the CI complains there is unexpected indentation on line 42, but I don't see an indentation problem there. Does anyone know why it complains?
--
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: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Documentation/netutils: add comprehensive guide for ftpd [nuttx]
Posted by "xiaoxiang781216 (via GitHub)" <gi...@apache.org>.
xiaoxiang781216 merged PR #20514:
URL: https://github.com/apache/nuttx/pull/20514
--
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: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org