.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.20)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "FS_MKMOUNT 1"
.TH FS_MKMOUNT 1 "2021-12-09" "OpenAFS" "AFS Command Reference"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
fs_mkmount \- Creates a mount point for a volume
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBfs mkmount\fR \fB\-dir\fR\ <\fIdirectory\fR> \fB\-vol\fR\ <\fIvolume\ name\fR>
    [\fB\-cell\fR\ <\fIcell\ name\fR>] [\fB\-rw\fR] [\fB\-fast\fR] [\fB\-help\fR]
.PP
\&\fBfs mk\fR \fB\-d\fR\ <\fIdirectory\fR> \fB\-v\fR\ <\fIvolume\ name\fR>
    [\fB\-c\fR\ <\fIcell\ name\fR>] [\fB\-r\fR] [\fB\-f\fR] [\fB\-h\fR]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \fBfs mkmount\fR command creates a mount point for the volume named by
the \fB\-vol\fR argument at the location in the \s-1AFS\s0 file space specified by
the \fB\-dir\fR argument. The mount point looks like a standard directory
element, and serves as the volume's root directory, but is actually a
special file system object that refers to an \s-1AFS\s0 volume. When the Cache
Manager first encounters a given mount point during pathname traversal, it
contacts the \s-1VL\s0 Server to learn which file server machines house the
indicated volume, then fetches a copy of the volume's root directory from
the appropriate file server machine.
.PP
It is possible, although not recommended, to create more than one mount
point to a volume. The Cache Manager can become confused if a volume is
mounted in two places along the same path through the filespace.
.PP
The Cache Manager observes three basic rules as it traverses the \s-1AFS\s0
filespace and encounters mount points:
.IP "Rule 1: Access Backup and Read-only Volumes When Specified" 4
.IX Item "Rule 1: Access Backup and Read-only Volumes When Specified"
When the Cache Manager encounters a mount point that specifies a volume
with either a \f(CW\*(C`.readonly\*(C'\fR or a \f(CW\*(C`.backup\*(C'\fR extension, it accesses that
type of volume only. If a mount point does not have either a \f(CW\*(C`.backup\*(C'\fR or
\&\f(CW\*(C`.readonly\*(C'\fR extension, the Cache Manager uses Rules 2 and 3.
.Sp
For example, the Cache Manager never accesses the read/write version of a
volume if the mount point names the backup version. If the specified
version is inaccessible, the Cache Manager reports an error.
.IP "Rule 2: Follow the Read-only Path When Possible" 4
.IX Item "Rule 2: Follow the Read-only Path When Possible"
If a mount point resides in a read-only volume and the volume that it
references is replicated, the Cache Manager attempts to access a read-only
copy of the volume; if the referenced volume is not replicated, the Cache
Manager accesses the read/write copy. The Cache Manager is thus said to
prefer a \fIread-only path\fR through the filespace, accessing read-only
volumes when they are available.
.Sp
The Cache Manager starts on the read-only path in the first place because
it always accesses a read-only copy of the \fBroot.afs\fR volume if it
exists; the volume is mounted at the root of a cell's \s-1AFS\s0 filespace (named
\&\fI/afs\fR by convention). That is, if the \f(CW\*(C`root.afs\*(C'\fR volume is replicated,
the Cache Manager attempts to access a read-only copy of it rather than
the read/write copy. This rule then keeps the Cache Manager on a read-only
path as long as each successive volume is replicated. The implication is
that both the \f(CW\*(C`root.afs\*(C'\fR and \f(CW\*(C`root.cell\*(C'\fR volumes must be replicated for
the Cache Manager to access replicated volumes mounted below them in the
\&\s-1AFS\s0 filespace. The volumes are conventionally mounted at the \fI/afs\fR and
\&\fI/afs/\fIcellname\fI\fR directories, respectively.
.IP "Rule 3: Once on a Read/write Path, Stay There" 4
.IX Item "Rule 3: Once on a Read/write Path, Stay There"
If a mount point resides in a read/write volume and the volume name does
not have a \f(CW\*(C`.readonly\*(C'\fR or a \f(CW\*(C`.backup\*(C'\fR extension, the Cache Manager
attempts to access only the read/write version of the volume. The access
attempt fails with an error if the read/write version is inaccessible,
even if a read-only version is accessible. In this situation the Cache
Manager is said to be on a \fIread/write path\fR and cannot switch back to
the read-only path unless mount point explicitly names a volume with a
\&\f(CW\*(C`.readonly\*(C'\fR extension. (Cellular mount points are an important exception
to this rule, as explained in the following discussion.
.PP
There are three types of mount points, each appropriate for a different
purpose because of the manner in which the Cache Manager interprets them.
.IP "\(bu" 4
When the Cache Manager crosses a \fIregular\fR mount point, it obeys all
three of the mount point traversal rules previously described. To create a
regular mount point, include only the required \fB\-dir\fR and \fB\-vol\fR
arguments to the \fBfs mkmount\fR command.
.IP "\(bu" 4
When the Cache Manager crosses a \fIread/write\fR mount point, it attempts to
access only the volume version named in the mount point. If the volume
name is the base (read/write) form, without a \f(CW\*(C`.readonly\*(C'\fR or \f(CW\*(C`.backup\*(C'\fR
extension, the Cache Manager accesses the read/write version of the
volume, even if it is replicated. In other words, the Cache Manager
disregards the second mount point traversal rule when crossing a
read/write mount point: it switches to the read/write path through the
filespace.
.Sp
To create a read/write mount point, include the \fB\-rw\fR flag on the \fBfs
mkmount\fR command. It is conventional to create only one read/write mount
point in a cell's filespace, using it to mount the cell's \f(CW\*(C`root.cell\*(C'\fR
volume just below the \s-1AFS\s0 filespace root (by convention,
\&\fI/afs/.\fIcellname\fI\fR). See the \fIOpenAFS Quick Start Guide\fR for
instructions and the chapter about volume management in the \fIOpenAFS
Administration Guide\fR for further discussion.
.Sp
Creating a read/write mount point for a read-only or backup volume is
acceptable, but unnecessary. The first rule of mount point traversal
already specifies that the Cache Manager accesses them if the volume name
in a regular mount point has a \f(CW\*(C`.readonly\*(C'\fR or \f(CW\*(C`.backup\*(C'\fR extension.
.IP "\(bu" 4
When the Cache Manager crosses a \fIcellular\fR mount point, it accesses the
indicated volume in the specified cell, which is normally a foreign
cell. (If the mount point does not name a cell along with the volume, the
Cache Manager accesses the volume in the cell where the mount point
resides.) The Cache Manager disregards the third mount point traversal
rule when crossing a regular cellular mount point: it accesses a read-only
version of the volume if it is replicated, even if the volume that houses
the mount point is read/write. Switching to the read-only path in this way
is designed to avoid imposing undue load on the file server machines in
foreign cells.
.Sp
To create a regular cellular mount point, include the \fB\-cell\fR argument on
the \fBfs mkmount\fR command. It is conventional to create cellular mount
points only at the second level in a cell's filespace, using them to mount
foreign cells' \fBroot.cell\fR volumes just below the \s-1AFS\s0 filespace root (by
convention, at \fI/afs/\fIforeign_cellname\fI\fR). The mount point enables local
users to access the foreign cell's filespace, assuming they have the
necessary permissions on the \s-1ACL\s0 of the volume's root directory and that
there is an entry for the foreign cell in each local client machine's
\&\fI/usr/vice/etc/CellServDB\fR file. In the output of the \fBfs lsmount\fR
command, the cell name and a colon (\f(CW\*(C`:\*(C'\fR) appear between the initial
number sign and the volume name in a regular cellular mount point name.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-dir\fR <\fIdirectory\fR>+" 4
.IX Item "-dir <directory>+"
Names the directory to create as a mount point. The directory must not
already exist. Relative pathnames are interpreted with respect to the
current working directory.
.Sp
Specify the read/write path to the directory, to avoid the failure that
results from attempting to create a new mount point in a read-only
volume. By convention, the read/write path is indicated by placing a
period before the cell name at the pathname's second level (for example,
\&\fI/afs/.example.com\fR). For further discussion of the concept of read/write and
read-only paths through the filespace, see \*(L"\s-1DESCRIPTION\s0\*(R".
.IP "\fB\-vol\fR <\fIvolume name\fR>" 4
.IX Item "-vol <volume name>"
Specifies the name or volume \s-1ID\s0 number of the volume to mount. If
appropriate, add the \f(CW\*(C`.readonly\*(C'\fR or \f(CW\*(C`.backup\*(C'\fR extension to the name, or
specify the appropriate volume \s-1ID\s0 number.
.IP "\fB\-cell\fR <\fIcell name\fR>" 4
.IX Item "-cell <cell name>"
Names the cell in which the volume resides (creates a cellular mount
point). Provide the fully qualified domain name, or a shortened form that
disambiguates it from the other cells listed in the local
\&\fI/usr/vice/etc/CellServDB\fR file.
.Sp
If this argument is omitted, no cell indicator appears in the mount
point. When the Cache Manager interprets it, it assumes that the volume
named in the mount point resides in the same cell as the volume that
houses the mount point.
.IP "\fB\-rw\fR" 4
.IX Item "-rw"
Creates a read/write mount point. Omit this flag to create a regular mount
point.
.IP "\fB\-fast\fR" 4
.IX Item "-fast"
Prevents the Volume Location (\s-1VL\s0) Server from checking that the volume has
a \s-1VLDB\s0 entry and printing a warning message if it does not. Whether or not
this flag is included, the File Server creates the mount point even when
the volume has no \s-1VLDB\s0 entry.
.IP "\fB\-help\fR" 4
.IX Item "-help"
Prints the online help for this command. All other valid options are
ignored.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
The following command creates a regular mount point, mounting the volume
\&\f(CW\*(C`user.smith\*(C'\fR at \fI/afs/example.com/usr/smith\fR:
.PP
.Vb 2
\&   % cd /afs/example.com/usr
\&   % fs mkmount \-dir smith \-vol user.smith
.Ve
.PP
The following commands create a read/write mount point and a regular mount
point for the Example Corporation cell's \f(CW\*(C`root.cell\*(C'\fR volume in that cell's
file tree. The second command follows the convention of putting a period
at the beginning of the read/write mount point's name.
.PP
.Vb 2
\&   % fs mkmount \-dir /afs/example.com \-vol root.cell
\&   % fs mkmount \-dir /afs/.example.com \-vol root.cell \-rw
.Ve
.PP
The following command mounts the Example Organization cell's \f(CW\*(C`root.cell\*(C'\fR
volume in the Example Corporation cell's file tree, creating a regular
cellular mount point called \fI/afs/example.org\fR. When a Example Corporation
Cache Manager encounters this mount point, it crosses into the Example
Organization cell on a read-only path.
.PP
.Vb 1
\&   % fs mkmount \-dir /afs/example.org \-vol root.cell \-c example.org
.Ve
.SH "PRIVILEGE REQUIRED"
.IX Header "PRIVILEGE REQUIRED"
The issuer must have the \f(CW\*(C`i\*(C'\fR (insert) and \f(CW\*(C`a\*(C'\fR (administer) permissions
on the \s-1ACL\s0 of the directory that is to house the mount point.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fICellServDB\fR\|(5),
\&\fIfs_lsmount\fR\|(1),
\&\fIfs_rmmount\fR\|(1)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
\&\s-1IBM\s0 Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
.PP
This documentation is covered by the \s-1IBM\s0 Public License Version 1.0.  It was
converted from \s-1HTML\s0 to \s-1POD\s0 by software written by Chas Williams and Russ
Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.