shaba/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2024-12-23 21:35:11 +03:00
Code
d68c8888c2
systemd/man/systemd-fstab-generator.xml

334 lines
17 KiB
XML
Raw Normal View History

man: document fstab generator
2012-06-27 17:27:29 +04:00
<?xml version="1.0"?>
<!--*-nxml-*-->
man: use same header for all files The "include" files had type "book" for some raeason. I don't think this is meaningful. Let's just use the same everywhere. $ perl -i -0pe 's^..DOCTYPE (book|refentry) PUBLIC "-//OASIS//DTD DocBook XML V4.[25]//EN"\s+"http^<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"\n "http^gms' man/*.xml
2019-03-14 16:40:58 +03:00
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
man: use same version in public and system ident.
2023-12-25 17:48:33 +03:00
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
license: LGPL-2.1+ -> LGPL-2.1-or-later
2020-11-09 07:23:58 +03:00
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
man: Add xinclude namespace This will be used by the next commit to add version information to the nodes.
2023-08-22 19:52:02 +03:00
<refentry id="systemd-fstab-generator" xmlns:xi="http://www.w3.org/2001/XInclude">
man: document fstab generator
2012-06-27 17:27:29 +04:00
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
<refentryinfo>
<title>systemd-fstab-generator</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>systemd-fstab-generator</refentrytitle>
<manvolnum>8</manvolnum>
</refmeta>
<refnamediv>
<refname>systemd-fstab-generator</refname>
<refpurpose>Unit generator for /etc/fstab</refpurpose>
</refnamediv>
<refsynopsisdiv>
man: revert dynamic paths for split-usr setups This did not really work out as we had hoped. Trying to do this upstream introduced several problems that probably makes it better suited as a downstream patch after all. At any rate, it is not releaseable in the current state, so we at least need to revert this before the release. * by adjusting the path to binaries, but not do the same thing to the search path we end up with inconsistent man-pages. Adjusting the search path too would be quite messy, and it is not at all obvious that this is worth the effort, but at any rate it would have to be done before we could ship this. * this means that distributed man-pages does not make sense as they depend on config options, and for better or worse we are still distributing man pages, so that is something that definitely needs sorting out before we could ship with this patch. * we have long held that split-usr is only minimally supported in order to boot, and something we hope will eventually go away. So before we start adding even more magic/effort in order to make this work nicely, we should probably question if it makes sense at all.
2015-06-18 20:47:44 +03:00
<para><filename>/usr/lib/systemd/system-generators/systemd-fstab-generator</filename></para>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><filename>systemd-fstab-generator</filename> is a generator
that translates <filename>/etc/fstab</filename> (see
man: fix a bunch of links All hail linkchecker!
2015-03-14 05:22:39 +03:00
<citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
for details) into native systemd units early at boot and when
configuration of the system manager is reloaded. This will
instantiate mount and swap units as necessary.</para>
<para>The <varname>passno</varname> field is treated like a simple
boolean, and the ordering information is discarded. However, if
the root file system is checked, it is checked before all the
other file systems.</para>
<para>See
<citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>
and
<citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for more information about special <filename>/etc/fstab</filename>
mount options this generator understands.</para>
fstab-generator: allow overriding path to /sysroot/etc/fstab too This adds $SYSTEMD_SYSROOT_FSTAB analoguous to $SYSTEMD_FSTAB.
2022-07-14 14:29:06 +03:00
<para>One special topic is handling of symbolic links. Historical init
fstab-generator: Chase symlinks where possible (#6293) This has a long history; see see 5261ba901845c084de5a8fd06500ed09bfb0bd80 which originally introduced the behavior. Unfortunately that commit doesn't include any rationale, but IIRC the basic issue is that systemd wants to model the real mount state as units, and symlinks make canonicalization much more difficult. At the same time, on a RHEL6 system (upstart), one can make e.g. `/home` a symlink, and things work as well as they always did; but one doesn't have access to the sophistication of mount units (dependencies, introspection, etc.) Supporting symlinks here will hence make it easier for people to do upgrades to RHEL7 and beyond. The `/home` as symlink case also appears prominently for OSTree; see https://ostree.readthedocs.io/en/latest/manual/adapting-existing/ Further work has landed in the nspawn case for this; see e.g. d944dc9553009822deaddec76814f5642a6a8176 A basic limitation with doing this in the fstab generator (and that I hit while doing some testing) is that we obviously can't chase symlinks into mounts, since the generator runs early before mounts. Or at least - doing so would require multiple passes over the fstab data (as well as looking at existing mount units), and potentially doing multi-phase generation. I'm not sure it's worth doing that without a real world use case. For now, this will fix at least the OSTree + `/home` <https://bugzilla.redhat.com/show_bug.cgi?id=1382873> case mentioned above, and in general anyone who for whatever reason has symlinks in their `/etc/fstab`.
2017-07-11 19:48:57 +03:00
implementations supported symlinks in <filename>/etc/fstab</filename>.
Because mount units will refuse mounts where the target is a symbolic link,
this generator will resolve any symlinks as far as possible when processing
<filename>/etc/fstab</filename> in order to enhance backwards compatibility.
If a symlink target does not exist at the time that this generator runs, it
is assumed that the symlink target is the final target of the mount.</para>
man: replace obsolete wiki link with man page
2015-03-05 02:43:20 +03:00
<para><filename>systemd-fstab-generator</filename> implements
<citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
</refsect1>
<refsect1>
<title>Kernel Command Line</title>
<para><filename>systemd-fstab-generator</filename> understands the
following kernel command line parameters:</para>
<variablelist class='kernel-commandline-options'>
<varlistentry>
<term><varname>fstab=</varname></term>
<term><varname>rd.fstab=</varname></term>
man: "the initial RAM disk" → "the initrd" In many places we spelled out the phrase behind "initrd" in full, but this isn't terribly useful. In fact, no "RAM disk" is used, so emphasizing this is just confusing to the reader. Let's just say "initrd" everywhere, people understand what this refers to, and that it's in fact an initramfs image. Also, s/i.e./e.g./ where appropriate. Also, don't say "in RAM", when in fact it's virtual memory, whose pages may or may not be loaded in page frames in RAM, and we have no control over this. Also, add <filename></filename> and other minor cleanups.
2022-09-15 15:43:59 +03:00
<listitem><para>Takes a boolean argument. Defaults to <literal>yes</literal>. If
<literal>no</literal>, causes the generator to ignore any mounts or swap devices configured in
<filename>/etc/fstab</filename>. <varname>rd.fstab=</varname> is honored only in the initrd, while
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 19:52:36 +03:00
<varname>fstab=</varname> is honored by both the main system and the initrd.</para>
<xi:include href="version-info.xml" xpointer="v186"/></listitem>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
</varlistentry>
fstab-generator: add support for volatile boots This adds support for a new kernel command line option "systemd.volatile=" that provides the same functionality that systemd-nspawn's --volatile= switch provides, but for host systems (i.e. systems booting with a kernel). It takes the same parameter and has the same effect. In order to implement systemd.volatile=yes a new service systemd-volatile-root.service is introduced that only runs in the initrd and rearranges the root directory as needed to become a tmpfs instance. Note that systemd.volatile=state is implemented different: it simply generates a var.mount unit file that is part of the normal boot and has no effect on the initrd execution. The way this is implemented ensures that other explicit configuration for /var can always override the effect of these options. Specifically, the var.mount unit is generated in the "late" generator directory, so that it only is in effect if nothing else overrides it.
2016-12-13 14:45:19 +03:00
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
<varlistentry>
<term><varname>root=</varname></term>
fstab-generator: add new root=tmpfs option It's useful to be able to combine a regular /usr/ file system with a tmpfs as root, for an OS that boots up in volatile mode on every single boot. Let's add explicit support for this via root=tmpfs. Note the relationship to the existing systemd.volatile= option: 1. The kernel command line "root=/dev/… systemd.volatile=yes" will mount the specified root fs, and then hide everything at the top by overmounting it with a tmpfs, except for the /usr subtree. 2. The kernel command line "root=tmpfs mount.usr=/dev/…" otoh will mount a toot fs at the top (just like the case above), but will then mount the top-level dir of the fs specified in mount.usr= directly below it. Or to say this differently: in the first case /usr/ from the physical storage fs is going to become /usr/ of the hierarchy ultimately booted, while in the second case / from the physical storage fs is going to become /usr of the hierarchy booted. Philosophically I figure systemd.volatile= is more an option for "one-off" boots, while root=tmpfs is something to have as default mode of operation for suitable images. This is currently hard to test reasonably, since Dracut refuses to accept root=tmpfs. This needs to be addressed separately though.
2021-03-02 20:57:04 +03:00
<listitem><para>Configures the operating system's root filesystem to mount when running in the
initrd. This accepts a device node path (usually <filename>/dev/disk/by-uuid/…</filename> or
fstab-generator: use correct targets when /sysroot is specificied in fstab only
2023-01-26 03:05:08 +03:00
<filename>/dev/disk/by-label/…</filename> or similar), or the special values <literal>gpt-auto</literal>,
<literal>fstab</literal>, and <literal>tmpfs</literal>.</para>
fstab-generator: add new root=tmpfs option It's useful to be able to combine a regular /usr/ file system with a tmpfs as root, for an OS that boots up in volatile mode on every single boot. Let's add explicit support for this via root=tmpfs. Note the relationship to the existing systemd.volatile= option: 1. The kernel command line "root=/dev/… systemd.volatile=yes" will mount the specified root fs, and then hide everything at the top by overmounting it with a tmpfs, except for the /usr subtree. 2. The kernel command line "root=tmpfs mount.usr=/dev/…" otoh will mount a toot fs at the top (just like the case above), but will then mount the top-level dir of the fs specified in mount.usr= directly below it. Or to say this differently: in the first case /usr/ from the physical storage fs is going to become /usr/ of the hierarchy ultimately booted, while in the second case / from the physical storage fs is going to become /usr of the hierarchy booted. Philosophically I figure systemd.volatile= is more an option for "one-off" boots, while root=tmpfs is something to have as default mode of operation for suitable images. This is currently hard to test reasonably, since Dracut refuses to accept root=tmpfs. This needs to be addressed separately though.
2021-03-02 20:57:04 +03:00
<para>Use <literal>gpt-auto</literal> to explicitly request automatic root file system discovery via
<citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
fstab-generator: use correct targets when /sysroot is specificied in fstab only
2023-01-26 03:05:08 +03:00
<para>Use <literal>fstab</literal> to explicitly request automatic root file system discovery via
the initrd <filename>/etc/fstab</filename> rather than via kernel command line.</para>
fstab-generator: add new root=tmpfs option It's useful to be able to combine a regular /usr/ file system with a tmpfs as root, for an OS that boots up in volatile mode on every single boot. Let's add explicit support for this via root=tmpfs. Note the relationship to the existing systemd.volatile= option: 1. The kernel command line "root=/dev/… systemd.volatile=yes" will mount the specified root fs, and then hide everything at the top by overmounting it with a tmpfs, except for the /usr subtree. 2. The kernel command line "root=tmpfs mount.usr=/dev/…" otoh will mount a toot fs at the top (just like the case above), but will then mount the top-level dir of the fs specified in mount.usr= directly below it. Or to say this differently: in the first case /usr/ from the physical storage fs is going to become /usr/ of the hierarchy ultimately booted, while in the second case / from the physical storage fs is going to become /usr of the hierarchy booted. Philosophically I figure systemd.volatile= is more an option for "one-off" boots, while root=tmpfs is something to have as default mode of operation for suitable images. This is currently hard to test reasonably, since Dracut refuses to accept root=tmpfs. This needs to be addressed separately though.
2021-03-02 20:57:04 +03:00
<para>Use <literal>tmpfs</literal> in order to mount a <citerefentry
project='man-pages'><refentrytitle>tmpfs</refentrytitle><manvolnum>5</manvolnum></citerefentry> file
system as root file system of the OS. This is useful in combination with
<varname>mount.usr=</varname> (see below) in order to combine a volatile root file system with a
separate, immutable <filename>/usr/</filename> file system. Also see
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 19:52:36 +03:00
<varname>systemd.volatile=</varname> below.</para>
<xi:include href="version-info.xml" xpointer="v217"/></listitem>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
</varlistentry>
fstab-generator: add support for volatile boots This adds support for a new kernel command line option "systemd.volatile=" that provides the same functionality that systemd-nspawn's --volatile= switch provides, but for host systems (i.e. systems booting with a kernel). It takes the same parameter and has the same effect. In order to implement systemd.volatile=yes a new service systemd-volatile-root.service is introduced that only runs in the initrd and rearranges the root directory as needed to become a tmpfs instance. Note that systemd.volatile=state is implemented different: it simply generates a var.mount unit file that is part of the normal boot and has no effect on the initrd execution. The way this is implemented ensures that other explicit configuration for /var can always override the effect of these options. Specifically, the var.mount unit is generated in the "late" generator directory, so that it only is in effect if nothing else overrides it.
2016-12-13 14:45:19 +03:00
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
<varlistentry>
<term><varname>rootfstype=</varname></term>
<listitem><para>Takes the root filesystem type that will be
passed to the mount command. <varname>rootfstype=</varname> is
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 19:52:36 +03:00
honored by the initrd.</para>
<xi:include href="version-info.xml" xpointer="v217"/></listitem>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
</varlistentry>
fstab-generator: add support for volatile boots This adds support for a new kernel command line option "systemd.volatile=" that provides the same functionality that systemd-nspawn's --volatile= switch provides, but for host systems (i.e. systems booting with a kernel). It takes the same parameter and has the same effect. In order to implement systemd.volatile=yes a new service systemd-volatile-root.service is introduced that only runs in the initrd and rearranges the root directory as needed to become a tmpfs instance. Note that systemd.volatile=state is implemented different: it simply generates a var.mount unit file that is part of the normal boot and has no effect on the initrd execution. The way this is implemented ensures that other explicit configuration for /var can always override the effect of these options. Specifically, the var.mount unit is generated in the "late" generator directory, so that it only is in effect if nothing else overrides it.
2016-12-13 14:45:19 +03:00
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
<varlistentry>
<term><varname>rootflags=</varname></term>
man: document that rootflags= does not override /etc/fstab Fixes: #13324
2020-01-16 20:51:19 +03:00
<listitem><para>Takes the root filesystem mount options to use. <varname>rootflags=</varname> is
honored by the initrd.</para>
<para>Note that unlike most kernel command line options this setting does not override settings made
in configuration files (specifically: the mount option string in
<filename>/etc/fstab</filename>). See
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 19:52:36 +03:00
<citerefentry><refentrytitle>systemd-remount-fs.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
<xi:include href="version-info.xml" xpointer="v217"/></listitem>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
</varlistentry>
fstab-generator: add support for volatile boots This adds support for a new kernel command line option "systemd.volatile=" that provides the same functionality that systemd-nspawn's --volatile= switch provides, but for host systems (i.e. systems booting with a kernel). It takes the same parameter and has the same effect. In order to implement systemd.volatile=yes a new service systemd-volatile-root.service is introduced that only runs in the initrd and rearranges the root directory as needed to become a tmpfs instance. Note that systemd.volatile=state is implemented different: it simply generates a var.mount unit file that is part of the normal boot and has no effect on the initrd execution. The way this is implemented ensures that other explicit configuration for /var can always override the effect of these options. Specifically, the var.mount unit is generated in the "late" generator directory, so that it only is in effect if nothing else overrides it.
2016-12-13 14:45:19 +03:00
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
<varlistentry>
<term><varname>mount.usr=</varname></term>
man: use trailing slash on directories in more places
2020-10-05 19:08:21 +03:00
<listitem><para>Takes the <filename>/usr/</filename> filesystem
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
to be mounted by the initrd. If
<varname>mount.usrfstype=</varname> or
<varname>mount.usrflags=</varname> is set, then
<varname>mount.usr=</varname> will default to the value set in
<varname>root=</varname>.</para>
doc: correct punctuation and improve typography in documentation
2014-08-03 09:11:12 +04:00
<para>Otherwise, this parameter defaults to the
man: use trailing slash on directories in more places
2020-10-05 19:08:21 +03:00
<filename>/usr/</filename> entry found in
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
<filename>/etc/fstab</filename> on the root filesystem.</para>
<para><varname>mount.usr=</varname> is honored by the initrd.
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 19:52:36 +03:00
</para>
<xi:include href="version-info.xml" xpointer="v217"/></listitem>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
</varlistentry>
fstab-generator: add support for volatile boots This adds support for a new kernel command line option "systemd.volatile=" that provides the same functionality that systemd-nspawn's --volatile= switch provides, but for host systems (i.e. systems booting with a kernel). It takes the same parameter and has the same effect. In order to implement systemd.volatile=yes a new service systemd-volatile-root.service is introduced that only runs in the initrd and rearranges the root directory as needed to become a tmpfs instance. Note that systemd.volatile=state is implemented different: it simply generates a var.mount unit file that is part of the normal boot and has no effect on the initrd execution. The way this is implemented ensures that other explicit configuration for /var can always override the effect of these options. Specifically, the var.mount unit is generated in the "late" generator directory, so that it only is in effect if nothing else overrides it.
2016-12-13 14:45:19 +03:00
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
<varlistentry>
<term><varname>mount.usrfstype=</varname></term>
man: use trailing slash on directories in more places
2020-10-05 19:08:21 +03:00
<listitem><para>Takes the <filename>/usr/</filename> filesystem
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
type that will be passed to the mount command. If
<varname>mount.usr=</varname> or
<varname>mount.usrflags=</varname> is set, then
<varname>mount.usrfstype=</varname> will default to the value
set in <varname>rootfstype=</varname>.</para>
doc: correct punctuation and improve typography in documentation
2014-08-03 09:11:12 +04:00
<para>Otherwise, this value will be read from the
man: use trailing slash on directories in more places
2020-10-05 19:08:21 +03:00
<filename>/usr/</filename> entry in
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
<filename>/etc/fstab</filename> on the root filesystem.</para>
<para><varname>mount.usrfstype=</varname> is honored by the
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 19:52:36 +03:00
initrd.</para>
<xi:include href="version-info.xml" xpointer="v217"/></listitem>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
</varlistentry>
fstab-generator: add support for volatile boots This adds support for a new kernel command line option "systemd.volatile=" that provides the same functionality that systemd-nspawn's --volatile= switch provides, but for host systems (i.e. systems booting with a kernel). It takes the same parameter and has the same effect. In order to implement systemd.volatile=yes a new service systemd-volatile-root.service is introduced that only runs in the initrd and rearranges the root directory as needed to become a tmpfs instance. Note that systemd.volatile=state is implemented different: it simply generates a var.mount unit file that is part of the normal boot and has no effect on the initrd execution. The way this is implemented ensures that other explicit configuration for /var can always override the effect of these options. Specifically, the var.mount unit is generated in the "late" generator directory, so that it only is in effect if nothing else overrides it.
2016-12-13 14:45:19 +03:00
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
<varlistentry>
<term><varname>mount.usrflags=</varname></term>
man: use trailing slash on directories in more places
2020-10-05 19:08:21 +03:00
<listitem><para>Takes the <filename>/usr/</filename> filesystem
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
mount options to use. If <varname>mount.usr=</varname> or
<varname>mount.usrfstype=</varname> is set, then
treewide: Correct typos and spell plural of bus consistent
2015-05-11 14:49:29 +03:00
<varname>mount.usrflags=</varname> will default to the value
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
set in <varname>rootflags=</varname>.</para>
doc: correct punctuation and improve typography in documentation
2014-08-03 09:11:12 +04:00
<para>Otherwise, this value will be read from the
man: use trailing slash on directories in more places
2020-10-05 19:08:21 +03:00
<filename>/usr/</filename> entry in
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
<filename>/etc/fstab</filename> on the root filesystem.</para>
<para><varname>mount.usrflags=</varname> is honored by the
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 19:52:36 +03:00
initrd.</para>
<xi:include href="version-info.xml" xpointer="v217"/></listitem>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
</varlistentry>
fstab-generator: add support for volatile boots This adds support for a new kernel command line option "systemd.volatile=" that provides the same functionality that systemd-nspawn's --volatile= switch provides, but for host systems (i.e. systems booting with a kernel). It takes the same parameter and has the same effect. In order to implement systemd.volatile=yes a new service systemd-volatile-root.service is introduced that only runs in the initrd and rearranges the root directory as needed to become a tmpfs instance. Note that systemd.volatile=state is implemented different: it simply generates a var.mount unit file that is part of the normal boot and has no effect on the initrd execution. The way this is implemented ensures that other explicit configuration for /var can always override the effect of these options. Specifically, the var.mount unit is generated in the "late" generator directory, so that it only is in effect if nothing else overrides it.
2016-12-13 14:45:19 +03:00
man: document that systemd-fstab-generator actually cares about roothash=/usrhash= on the kernel cmdline It doesn't really care about the hash value passed (which is processed by systemd-veritysetup-generator), but it does care about the fact that it is set (and mounts the DM nodes /dev/mapper/usr + /dev/mapper/root in that case).
2022-05-02 17:42:50 +03:00
<varlistentry>
<term><varname>roothash=</varname></term>
<term><varname>usrhash=</varname></term>
<listitem><para>These options are primarily read by
<citerefentry><refentrytitle>systemd-veritysetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>. When
set this indicates that the root file system (or <filename>/usr/</filename>) shall be mounted from
Verity volumes with the specified hashes. If these kernel command line options are set the root (or
<filename>/usr/</filename>) file system is thus mounted from a device mapper volume
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 19:52:36 +03:00
<filename>/dev/mapper/root</filename> (or <filename>/dev/mapper/usr</filename>).</para>
<xi:include href="version-info.xml" xpointer="v251"/></listitem>
man: document that systemd-fstab-generator actually cares about roothash=/usrhash= on the kernel cmdline It doesn't really care about the hash value passed (which is processed by systemd-veritysetup-generator), but it does care about the fact that it is set (and mounts the DM nodes /dev/mapper/usr + /dev/mapper/root in that case).
2022-05-02 17:42:50 +03:00
</varlistentry>
fstab-generator: add support for volatile boots This adds support for a new kernel command line option "systemd.volatile=" that provides the same functionality that systemd-nspawn's --volatile= switch provides, but for host systems (i.e. systems booting with a kernel). It takes the same parameter and has the same effect. In order to implement systemd.volatile=yes a new service systemd-volatile-root.service is introduced that only runs in the initrd and rearranges the root directory as needed to become a tmpfs instance. Note that systemd.volatile=state is implemented different: it simply generates a var.mount unit file that is part of the normal boot and has no effect on the initrd execution. The way this is implemented ensures that other explicit configuration for /var can always override the effect of these options. Specifically, the var.mount unit is generated in the "late" generator directory, so that it only is in effect if nothing else overrides it.
2016-12-13 14:45:19 +03:00
<varlistentry>
<term><varname>systemd.volatile=</varname></term>
<listitem><para>Controls whether the system shall boot up in volatile mode. Takes a boolean argument or the
special value <option>state</option>.</para>
<para>If false (the default), this generator makes no changes to the mount tree and the system is booted up in
normal mode.</para>
<para>If true the generator ensures
<citerefentry><refentrytitle>systemd-volatile-root.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
man: "the initial RAM disk" → "the initrd" In many places we spelled out the phrase behind "initrd" in full, but this isn't terribly useful. In fact, no "RAM disk" is used, so emphasizing this is just confusing to the reader. Let's just say "initrd" everywhere, people understand what this refers to, and that it's in fact an initramfs image. Also, s/i.e./e.g./ where appropriate. Also, don't say "in RAM", when in fact it's virtual memory, whose pages may or may not be loaded in page frames in RAM, and we have no control over this. Also, add <filename></filename> and other minor cleanups.
2022-09-15 15:43:59 +03:00
is run in the initrd. This service changes the mount table before transitioning to the host system,
so that a volatile memory file system (<literal>tmpfs</literal>) is used as root directory, with only
<filename>/usr/</filename> mounted into it from the configured root file system, in read-only mode.
This way the system operates in fully stateless mode, with all configuration and state reset at boot
and lost at shutdown, as <filename>/etc/</filename> and <filename>/var/</filename> will be served
from the (initially unpopulated) volatile memory file system.</para>
fstab-generator: add support for volatile boots This adds support for a new kernel command line option "systemd.volatile=" that provides the same functionality that systemd-nspawn's --volatile= switch provides, but for host systems (i.e. systems booting with a kernel). It takes the same parameter and has the same effect. In order to implement systemd.volatile=yes a new service systemd-volatile-root.service is introduced that only runs in the initrd and rearranges the root directory as needed to become a tmpfs instance. Note that systemd.volatile=state is implemented different: it simply generates a var.mount unit file that is part of the normal boot and has no effect on the initrd execution. The way this is implemented ensures that other explicit configuration for /var can always override the effect of these options. Specifically, the var.mount unit is generated in the "late" generator directory, so that it only is in effect if nothing else overrides it.
2016-12-13 14:45:19 +03:00
man: document new systemd.volatile=overlay kernel command line option
2018-12-22 02:51:13 +03:00
<para>If set to <option>state</option> the generator will leave the root directory mount point unaltered,
man: use trailing slash on directories in more places
2020-10-05 19:08:21 +03:00
however will mount a <literal>tmpfs</literal> file system to <filename>/var/</filename>. In this mode the normal
system configuration (i.e. the contents of <literal>/etc/</literal>) is in effect (and may be modified during
system runtime), however the system state (i.e. the contents of <literal>/var/</literal>) is reset at boot and
man: document new systemd.volatile=overlay kernel command line option
2018-12-22 02:51:13 +03:00
lost at shutdown.</para>
<para>If this setting is set to <literal>overlay</literal> the root file system is set up as
<literal>overlayfs</literal> mount combining the read-only root directory with a writable
<literal>tmpfs</literal>, so that no modifications are made to disk, but the file system may be modified
nonetheless with all changes being lost at reboot.</para>
fstab-generator: add support for volatile boots This adds support for a new kernel command line option "systemd.volatile=" that provides the same functionality that systemd-nspawn's --volatile= switch provides, but for host systems (i.e. systems booting with a kernel). It takes the same parameter and has the same effect. In order to implement systemd.volatile=yes a new service systemd-volatile-root.service is introduced that only runs in the initrd and rearranges the root directory as needed to become a tmpfs instance. Note that systemd.volatile=state is implemented different: it simply generates a var.mount unit file that is part of the normal boot and has no effect on the initrd execution. The way this is implemented ensures that other explicit configuration for /var can always override the effect of these options. Specifically, the var.mount unit is generated in the "late" generator directory, so that it only is in effect if nothing else overrides it.
2016-12-13 14:45:19 +03:00
man: use trailing slash on directories in more places
2020-10-05 19:08:21 +03:00
<para>Note that in none of these modes the root directory, <filename>/etc/</filename>, <filename>/var/</filename>
fstab-generator: add support for volatile boots This adds support for a new kernel command line option "systemd.volatile=" that provides the same functionality that systemd-nspawn's --volatile= switch provides, but for host systems (i.e. systems booting with a kernel). It takes the same parameter and has the same effect. In order to implement systemd.volatile=yes a new service systemd-volatile-root.service is introduced that only runs in the initrd and rearranges the root directory as needed to become a tmpfs instance. Note that systemd.volatile=state is implemented different: it simply generates a var.mount unit file that is part of the normal boot and has no effect on the initrd execution. The way this is implemented ensures that other explicit configuration for /var can always override the effect of these options. Specifically, the var.mount unit is generated in the "late" generator directory, so that it only is in effect if nothing else overrides it.
2016-12-13 14:45:19 +03:00
or any other resources stored in the root file system are physically removed. It's thus safe to boot a system
that is normally operated in non-volatile mode temporarily into volatile mode, without losing data.</para>
fstab-generator: add new root=tmpfs option It's useful to be able to combine a regular /usr/ file system with a tmpfs as root, for an OS that boots up in volatile mode on every single boot. Let's add explicit support for this via root=tmpfs. Note the relationship to the existing systemd.volatile= option: 1. The kernel command line "root=/dev/… systemd.volatile=yes" will mount the specified root fs, and then hide everything at the top by overmounting it with a tmpfs, except for the /usr subtree. 2. The kernel command line "root=tmpfs mount.usr=/dev/…" otoh will mount a toot fs at the top (just like the case above), but will then mount the top-level dir of the fs specified in mount.usr= directly below it. Or to say this differently: in the first case /usr/ from the physical storage fs is going to become /usr/ of the hierarchy ultimately booted, while in the second case / from the physical storage fs is going to become /usr of the hierarchy booted. Philosophically I figure systemd.volatile= is more an option for "one-off" boots, while root=tmpfs is something to have as default mode of operation for suitable images. This is currently hard to test reasonably, since Dracut refuses to accept root=tmpfs. This needs to be addressed separately though.
2021-03-02 20:57:04 +03:00
<para>Note that with the exception of <literal>overlay</literal> mode, enabling this setting will
only work correctly on operating systems that can boot up with only <filename>/usr/</filename>
mounted, and are able to automatically populate <filename>/etc/</filename>, and also
<filename>/var/</filename> in case of <literal>systemd.volatile=yes</literal>.</para>
<para>Also see <varname>root=tmpfs</varname> above, for a method to combine a
<literal>tmpfs</literal> file system with a regular <filename>/usr/</filename> file system (as
configured via <varname>mount.usr=</varname>). The main distinction between
<varname>systemd.volatile=yes</varname>, and <varname>root=tmpfs</varname> in combination
<varname>mount.usr=</varname> is that the former operates on top of a regular root file system and
temporarily obstructs the files and directories above its <filename>/usr/</filename> subdirectory,
while the latter does not hide any files, but simply mounts a unpopulated tmpfs as root file system
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 19:52:36 +03:00
and combines it with a user picked <filename>/usr/</filename> file system.</para>
<xi:include href="version-info.xml" xpointer="v233"/></listitem>
fstab-generator: add support for volatile boots This adds support for a new kernel command line option "systemd.volatile=" that provides the same functionality that systemd-nspawn's --volatile= switch provides, but for host systems (i.e. systems booting with a kernel). It takes the same parameter and has the same effect. In order to implement systemd.volatile=yes a new service systemd-volatile-root.service is introduced that only runs in the initrd and rearranges the root directory as needed to become a tmpfs instance. Note that systemd.volatile=state is implemented different: it simply generates a var.mount unit file that is part of the normal boot and has no effect on the initrd execution. The way this is implemented ensures that other explicit configuration for /var can always override the effect of these options. Specifically, the var.mount unit is generated in the "late" generator directory, so that it only is in effect if nothing else overrides it.
2016-12-13 14:45:19 +03:00
</varlistentry>
fstab-generator: handle systemd.swap= command-line argument Don't generate swap units if set to false The inverse of this argument is present as "noswap" on Debian sysvinit Ref: https://salsa.debian.org/debian/sysvinit/blob/4422988cb41c3022eee7444378cac3b2e36eac28/debian/vars.sh#L34 https://salsa.debian.org/debian/sysvinit/blob/4422988cb41c3022eee7444378cac3b2e36eac28/debian/src/initscripts/etc/init.d/mountall.sh#L78 Fixes https://github.com/systemd/systemd/issues/6686
2019-12-21 09:17:59 +03:00
<varlistentry>
man: add trailing =
2023-05-25 09:44:21 +03:00
<term><varname>systemd.swap=</varname></term>
fstab-generator: handle systemd.swap= command-line argument Don't generate swap units if set to false The inverse of this argument is present as "noswap" on Debian sysvinit Ref: https://salsa.debian.org/debian/sysvinit/blob/4422988cb41c3022eee7444378cac3b2e36eac28/debian/vars.sh#L34 https://salsa.debian.org/debian/sysvinit/blob/4422988cb41c3022eee7444378cac3b2e36eac28/debian/src/initscripts/etc/init.d/mountall.sh#L78 Fixes https://github.com/systemd/systemd/issues/6686
2019-12-21 09:17:59 +03:00
<listitem><para>Takes a boolean argument or enables the option if specified
without an argument. If disabled, causes the generator to ignore
any swap devices configured in <filename>/etc/fstab</filename>.
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 19:52:36 +03:00
Defaults to enabled.</para>
man: update version information As I noticed a lot of missing information when trying to implement checking for missing info. I reimplemented the version information script to be more robust, and here is the result. Follow up to ec07c3c80b2b1bfa6788500202006ff85f5ae4f4
2023-09-18 18:03:38 +03:00
<xi:include href="version-info.xml" xpointer="v246"/></listitem>
fstab-generator: handle systemd.swap= command-line argument Don't generate swap units if set to false The inverse of this argument is present as "noswap" on Debian sysvinit Ref: https://salsa.debian.org/debian/sysvinit/blob/4422988cb41c3022eee7444378cac3b2e36eac28/debian/vars.sh#L34 https://salsa.debian.org/debian/sysvinit/blob/4422988cb41c3022eee7444378cac3b2e36eac28/debian/src/initscripts/etc/init.d/mountall.sh#L78 Fixes https://github.com/systemd/systemd/issues/6686
2019-12-21 09:17:59 +03:00
</varlistentry>
fstab-generator: support defining mount units through kernel command line Now, the following kernel command line options are supported: systemd.mount-extra=what:where:fstype:options systemd.swap-extra=what:options Closes #27260.
2023-05-08 13:49:33 +03:00
<varlistentry>
<term><varname>systemd.mount-extra=<replaceable>WHAT</replaceable>:<replaceable>WHERE</replaceable>[:<replaceable>FSTYPE</replaceable>[:<replaceable>OPTIONS</replaceable>]]</varname></term>
fstab-generator: add rd.systemd.mount-extra= and friends Previously, mounts specified in systemd.mount-extra= are equally handled both in initrd and the main system. So, the mounts for the main system are also mounted in initrd. This introduces rd.systemd.mount-extra=, which specifies mounts in initrd. Then, mounts specified in systemd.mount-extra= are still mounted both in initrd and the main system, but prefixed with /sysroot/ when running in initrd. Fixes #28516.
2023-07-25 22:17:27 +03:00
<term><varname>rd.systemd.mount-extra=<replaceable>WHAT</replaceable>:<replaceable>WHERE</replaceable>[:<replaceable>FSTYPE</replaceable>[:<replaceable>OPTIONS</replaceable>]]</varname></term>
fstab-generator: support defining mount units through kernel command line Now, the following kernel command line options are supported: systemd.mount-extra=what:where:fstype:options systemd.swap-extra=what:options Closes #27260.
2023-05-08 13:49:33 +03:00
<listitem>
<para>Specifies the mount unit. Takes at least two and at most four fields separated with a colon
(<literal>:</literal>). Each field is handled as the corresponding fstab field. This option can be
fstab-generator: add rd.systemd.mount-extra= and friends Previously, mounts specified in systemd.mount-extra= are equally handled both in initrd and the main system. So, the mounts for the main system are also mounted in initrd. This introduces rd.systemd.mount-extra=, which specifies mounts in initrd. Then, mounts specified in systemd.mount-extra= are still mounted both in initrd and the main system, but prefixed with /sysroot/ when running in initrd. Fixes #28516.
2023-07-25 22:17:27 +03:00
specified multiple times. <varname>rd.systemd.mount-extra=</varname> is honored only in the initrd,
while <varname>systemd.mount-extra=</varname> is honored by both the main system and the initrd.
In the initrd, the mount point (and also source path if the mount is bind mount) specified in
<varname>systemd.mount-extra=</varname> is prefixed with <filename>/sysroot/</filename>.</para>
fstab-generator: support defining mount units through kernel command line Now, the following kernel command line options are supported: systemd.mount-extra=what:where:fstype:options systemd.swap-extra=what:options Closes #27260.
2023-05-08 13:49:33 +03:00
<para>Example:
<programlisting>
systemd.mount-extra=/dev/sda1:/mount-point:ext4:rw,noatime</programlisting>
</para>
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 19:52:36 +03:00
<xi:include href="version-info.xml" xpointer="v254"/>
fstab-generator: support defining mount units through kernel command line Now, the following kernel command line options are supported: systemd.mount-extra=what:where:fstype:options systemd.swap-extra=what:options Closes #27260.
2023-05-08 13:49:33 +03:00
</listitem>
</varlistentry>
<varlistentry>
<term><varname>systemd.swap-extra=<replaceable>WHAT</replaceable>[:<replaceable>OPTIONS</replaceable>]</varname></term>
fstab-generator: add rd.systemd.mount-extra= and friends Previously, mounts specified in systemd.mount-extra= are equally handled both in initrd and the main system. So, the mounts for the main system are also mounted in initrd. This introduces rd.systemd.mount-extra=, which specifies mounts in initrd. Then, mounts specified in systemd.mount-extra= are still mounted both in initrd and the main system, but prefixed with /sysroot/ when running in initrd. Fixes #28516.
2023-07-25 22:17:27 +03:00
<term><varname>rd.systemd.swap-extra=<replaceable>WHAT</replaceable>[:<replaceable>OPTIONS</replaceable>]</varname></term>
fstab-generator: support defining mount units through kernel command line Now, the following kernel command line options are supported: systemd.mount-extra=what:where:fstype:options systemd.swap-extra=what:options Closes #27260.
2023-05-08 13:49:33 +03:00
<listitem>
<para>Specifies the swap unit. Takes the block device to be used as a swap device, and optionally
fstab-generator: add rd.systemd.mount-extra= and friends Previously, mounts specified in systemd.mount-extra= are equally handled both in initrd and the main system. So, the mounts for the main system are also mounted in initrd. This introduces rd.systemd.mount-extra=, which specifies mounts in initrd. Then, mounts specified in systemd.mount-extra= are still mounted both in initrd and the main system, but prefixed with /sysroot/ when running in initrd. Fixes #28516.
2023-07-25 22:17:27 +03:00
takes mount options followed by a colon (<literal>:</literal>). This option can be specified
multiple times. <varname>rd.systemd.swap-extra=</varname> is honored only in the initrd, while
<varname>systemd.swap-extra=</varname> is honored by both the main system and the initrd.</para>
fstab-generator: support defining mount units through kernel command line Now, the following kernel command line options are supported: systemd.mount-extra=what:where:fstype:options systemd.swap-extra=what:options Closes #27260.
2023-05-08 13:49:33 +03:00
<para>Example:
<programlisting>
man: fix example for systemd.swap-extra
2023-10-10 16:45:20 +03:00
systemd.swap-extra=/dev/sda2:x-systemd.makefs</programlisting>
fstab-generator: support defining mount units through kernel command line Now, the following kernel command line options are supported: systemd.mount-extra=what:where:fstype:options systemd.swap-extra=what:options Closes #27260.
2023-05-08 13:49:33 +03:00
</para>
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 19:52:36 +03:00
<xi:include href="version-info.xml" xpointer="v254"/>
fstab-generator: support defining mount units through kernel command line Now, the following kernel command line options are supported: systemd.mount-extra=what:where:fstype:options systemd.swap-extra=what:options Closes #27260.
2023-05-08 13:49:33 +03:00
</listitem>
</varlistentry>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
</variablelist>
</refsect1>
fstab-generator: optional read addtional fstab lines from credentials Fixes: #27260
2023-06-23 22:51:12 +03:00
<refsect1>
<title>System Credentials</title>
<variablelist class='system-credentials'>
<varlistentry>
<term><varname>fstab.extra</varname></term>
<listitem><para>This credential may contain addition mounts to establish, in the same format as
<citerefentry
project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>, with
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 19:52:36 +03:00
one mount per line. It is read in addition to <filename>/etc/fstab</filename>.</para>
<xi:include href="version-info.xml" xpointer="v254"/></listitem>
fstab-generator: optional read addtional fstab lines from credentials Fixes: #27260
2023-06-23 22:51:12 +03:00
</varlistentry>
</variablelist>
</refsect1>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
<refsect1>
<title>See Also</title>
man: use <simplelist> for 'See also' sections This is just a slight markup improvement; there should be no difference in rendering.
2023-12-22 21:09:32 +03:00
<para><simplelist type="inline">
<member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
<member><ulink url="https://systemd.io/ENVIRONMENT/">Known Environment Variables</ulink></member>
</simplelist></para>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
</refsect1>
man: document fstab generator
2012-06-27 17:27:29 +04:00
</refentry>
Copy Permalink