nfsd-maintainer-entry-profile.rst

  1NFSD Maintainer Entry Profile
  2=============================
  3
  4A Maintainer Entry Profile supplements the top-level process
  5documents (found in Documentation/process/) with customs that are
  6specific to a subsystem and its maintainers. A contributor may use
  7this document to set their expectations and avoid common mistakes.
  8A maintainer may use these profiles to look across subsystems for
  9opportunities to converge on best common practices.
 10
 11Overview
 12--------
 13The Network File System (NFS) is a standardized family of network
 14protocols that enable access to files across a set of network-
 15connected peer hosts. Applications on NFS clients access files that
 16reside on file systems that are shared by NFS servers. A single
 17network peer can act as both an NFS client and an NFS server.
 18
 19NFSD refers to the NFS server implementation included in the Linux
 20kernel. An in-kernel NFS server has fast access to files stored
 21in file systems local to that server. NFSD can share files stored
 22on most of the file system types native to Linux, including xfs,
 23ext4, btrfs, and tmpfs.
 24
 25Mailing list
 26------------
 27The linux-nfs@vger.kernel.org mailing list is a public list. Its
 28purpose is to enable collaboration among developers working on the
 29Linux NFS stack, both client and server. It is not a place for
 30conversations that are not related directly to the Linux NFS stack.
 31
 32The linux-nfs mailing list is archived on `lore.kernel.org <https://lore.kernel.org/linux-nfs/>`_.
 33
 34The Linux NFS community does not have any chat room.
 35
 36Reporting bugs
 37--------------
 38If you experience an NFSD-related bug on a distribution-built
 39kernel, please start by working with your Linux distributor.
 40
 41Bug reports against upstream Linux code bases are welcome on the
 42linux-nfs@vger.kernel.org mailing list, where some active triage
 43can be done. NFSD bugs may also be reported in the Linux kernel
 44community's bugzilla at:
 45
 46  https://bugzilla.kernel.org
 47
 48Please file NFSD-related bugs under the "Filesystems/NFSD"
 49component. In general, including as much detail as possible is a
 50good start, including pertinent system log messages from both
 51the client and server.
 52
 53User space software related to NFSD, such as mountd or the exportfs
 54command, is contained in the nfs-utils package. Report problems
 55with those components to linux-nfs@vger.kernel.org. You might be
 56directed to move the report to a specific bug tracker.
 57
 58Contributor's Guide
 59-------------------
 60
 61Standards compliance
 62~~~~~~~~~~~~~~~~~~~~
 63The priority is for NFSD to interoperate fully with the Linux NFS
 64client. We also test against other popular NFS client implementa-
 65tions regularly at NFS bake-a-thon events (also known as plug-
 66fests). Non-Linux NFS clients are not part of upstream NFSD CI/CD.
 67
 68The NFSD community strives to provide an NFS server implementation
 69that interoperates with all standards-compliant NFS client
 70implementations. This is done by staying as close as is sensible to
 71the normative mandates in the IETF's published NFS, RPC, and GSS-API
 72standards.
 73
 74It is always useful to reference an RFC and section number in a code
 75comment where behavior deviates from the standard (and even when the
 76behavior is compliant but the implementation is obfuscatory).
 77
 78On the rare occasion when a deviation from standard-mandated
 79behavior is needed, brief documentation of the use case or
 80deficiencies in the standard is a required part of in-code
 81documentation.
 82
 83Care must always be taken to avoid leaking local error codes (ie,
 84errnos) to clients of NFSD. A proper NFS status code is always
 85required in NFS protocol replies.
 86
 87NFSD administrative interfaces
 88~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 89NFSD administrative interfaces include:
 90
 91- an NFSD or SUNRPC module parameter
 92
 93- export options in /etc/exports
 94
 95- files under /proc/fs/nfsd/ or /proc/sys/sunrpc/
 96
 97- the NFSD netlink protocol
 98
 99Frequently, a request is made to introduce or modify one of NFSD's
