'\" t
.TH "SYSTEMD\-MSTACK" "1" "" "systemd 260.1" "systemd-mstack"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
systemd-mstack, mount.mstack \- Mstack Discoverable Disk Images (DDIs)
.SH "SYNOPSIS"
.HP \w'\fBsystemd\-mstack\fR\ 'u
\fBsystemd\-mstack\fR [OPTIONS...] \fIIMAGE\fR
.HP \w'\fBsystemd\-mstack\fR\ 'u
\fBsystemd\-mstack\fR [OPTIONS...] [\-\-mount] \fIIMAGE\fR \fIPATH\fR
.HP \w'\fBsystemd\-mstack\fR\ 'u
\fBsystemd\-mstack\fR [OPTIONS...] [\-\-umount] \fIPATH\fR
.SH "DESCRIPTION"
.PP
\fBsystemd\-mstack\fR
is a tool for introspecting and interacting with
\&.mstack/
mount stack directories, as described in
\fBsystemd.mstack\fR(7)\&. It supports three different operations:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  1." 4.2
.\}
Show general mount stack information, including all described
"overlayfs"
layers and bind mounts\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  2." 4.2
.\}
Mount a mount stack to a local directory\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  3." 4.2
.\}
Unmount a mount stack from a local directory\&.
.RE
.PP
The
\fBsystemd\-mstack\fR
command may be invoked as
\fBmount\&.mstack\fR
in which case it implements the
\fBmount\fR(8)
"external helper" interface\&. This ensures mount stack directories compatible with
\fBsystemd\-mstack\fR
can be mounted directly by
\fBmount\fR
and
\fBfstab\fR(5)\&. For details see below\&.
.PP
In place of the image path a
"\&.v/"
versioned directory may be specified, see
\fBsystemd.v\fR(7)
for details\&.
.SH "COMMANDS"
.PP
If neither of the command switches listed below are passed the specified mount stack is opened and general information about it is shown, including a list of all defined layers\&.
.PP
\fB\-\-mount\fR, \fB\-m\fR
.RS 4
Mount the specified mount stack to the specified directory\&.
.sp
To unmount a mount stack directory mounted like this use the
\fB\-\-umount\fR
operation\&.
.sp
Note that this functionality is also available in
\fBmount\fR(8)
via a command such as
\fBmount \-t mstack mystack\&.mstack targetdir/\fR, as well as in
\fBfstab\fR(5)\&. For details, see below\&.
.sp
Added in version 260\&.
.RE
.PP
\fB\-M\fR
.RS 4
This is a shortcut for
\fB\-\-mount \-\-mkdir\fR\&.
.sp
Added in version 260\&.
.RE
.PP
\fB\-\-umount\fR, \fB\-u\fR
.RS 4
Unmount a mount stack from the specified directory\&. This command expects one argument: a directory where mount stack was mounted\&.
.sp
All mounted mounts will be recursively unmounted
.sp
Added in version 260\&.
.RE
.PP
\fB\-U\fR
.RS 4
This is a shortcut for
\fB\-\-umount \-\-rmdir\fR\&.
.sp
Added in version 260\&.
.RE
.PP
\fB\-h\fR, \fB\-\-help\fR
.RS 4
Print a short help text and exit\&.
.RE
.PP
\fB\-\-version\fR
.RS 4
Print a short version string and exit\&.
.RE
.SH "OPTIONS"
.PP
The following options are understood:
.PP
\fB\-\-read\-only\fR, \fB\-r\fR
.RS 4
Operate in read\-only mode\&. By default,
\fB\-\-mount\fR
will establish writable mount points\&. If this option is specified they are established in read\-only mode instead\&.
.sp
Added in version 260\&.
.RE
.PP
\fB\-\-mkdir\fR
.RS 4
If combined with
\fB\-\-mount\fR
the directory to mount the mount stack to is created if it is missing\&. Note that the directory is not automatically removed when the mount stack is unmounted again\&.
.sp
Added in version 260\&.
.RE
.PP
\fB\-\-rmdir\fR
.RS 4
If combined with
\fB\-\-umount\fR
the specified directory where the mount stack is mounted is removed after unmounting it\&.
.sp
Added in version 260\&.
.RE
.PP
\fB\-\-image\-policy=\fR\fB\fIpolicy\fR\fR
.RS 4
Takes an image policy string as argument, as per
\fBsystemd.image-policy\fR(7)\&. The policy is enforced when operating on the disk image specified via
\fB\-\-image=\fR, see above\&. If not specified, defaults to the
"*"
policy, i\&.e\&. all recognized file systems in the image are used\&.
.RE
.PP
\fB\-\-image\-filter=\fR\fB\fIfilter\fR\fR
.RS 4
Takes an image filter string as argument, as per
\fBsystemd.image-filter\fR(7)\&. The filter is taken into consideration when operating on the disk image specified via
\fB\-\-image=\fR, see above\&. If not specified no filtering is applied\&.
.RE
.PP
\fB\-\-no\-pager\fR
.RS 4
Do not pipe output into a pager\&.
.RE
.PP
\fB\-\-no\-legend\fR
.RS 4
Do not print the legend, i\&.e\&. column headers and the footer with hints\&.
.RE
.PP
\fB\-\-json=\fR\fB\fIMODE\fR\fR
.RS 4
Shows output formatted as JSON\&. Expects one of
"short"
(for the shortest possible output without any redundant whitespace or line breaks),
"pretty"
(for a pretty version of the same, with indentation and line breaks) or
"off"
(to turn off JSON output, the default)\&.
.RE
.SH "EXIT STATUS"
.PP
On success, 0 is returned, a non\-zero failure code otherwise\&.
.SH "INVOCATION AS /SBIN/MOUNT\&.MSTACK"
.PP
The
\fBsystemd\-mstack\fR
executable may be symlinked to
/sbin/mount\&.mstack\&. If invoked through that it implements
\fBmount\fR(8)\*(Aqs "external helper" interface for the (pseudo) file system type
"mstack"\&. This means conformant mount stack directories may be mounted directly via
.sp
.if n \{\
.RS 4
.\}
.nf
# mount \-t mstack mystack\&.mstack targetdir/
.fi
.if n \{\
.RE
.\}
.PP
in a fashion mostly equivalent to:
.sp
.if n \{\
.RS 4
.\}
.nf
# systemd\-mstack \-\-mount mystack\&.mstack targetdir/
.fi
.if n \{\
.RE
.\}
.PP
Note that since a single mount stack may contain multiple mount points it should later be unmounted with
\fBumount \-R targetdir/\fR, for recursive operation\&.
.PP
This functionality is particularly useful to mount mount stacks automatically at boot via simple
/etc/fstab
entries\&. For example:
.sp
.if n \{\
.RS 4
.\}
.nf
/path/to/mystack\&.nspawn /images/mystack/ mstack defaults 0 0
.fi
.if n \{\
.RE
.\}
.PP
When invoked this way the mount options
"ro",
"rw"
map to the corresponding options listed above (i\&.e\&.
\fB\-\-read\-only\fR)\&.
.SH "SEE ALSO"
.PP
\fBsystemd\fR(1), \fBsystemd.mstack\fR(7), \fBsystemd-nspawn\fR(1), \fBsystemd.exec\fR(5), \fBmount\fR(8), \fBumount\fR(8)