chiark / gitweb /
core: allow setting RemainAfterExit= for transient services
[elogind.git] / man / kernel-install.xml
1 <?xml version='1.0'?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4
5 <!--
6 This file is part of systemd.
7
8 Copyright 2013 Harald Hoyer
9
10 systemd is free software; you can redistribute it and/or modify it
11 under the terms of the GNU Lesser General Public License as published by
12 the Free Software Foundation; either version 2.1 of the License, or
13 (at your option) any later version.
14
15 systemd is distributed in the hope that it will be useful, but
16 WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 Lesser General Public License for more details.
19
20 You should have received a copy of the GNU Lesser General Public License
21 along with systemd; If not, see <http://www.gnu.org/licenses/>.
22 -->
23
24 <refentry id="kernel-install">
25
26   <refentryinfo>
27     <title>kernel-install</title>
28     <productname>systemd</productname>
29
30     <authorgroup>
31       <author>
32         <contrib>Developer</contrib>
33         <firstname>Harald</firstname>
34         <surname>Hoyer</surname>
35         <email>harald@redhat.com</email>
36       </author>
37     </authorgroup>
38   </refentryinfo>
39
40   <refmeta>
41     <refentrytitle>kernel-install</refentrytitle>
42     <manvolnum>8</manvolnum>
43   </refmeta>
44
45   <refnamediv>
46     <refname>kernel-install</refname>
47     <refpurpose>Add and remove kernel and initramfs images to and from /boot</refpurpose>
48   </refnamediv>
49
50   <refsynopsisdiv>
51     <cmdsynopsis>
52       <command>kernel-install</command>
53       <arg choice="plain">COMMAND</arg>
54       <arg choice="plain"><replaceable>KERNEL-VERSION</replaceable></arg>
55       <arg choice="opt"><replaceable>KERNEL-IMAGE</replaceable></arg>
56     </cmdsynopsis>
57   </refsynopsisdiv>
58
59   <refsect1>
60     <title>Description</title>
61     <para>
62       <command>kernel-install</command> is used to install and remove kernel and
63       initramfs images to and from <filename>/boot</filename>.
64     </para>
65
66     <para><command>kernel-install</command> will execute the files
67     located in the directory <filename>/usr/lib/kernel/install.d/</filename>
68     and the local administration directory <filename>/etc/kernel/install.d/</filename>.
69     All files are collectively sorted and executed in lexical order, regardless of the directory in
70     which they live. However, files with identical filenames replace each other.
71     Files in <filename>/etc/kernel/install.d/</filename> take precedence over files with the same name
72     in <filename>/usr/lib/kernel/install.d/</filename>. This can be used to override a system-supplied
73     executables with a local file if needed; a symbolic link in <filename>/etc/kernel/install.d/</filename>
74     with the same name as an executable in <filename>/usr/lib/kernel/install.d/</filename>,
75     pointing to /dev/null, disables the executable entirely. Executables must have the
76     extension <literal>.install</literal>; other extensions are ignored.</para>
77
78   </refsect1>
79
80   <refsect1>
81     <title>Commands</title>
82     <para>The following commands are understood:</para>
83     <variablelist>
84       <varlistentry>
85         <term><command>add <replaceable>KERNEL-VERSION</replaceable> <replaceable>KERNEL-IMAGE</replaceable></command></term>
86         <listitem>
87           <para><command>kernel-install</command> creates the directory
88           <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename>
89           and calls every executable
90           <filename>/usr/lib/kernel/install.d/*.install</filename> and
91           <filename>/etc/kernel/install.d/*.install</filename> with
92           the arguments
93           <programlisting>
94 add <replaceable>KERNEL-VERSION</replaceable> <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename>
95           </programlisting>
96           </para>
97
98           <para>The kernel-install plugin <filename>50-depmod.install</filename> runs depmod for the <replaceable>KERNEL-VERSION</replaceable>.</para>
99
100           <para>The kernel-install plugin <filename>90-loaderentry.install</filename> copies
101           <replaceable>KERNEL-IMAGE</replaceable> to
102           <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/linux</filename>.
103           It also creates a boot loader entry according to the boot loader specification in
104           <filename>/boot/loader/entries/<replaceable>MACHINE-ID</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.conf</filename>.
105           The title of the entry is the <replaceable>PRETTY_NAME</replaceable> parameter specified in <filename>/etc/os-release</filename>,
106           or "Linux <replaceable>KERNEL-VERSION</replaceable>", if unset.
107           If the file <filename>initrd</filename> is found next to the
108           <filename>linux</filename> file, the initrd will be added to
109           the configuration.</para>
110         </listitem>
111       </varlistentry>
112       <varlistentry>
113         <term><command>remove <replaceable>KERNEL-VERSION</replaceable></command></term>
114         <listitem>
115           <para>Calls every executable <filename>/usr/lib/kernel/install.d/*.install</filename>
116           and <filename>/etc/kernel/install.d/*.install</filename> with the arguments
117           <programlisting>
118 remove <replaceable>KERNEL-VERSION</replaceable> <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename>
119           </programlisting>
120           </para>
121
122           <para><command>kernel-install</command> removes the entire directory
123           <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename> afterwards.</para>
124
125           <para>The kernel-install plugin <filename>90-loaderentry.install</filename> removes the file
126           <filename>/boot/loader/entries/<replaceable>MACHINE-ID</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.conf</filename>.</para>
127         </listitem>
128       </varlistentry>
129
130     </variablelist>
131
132   </refsect1>
133
134   <refsect1>
135     <title>Exit status</title>
136     <para>If every executable returns with 0, 0 is returned, a non-zero failure code otherwise.</para>
137   </refsect1>
138
139   <refsect1>
140     <title>Files</title>
141     <variablelist>
142       <varlistentry>
143         <term>
144           <filename>/usr/lib/kernel/install.d/*.install</filename>
145           <filename>/etc/kernel/install.d/*.install</filename>
146         </term>
147           <listitem>
148             <para>Drop-in files which are executed by kernel-install.</para>
149           </listitem>
150       </varlistentry>
151       <varlistentry>
152         <term>
153           <filename>/etc/kernel/cmdline</filename>
154           <filename>/proc/cmdline</filename>
155         </term>
156           <listitem>
157             <para>The content of the file <filename>/etc/kernel/cmdline</filename> specifies the kernel command line to use.
158             If that file does not exist, <filename>/proc/cmdline</filename> is used.</para>
159           </listitem>
160       </varlistentry>
161       <varlistentry>
162         <term>
163           <filename>/etc/machine-id</filename>
164         </term>
165           <listitem>
166             <para>The content of the file specifies the machine identification <replaceable>MACHINE-ID</replaceable>.</para>
167           </listitem>
168       </varlistentry>
169       <varlistentry>
170         <term>
171           <filename>/etc/os-release</filename>
172         </term>
173           <listitem>
174             <para>The content of the file specifies the operating system title <replaceable>PRETTY_NAME</replaceable>.</para>
175           </listitem>
176       </varlistentry>
177     </variablelist>
178   </refsect1>
179
180   <refsect1>
181     <title>See Also</title>
182     <para>
183       <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
184       <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
185       <ulink url="http://www.freedesktop.org/wiki/Specifications/BootLoaderSpec">Boot loader specification</ulink>
186     </para>
187   </refsect1>
188
189 </refentry>