1.\" 2.\" Copyright 2014 Nexenta Systems, Inc. All Rights Reserved. 3.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved 4.\" Copyright 2021 Oxide Computer Company 5.\" 6.\" The contents of this file are subject to the terms of the 7.\" Common Development and Distribution License (the "License"). 8.\" You may not use this file except in compliance with the License. 9.\" 10.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 11.\" or http://www.opensolaris.org/os/licensing. 12.\" See the License for the specific language governing permissions 13.\" and limitations under the License. 14.\" 15.\" When distributing Covered Code, include this CDDL HEADER in each 16.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. 17.\" If applicable, add the following below this CDDL HEADER, with the 18.\" fields enclosed by brackets "[]" replaced with your own identifying 19.\" information: Portions Copyright [yyyy] [name of copyright owner] 20.\" 21.Dd November 24, 2014 22.Dt LOFS 4FS 23.Os 24.Sh NAME 25.Nm lofs 26.Nd loopback virtual file system 27.Sh SYNOPSIS 28.In sys/param.h 29.In sys/mount.h 30.Ft int 31.Fo mount 32.Fa "const char *dir" 33.Fa "const char *virtual" 34.Fa "int mflag" 35.Fa \(dqlofs\(dq , 36.Fa NULL , 37.Fa 0 38.Fc 39.Sh DESCRIPTION 40The loopback file system device allows new, virtual file systems to be created, 41which provide access to existing files using alternate pathnames. 42Once the virtual file system is created, other file systems can be mounted 43within it, without affecting the original file system. 44However, file systems which are subsequently mounted onto the original file 45system 46.Em are 47visible to the virtual file system, unless or until the corresponding mount 48point in the virtual file system is covered by a file system mounted there. 49.Pp 50.Fa virtual 51is the mount point for the virtual file system. 52.Fa dir 53is the pathname of the existing file system. 54.Fa mflag 55specifies the mount options; the 56.Dv MS_DATA 57bit in 58.Fa mflag 59must be set. 60If the 61.Dv MS_RDONLY 62bit in 63.Fa mflag 64is not set, accesses to the loop back file system are the same as for the 65underlying file system. 66Otherwise, all accesses in the loopback file system will be read-only. 67All other 68.Xr mount 2 69options are inherited from the underlying file systems. 70.Pp 71A loopback mount of 72.Pa / 73onto 74.Pa /tmp/newroot 75allows the entire file system hierarchy to appear as if it were duplicated under 76.Pa /tmp/newroot , 77including any file systems mounted from remote NFS servers. 78All files would then be accessible either from a pathname relative to 79.Pa / 80or from a pathname relative to 81.Pa /tmp/newroot 82until such time as a file system is mounted in 83.Pa /tmp/newroot 84or any of its subdirectories. 85.Pp 86Loopback mounts of 87.Pa / 88can be performed in conjunction with the 89.Xr chroot 2 90system call, to provide a complete virtual file system to a process or family of 91processes. 92.Pp 93Recursive traversal of loopback mount points is not allowed. 94After the loopback mount of 95.Pa /tmp/newroot , 96the file 97.Pa /tmp/newroot/tmp/newroot 98does not contain yet another file system hierarchy; rather, it appears just as 99.Pa /tmp/newroot 100did before the loopback mount was performed 101.Pq for example, as an empty directory . 102.Sh EXAMPLES 103.Nm 104file systems are mounted using: 105.Bd -literal -offset indent 106mount -F lofs /tmp /mnt 107.Ed 108.Sh SEE ALSO 109.Xr chroot 2 , 110.Xr mount 2 , 111.Xr sysfs 2 , 112.Xr lofi 4D , 113.Xr vfstab 5 , 114.Xr lofiadm 8 , 115.Xr mount 8 116.Sh NOTES 117All access to entries in 118.Nm 119mounted file systems map to their underlying file system. 120If a mount point is made available in multiple locations via 121.Nm 122and is busy in any of those locations, an attempt to mount a file system at that 123mount point fails unless the overlay flag is specified. 124See 125.Xr mount 8 . 126Examples of a mount point being busy within a 127.Nm 128mount include having a file system mounted on it or it being a processes' 129current working directory. 130.Sh WARNINGS 131Because of the potential for confusing users and applications, you should use 132loopback mounts with care. 133A loopback mount entry in 134.Pa /etc/vfstab 135must be placed after the mount points of both directories it depends on. 136This is most easily accomplished by making the loopback mount entry the last in 137.Pa /etc/vfstab . 138