100traditional administrative interfaces. Certainly it is technically
101easy to introduce a new administrative setting. However, there are
102good reasons why the NFSD maintainers prefer to leave that as a last
103resort:
104
105- As with any API, administrative interfaces are difficult to get
106  right.
107
108- Once they are documented and have a legacy of use, administrative
109  interfaces become difficult to modify or remove.
110
111- Every new administrative setting multiplies the NFSD test matrix.
112
113- The cost of one administrative interface is incremental, but costs
114  add up across all of the existing interfaces.
115
116It is often better for everyone if effort is made up front to
117understanding the underlying requirement of the new setting, and
118then trying to make it tune itself (or to become otherwise
119unnecessary).
120
121If a new setting is indeed necessary, first consider adding it to
122the NFSD netlink protocol. Or if it doesn't need to be a reliable
123long term user space feature, it can be added to NFSD's menagerie of
124experimental settings which reside under /sys/kernel/debug/nfsd/ .
125
126Field observability
127~~~~~~~~~~~~~~~~~~~
128NFSD employs several different mechanisms for observing operation,
129including counters, printks, WARNings, and static trace points. Each
130have their strengths and weaknesses. Contributors should select the
131most appropriate tool for their task.
132
133- BUG must be avoided if at all possible, as it will frequently
134  result in a full system crash.
135
136- WARN is appropriate only when a full stack trace is useful.
137
138- printk can show detailed information. These must not be used
139  in code paths where they can be triggered repeatedly by remote
140  users.
141
142- dprintk can show detailed information, but can be enabled only
143  in pre-set groups. The overhead of emitting output makes dprintk
144  inappropriate for frequent operations like I/O.
145
146- Counters are always on, but provide little information about
147  individual events other than how frequently they occur.
148
149- static trace points can be enabled individually or in groups
150  (via a glob). These are generally low overhead, and thus are
151  favored for use in hot paths.
152
153- dynamic tracing, such as kprobes or eBPF, are quite flexible but
154  cannot be used in certain environments (eg, full kernel lock-
155  down).
156
157Testing
158~~~~~~~
159The kdevops project
160
161  https://github.com/linux-kdevops/kdevops
162
163contains several NFS-specific workflows, as well as the community
164standard fstests suite. These workflows are based on open source
165testing tools such as ltp and fio. Contributors are encouraged to
166use these tools without kdevops, or contributors should install and
167use kdevops themselves to verify their patches before submission.
168
169Coding style
170~~~~~~~~~~~~
171Follow the coding style preferences described in
172
173  Documentation/process/coding-style.rst
174
175with the following exceptions:
176
177- Add new local variables to a function in reverse Christmas tree
178  order
179
180- Use the kdoc comment style for
181  + non-static functions
182  + static inline functions
183  + static functions that are callbacks/virtual functions
184
185- All new function names start with ``nfsd_`` for non-NFS-version-
186  specific functions.
187
188- New function names that are specific to NFSv2 or NFSv3, or are
189  used by all minor versions of NFSv4, use ``nfsdN_`` where N is
190  the version.
191
192- New function names specific to an NFSv4 minor version can be
193  named with ``nfsd4M_`` where M is the minor version.
194
195Patch preparation
196~~~~~~~~~~~~~~~~~
197Read and follow all guidelines in
198
199  Documentation/process/submitting-patches.rst
200
201Use tagging to identify all patch authors. However, reviewers and
202testers should be added by replying to the email patch submission.
203Email is extensively used in order to publicly archive review and
204testing attributions. These tags are automatically inserted into
205your patches when they are applied.
206
207The code in the body of the diff already shows /what/ is being
208changed. Thus it is not necessary to repeat that in the patch
209description. Instead, the description should contain one or more
210of:
211
212- A brief problem statement ("what is this patch trying to fix?")
213  with a root-cause analysis.
214
215- End-user visible symptoms or items that a support engineer might
216  use to search for the patch, like stack traces.
217
218- A brief explanation of why the patch is the best way to address
219  the problem.
220
221- Any context that reviewers might need to understand the changes
222  made by the patch.
223
224- Any relevant benchmarking results, and/or functional test results.
225
226As detailed in Documentation/process/submitting-patches.rst,
227identify the point in history that the issue being addressed was
228introduced by using a Fixes: tag.
229
230Mention in the patch description if that point in history cannot be
231determined -- that is, no Fixes: tag can be provided. In this case,
232please make it clear to maintainers whether an LTS backport is
233needed even though there is no Fixes: tag.
234
235The NFSD maintainers prefer to add stable tagging themselves, after
236public discussion in response to the patch submission. Contributors
237may suggest stable tagging, but be aware that many version
238management tools add such stable Cc's when you post your patches.
239Don't add "Cc: stable" unless you are absolutely sure the patch
240needs to go to stable during the initial submission process.
241
242Patch submission
243~~~~~~~~~~~~~~~~
244Patches to NFSD are submitted via the kernel's email-based review
245process that is common to most other kernel subsystems.
246
247Just before each submission, rebase your patch or series on the
248nfsd-testing branch at
249
250  https://git.kernel.org/pub/scm/linux/kernel/git/cel/linux.git
251
252The NFSD subsystem is maintained separately from the Linux in-kernel
253NFS client. The NFSD maintainers do not normally take submissions
254for client changes, nor can they respond authoritatively to bug
255reports or feature requests for NFS client code.
256
257This means that contributors might be asked to resubmit patches if
258they were emailed to the incorrect set of maintainers and reviewers.
259This is not a rejection, but simply a correction of the submission
260process.
261
262When in doubt, consult the NFSD entry in the MAINTAINERS file to
263see which files and directories fall under the NFSD subsystem.
264
265The proper set of email addresses for NFSD patches are:
266
267To: the NFSD maintainers and reviewers listed in MAINTAINERS
268Cc: linux-nfs@vger.kernel.org and optionally linux-kernel@
269
270If there are other subsystems involved in the patches (for example
271MM or RDMA) their primary mailing list address can be included in
272the Cc: field. Other contributors and interested parties may be
273included there as well.
274
275In general we prefer that contributors use common patch email tools
276such as "git send-email" or "stg email format/send", which tend to
277get the details right without a lot of fuss.
278
279A series consisting of a single patch is not required to have a
280cover letter. However, a cover letter can be included if there is
281substantial context that is not appropriate to include in the
282patch description.
283
284Please note that, with an e-mail based submission process, series
285cover letters are not part of the work that is committed to the
286kernel source code base or its commit history. Therefore always try
287to keep pertinent information in the patch descriptions.
288
289Design documentation is welcome, but as cover letters are not
290preserved, a perhaps better option is to include a patch that adds
291such documentation under Documentation/filesystems/nfs/.
292
293Reviewers will ask about test coverage and what use cases the
294patches are expected to address. Please be prepared to answer these
295questions.
296
297Review comments from maintainers might be politely stated, but in
298general, these are not optional to address when they are actionable.
299If necessary, the maintainers retain the right to not apply patches
300when contributors refuse to address reasonable requests.
301
302Post changes to kernel source code and user space source code as
303separate series. You can connect the two series with comments in
304your cover letters.
305
306Generally the NFSD maintainers ask for a reposts even for simple
307modifications in order to publicly archive the request and the
308resulting repost before it is pulled into the NFSD trees. This
309also enables us to rebuild a patch series quickly without missing
310changes that might have been discussed via email.
311
312Avoid frequently reposting large series with only small changes. As
313a rule of thumb, posting substantial changes more than once a week
314will result in reviewer overload.
315
316Remember, there are only a handful of subsystem maintainers and
317reviewers, but potentially many sources of contributions. The
318maintainers and reviewers, therefore, are always the less scalable
319resource. Be kind to your friendly neighborhood maintainer.
320
321Patch Acceptance
322~~~~~~~~~~~~~~~~
323There isn't a formal review process for NFSD, but we like to see
324at least two Reviewed-by: notices for patches that are more than
325simple clean-ups. Reviews are done in public on
326linux-nfs@vger.kernel.org and are archived on lore.kernel.org.
327
328Currently the NFSD patch queues are maintained in branches here:
329
330  https://git.kernel.org/pub/scm/linux/kernel/git/cel/linux.git
331
332The NFSD maintainers apply patches initially to the nfsd-testing
333branch, which is always open to new submissions. Patches can be
334applied while review is ongoing. nfsd-testing is a topic branch,
335so it can change frequently, it will be rebased, and your patch
336might get dropped if there is a problem with it.
337
338Generally a script-generated "thank you" email will indicate when
339your patch has been added to the nfsd-testing branch. You can track
340the progress of your patch using the linux-nfs patchworks instance:
341
342  https://patchwork.kernel.org/project/linux-nfs/list/
343
344While your patch is in nfsd-testing, it is exposed to a variety of
345test environments, including community zero-day bots, static
346analysis tools, and NFSD continuous integration testing. The soak
347period is three to four weeks.
348
349Each patch that survives in nfsd-testing for the soak period without
350changes is moved to the nfsd-next branch.
351
352The nfsd-next branch is automatically merged into linux-next and
353fs-next on a nightly basis.
354
355Patches that survive in nfsd-next are included in the next NFSD
356merge window pull request. These windows typically occur once every
35763 days (nine weeks).
358
359When the upstream merge window closes, the nfsd-next branch is
360renamed nfsd-fixes, and a new nfsd-next branch is created, based on
361the upstream -rc1 tag.
362
363Fixes that are destined for an upstream -rc release also run the
364nfsd-testing gauntlet, but are then applied to the nfsd-fixes
365branch. That branch is made available for Linus to pull after a
366short time. In order to limit the risk of introducing regressions,
367we limit such fixes to emergency situations or fixes to breakage
368that occurred during the most recent upstream merge.
369
370Please make it clear when submitting an emergency patch that
371immediate action (either application to -rc or LTS backport) is
372needed.
373
374Sensitive patch submissions and bug reports
375~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
376CVEs are generated by specific members of the Linux kernel community
377and several external entities. The Linux NFS community does not emit
378or assign CVEs. CVEs are assigned after an issue and its fix are
379known.
380
381However, the NFSD maintainers sometimes receive sensitive security
382reports, and at times these are significant enough to need to be
383embargoed. In such rare cases, fixes can be developed and reviewed
384out of the public eye.
385
386Please be aware that many version management tools add the stable
387Cc's when you post your patches. This is generally a nuisance, but
388it can result in outing an embargoed security issue accidentally.
389Don't add "Cc: stable" unless you are absolutely sure the patch
390needs to go to stable@ during the initial submission process.
391
392Patches that are merged without ever appearing on any list, and
393which carry a Reported-by: or Fixes: tag are detected as suspicious
394by security-focused people. We encourage that, after any private
395review, security-sensitive patches should be posted to linux-nfs@
396for the usual public review, archiving, and test period.
397
398LLM-generated submissions
399~~~~~~~~~~~~~~~~~~~~~~~~~
400The Linux kernel community as a whole is still exploring the new
401world of LLM-generated code. The NFSD maintainers will entertain
402submission of patches that are partially or wholly generated by
403LLM-based development tools. Such submissions are held to the
404same standards as submissions created entirely by human authors:
405
406- The human contributor identifies themselves via a Signed-off-by:
407  tag. This tag counts as a DoC.
408
409- The human contributor is solely responsible for code provenance
410  and any contamination by inadvertently-included code with a
411  conflicting license, as usual.
412
413- The human contributor must be able to answer and address review
414  questions. A patch description such as "This fixed my problem
415  but I don't know why" is not acceptable.
416
417- The contribution is subjected to the same test regimen as all
418  other submissions.
419
420- An indication (via a Generated-by: tag or otherwise) that the
421  contribution is LLM-generated is not required.
422
423It is easy to address review comments and fix requests in LLM
424generated code. So easy, in fact, that it becomes tempting to repost
425refreshed code immediately. Please resist that temptation.
426
427As always, please avoid reposting series revisions more than once
428every 24 hours.
429
430Clean-up patches
431~~~~~~~~~~~~~~~~
432The NFSD maintainers discourage patches which perform simple clean-
433ups, which are not in the context of other work. For example:
434
435* Addressing ``checkpatch.pl`` warnings after merge
436* Addressing :ref:`Local variable ordering<rcs>` issues
437* Addressing long-standing whitespace damage
438
439This is because it is felt that the churn that such changes produce
440comes at a greater cost than the value of such clean-ups.
441
442Conversely, spelling and grammar fixes are encouraged.
443
444Stable and LTS support
445----------------------
446Upstream NFSD continuous integration testing runs against LTS trees
447whenever they are updated.
448
449Please indicate when a patch containing a fix needs to be considered
450for LTS kernels, either via a Fixes: tag or explicit mention.
451
452Feature requests
453----------------
454There is no one way to make an official feature request, but
455discussion about the request should eventually make its way to
456the linux-nfs@vger.kernel.org mailing list for public review by
457the community.
458
459Subsystem boundaries
460~~~~~~~~~~~~~~~~~~~~
461NFSD itself is not much more than a protocol engine. This means its
462primary responsibility is to translate the NFS protocol into API
463calls in the Linux kernel. For example, NFSD is not responsible for
464knowing exactly how bytes or file attributes are managed on a block
465device. It relies on other kernel subsystems for that.
466
467If the subsystems on which NFSD relies do not implement a particular
468feature, even if the standard NFS protocols do support that feature,
469that usually means NFSD cannot provide that feature without
470substantial development work in other areas of the kernel.
471
472Specificity
473~~~~~~~~~~~
474Feature requests can come from anywhere, and thus can often be
475nebulous. A requester might not understand what a "use case" or
476"user story" is. These descriptive paradigms are often used by
477developers and architects to understand what is required of a
478design, but are terms of art in the software trade, not used in
479the everyday world.
480
481In order to prevent contributors and maintainers from becoming
482overwhelmed, we won't be afraid of saying "no" politely to
483underspecified requests.
484
485Community roles and their authority
486-----------------------------------
487The purpose of Linux subsystem communities is to provide expertise
488and active stewardship of a narrow set of source files in the Linux
489kernel. This can include managing user space tooling as well.
490
491To contextualize the structure of the Linux NFS community that
492is responsible for stewardship of the NFS server code base, we
493define the community roles here.
494
495- **Contributor** : Anyone who submits a code change, bug fix,
496  recommendation, documentation fix, and so on. A contributor can
497  submit regularly or infrequently.
498
499- **Outside Contributor** : A contributor who is not a regular actor
500  in the Linux NFS community. This can mean someone who contributes
501  to other parts of the kernel, or someone who just noticed a
502  misspelling in a comment and sent a patch.
503
504- **Reviewer** : Someone who is named in the MAINTAINERS file as a
505  reviewer is an area expert who can request changes to contributed
506  code, and expects that contributors will address the request.
507
508- **External Reviewer** : Someone who is not named in the
509  MAINTAINERS file as a reviewer, but who is an area expert.
510  Examples include Linux kernel contributors with networking,
511  security, or persistent storage expertise, or developers who
512  contribute primarily to other NFS implementations.
513
514One or more people will take on the following roles. These people
515are often generically referred to as "maintainers", and are
516identified in the MAINTAINERS file with the "M:" tag under the NFSD
517subsystem.
518
519- **Upstream Release Manager** : This role is responsible for
520  curating contributions into a branch, reviewing test results, and
521  then sending a pull request during merge windows. There is a
522  trust relationship between the release manager and Linus.
523
524- **Bug Triager** : Someone who is a first responder to bug reports
525  submitted to the linux-nfs mailing list or bug trackers, and helps
526  troubleshoot and identify next steps.
527
528- **Security Lead** : The security lead handles contacts from the
529  security community to resolve immediate issues, as well as dealing
530  with long-term security issues such as supply chain concerns. For
531  upstream, that's usually whether contributions violate licensing
532  or other intellectual property agreements.
533
534- **Testing Lead** : The testing lead builds and runs the test
535  infrastructure for the subsystem. The testing lead may ask for
536  patches to be dropped because of ongoing high defect rates.
537
538- **LTS Maintainer** : The LTS maintainer is responsible for managing
539  the Fixes: and Cc: stable annotations on patches, and seeing that
540  patches that cannot be automatically applied to LTS kernels get
541  proper manual backports as necessary.
542
543- **Community Manager** : This umpire role can be asked to call balls
544  and strikes during conflicts, but is also responsible for ensuring
545  the health of the relationships within the community and for
546  facilitating discussions on long-term topics such as how to manage
547  growing technical debt.