Commit 0150aedd authored by Jonathan Corbet's avatar Jonathan Corbet
Browse files

Merge branch 'mauro' into docs-next 



Mauro sez:

  There are lots of plain text documents under Documentation/filesystems.
  Manually convert several of those to ReST and add them to the index file.

Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parents 3eb30c51 9a610812

Documentation/filesystems/9p.txt→Documentation/filesystems/9p.rst

+69 −45
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0



=======================================

v9fs: Plan 9 Resource Sharing for Linux

=======================================



ABOUT

About

=====



v9fs is a Unix implementation of the Plan 9 9p remote filesystem protocol.
@@ -14,9 +17,11 @@ and Maya Gokhale. Additional development by Greg Watson 


The best detailed explanation of the Linux implementation and applications of

the 9p client is available in the form of a USENIX paper:



   http://www.usenix.org/events/usenix05/tech/freenix/hensbergen.html



Other applications are described in the following papers:



	* XCPU & Clustering

	  http://xcpu.org/papers/xcpu-talk.pdf

	* KVMFS: control file system for KVM
@@ -28,18 +33,18 @@ Other applications are described in the following papers: 
	* VirtFS: A Virtualization Aware File System pass-through

	  http://goo.gl/3WPDg



USAGE

Usage

=====



For remote file server:

For remote file server::



	mount -t 9p 10.10.1.2 /mnt/9



