.\"
.\" Copyright 2014 Nexenta Systems, Inc.  All Rights Reserved.
.\"  Copyright (c) 2009, Sun Microsystems, Inc.  All Rights Reserved
.\" Copyright 2021 Oxide Computer Company
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.Dd November 24, 2014
.Dt LOFS 4FS
.Os
.Sh NAME
.Nm lofs
.Nd loopback virtual file system
.Sh SYNOPSIS
.In sys/param.h
.In sys/mount.h
.Ft int
.Fo mount
.Fa "const char *dir"
.Fa "const char *virtual"
.Fa "int mflag"
.Fa \(dqlofs\(dq ,
.Fa NULL ,
.Fa 0
.Fc
.Sh DESCRIPTION
The loopback file system device allows new, virtual file systems to be created,
which provide access to existing files using alternate pathnames.
Once the virtual file system is created, other file systems can be mounted
within it, without affecting the original file system.
However, file systems which are subsequently mounted onto the original file
system
.Em are
visible to the virtual file system, unless or until the corresponding mount
point in the virtual file system is covered by a file system mounted there.
.Pp
.Fa virtual
is the mount point for the virtual file system.
.Fa dir
is the pathname of the existing file system.
.Fa mflag
specifies the mount options; the
.Dv MS_DATA
bit in
.Fa mflag
must be set.
If the
.Dv MS_RDONLY
bit in
.Fa mflag
is not set, accesses to the loop back file system are the same as for the
underlying file system.
Otherwise, all accesses in the loopback file system will be read-only.
All other
.Xr mount 2
options are inherited from the underlying file systems.
.Pp
A loopback mount of
.Pa /
onto
.Pa /tmp/newroot
allows the entire file system hierarchy to appear as if it were duplicated under
.Pa /tmp/newroot ,
including any file systems mounted from remote NFS servers.
All files would then be accessible either from a pathname relative to
.Pa /
or from a pathname relative to
.Pa /tmp/newroot
until such time as a file system is mounted in
.Pa /tmp/newroot
or any of its subdirectories.
.Pp
Loopback mounts of
.Pa /
can be performed in conjunction with the
.Xr chroot 2
system call, to provide a complete virtual file system to a process or family of
processes.
.Pp
Recursive traversal of loopback mount points is not allowed.
After the loopback mount of
.Pa /tmp/newroot ,
the file
.Pa /tmp/newroot/tmp/newroot
does not contain yet another file system hierarchy; rather, it appears just as
.Pa /tmp/newroot
did before the loopback mount was performed
.Pq for example, as an empty directory .
.Sh EXAMPLES
.Nm
file systems are mounted using:
.Bd -literal -offset indent
mount -F lofs /tmp /mnt
.Ed
.Sh SEE ALSO
.Xr chroot 2 ,
.Xr mount 2 ,
.Xr sysfs 2 ,
.Xr lofi 4D ,
.Xr vfstab 5 ,
.Xr lofiadm 8 ,
.Xr mount 8
.Sh NOTES
All access to entries in
.Nm
mounted file systems map to their underlying file system.
If a mount point is made available in multiple locations via
.Nm
and is busy in any of those locations, an attempt to mount a file system at that
mount point fails unless the overlay flag is specified.
See
.Xr mount 8 .
Examples of a mount point being busy within a
.Nm
mount include having a file system mounted on it or it being a processes'
current working directory.
.Sh WARNINGS
Because of the potential for confusing users and applications, you should use
loopback mounts with care.
A loopback mount entry in
.Pa /etc/vfstab
must be placed after the mount points of both directories it depends on.
This is most easily accomplished by making the loopback mount entry the last in
.Pa /etc/vfstab .