Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 317 lines (195 sloc) 9.59 kb
855cefa @falconindy add the beginnings of a man page
authored
1 =head1 NAME
2
3 geninit - modular initramfs creation utility
4
5 =head1 SYNOPSIS
6
7 Usage: I<geninit> [ options ]
8
9 =head1 DESCRIPTION
10
11 geninit is a tool for creating cpio archives to be used as an initial ramfs
12 during system bootstrap. It features a modular design, making it easy to
13 tailor the image to the system's hardware and software needs.
14
15 =head1 OPTIONS
16
17 =over 4
18
8c04a8f @falconindy Cleanup README
authored
19 =item B<-b> I<basedir>
855cefa @falconindy add the beginnings of a man page
authored
20
cb48ffc @falconindy document public API
authored
21 Specify a base directory other than C</>. This is reserved for usage during a
855cefa @falconindy add the beginnings of a man page
authored
22 chroot. geninit will attempt to use as much as possible from the guest system,
23 drawing only from the host system when necessary.
24
8c04a8f @falconindy Cleanup README
authored
25 =item B<-c> I<config-file>
855cefa @falconindy add the beginnings of a man page
authored
26
cb48ffc @falconindy document public API
authored
27 Use an alterate config file. Defaults to C</etc/geninit.conf>.
855cefa @falconindy add the beginnings of a man page
authored
28
8c04a8f @falconindy Cleanup README
authored
29 =item B<-g> I<imagename>
855cefa @falconindy add the beginnings of a man page
authored
30
31 Specify the absolute path of the generated initramfs image. If unspecified,
32 a dry-run will be performed and no image will be created.
33
8c04a8f @falconindy Cleanup README
authored
34 =item B<-H> I<builder>
855cefa @falconindy add the beginnings of a man page
authored
35
36 Display the help message for a I<builder>. A list of available builders can
37 be generated with the B<-L> option.
38
39 =item B<-h>
40
41 Display the help message and quit.
42
8c04a8f @falconindy Cleanup README
authored
43 =item B<-k> I<kernel>
855cefa @falconindy add the beginnings of a man page
authored
44
45 Specify an alternate kernel version to create an image for. The kernel can be
cb48ffc @falconindy document public API
authored
46 specified as an exact version (such as 2.6.38-ARCH), or provided as a path to
47 the kernel bzImage itself. By default, this is the currently loaded kernel.
855cefa @falconindy add the beginnings of a man page
authored
48
49 =item B<-L>
50
51 List all available builders for use in the I<builders> array in the config
52 file.
53
8c04a8f @falconindy Cleanup README
authored
54 =item B<-p> I<preset>
855cefa @falconindy add the beginnings of a man page
authored
55
56 Specify a preset file to drive image creation. This is any file named with a
cb48ffc @falconindy document public API
authored
57 .preset extension in C</etc/geninit.d>. An example preset file is packaged
855cefa @falconindy add the beginnings of a man page
authored
58 with geninit for explanatory purpose.
59
8c04a8f @falconindy Cleanup README
authored
60 =item B<-S> I<builders>
855cefa @falconindy add the beginnings of a man page
authored
61
62 A comma delimited list of builders to skip during image creation.
63
64 =item B<-s>
65
8c04a8f @falconindy Cleanup README
authored
66 Save the temporary workspace after the build process. This is useful for
67 debugging purposes.
855cefa @falconindy add the beginnings of a man page
authored
68
8c04a8f @falconindy Cleanup README
authored
69 =item B<-t> I<path>
855cefa @falconindy add the beginnings of a man page
authored
70
71 Specify an alterate version to the temporary directory used as a workspace. This
72 needs to be a writeable directory with a minimum of 20mb free.
73
8c04a8f @falconindy Cleanup README
authored
74 =item B<-z> I<compression>
855cefa @falconindy add the beginnings of a man page
authored
75
76 Override the compression method specified by the config file. geninit supports
1a5e61c @falconindy Add support for LZO compression via lzop
authored
77 compression via B<gzip>, B<bzip2>, B<lzma>, and B<xz> (with optional support for
78 B<lzop>). You can also use B<none> to disable compression. Please note that your
79 kernel I<must> support your method and choice and your kernel will not be
80 checked for this support! If in doubt, gzip is a safe choice.
855cefa @falconindy add the beginnings of a man page
authored
81
82 =back
83
cb48ffc @falconindy document public API
authored
84 =head1 EXAMPLES
85
86 =over 4
87
88 =item B<geninit>
89
90 Perform a dry run against the currently loaded kernel. Although a temporary
91 workspace is created, no bootable image is generated from this operation.
92
93 =item B<geninit -k /boot/vmlinuz26 -g /boot/initramfs-ARCH>
94
95 Create an image for the kernel located at C</boot/vmlinuz26> called
96 C</boot/initramfs-ARCH>, described by the default config file.
97
5b82bea @falconindy add sections on builders, hooks, and files & directories
authored
98 =item B<geninit -b /mnt -p kernel26>
cb48ffc @falconindy document public API
authored
99
5b82bea @falconindy add sections on builders, hooks, and files & directories
authored
100 Build an image, or images, as described in C</mnt/etc/geninit.d/kernel26.preset>.
cb48ffc @falconindy document public API
authored
101
102 =back
103
7ad9e1f @falconindy README: document the non-obvious kernel cmdline flags
authored
104 =head1 KERNEL COMMAND LINE
105
106 geninit pays special attention to some parameters on the kernel cmdline, in
107 addition to the standard parameters such as B<root> and B<init>. In addition
108 to the ensuing list, some hooks may look for environment variables. Refer to
109 the help for individual builders for more information.
110
111 =over 4
112
113 =item B<break>
114
115 Request a shell during the early userspace process. This occurs after all hooks
116 have been run, but prior to the root device being mounted.
117
69e29e4 @falconindy README: document more cmdline vars
authored
118 =item B<init=>I<path>
119
120 An optional parameter to specify an alternate init system for userspace. If not
121 specified, this defaults to /sbin/init.
122
7ad9e1f @falconindy README: document the non-obvious kernel cmdline flags
authored
123 =item B<loglevel=>I<#>
124
125 Sets the kernel log priority according to the number provided (1-8), with
126 larger values producing more output. See B<klogctl>(3) for an explanation of
69e29e4 @falconindy README: document more cmdline vars
authored
127 the values.
128
129 =item B<root=>I<device>
130
131 The root device to be mounted before leaving early userspace. This can take
132 a number of different formats, such as:
133
134 root=/dev/sda2
135 root=LABEL=root
136 root=UUID=037b9d94-148e-4ee4-8d38-67bfe15bb535
137 root=MAJOR:MINOR
138
139 This parameter, for obvious reasons, must be specified.
7ad9e1f @falconindy README: document the non-obvious kernel cmdline flags
authored
140
141 =item B<rootflags=>I<flags>
142
143 A comma separated list of options passed directly to the final parameter of
144 B<mount>(2) when mounting the root device.
145
146 =back
147
5b82bea @falconindy add sections on builders, hooks, and files & directories
authored
148 =head1 BUILDERS
149
3fb791d @falconindy split out a section environment variables for hook
authored
150 Builders are bash scripts that are executed during build time in order to add
5b82bea @falconindy add sections on builders, hooks, and files & directories
authored
151 functionality to the image. They are sourced from the appropriate config file,
3fb791d @falconindy split out a section environment variables for hook
authored
152 and run in array index order. Builders may draw in an additional hookscript for
153 use at runtime.
578cd54 @falconindy refactor BUILDER section, mainly to detail function reqs
authored
154
155 At a minimum, builders must define a function called I<build>, which contains
156 instructions on what geninit should add to the image. See the B<BUILDER API>
157 section for documentation on the available methods for adding files.
158 Additionally, a builder should also include a I<helpmsg> function, which
159 describes the features and/or functionality provided by the builder. This is
160 called via geninit's -H option.
5b82bea @falconindy add sections on builders, hooks, and files & directories
authored
161
162 =head1 HOOKS
163
164 Hooks are executed during the bootstrap process in order to facilitate finding
3fb791d @falconindy split out a section environment variables for hook
authored
165 and/or mounting of the root device. They run under Busybox's almquist shell. In
166 addition to any variables sourced from the kernel cmdline, the following variables
167 may be available from within the environment that hooks run in:
5b82bea @falconindy add sections on builders, hooks, and files & directories
authored
168
3fb791d @falconindy split out a section environment variables for hook
authored
169 =over 4
170
171 =item I<UDEVPID>
172
173 When set, contains the PID of the udev daemon process.
174
175 =item I<FDINIT>
176
177 A numerical value describing a file descriptor which can be used to communicate
178 with the parent process (init). The preferred method of setting variables in
179 init is via the I<initexport> function defined by libinit.
180
181 =back
5b82bea @falconindy add sections on builders, hooks, and files & directories
authored
182
3fb791d @falconindy split out a section environment variables for hook
authored
183 =head1 LIBINIT
a9337fe @falconindy note that FDINIT is available for rescue shells
authored
184
3fb791d @falconindy split out a section environment variables for hook
authored
185 A small shell library called libinit is included by the C<base> builder. Hooks
186 can use functions defined in this library by sourcing it from /libinit. The
187 following functions are defined by libinit:
9348d93 @falconindy document libinit
authored
188
189 =over 4
190
3fb791d @falconindy split out a section environment variables for hook
authored
191 =item B<msg> I<format> [I<message>]
9348d93 @falconindy document libinit
authored
192
193 Sends a formatted message to standard output, provided that the kernel parameter
3fb791d @falconindy split out a section environment variables for hook
authored
194 'quiet' was not passed. Messages are prefixed with ":: ".
9348d93 @falconindy document libinit
authored
195
3fb791d @falconindy split out a section environment variables for hook
authored
196 =item B<err> I<format> [I<message>]
9348d93 @falconindy document libinit
authored
197
3fb791d @falconindy split out a section environment variables for hook
authored
198 Sends a formatted message to standard error. Messages are prefixed with "error:
199 ".
9348d93 @falconindy document libinit
authored
200
201 =item B<poll_device> I<device> [I<timeout>]
202
203 Waits up to I<timeout> seconds for the specified I<device>, which is a block device
204 or a symlink to a block device. This functions returns 0 when the device shows up,
205 and 1 when it does not.
206
207 =item B<initexport> I<key=val...>
208
3fb791d @falconindy split out a section environment variables for hook
authored
209 Set a variable in init's environment. Any number of whitespace delimited
210 key=value pairs can be exported via a single invocation.
9348d93 @falconindy document libinit
authored
211
212 =back
213
cb48ffc @falconindy document public API
authored
214 =head1 BUILDER API
215
eaa4d57 @falconindy refactor BUILDER API section. fix a few typos
authored
216 geninit features a small API intended for use by builders. These are base
217 directory aware functions with error checking and are the recommended method of
512b081 @falconindy seriously, learn to spell components
authored
218 adding files to the cpio image from builders. Leading path components, if not
eaa4d57 @falconindy refactor BUILDER API section. fix a few typos
authored
219 already created, will be added implicitly. If, for some reason, you need to
220 override the base directory and specify a truly absolute path, you can prefix a
221 source argument with a '@'.
cb48ffc @falconindy document public API
authored
222
223 =over 4
224
225 =item B<add_binary> I<source> [I<path>]
226
227 Add a binary file, specified by the absolute path to its source. Unless specified,
228 the path on the image will be the same as the source. Files will be scanned for
229 library dependencies which will also be added to the image.
230
231 =item B<add_dir> I<path> [I<mode>]
232
233 Add a directory, specified by its absolute path on the image. Unless specified,
234 the permissions of the directory will be 755.
235
e735fbc @falconindy change add_driver_classes -> add_checked_modules, add add_all_modules
authored
236 =item B<add_checked_modules> I<class>...
cb48ffc @falconindy document public API
authored
237
238 Add one or more classifications of modules to the image, specified as a
239 directory relative to C</lib/modules/KERNELVERSION/kernel>, e.g. 'drivers/scsi'
240 or 'crypto'. Modules can be filtered by name by adding glob (including extended
7682d99 @falconindy modulefilter => MODFILTER
authored
241 glob) patterns to the I<MODFILTER> array prior to calling
e735fbc @falconindy change add_driver_classes -> add_checked_modules, add add_all_modules
authored
242 B<add_checked_modules>. This filter is cleared after the parsing of each hook,
cb48ffc @falconindy document public API
authored
243 although you are free to call B<unset> from within the builder, if desired.
244
245 Additionally, if the autodetect builder is used as part of image generation,
246 only the intersection of the autodetect module list and the results of the
e735fbc @falconindy change add_driver_classes -> add_checked_modules, add add_all_modules
authored
247 add_checked_modules call will be added to the resulting image.
248
249 =item B<all_all_modules> I<class>...
250
251 Identical to B<add_checked_modules> with the exception that no comparison
252 against the autodetected module list is performed.
cb48ffc @falconindy document public API
authored
253
254 =item B<add_file> I<source> [I<path>]
255
256 Add a plain file, specified by the absolute path to its source. Unless
257 specified, the path on the image will be the same as the source. No
258 type checking of the file is done.
259
260 =item B<add_module> I<module_name>
261
262 Add a kernel module to the image, specified by its name (with or without
3b43e58 @falconindy add_module will also find firmware
authored
263 extension). Modules will be scanned for dependencies and firmware which will
264 also be added to the image.
cb48ffc @falconindy document public API
authored
265
266 =item B<add_path_to_file> I<file>
267
512b081 @falconindy seriously, learn to spell components
authored
268 Add all leading path components to a file to the image.
cb48ffc @falconindy document public API
authored
269
270 =item B<add_pipe> I<path> [I<mode>]
271
272 Add a FIFO device to the image, specified by its absolute path. Unless
273 specified, the permissions of the FIFO will be 644.
274
275 =item B<add_symlink> I<target> I<link>
276
277 Add a symlink to the image, located at the absolute path specified by link,
8c04a8f @falconindy Cleanup README
authored
278 and pointing to the path specified by target.
cb48ffc @falconindy document public API
authored
279
4d2713d @falconindy allow specifying a alternate name for the hookscript
authored
280 =item B<use_hookscript> [I<script>]
cb48ffc @falconindy document public API
authored
281
0fde32b @falconindy and that doesn't even make sense...
authored
282 Indicate that a script should be added to be run during bootstrap. Unless
283 specified, geninit will look for a script by the same name as the builder.
5b82bea @falconindy add sections on builders, hooks, and files & directories
authored
284
285 =back
286
287 =head1 FILES AND DIRECTORIES
288
289 =over 4
290
291 =item C</etc/geninit.conf>
292
293 Default config file
294
295 =item C</etc/geninit.d>
296
297 Location of geninit preset files
298
299 =item C</usr/share/geninit/geninit.api>
300
301 Builder API file
302
303 =item C</usr/share/geninit/builders>
304
305 Location of builders
306
307 =item C</usr/share/geninit/hooks>
308
309 Location of hookscripts
cb48ffc @falconindy document public API
authored
310
311 =back
312
855cefa @falconindy add the beginnings of a man page
authored
313 =head1 AUTHOR
314
315 Dave Reisner E<lt>d@falconindy.comE<gt>
316
Something went wrong with that request. Please try again.