819 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3====================4Filesystem Mount API5====================6 7.. CONTENTS8 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 26Overview27========28 29The creation of new mounts is now to be done in a multistep process:30 31 (1) Create a filesystem context.32 33 (2) Parse the parameters and attach them to the context. Parameters are34 expected to be passed individually from userspace, though legacy binary35 parameters can also be handled.36 37 (3) Validate and pre-process the context.38 39 (4) Get or create a superblock and mountable root.40 41 (5) Perform the mount.42 43 (6) Return an error message attached to the context.44 45 (7) Destroy the context.46 47To support this, the file_system_type struct gains two new fields::48 49 int (*init_fs_context)(struct fs_context *fc);50 const struct fs_parameter_description *parameters;51 52The first is invoked to set up the filesystem-specific parts of a filesystem53context, including the additional space, and the second points to the54parameter description for validation at registration time and querying by a55future system call.56 57Note that security initialisation is done *after* the filesystem is called so58that the namespaces may be adjusted first.59 60 61The Filesystem context62======================63 64The creation and reconfiguration of a superblock is governed by a filesystem65context. This is represented by the fs_context structure::66 67 struct fs_context {68 const struct fs_context_operations *ops;69 struct file_system_type *fs_type;70 void *fs_private;71 struct dentry *root;72 struct user_namespace *user_ns;73 struct net *net_ns;74 const struct cred *cred;75 char *source;76 char *subtype;77 void *security;78 void *s_fs_info;79 unsigned int sb_flags;80 unsigned int sb_flags_mask;81 unsigned int s_iflags;82 enum fs_context_purpose purpose:8;83 ...84 };85 86The fs_context fields are as follows:87 88 * ::89 90 const struct fs_context_operations *ops91 92 These are operations that can be done on a filesystem context (see93 below). This must be set by the ->init_fs_context() file_system_type94 operation.95 96 * ::97 98 struct file_system_type *fs_type99 100 A pointer to the file_system_type of the filesystem that is being101 constructed or reconfigured. This retains a reference on the type owner.102 103 * ::104 105 void *fs_private106 107 A pointer to the file system's private data. This is where the filesystem108 will need to store any options it parses.109 110 * ::111 112 struct dentry *root113 114 A pointer to the root of the mountable tree (and indirectly, the115 superblock thereof). This is filled in by the ->get_tree() op. If this116 is set, an active reference on root->d_sb must also be held.117 118 * ::119 120 struct user_namespace *user_ns121 struct net *net_ns122 123 There are a subset of the namespaces in use by the invoking process. They124 retain references on each namespace. The subscribed namespaces may be125 replaced by the filesystem to reflect other sources, such as the parent126 mount superblock on an automount.127 128 * ::129 130 const struct cred *cred131 132 The mounter's credentials. This retains a reference on the credentials.133 134 * ::135 136 char *source137 138 This specifies the source. It may be a block device (e.g. /dev/sda1) or139 something more exotic, such as the "host:/path" that NFS desires.140 141 * ::142 143 char *subtype144 145 This is a string to be added to the type displayed in /proc/mounts to146 qualify it (used by FUSE). This is available for the filesystem to set if147 desired.148 149 * ::150 151 void *security152 153 A place for the LSMs to hang their security data for the superblock. The154 relevant security operations are described below.155 156 * ::157 158 void *s_fs_info159 160 The proposed s_fs_info for a new superblock, set in the superblock by161 sget_fc(). This can be used to distinguish superblocks.162 163 * ::164 165 unsigned int sb_flags166 unsigned int sb_flags_mask167 168 Which bits SB_* flags are to be set/cleared in super_block::s_flags.169 170 * ::171 172 unsigned int s_iflags173 174 These will be bitwise-OR'd with s->s_iflags when a superblock is created.175 176 * ::177 178 enum fs_context_purpose179 180 This indicates the purpose for which the context is intended. The181 available values are:182 183 ========================== ======================================184 FS_CONTEXT_FOR_MOUNT, New superblock for explicit mount185 FS_CONTEXT_FOR_SUBMOUNT New automatic submount of extant mount186 FS_CONTEXT_FOR_RECONFIGURE Change an existing mount187 ========================== ======================================188 189The mount context is created by calling vfs_new_fs_context() or190vfs_dup_fs_context() and is destroyed with put_fs_context(). Note that the191structure is not refcounted.192 193VFS, security and filesystem mount options are set individually with194vfs_parse_mount_option(). Options provided by the old mount(2) system call as195a page of data can be parsed with generic_parse_monolithic().196 197When mounting, the filesystem is allowed to take data from any of the pointers198and attach it to the superblock (or whatever), provided it clears the pointer199in the mount context.200 201The filesystem is also allowed to allocate resources and pin them with the202mount context. For instance, NFS might pin the appropriate protocol version203module.204 205 206The Filesystem Context Operations207=================================208 209The filesystem context points to a table of operations::210 211 struct fs_context_operations {212 void (*free)(struct fs_context *fc);213 int (*dup)(struct fs_context *fc, struct fs_context *src_fc);214 int (*parse_param)(struct fs_context *fc,215 struct fs_parameter *param);216 int (*parse_monolithic)(struct fs_context *fc, void *data);217 int (*get_tree)(struct fs_context *fc);218 int (*reconfigure)(struct fs_context *fc);219 };220 221These operations are invoked by the various stages of the mount procedure to222manage the filesystem context. They are as follows:223 224 * ::225 226 void (*free)(struct fs_context *fc);227 228 Called to clean up the filesystem-specific part of the filesystem context229 when the context is destroyed. It should be aware that parts of the230 context may have been removed and NULL'd out by ->get_tree().231 232 * ::233 234 int (*dup)(struct fs_context *fc, struct fs_context *src_fc);235 236 Called when a filesystem context has been duplicated to duplicate the237 filesystem-private data. An error may be returned to indicate failure to238 do this.239 240 .. Warning::241 242 Note that even if this fails, put_fs_context() will be called243 immediately thereafter, so ->dup() *must* make the244 filesystem-private data safe for ->free().245 246 * ::247 248 int (*parse_param)(struct fs_context *fc,249 struct fs_parameter *param);250 251 Called when a parameter is being added to the filesystem context. param252 points to the key name and maybe a value object. VFS-specific options253 will have been weeded out and fc->sb_flags updated in the context.254 Security options will also have been weeded out and fc->security updated.255 256 The parameter can be parsed with fs_parse() and fs_lookup_param(). Note257 that the source(s) are presented as parameters named "source".258 259 If successful, 0 should be returned or a negative error code otherwise.260 261 * ::262 263 int (*parse_monolithic)(struct fs_context *fc, void *data);264 265 Called when the mount(2) system call is invoked to pass the entire data266 page in one go. If this is expected to be just a list of "key[=val]"267 items separated by commas, then this may be set to NULL.268 269 The return value is as for ->parse_param().270 271 If the filesystem (e.g. NFS) needs to examine the data first and then272 finds it's the standard key-val list then it may pass it off to273 generic_parse_monolithic().274 275 * ::276 277 int (*get_tree)(struct fs_context *fc);278 279 Called to get or create the mountable root and superblock, using the280 information stored in the filesystem context (reconfiguration goes via a281 different vector). It may detach any resources it desires from the282 filesystem context and transfer them to the superblock it creates.283 284 On success it should set fc->root to the mountable root and return 0. In285 the case of an error, it should return a negative error code.286 287 The phase on a userspace-driven context will be set to only allow this to288 be called once on any particular context.289 290 * ::291 292 int (*reconfigure)(struct fs_context *fc);293 294 Called to effect reconfiguration of a superblock using information stored295 in the filesystem context. It may detach any resources it desires from296 the filesystem context and transfer them to the superblock. The297 superblock can be found from fc->root->d_sb.298 299 On success it should return 0. In the case of an error, it should return300 a negative error code.301 302 .. Note:: reconfigure is intended as a replacement for remount_fs.303 304 305Filesystem context Security306===========================307 308The filesystem context contains a security pointer that the LSMs can use for309building up a security context for the superblock to be mounted. There are a310number of operations used by the new mount code for this purpose:311 312 * ::313 314 int security_fs_context_alloc(struct fs_context *fc,315 struct dentry *reference);316 317 Called to initialise fc->security (which is preset to NULL) and allocate318 any resources needed. It should return 0 on success or a negative error319 code on failure.320 321 reference will be non-NULL if the context is being created for superblock322 reconfiguration (FS_CONTEXT_FOR_RECONFIGURE) in which case it indicates323 the root dentry of the superblock to be reconfigured. It will also be324 non-NULL in the case of a submount (FS_CONTEXT_FOR_SUBMOUNT) in which case325 it indicates the automount point.326 327 * ::328 329 int security_fs_context_dup(struct fs_context *fc,330 struct fs_context *src_fc);331 332 Called to initialise fc->security (which is preset to NULL) and allocate333 any resources needed. The original filesystem context is pointed to by334 src_fc and may be used for reference. It should return 0 on success or a335 negative error code on failure.336 337 * ::338 339 void security_fs_context_free(struct fs_context *fc);340 341 Called to clean up anything attached to fc->security. Note that the342 contents may have been transferred to a superblock and the pointer cleared343 during get_tree.344 345 * ::346 347 int security_fs_context_parse_param(struct fs_context *fc,348 struct fs_parameter *param);349 350 Called for each mount parameter, including the source. The arguments are351 as for the ->parse_param() method. It should return 0 to indicate that352 the parameter should be passed on to the filesystem, 1 to indicate that353 the parameter should be discarded or an error to indicate that the354 parameter should be rejected.355 356 The value pointed to by param may be modified (if a string) or stolen357 (provided the value pointer is NULL'd out). If it is stolen, 1 must be358 returned to prevent it being passed to the filesystem.359 360 * ::361 362 int security_fs_context_validate(struct fs_context *fc);363 364 Called after all the options have been parsed to validate the collection365 as a whole and to do any necessary allocation so that366 security_sb_get_tree() and security_sb_reconfigure() are less likely to367 fail. It should return 0 or a negative error code.368 369 In the case of reconfiguration, the target superblock will be accessible370 via fc->root.371 372 * ::373 374 int security_sb_get_tree(struct fs_context *fc);375 376 Called during the mount procedure to verify that the specified superblock377 is allowed to be mounted and to transfer the security data there. It378 should return 0 or a negative error code.379 380 * ::381 382 void security_sb_reconfigure(struct fs_context *fc);383 384 Called to apply any reconfiguration to an LSM's context. It must not385 fail. Error checking and resource allocation must be done in advance by386 the parameter parsing and validation hooks.387 388 * ::389 390 int security_sb_mountpoint(struct fs_context *fc,391 struct path *mountpoint,392 unsigned int mnt_flags);393 394 Called during the mount procedure to verify that the root dentry attached395 to the context is permitted to be attached to the specified mountpoint.396 It should return 0 on success or a negative error code on failure.397 398 399VFS Filesystem context API400==========================401 402There are four operations for creating a filesystem context and one for403destroying a context:404 405 * ::406 407 struct fs_context *fs_context_for_mount(struct file_system_type *fs_type,408 unsigned int sb_flags);409 410 Allocate a filesystem context for the purpose of setting up a new mount,411 whether that be with a new superblock or sharing an existing one. This412 sets the superblock flags, initialises the security and calls413 fs_type->init_fs_context() to initialise the filesystem private data.414 415 fs_type specifies the filesystem type that will manage the context and416 sb_flags presets the superblock flags stored therein.417 418 * ::419 420 struct fs_context *fs_context_for_reconfigure(421 struct dentry *dentry,422 unsigned int sb_flags,423 unsigned int sb_flags_mask);424 425 Allocate a filesystem context for the purpose of reconfiguring an426 existing superblock. dentry provides a reference to the superblock to be427 configured. sb_flags and sb_flags_mask indicate which superblock flags428 need changing and to what.429 430 * ::431 432 struct fs_context *fs_context_for_submount(433 struct file_system_type *fs_type,434 struct dentry *reference);435 436 Allocate a filesystem context for the purpose of creating a new mount for437 an automount point or other derived superblock. fs_type specifies the438 filesystem type that will manage the context and the reference dentry439 supplies the parameters. Namespaces are propagated from the reference440 dentry's superblock also.441 442 Note that it's not a requirement that the reference dentry be of the same443 filesystem type as fs_type.444 445 * ::446 447 struct fs_context *vfs_dup_fs_context(struct fs_context *src_fc);448 449 Duplicate a filesystem context, copying any options noted and duplicating450 or additionally referencing any resources held therein. This is available451 for use where a filesystem has to get a mount within a mount, such as NFS4452 does by internally mounting the root of the target server and then doing a453 private pathwalk to the target directory.454 455 The purpose in the new context is inherited from the old one.456 457 * ::458 459 void put_fs_context(struct fs_context *fc);460 461 Destroy a filesystem context, releasing any resources it holds. This462 calls the ->free() operation. This is intended to be called by anyone who463 created a filesystem context.464 465 .. Warning::466 467 filesystem contexts are not refcounted, so this causes unconditional468 destruction.469 470In all the above operations, apart from the put op, the return is a mount471context pointer or a negative error code.472 473For the remaining operations, if an error occurs, a negative error code will be474returned.475 476 * ::477 478 int vfs_parse_fs_param(struct fs_context *fc,479 struct fs_parameter *param);480 481 Supply a single mount parameter to the filesystem context. This includes482 the specification of the source/device which is specified as the "source"483 parameter (which may be specified multiple times if the filesystem484 supports that).485 486 param specifies the parameter key name and the value. The parameter is487 first checked to see if it corresponds to a standard mount flag (in which488 case it is used to set an SB_xxx flag and consumed) or a security option489 (in which case the LSM consumes it) before it is passed on to the490 filesystem.491 492 The parameter value is typed and can be one of:493 494 ==================== =============================495 fs_value_is_flag Parameter not given a value496 fs_value_is_string Value is a string497 fs_value_is_blob Value is a binary blob498 fs_value_is_filename Value is a filename* + dirfd499 fs_value_is_file Value is an open file (file*)500 ==================== =============================501 502 If there is a value, that value is stored in a union in the struct in one503 of param->{string,blob,name,file}. Note that the function may steal and504 clear the pointer, but then becomes responsible for disposing of the505 object.506 507 * ::508 509 int vfs_parse_fs_string(struct fs_context *fc, const char *key,510 const char *value, size_t v_size);511 512 A wrapper around vfs_parse_fs_param() that copies the value string it is513 passed.514 515 * ::516 517 int generic_parse_monolithic(struct fs_context *fc, void *data);518 519 Parse a sys_mount() data page, assuming the form to be a text list520 consisting of key[=val] options separated by commas. Each item in the521 list is passed to vfs_mount_option(). This is the default when the522 ->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 superblock, using the parameters in529 the filesystem context to select/configure the superblock. This invokes530 the ->get_tree() method.531 532 * ::533 534 struct vfsmount *vfs_create_mount(struct fs_context *fc);535 536 Create a mount given the parameters in the specified filesystem context.537 Note that this does not attach the mount to anything.538 539 540Superblock Creation Helpers541===========================542 543A number of VFS helpers are available for use by filesystems for the creation544or looking up of superblocks.545 546 * ::547 548 struct super_block *549 sget_fc(struct fs_context *fc,550 int (*test)(struct super_block *sb, struct fs_context *fc),551 int (*set)(struct super_block *sb, struct fs_context *fc));552 553 This is the core routine. If test is non-NULL, it searches for an554 existing superblock matching the criteria held in the fs_context, using555 the test function to match them. If no match is found, a new superblock556 is created and the set function is called to set it up.557 558 Prior to the set function being called, fc->s_fs_info will be transferred559 to sb->s_fs_info - and fc->s_fs_info will be cleared if set returns560 success (ie. 0).561 562The following helpers all wrap sget_fc():563 564 (1) vfs_get_single_super565 566 Only one such superblock may exist in the system. Any further567 attempt to get a new superblock gets this one (and any parameter568 differences are ignored).569 570 (2) vfs_get_keyed_super571 572 Multiple superblocks of this type may exist and they're keyed on573 their s_fs_info pointer (for example this may refer to a574 namespace).575 576 (3) vfs_get_independent_super577 578 Multiple independent superblocks of this type may exist. This579 function never matches an existing one and always creates a new580 one.581 582 583Parameter Description584=====================585 586Parameters are described using structures defined in linux/fs_parser.h.587There's a core description struct that links everything together::588 589 struct fs_parameter_description {590 const struct fs_parameter_spec *specs;591 const struct fs_parameter_enum *enums;592 };593 594For 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_description afs_fs_parameters = {605 .specs = afs_param_specs,606 .enums = afs_param_enums,607 };608 609The members are as follows:610 611 (1) ::612 613 const struct fs_parameter_specification *specs;614 615 Table of parameter specifications, terminated with a null entry, where the616 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 exactly to the parameter key (no626 wildcards, patterns and no case-independence) and 'opt' is the value that627 will be returned by the fs_parser() function in the case of a successful628 match.629 630 The 'type' field indicates the desired value type and must be one of:631 632 ======================= ======================= =====================633 TYPE NAME EXPECTED VALUE RESULT IN634 ======================= ======================= =====================635 fs_param_is_flag No value n/a636 fs_param_is_bool Boolean value result->boolean637 fs_param_is_u32 32-bit unsigned int result->uint_32638 fs_param_is_u32_octal 32-bit octal int result->uint_32639 fs_param_is_u32_hex 32-bit hex int result->uint_32640 fs_param_is_s32 32-bit signed int result->int_32641 fs_param_is_u64 64-bit unsigned int result->uint_64642 fs_param_is_enum Enum value name result->uint_32643 fs_param_is_string Arbitrary string param->string644 fs_param_is_blob Binary blob param->blob645 fs_param_is_blockdev Blockdev path * Needs lookup646 fs_param_is_path Path * Needs lookup647 fs_param_is_fd File descriptor result->int_32648 fs_param_is_uid User ID (u32) result->uid649 fs_param_is_gid Group ID (u32) result->gid650 ======================= ======================= =====================651 652 Note that if the value is of fs_param_is_bool type, fs_parse() will try653 to match any string value against "0", "1", "no", "yes", "false", "true".654 655 Each parameter can also be qualified with 'flags':656 657 ======================= ================================================658 fs_param_v_optional The value is optional659 fs_param_neg_with_no result->negated set if key is prefixed with "no"660 fs_param_neg_with_empty result->negated set if value is ""661 fs_param_deprecated The parameter is deprecated.662 ======================= ================================================663 664 These are wrapped with a number of convenience wrappers:665 666 ======================= ===============================================667 MACRO SPECIFIES668 ======================= ===============================================669 fsparam_flag() fs_param_is_flag670 fsparam_flag_no() fs_param_is_flag, fs_param_neg_with_no671 fsparam_bool() fs_param_is_bool672 fsparam_u32() fs_param_is_u32673 fsparam_u32oct() fs_param_is_u32_octal674 fsparam_u32hex() fs_param_is_u32_hex675 fsparam_s32() fs_param_is_s32676 fsparam_u64() fs_param_is_u64677 fsparam_enum() fs_param_is_enum678 fsparam_string() fs_param_is_string679 fsparam_blob() fs_param_is_blob680 fsparam_bdev() fs_param_is_blockdev681 fsparam_path() fs_param_is_path682 fsparam_fd() fs_param_is_fd683 fsparam_uid() fs_param_is_uid684 fsparam_gid() fs_param_is_gid685 ======================= ===============================================686 687 all of which take two arguments, name string and option number - for688 example::689 690 static const struct fs_parameter_spec afs_param_specs[] = {691 fsparam_flag ("autocell", Opt_autocell),692 fsparam_flag ("dyn", Opt_dyn),693 fsparam_string ("source", Opt_source),694 fsparam_flag_no ("foo", Opt_foo),695 {}696 };697 698 An addition macro, __fsparam() is provided that takes an additional pair699 of arguments to specify the type and the flags for anything that doesn't700 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 mappings, terminated with a null707 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 { parameter ID, name }-keyed716 elements that indicate the value to map to, e.g.::717 718 static const struct fs_parameter_enum afs_param_enums[] = {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 is encountered, fs_parse() will725 try to look the value up in the enum table and the result will be stored726 in the parse result.727 728The parser should be pointed to by the parser pointer in the file_system_type729struct as this will provide validation on registration (if730CONFIG_VALIDATE_FS_PARSER=y) and will allow the description to be queried from731userspace using the fsinfo() syscall.732 733 734Parameter Helper Functions735==========================736 737A number of helper functions are provided to help a filesystem or an LSM738process the parameters it is given.739 740 * ::741 742 int lookup_constant(const struct constant_table tbl[],743 const char *name, int not_found);744 745 Look up a constant by name in a table of name -> integer mappings. The746 table is an array of elements of the following type::747 748 struct constant_table {749 const char *name;750 int value;751 };752 753 If a match is found, the corresponding value is returned. If a match754 isn't found, the not_found value is returned instead.755 756 * ::757 758 bool validate_constant_table(const struct constant_table *tbl,759 size_t tbl_size,760 int low, int high, int special);761 762 Validate a constant table. Checks that all the elements are appropriately763 ordered, that there are no duplicates and that the values are between low764 and high inclusive, though provision is made for one allowable special765 value outside of that range. If no special value is required, special766 should just be set to lie inside the low-to-high range.767 768 If all is good, true is returned. If the table is invalid, errors are769 logged to the kernel log buffer and false is returned.770 771 * ::772 773 bool fs_validate_description(const struct fs_parameter_description *desc);774 775 This performs some validation checks on a parameter description. It776 returns true if the description is good and false if it is not. It will777 log errors to the kernel log buffer if validation fails.778 779 * ::780 781 int fs_parse(struct fs_context *fc,782 const struct fs_parameter_description *desc,783 struct fs_parameter *param,784 struct fs_parse_result *result);785 786 This is the main interpreter of parameters. It uses the parameter787 description to look up a parameter by key name and to convert that to an788 option number (which it returns).789 790 If successful, and if the parameter type indicates the result is a791 boolean, integer, enum, uid, or gid type, the value is converted by this792 function and the result stored in793 result->{boolean,int_32,uint_32,uint_64,uid,gid}.794 795 If a match isn't initially made, the key is prefixed with "no" and no796 value is present then an attempt will be made to look up the key with the797 prefix removed. If this matches a parameter for which the type has flag798 fs_param_neg_with_no set, then a match will be made and result->negated799 will be set to true.800 801 If the parameter isn't matched, -ENOPARAM will be returned; if the802 parameter is matched, but the value is erroneous, -EINVAL will be803 returned; otherwise the parameter's option number will be returned.804 805 * ::806 807 int fs_lookup_param(struct fs_context *fc,808 struct fs_parameter *value,809 bool want_bdev,810 unsigned int flags,811 struct path *_path);812 813 This takes a parameter that carries a string or filename type and attempts814 to do a path lookup on it. If the parameter expects a blockdev, a check815 is made that the inode actually represents one.816 817 Returns 0 if successful and ``*_path`` will be set; returns a negative818 error code if not.819