For Plan 9 From User Space applications (http://swtch.com/plan9)

For Plan 9 From User Space applications (http://swtch.com/plan9)::



	mount -t 9p `namespace`/acme /mnt/9 -o trans=unix,uname=$USER



For server running on QEMU host with virtio transport:

For server running on QEMU host with virtio transport::



	mount -t 9p -o trans=virtio <mount_tag> /mnt/9
@@ -48,18 +53,22 @@ mount points. Each 9P export is seen by the client as a virtio device with an 
associated "mount_tag" property. Available mount tags can be

seen by reading /sys/bus/virtio/drivers/9pnet_virtio/virtio<n>/mount_tag files.



OPTIONS

Options

=======



  ============= ===============================================================

  trans=name	select an alternative transport.  Valid options are

  		currently:

			unix 	- specifying a named pipe mount point

			tcp	- specifying a normal TCP/IP connection

			fd   	- used passed file descriptors for connection



			========  ============================================

			unix 	  specifying a named pipe mount point

			tcp	  specifying a normal TCP/IP connection

			fd   	  used passed file descriptors for connection

                                  (see rfdno and wfdno)

			virtio	- connect to the next virtio channel available

			virtio	  connect to the next virtio channel available

				  (from QEMU with trans_virtio module)

			rdma	- connect to a specified RDMA channel

			rdma	  connect to a specified RDMA channel

			========  ============================================



  uname=name	user name to attempt mount as on the remote server.  The

  		server may override or ignore this value.  Certain user
@@ -69,28 +78,36 @@ OPTIONS 
  		offering several exported file systems.



  cache=mode	specifies a caching policy.  By default, no caches are used.

                        none = default no cache policy, metadata and data



                        none

				default no cache policy, metadata and data

                                alike are synchronous.

			loose = no attempts are made at consistency,

			loose

				no attempts are made at consistency,

                                intended for exclusive, read-only mounts

                        fscache = use FS-Cache for a persistent, read-only

                        fscache

				use FS-Cache for a persistent, read-only

				cache backend.

                        mmap = minimal cache that is only used for read-write

                        mmap

				minimal cache that is only used for read-write

                                mmap.  Northing else is cached, like cache=none



  debug=n	specifies debug level.  The debug level is a bitmask.

			0x01  = display verbose error messages

			0x02  = developer debug (DEBUG_CURRENT)

			0x04  = display 9p trace

			0x08  = display VFS trace

			0x10  = display Marshalling debug

			0x20  = display RPC debug

			0x40  = display transport debug

			0x80  = display allocation debug

			0x100 = display protocol message debug

			0x200 = display Fid debug

			0x400 = display packet debug

			0x800 = display fscache tracing debug



			=====   ================================

			0x01    display verbose error messages

			0x02    developer debug (DEBUG_CURRENT)

			0x04    display 9p trace

			0x08    display VFS trace

			0x10    display Marshalling debug

			0x20    display RPC debug

			0x40    display transport debug

			0x80    display allocation debug

			0x100   display protocol message debug

			0x200   display Fid debug

			0x400   display packet debug

			0x800   display fscache tracing debug

			=====   ================================



  rfdno=n	the file descriptor for reading with trans=fd
@@ -103,9 +120,12 @@ OPTIONS 
  noextend	force legacy mode (no 9p2000.u or 9p2000.L semantics)



  version=name	Select 9P protocol version. Valid options are:

			9p2000          - Legacy mode (same as noextend)

			9p2000.u        - Use 9P2000.u protocol

			9p2000.L        - Use 9P2000.L protocol



			========        ==============================

			9p2000          Legacy mode (same as noextend)

			9p2000.u        Use 9P2000.u protocol

			9p2000.L        Use 9P2000.L protocol

			========        ==============================



  dfltuid	attempt to mount as a particular uid
@@ -118,22 +138,27 @@ OPTIONS 
		hosts.  This functionality will be expanded in later versions.



  access	there are four access modes.

			user  = if a user tries to access a file on v9fs

			user

				if a user tries to access a file on v9fs

			        filesystem for the first time, v9fs sends an

			        attach command (Tattach) for that user.

				This is the default mode.

			<uid> = allows only user with uid=<uid> to access

			<uid>

				allows only user with uid=<uid> to access

				the files on the mounted filesystem

			any   = v9fs does single attach and performs all

			any

				v9fs does single attach and performs all

				operations as one user

			client = ACL based access check on the 9p client

			clien

				 ACL based access check on the 9p client

			         side for access validation



  cachetag	cache tag to use the specified persistent cache.

		cache tags for existing cache sessions can be listed at

		/sys/fs/9p/caches. (applies only to cache=fscache)

  ============= ===============================================================



RESOURCES

Resources

=========



Protocol specifications are maintained on github:
@@ -158,4 +183,3 @@ http://plan9.bell-labs.com/plan9 


For information on Plan 9 from User Space (Plan 9 applications and libraries

ported to Linux/BSD/OSX/etc) check out http://swtch.com/plan9

Documentation/filesystems/adfs.txt→Documentation/filesystems/adfs.rst

+19 −10
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0



===============================

Acorn Disc Filing System - ADFS

===============================



Filesystems supported by ADFS

-----------------------------
@@ -25,6 +31,7 @@ directory updates, specifically updating the access mode and timestamp. 
Mount options for ADFS

----------------------



  ============  ======================================================

  uid=nnn	All files in the partition will be owned by

		user id nnn.  Default 0 (root).

  gid=nnn	All files in the partition will be in group
@@ -36,22 +43,23 @@ Mount options for ADFS 
  ftsuffix=n	When ftsuffix=0, no file type suffix will be applied.

		When ftsuffix=1, a hexadecimal suffix corresponding to

		the RISC OS file type will be added.  Default 0.

  ============  ======================================================



Mapping of ADFS permissions to Linux permissions

------------------------------------------------



  ADFS permissions consist of the following:



	Owner read

	Owner write

	Other read

	Other write

	- Owner read

	- Owner write

	- Other read

	- Other write



  (In older versions, an 'execute' permission did exist, but this

  does not hold the same meaning as the Linux 'execute' permission

  and is now obsolete).



  The mapping is performed as follows:

  The mapping is performed as follows::



	Owner read				-> -r--r--r--

	Owner write				-> --w--w---w
@@ -66,17 +74,18 @@ Mapping of ADFS permissions to Linux permissions 
	Possible other mode permissions		-> ----rwxrwx



  Hence, with the default masks, if a file is owner read/write, and

  not a UnixExec filetype, then the permissions will be:

  not a UnixExec filetype, then the permissions will be::



			-rw-------



  However, if the masks were ownmask=0770,othmask=0007, then this would

  be modified to:

  be modified to::



			-rw-rw----



  There is no restriction on what you can do with these masks.  You may

  wish that either read bits give read access to the file for all, but

  keep the default write protection (ownmask=0755,othmask=0577):

  keep the default write protection (ownmask=0755,othmask=0577)::



			-rw-r--r--

Documentation/filesystems/affs.txt→Documentation/filesystems/affs.rst

+43 −19
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0



=============================

Overview of Amiga Filesystems

=============================



Not all varieties of the Amiga filesystems are supported for reading and

writing. The Amiga currently knows six different filesystems:



==============	===============================================================

DOS\0		The old or original filesystem, not really suited for

		hard disks and normally not used on them, either.

		Supported read/write.
@@ -23,6 +27,7 @@ DOS\4 The original filesystem with directory cache. The directory 
		sense on hard disks. Supported read only.



DOS\5		The Fast File System with directory cache. Supported read only.

==============	===============================================================



All of the above filesystems allow block sizes from 512 to 32K bytes.

Supported block sizes are: 512, 1024, 2048 and 4096 bytes. Larger blocks
@@ -36,14 +41,18 @@ are supported, too. 
Mount options for the AFFS

==========================



protect		If this option is set, the protection bits cannot be altered.

protect

		If this option is set, the protection bits cannot be altered.



setuid[=uid]	This sets the owner of all files and directories in the file

setuid[=uid]

		This sets the owner of all files and directories in the file

		system to uid or the uid of the current user, respectively.



setgid[=gid]	Same as above, but for gid.

setgid[=gid]

		Same as above, but for gid.



mode=mode	Sets the mode flags to the given (octal) value, regardless

mode=mode

		Sets the mode flags to the given (octal) value, regardless

		of the original permissions. Directories will get an x

		permission if the corresponding r bit is set.

		This is useful since most of the plain AmigaOS files
@@ -53,33 +62,41 @@ nofilenametruncate 
		The file system will return an error when filename exceeds

		standard maximum filename length (30 characters).



reserved=num	Sets the number of reserved blocks at the start of the

reserved=num

		Sets the number of reserved blocks at the start of the

		partition to num. You should never need this option.

		Default is 2.



root=block	Sets the block number of the root block. This should never

root=block

		Sets the block number of the root block. This should never

		be necessary.



bs=blksize	Sets the blocksize to blksize. Valid block sizes are 512,

bs=blksize

		Sets the blocksize to blksize. Valid block sizes are 512,

		1024, 2048 and 4096. Like the root option, this should

		never be necessary, as the affs can figure it out itself.



quiet		The file system will not return an error for disallowed

quiet

		The file system will not return an error for disallowed

		mode changes.



verbose		The volume name, file system type and block size will

verbose

		The volume name, file system type and block size will

		be written to the syslog when the filesystem is mounted.



mufs		The filesystem is really a muFS, also it doesn't

mufs

		The filesystem is really a muFS, also it doesn't

		identify itself as one. This option is necessary if

		the filesystem wasn't formatted as muFS, but is used

		as one.



prefix=path	Path will be prefixed to every absolute path name of

prefix=path

		Path will be prefixed to every absolute path name of

		symbolic links on an AFFS partition. Default = "/".

		(See below.)



volume=name	When symbolic links with an absolute path are created

volume=name

		When symbolic links with an absolute path are created

		on an AFFS partition, name will be prepended as the

		volume name. Default = "" (empty string).

		(See below.)
@@ -148,11 +165,13 @@ might be "User", "WB" and "Graphics", the mount points /amiga/User, 
Examples

========



Command line:

Command line::



    mount  Archive/Amiga/Workbench3.1.adf /mnt -t affs -o loop,verbose

    mount  /dev/sda3 /Amiga -t affs



/etc/fstab entry:

/etc/fstab entry::



    /dev/sdb5	/amiga/Workbench    affs    noauto,user,exec,verbose 0 0



IMPORTANT NOTE
@@ -170,7 +189,8 @@ before booting Windows! 


If the damage is already done, the following should fix the RDB

(where <disk> is the device name).

DO AT YOUR OWN RISK:



DO AT YOUR OWN RISK::



  dd if=/dev/<disk> of=rdb.tmp count=1

  cp rdb.tmp rdb.fixed
@@ -189,10 +209,14 @@ By default, filenames are truncated to 30 characters without warning. 
'nofilenametruncate' mount option can change that behavior.



Case is ignored by the affs in filename matching, but Linux shells

do care about the case. Example (with /wb being an affs mounted fs):

do care about the case. Example (with /wb being an affs mounted fs)::



    rm /wb/WRONGCASE

will remove /mnt/wrongcase, but



will remove /mnt/wrongcase, but::



    rm /wb/WR*



will not since the names are matched by the shell.



The block allocation is designed for hard disk partitions. If more
@@ -219,4 +243,4 @@ due to an incompatibility with the Amiga floppy controller. 


If you are interested in an Amiga Emulator for Linux, look at



http://web.archive.org/web/*/http://www.freiburg.linux.de/~uae/
 
http://web.archive.org/web/%2E/http://www.freiburg.linux.de/~uae/

Documentation/filesystems/afs.txt→Documentation/filesystems/afs.rst

+33 −40
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0



====================

kAFS: AFS FILESYSTEM

====================



Contents:

.. Contents:



 - Overview.

 - Usage.
@@ -14,8 +16,7 @@ Contents: 
 - The @sys substitution.





========

OVERVIEW

Overview

========



This filesystem provides a fairly simple secure AFS filesystem driver. It is
@@ -35,35 +36,33 @@ It does not yet support the following AFS features: 
 (*) pioctl() system call.





===========

COMPILATION

Compilation

===========



The filesystem should be enabled by turning on the kernel configuration

options:

options::



	CONFIG_AF_RXRPC		- The RxRPC protocol transport

	CONFIG_RXKAD		- The RxRPC Kerberos security handler

	CONFIG_AFS		- The AFS filesystem



Additionally, the following can be turned on to aid debugging:

Additionally, the following can be turned on to aid debugging::



	CONFIG_AF_RXRPC_DEBUG	- Permit AF_RXRPC debugging to be enabled

	CONFIG_AFS_DEBUG	- Permit AFS debugging to be enabled



They permit the debugging messages to be turned on dynamically by manipulating

the masks in the following files:

the masks in the following files::



	/sys/module/af_rxrpc/parameters/debug

	/sys/module/kafs/parameters/debug





=====

USAGE

Usage

=====



When inserting the driver modules the root cell must be specified along with a

list of volume location server IP addresses:

list of volume location server IP addresses::



	modprobe rxrpc

	modprobe kafs rootcell=cambridge.redhat.com:172.16.18.73:172.16.18.91
@@ -77,14 +76,14 @@ The second module is the kerberos RxRPC security driver, and the third module 
is the actual filesystem driver for the AFS filesystem.



Once the module has been loaded, more modules can be added by the following

procedure:

procedure::



	echo add grand.central.org 18.9.48.14:128.2.203.61:130.237.48.87 >/proc/fs/afs/cells



Where the parameters to the "add" command are the name of a cell and a list of

volume location servers within that cell, with the latter separated by colons.



Filesystems can be mounted anywhere by commands similar to the following:

Filesystems can be mounted anywhere by commands similar to the following::



	mount -t afs "%cambridge.redhat.com:root.afs." /afs

	mount -t afs "#cambridge.redhat.com:root.cell." /afs/cambridge
@@ -104,8 +103,7 @@ named volume will be looked up in the cell specified during modprobe. 
Additional cells can be added through /proc (see later section).





===========

MOUNTPOINTS

Mountpoints

===========



AFS has a concept of mountpoints. In AFS terms, these are specially formatted
@@ -123,42 +121,40 @@ culled first. If all are culled, then the requested volume will also be 
unmounted, otherwise error EBUSY will be returned.



This can be used by the administrator to attempt to unmount the whole AFS tree

mounted on /afs in one go by doing:

mounted on /afs in one go by doing::



	umount /afs





============

DYNAMIC ROOT

Dynamic Root

============



A mount option is available to create a serverless mount that is only usable

for dynamic lookup.  Creating such a mount can be done by, for example:

for dynamic lookup.  Creating such a mount can be done by, for example::



	mount -t afs none /afs -o dyn



This creates a mount that just has an empty directory at the root.  Attempting

to look up a name in this directory will cause a mountpoint to be created that

looks up a cell of the same name, for example:

looks up a cell of the same name, for example::



	ls /afs/grand.central.org/





===============

PROC FILESYSTEM

Proc Filesystem

===============



The AFS modules creates a "/proc/fs/afs/" directory and populates it:



  (*) A "cells" file that lists cells currently known to the afs module and

      their usage counts:

      their usage counts::



	[root@andromeda ~]# cat /proc/fs/afs/cells

	USE NAME

	  3 cambridge.redhat.com



  (*) A directory per cell that contains files that list volume location

      servers, volumes, and active servers known within that cell.

      servers, volumes, and active servers known within that cell::



	[root@andromeda ~]# cat /proc/fs/afs/cambridge.redhat.com/servers

	USE ADDR            STATE
@@ -171,8 +167,7 @@ The AFS modules creates a "/proc/fs/afs/" directory and populates it: 
	  1 Val 20000000 20000001 20000002 root.afs





=================

THE CELL DATABASE

The Cell Database

=================



The filesystem maintains an internal database of all the cells it knows and the
@@ -181,7 +176,7 @@ the system belongs is added to the database when modprobe is performed by the 
"rootcell=" argument or, if compiled in, using a "kafs.rootcell=" argument on

the kernel command line.



Further cells can be added by commands similar to the following:

Further cells can be added by commands similar to the following::



	echo add CELLNAME VLADDR[:VLADDR][:VLADDR]... >/proc/fs/afs/cells

	echo add grand.central.org 18.9.48.14:128.2.203.61:130.237.48.87 >/proc/fs/afs/cells
@@ -189,8 +184,7 @@ Further cells can be added by commands similar to the following: 
No other cell database operations are available at this time.





========

SECURITY

Security

========



Secure operations are initiated by acquiring a key using the klog program.  A
@@ -198,17 +192,17 @@ very primitive klog program is available at: 


	http://people.redhat.com/~dhowells/rxrpc/klog.c



This should be compiled by:

This should be compiled by::



	make klog LDLIBS="-lcrypto -lcrypt -lkrb4 -lkeyutils"



And then run as:

And then run as::



	./klog



Assuming it's successful, this adds a key of type RxRPC, named for the service

and cell, eg: "afs@<cellname>".  This can be viewed with the keyctl program or

by cat'ing /proc/keys:

by cat'ing /proc/keys::



	[root@andromeda ~]# keyctl show

	Session Keyring
@@ -232,20 +226,19 @@ socket), then the operations on the file will be made with key that was used to 
open the file.





=====================

THE @SYS SUBSTITUTION

The @sys Substitution

=====================



The list of up to 16 @sys substitutions for the current network namespace can

be configured by writing a list to /proc/fs/afs/sysname:

be configured by writing a list to /proc/fs/afs/sysname::



	[root@andromeda ~]# echo foo amd64_linux_26 >/proc/fs/afs/sysname



or cleared entirely by writing an empty list:

or cleared entirely by writing an empty list::



	[root@andromeda ~]# echo >/proc/fs/afs/sysname



The current list for current network namespace can be retrieved by:

The current list for current network namespace can be retrieved by::



	[root@andromeda ~]# cat /proc/fs/afs/sysname

	foo

Documentation/filesystems/autofs-mount-control.txt→Documentation/filesystems/autofs-mount-control.rst

+55 −53
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0



====================================================================

Miscellaneous Device control operations for the autofs kernel module

====================================================================
@@ -36,12 +38,12 @@ For example, there are two types of automount maps, direct (in the kernel 
module source you will see a third type called an offset, which is just

a direct mount in disguise) and indirect.



Here is a master map with direct and indirect map entries:

Here is a master map with direct and indirect map entries::



    /-      /etc/auto.direct

    /test   /etc/auto.indirect



and the corresponding map files:

and the corresponding map files::



    /etc/auto.direct:
@@ -49,7 +51,7 @@ and the corresponding map files: 
    /automount/dparse/g1  shark:/autofs/export1

    and so on.



/etc/auto.indirect:

/etc/auto.indirect::



    g1    shark:/autofs/export1

    g6    budgie:/autofs/export1
@@ -69,7 +71,7 @@ use the follow_link inode operation to trigger the mount. 
But, each entry in direct and indirect maps can have offsets (making

them multi-mount map entries).



For example, an indirect mount map entry could also be:

For example, an indirect mount map entry could also be::



    g1  \

    /        shark:/autofs/export5/testing/test \
@@ -78,7 +80,7 @@ g1 \ 
    /s1/ss1  shark:/autofs/export1 \

    /s2/ss2  shark:/autofs/export2



and a similarly a direct mount map entry could also be:

and a similarly a direct mount map entry could also be::



    /automount/dparse/g1 \

	/       shark:/autofs/export5/testing/test \
@@ -170,7 +172,7 @@ autofs Miscellaneous Device mount control interface 
The control interface is opening a device node, typically /dev/autofs.



All the ioctls use a common structure to pass the needed parameter

information and return operation results:

information and return operation results::



    struct autofs_dev_ioctl {

	    __u32 ver_major;
@@ -212,7 +214,7 @@ is used account for the increased structure length when translating the 
structure sent from user space.



This structure can be initialized before setting specific fields by using

the void function call init_autofs_dev_ioctl(struct autofs_dev_ioctl *).

the void function call init_autofs_dev_ioctl(``struct autofs_dev_ioctl *``).



All of the ioctls perform a copy of this structure from user space to

kernel space and return -EINVAL if the size parameter is smaller than

CRA Git | Maintained and supported by SUSTech CRA and CCSE