Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 268 lines (164 sloc) 8.117 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
77 compression via B<gzip>, B<bzip2>, B<lzma>, and B<xz>. You can also use B<none>
8c04a8f @falconindy Cleanup README
authored
78 to disable compression. Please note that your kernel I<must> support your
79 method and choice and your kernel will not be checked for this support! If in
80 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
5b82bea @falconindy add sections on builders, hooks, and files & directories
authored
104 =head1 BUILDERS
105
3fb791d @falconindy split out a section environment variables for hook
authored
106 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
107 functionality to the image. They are sourced from the appropriate config file,
3fb791d @falconindy split out a section environment variables for hook
authored
108 and run in array index order. Builders may draw in an additional hookscript for
109 use at runtime.
578cd54 @falconindy refactor BUILDER section, mainly to detail function reqs
authored
110
111 At a minimum, builders must define a function called I<build>, which contains
112 instructions on what geninit should add to the image. See the B<BUILDER API>
113 section for documentation on the available methods for adding files.
114 Additionally, a builder should also include a I<helpmsg> function, which
115 describes the features and/or functionality provided by the builder. This is
116 called via geninit's -H option.
5b82bea @falconindy add sections on builders, hooks, and files & directories
authored
117
118 =head1 HOOKS
119
120 Hooks are executed during the bootstrap process in order to facilitate finding
3fb791d @falconindy split out a section environment variables for hook
authored
121 and/or mounting of the root device. They run under Busybox's almquist shell. In
122 addition to any variables sourced from the kernel cmdline, the following variables
123 may be available from within the environment that hooks run in:
5b82bea @falconindy add sections on builders, hooks, and files & directories
authored
124
3fb791d @falconindy split out a section environment variables for hook
authored
125 =over 4
126
127 =item I<UDEVPID>
128
129 When set, contains the PID of the udev daemon process.
130
131 =item I<FDINIT>
132
133 A numerical value describing a file descriptor which can be used to communicate
134 with the parent process (init). The preferred method of setting variables in
135 init is via the I<initexport> function defined by libinit.
136
137 =back
5b82bea @falconindy add sections on builders, hooks, and files & directories
authored
138
3fb791d @falconindy split out a section environment variables for hook
authored
139 =head1 LIBINIT
a9337fe @falconindy note that FDINIT is available for rescue shells
authored
140
3fb791d @falconindy split out a section environment variables for hook
authored
141 A small shell library called libinit is included by the C<base> builder. Hooks
142 can use functions defined in this library by sourcing it from /libinit. The
143 following functions are defined by libinit:
9348d93 @falconindy document libinit
authored
144
145 =over 4
146
3fb791d @falconindy split out a section environment variables for hook
authored
147 =item B<msg> I<format> [I<message>]
9348d93 @falconindy document libinit
authored
148
149 Sends a formatted message to standard output, provided that the kernel parameter
3fb791d @falconindy split out a section environment variables for hook
authored
150 'quiet' was not passed. Messages are prefixed with ":: ".
9348d93 @falconindy document libinit
authored
151
3fb791d @falconindy split out a section environment variables for hook
authored
152 =item B<err> I<format> [I<message>]
9348d93 @falconindy document libinit
authored
153
3fb791d @falconindy split out a section environment variables for hook
authored
154 Sends a formatted message to standard error. Messages are prefixed with "error:
155 ".
9348d93 @falconindy document libinit
authored
156
157 =item B<poll_device> I<device> [I<timeout>]
158
159 Waits up to I<timeout> seconds for the specified I<device>, which is a block device
160 or a symlink to a block device. This functions returns 0 when the device shows up,
161 and 1 when it does not.
162
163 =item B<initexport> I<key=val...>
164
3fb791d @falconindy split out a section environment variables for hook
authored
165 Set a variable in init's environment. Any number of whitespace delimited
166 key=value pairs can be exported via a single invocation.
9348d93 @falconindy document libinit
authored
167
168 =back
169
cb48ffc @falconindy document public API
authored
170 =head1 BUILDER API
171
eaa4d57 @falconindy refactor BUILDER API section. fix a few typos
authored
172 geninit features a small API intended for use by builders. These are base
173 directory aware functions with error checking and are the recommended method of
512b081 @falconindy seriously, learn to spell components
authored
174 adding files to the cpio image from builders. Leading path components, if not
eaa4d57 @falconindy refactor BUILDER API section. fix a few typos
authored
175 already created, will be added implicitly. If, for some reason, you need to
176 override the base directory and specify a truly absolute path, you can prefix a
177 source argument with a '@'.
cb48ffc @falconindy document public API
authored
178
179 =over 4
180
181 =item B<add_binary> I<source> [I<path>]
182
183 Add a binary file, specified by the absolute path to its source. Unless specified,
184 the path on the image will be the same as the source. Files will be scanned for
185 library dependencies which will also be added to the image.
186
187 =item B<add_dir> I<path> [I<mode>]
188
189 Add a directory, specified by its absolute path on the image. Unless specified,
190 the permissions of the directory will be 755.
191
192 =item B<add_driver_classes> I<class>...
193
194 Add one or more classifications of modules to the image, specified as a
195 directory relative to C</lib/modules/KERNELVERSION/kernel>, e.g. 'drivers/scsi'
196 or 'crypto'. Modules can be filtered by name by adding glob (including extended
7682d99 @falconindy modulefilter => MODFILTER
authored
197 glob) patterns to the I<MODFILTER> array prior to calling
cb48ffc @falconindy document public API
authored
198 B<add_driver_classes>. This filter is cleared after the parsing of each hook,
199 although you are free to call B<unset> from within the builder, if desired.
200
201 Additionally, if the autodetect builder is used as part of image generation,
202 only the intersection of the autodetect module list and the results of the
203 add_driver_classes call will be added to the resulting image.
204
205 =item B<add_file> I<source> [I<path>]
206
207 Add a plain file, specified by the absolute path to its source. Unless
208 specified, the path on the image will be the same as the source. No
209 type checking of the file is done.
210
211 =item B<add_module> I<module_name>
212
213 Add a kernel module to the image, specified by its name (with or without
3b43e58 @falconindy add_module will also find firmware
authored
214 extension). Modules will be scanned for dependencies and firmware which will
215 also be added to the image.
cb48ffc @falconindy document public API
authored
216
217 =item B<add_path_to_file> I<file>
218
512b081 @falconindy seriously, learn to spell components
authored
219 Add all leading path components to a file to the image.
cb48ffc @falconindy document public API
authored
220
221 =item B<add_pipe> I<path> [I<mode>]
222
223 Add a FIFO device to the image, specified by its absolute path. Unless
224 specified, the permissions of the FIFO will be 644.
225
226 =item B<add_symlink> I<target> I<link>
227
228 Add a symlink to the image, located at the absolute path specified by link,
8c04a8f @falconindy Cleanup README
authored
229 and pointing to the path specified by target.
cb48ffc @falconindy document public API
authored
230
4d2713d @falconindy allow specifying a alternate name for the hookscript
authored
231 =item B<use_hookscript> [I<script>]
cb48ffc @falconindy document public API
authored
232
0fde32b @falconindy and that doesn't even make sense...
authored
233 Indicate that a script should be added to be run during bootstrap. Unless
234 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
235
236 =back
237
238 =head1 FILES AND DIRECTORIES
239
240 =over 4
241
242 =item C</etc/geninit.conf>
243
244 Default config file
245
246 =item C</etc/geninit.d>
247
248 Location of geninit preset files
249
250 =item C</usr/share/geninit/geninit.api>
251
252 Builder API file
253
254 =item C</usr/share/geninit/builders>
255
256 Location of builders
257
258 =item C</usr/share/geninit/hooks>
259
260 Location of hookscripts
cb48ffc @falconindy document public API
authored
261
262 =back
263
855cefa @falconindy add the beginnings of a man page
authored
264 =head1 AUTHOR
265
266 Dave Reisner E<lt>d@falconindy.comE<gt>
267
Something went wrong with that request. Please try again.