1 .. SPDX-License-Identifier: GPL-2.0
2
3 ====================
4 Filesystem Mount API
5 ====================
6
7 .. CONTENTS
8
9 (1) Overview.
10
11 (2) The filesystem context.
12
13 (3) The filesystem context operations.
14
15 (4) Filesystem context security.
16
17 (5) VFS filesystem context API.
18
19 (6) Superblock creation helpers.
20
21 (7) Parameter description.
22
23 (8) Parameter helper functions.
24
25
26 Overview
27 ========
28
29 The creation of new mounts is now to be done i
30
31 (1) Create a filesystem context.
32
33 (2) Parse the parameters and attach them to t
34 expected to be passed individually from u
35 parameters can also be handled.
36
37 (3) Validate and pre-process the context.
38
39 (4) Get or create a superblock and mountable
40
41 (5) Perform the mount.
42
43 (6) Return an error message attached to the c
44
45 (7) Destroy the context.
46
47 To support this, the file_system_type struct g
48
49 int (*init_fs_context)(struct fs_conte
50 const struct fs_parameter_description
51
52 The first is invoked to set up the filesystem-
53 context, including the additional space, and t
54 parameter description for validation at regist
55 future system call.
56
57 Note that security initialisation is done *aft
58 that the namespaces may be adjusted first.
59
60
61 The Filesystem context
62 ======================
63
64 The creation and reconfiguration of a superblo
65 context. This is represented by the fs_contex
66
67 struct fs_context {
68 const struct fs_context_operat
69 struct file_system_type *fs_ty
70 void *fs_pr
71 struct dentry *root;
72 struct user_namespace *user_
73 struct net *net_n
74 const struct cred *cred;
75 char *sourc
76 char *subty
77 void *secur
78 void *s_fs_
79 unsigned int sb_fla
80 unsigned int sb_fla
81 unsigned int s_ifla
82 enum fs_context_purpose purpos
83 ...
84 };
85
86 The fs_context fields are as follows:
87
88 * ::
89
90 const struct fs_context_operations *ops
91
92 These are operations that can be done on
93 below). This must be set by the ->init_f
94 operation.
95
96 * ::
97
98 struct file_system_type *fs_type
99
100 A pointer to the file_system_type of the
101 constructed or reconfigured. This retain
102
103 * ::
104
105 void *fs_private
106
107 A pointer to the file system's private da
108 will need to store any options it parses.
109
110 * ::
111
112 struct dentry *root
113
114 A pointer to the root of the mountable tr
115 superblock thereof). This is filled in b
116 is set, an active reference on root->d_sb
117
118 * ::
119
120 struct user_namespace *user_ns
121 struct net *net_ns
122
123 There are a subset of the namespaces in u
124 retain references on each namespace. The
125 replaced by the filesystem to reflect oth
126 mount superblock on an automount.
127
128 * ::
129
130 const struct cred *cred
131
132 The mounter's credentials. This retains
133
134 * ::
135
136 char *source
137
138 This specifies the source. It may be a b
139 something more exotic, such as the "host:
140
141 * ::
142
143 char *subtype
144
145 This is a string to be added to the type
146 qualify it (used by FUSE). This is avail
147 desired.
148
149 * ::
150
151 void *security
152
153 A place for the LSMs to hang their securi
154 relevant security operations are describe
155
156 * ::
157
158 void *s_fs_info
159
160 The proposed s_fs_info for a new superblo
161 sget_fc(). This can be used to distingui
162
163 * ::
164
165 unsigned int sb_flags
166 unsigned int sb_flags_mask
167
168 Which bits SB_* flags are to be set/clear
169
170 * ::
171
172 unsigned int s_iflags
173
174 These will be bitwise-OR'd with s->s_ifla
175
176 * ::
177
178 enum fs_context_purpose
179
180 This indicates the purpose for which the
181 available values are:
182
183 ========================== ======
184 FS_CONTEXT_FOR_MOUNT, New su
185 FS_CONTEXT_FOR_SUBMOUNT New au
186 FS_CONTEXT_FOR_RECONFIGURE Change
187 ========================== ======
188
189 The mount context is created by calling vfs_ne
190 vfs_dup_fs_context() and is destroyed with put
191 structure is not refcounted.
192
193 VFS, security and filesystem mount options are
194 vfs_parse_mount_option(). Options provided by
195 a page of data can be parsed with generic_pars
196
197 When mounting, the filesystem is allowed to ta
198 and attach it to the superblock (or whatever),
199 in the mount context.
200
201 The filesystem is also allowed to allocate res
202 mount context. For instance, NFS might pin th
203 module.
204
205
206 The Filesystem Context Operations
207 =================================
208
209 The filesystem context points to a table of op
210
211 struct fs_context_operations {
212 void (*free)(struct fs_context
213 int (*dup)(struct fs_context *
214 int (*parse_param)(struct fs_c
215 struct fs_p
216 int (*parse_monolithic)(struct
217 int (*get_tree)(struct fs_cont
218 int (*reconfigure)(struct fs_c
219 };
220
221 These operations are invoked by the various st
222 manage the filesystem context. They are as fo
223
224 * ::
225
226 void (*free)(struct fs_context *fc);
227
228 Called to clean up the filesystem-specifi
229 when the context is destroyed. It should
230 context may have been removed and NULL'd
231
232 * ::
233
234 int (*dup)(struct fs_context *fc, stru
235
236 Called when a filesystem context has been
237 filesystem-private data. An error may be
238 do this.
239
240 .. Warning::
241
242 Note that even if this fails, put_fs_
243 immediately thereafter, so ->dup() *m
244 filesystem-private data safe for ->fr
245
246 * ::
247
248 int (*parse_param)(struct fs_context *
249 struct fs_parameter
250
251 Called when a parameter is being added to
252 points to the key name and maybe a value
253 will have been weeded out and fc->sb_flag
254 Security options will also have been weed
255
256 The parameter can be parsed with fs_parse
257 that the source(s) are presented as param
258
259 If successful, 0 should be returned or a
260
261 * ::
262
263 int (*parse_monolithic)(struct fs_cont
264
265 Called when the mount(2) system call is i
266 page in one go. If this is expected to b
267 items separated by commas, then this may
268
269 The return value is as for ->parse_param(
270
271 If the filesystem (e.g. NFS) needs to exa
272 finds it's the standard key-val list then
273 generic_parse_monolithic().
274
275 * ::
276
277 int (*get_tree)(struct fs_context *fc)
278
279 Called to get or create the mountable roo
280 information stored in the filesystem cont
281 different vector). It may detach any res
282 filesystem context and transfer them to t
283
284 On success it should set fc->root to the
285 the case of an error, it should return a
286
287 The phase on a userspace-driven context w
288 be called once on any particular context.
289
290 * ::
291
292 int (*reconfigure)(struct fs_context *
293
294 Called to effect reconfiguration of a sup
295 in the filesystem context. It may detach
296 the filesystem context and transfer them
297 superblock can be found from fc->root->d_
298
299 On success it should return 0. In the ca
300 a negative error code.
301
302 .. Note:: reconfigure is intended as a re
303
304
305 Filesystem context Security
306 ===========================
307
308 The filesystem context contains a security poi
309 building up a security context for the superbl
310 number of operations used by the new mount cod
311
312 * ::
313
314 int security_fs_context_alloc(struct f
315 struct d
316
317 Called to initialise fc->security (which
318 any resources needed. It should return 0
319 code on failure.
320
321 reference will be non-NULL if the context
322 reconfiguration (FS_CONTEXT_FOR_RECONFIGU
323 the root dentry of the superblock to be r
324 non-NULL in the case of a submount (FS_CO
325 it indicates the automount point.
326
327 * ::
328
329 int security_fs_context_dup(struct fs_
330 struct fs_
331
332 Called to initialise fc->security (which
333 any resources needed. The original files
334 src_fc and may be used for reference. It
335 negative error code on failure.
336
337 * ::
338
339 void security_fs_context_free(struct f
340
341 Called to clean up anything attached to f
342 contents may have been transferred to a s
343 during get_tree.
344
345 * ::
346
347 int security_fs_context_parse_param(st
348 st
349
350 Called for each mount parameter, includin
351 as for the ->parse_param() method. It sh
352 the parameter should be passed on to the
353 the parameter should be discarded or an e
354 parameter should be rejected.
355
356 The value pointed to by param may be modi
357 (provided the value pointer is NULL'd out
358 returned to prevent it being passed to th
359
360 * ::
361
362 int security_fs_context_validate(struc
363
364 Called after all the options have been pa
365 as a whole and to do any necessary alloca
366 security_sb_get_tree() and security_sb_re
367 fail. It should return 0 or a negative e
368
369 In the case of reconfiguration, the targe
370 via fc->root.
371
372 * ::
373
374 int security_sb_get_tree(struct fs_con
375
376 Called during the mount procedure to veri
377 is allowed to be mounted and to transfer
378 should return 0 or a negative error code.
379
380 * ::
381
382 void security_sb_reconfigure(struct fs
383
384 Called to apply any reconfiguration to an
385 fail. Error checking and resource alloca
386 the parameter parsing and validation hook
387
388 * ::
389
390 int security_sb_mountpoint(struct fs_c
391 struct path
392 unsigned in
393
394 Called during the mount procedure to veri
395 to the context is permitted to be attache
396 It should return 0 on success or a negati
397
398
399 VFS Filesystem context API
400 ==========================
401
402 There are four operations for creating a files
403 destroying a context:
404
405 * ::
406
407 struct fs_context *fs_context_for_mount
408
409
410 Allocate a filesystem context for the pur
411 whether that be with a new superblock or
412 sets the superblock flags, initialises th
413 fs_type->init_fs_context() to initialise
414
415 fs_type specifies the filesystem type tha
416 sb_flags presets the superblock flags sto
417
418 * ::
419
420 struct fs_context *fs_context_for_recon
421 struct dentry *dentry,
422 unsigned int sb_flags,
423 unsigned int sb_flags_mask);
424
425 Allocate a filesystem context for the pur
426 existing superblock. dentry provides a r
427 configured. sb_flags and sb_flags_mask i
428 need changing and to what.
429
430 * ::
431
432 struct fs_context *fs_context_for_submo
433 struct file_system_type *fs_ty
434 struct dentry *reference);
435
436 Allocate a filesystem context for the pur
437 an automount point or other derived super
438 filesystem type that will manage the cont
439 supplies the parameters. Namespaces are
440 dentry's superblock also.
441
442 Note that it's not a requirement that the
443 filesystem type as fs_type.
444
445 * ::
446
447 struct fs_context *vfs_dup_fs_context(
448
449 Duplicate a filesystem context, copying a
450 or additionally referencing any resources
451 for use where a filesystem has to get a m
452 does by internally mounting the root of t
453 private pathwalk to the target directory.
454
455 The purpose in the new context is inherit
456
457 * ::
458
459 void put_fs_context(struct fs_context *
460
461 Destroy a filesystem context, releasing a
462 calls the ->free() operation. This is in
463 created a filesystem context.
464
465 .. Warning::
466
467 filesystem contexts are not refcounted
468 destruction.
469
470 In all the above operations, apart from the pu
471 context pointer or a negative error code.
472
473 For the remaining operations, if an error occu
474 returned.
475
476 * ::
477
478 int vfs_parse_fs_param(struct fs_conte
479 struct fs_param
480
481 Supply a single mount parameter to the fi
482 the specification of the source/device wh
483 parameter (which may be specified multipl
484 supports that).
485
486 param specifies the parameter key name an
487 first checked to see if it corresponds to
488 case it is used to set an SB_xxx flag and
489 (in which case the LSM consumes it) befor
490 filesystem.
491
492 The parameter value is typed and can be o
493
494 ==================== ======
495 fs_value_is_flag Parame
496 fs_value_is_string Value
497 fs_value_is_blob Value
498 fs_value_is_filename Value
499 fs_value_is_file Value
500 ==================== ======
501
502 If there is a value, that value is stored
503 of param->{string,blob,name,file}. Note
504 clear the pointer, but then becomes respo
505 object.
506
507 * ::
508
509 int vfs_parse_fs_string(struct fs_conte
510 const char *val
511
512 A wrapper around vfs_parse_fs_param() tha
513 passed.
514
515 * ::
516
517 int generic_parse_monolithic(struct fs_
518
519 Parse a sys_mount() data page, assuming t
520 consisting of key[=val] options separated
521 list is passed to vfs_mount_option(). Th
522 ->parse_monolithic() method is NULL.
523
524 * ::
525
526 int vfs_get_tree(struct fs_context *fc)
527
528 Get or create the mountable root and supe
529 the filesystem context to select/configur
530 the ->get_tree() method.
531
532 * ::
533
534 struct vfsmount *vfs_create_mount(struc
535
536 Create a mount given the parameters in th
537 Note that this does not attach the mount
538
539
540 Superblock Creation Helpers
541 ===========================
542
543 A number of VFS helpers are available for use
544 or looking up of superblocks.
545
546 * ::
547
548 struct super_block *
549 sget_fc(struct fs_context *fc,
550 int (*test)(struct super_block
551 int (*set)(struct super_block *
552
553 This is the core routine. If test is non
554 existing superblock matching the criteria
555 the test function to match them. If no m
556 is created and the set function is called
557
558 Prior to the set function being called, f
559 to sb->s_fs_info - and fc->s_fs_info will
560 success (ie. 0).
561
562 The following helpers all wrap sget_fc():
563
564 (1) vfs_get_single_super
565
566 Only one such superblock may exist
567 attempt to get a new superblock ge
568 differences are ignored).
569
570 (2) vfs_get_keyed_super
571
572 Multiple superblocks of this type
573 their s_fs_info pointer (for examp
574 namespace).
575
576 (3) vfs_get_independent_super
577
578 Multiple independent superblocks o
579 function never matches an existing
580 one.
581
582
583 Parameter Description
584 =====================
585
586 Parameters are described using structures defi
587 There's a core description struct that links e
588
589 struct fs_parameter_description {
590 const struct fs_parameter_spec
591 const struct fs_parameter_enum
592 };
593
594 For example::
595
596 enum {
597 Opt_autocell,
598 Opt_bar,
599 Opt_dyn,
600 Opt_foo,
601 Opt_source,
602 };
603
604 static const struct fs_parameter_descr
605 .specs = afs_param_sp
606 .enums = afs_param_en
607 };
608
609 The members are as follows:
610
611 (1) ::
612
613 const struct fs_parameter_specification
614
615 Table of parameter specifications, termin
616 entries are of type::
617
618 struct fs_parameter_spec {
619 const char *name;
620 u8 opt;
621 enum fs_parameter_type type:8
622 unsigned short flags;
623 };
624
625 The 'name' field is a string to match exa
626 wildcards, patterns and no case-independe
627 will be returned by the fs_parser() funct
628 match.
629
630 The 'type' field indicates the desired va
631
632 ======================= ==============
633 TYPE NAME EXPECTED VALUE
634 ======================= ==============
635 fs_param_is_flag No value
636 fs_param_is_bool Boolean value
637 fs_param_is_u32 32-bit unsigne
638 fs_param_is_u32_octal 32-bit octal i
639 fs_param_is_u32_hex 32-bit hex int
640 fs_param_is_s32 32-bit signed
641 fs_param_is_u64 64-bit unsigne
642 fs_param_is_enum Enum value nam
643 fs_param_is_string Arbitrary stri
644 fs_param_is_blob Binary blob
645 fs_param_is_blockdev Blockdev path
646 fs_param_is_path Path
647 fs_param_is_fd File descripto
648 fs_param_is_uid User ID (u32)
649 fs_param_is_gid Group ID (u32)
650 ======================= ==============
651
652 Note that if the value is of fs_param_is_
653 to match any string value against "0", "1
654
655 Each parameter can also be qualified with
656
657 ======================= ==============
658 fs_param_v_optional The value is o
659 fs_param_neg_with_no result->negate
660 fs_param_neg_with_empty result->negate
661 fs_param_deprecated The parameter
662 ======================= ==============
663
664 These are wrapped with a number of conven
665
666 ======================= ==============
667 MACRO SPECIFIES
668 ======================= ==============
669 fsparam_flag() fs_param_is_fl
670 fsparam_flag_no() fs_param_is_fl
671 fsparam_bool() fs_param_is_bo
672 fsparam_u32() fs_param_is_u3
673 fsparam_u32oct() fs_param_is_u3
674 fsparam_u32hex() fs_param_is_u3
675 fsparam_s32() fs_param_is_s3
676 fsparam_u64() fs_param_is_u6
677 fsparam_enum() fs_param_is_en
678 fsparam_string() fs_param_is_st
679 fsparam_blob() fs_param_is_bl
680 fsparam_bdev() fs_param_is_bl
681 fsparam_path() fs_param_is_pa
682 fsparam_fd() fs_param_is_fd
683 fsparam_uid() fs_param_is_ui
684 fsparam_gid() fs_param_is_gi
685 ======================= ==============
686
687 all of which take two arguments, name str
688 example::
689
690 static const struct fs_parameter_spec
691 fsparam_flag ("autocell",
692 fsparam_flag ("dyn",
693 fsparam_string ("source",
694 fsparam_flag_no ("foo",
695 {}
696 };
697
698 An addition macro, __fsparam() is provide
699 of arguments to specify the type and the
700 match one of the above macros.
701
702 (2) ::
703
704 const struct fs_parameter_enum *enums;
705
706 Table of enum value names to integer mapp
707 entry. This is of type::
708
709 struct fs_parameter_enum {
710 u8 opt;
711 char name[14];
712 u8 value;
713 };
714
715 Where the array is an unsorted list of {
716 elements that indicate the value to map t
717
718 static const struct fs_parameter_enum
719 { Opt_bar, "x", 1},
720 { Opt_bar, "y", 23},
721 { Opt_bar, "z", 42},
722 };
723
724 If a parameter of type fs_param_is_enum i
725 try to look the value up in the enum tabl
726 in the parse result.
727
728 The parser should be pointed to by the parser
729 struct as this will provide validation on regi
730 CONFIG_VALIDATE_FS_PARSER=y) and will allow th
731 userspace using the fsinfo() syscall.
732
733
734 Parameter Helper Functions
735 ==========================
736
737 A number of helper functions are provided to h
738 process the parameters it is given.
739
740 * ::
741
742 int lookup_constant(const struct consta
743 const char *name, i
744
745 Look up a constant by name in a table of
746 table is an array of elements of the foll
747
748 struct constant_table {
749 const char *name;
750 int value;
751 };
752
753 If a match is found, the corresponding va
754 isn't found, the not_found value is retur
755
756 * ::
757
758 bool validate_constant_table(const stru
759 size_t tbl
760 int low, i
761
762 Validate a constant table. Checks that a
763 ordered, that there are no duplicates and
764 and high inclusive, though provision is m
765 value outside of that range. If no speci
766 should just be set to lie inside the low-
767
768 If all is good, true is returned. If the
769 logged to the kernel log buffer and false
770
771 * ::
772
773 bool fs_validate_description(const stru
774
775 This performs some validation checks on a
776 returns true if the description is good a
777 log errors to the kernel log buffer if va
778
779 * ::
780
781 int fs_parse(struct fs_context *fc,
782 const struct fs_parameter
783 struct fs_parameter *para
784 struct fs_parse_result *r
785
786 This is the main interpreter of parameter
787 description to look up a parameter by key
788 option number (which it returns).
789
790 If successful, and if the parameter type
791 boolean, integer, enum, uid, or gid type,
792 function and the result stored in
793 result->{boolean,int_32,uint_32,uint_64,u
794
795 If a match isn't initially made, the key
796 value is present then an attempt will be
797 prefix removed. If this matches a parame
798 fs_param_neg_with_no set, then a match wi
799 will be set to true.
800
801 If the parameter isn't matched, -ENOPARAM
802 parameter is matched, but the value is er
803 returned; otherwise the parameter's optio
804
805 * ::
806
807 int fs_lookup_param(struct fs_context *
808 struct fs_parameter
809 bool want_bdev,
810 unsigned int flags,
811 struct path *_path)
812
813 This takes a parameter that carries a str
814 to do a path lookup on it. If the parame
815 is made that the inode actually represent
816
817 Returns 0 if successful and ``*_path`` wi
818 error code if not.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.