Skip to content
Newer
Older
100644 231 lines (143 sloc) 7.02 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
106 Builders are bash scripts that are parsed during build time in order to add
107 functionality to the image. They are sourced from the appropriate config file,
578cd54 @falconindy refactor BUILDER section, mainly to detail function reqs
authored
108 and parsed in array index order. Builders may draw in an additional hookscript
109 for use at runtime.
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
121 and/or mounting of the root device. They run under Busybox's almquist shell.
122 Because hooks are run as a child process of init, they are unable to directly
123 export variables affecting their parent. If you need to communicate back with
a001934 @falconindy fully abstract write pipe from child to parent
authored
124 init, you may write environment variable declarations on file descriptor
125 pointed to by the B<FDINIT> environment variable, which will be picked back up
126 into the environment of init, e.g.
5b82bea @falconindy add sections on builders, hooks, and files & directories
authored
127
a001934 @falconindy fully abstract write pipe from child to parent
authored
128 echo 'root=/dev/foo' >&$FDINIT
5b82bea @falconindy add sections on builders, hooks, and files & directories
authored
129
a9337fe @falconindy note that FDINIT is available for rescue shells
authored
130 Note that B<FDINIT> is also available for any rescue shell that may be invoked
131 during bootstrap.
132
cb48ffc @falconindy document public API
authored
133 =head1 BUILDER API
134
eaa4d57 @falconindy refactor BUILDER API section. fix a few typos
authored
135 geninit features a small API intended for use by builders. These are base
136 directory aware functions with error checking and are the recommended method of
512b081 @falconindy seriously, learn to spell components
authored
137 adding files to the cpio image from builders. Leading path components, if not
eaa4d57 @falconindy refactor BUILDER API section. fix a few typos
authored
138 already created, will be added implicitly. If, for some reason, you need to
139 override the base directory and specify a truly absolute path, you can prefix a
140 source argument with a '@'.
cb48ffc @falconindy document public API
authored
141
142 =over 4
143
144 =item B<add_binary> I<source> [I<path>]
145
146 Add a binary file, specified by the absolute path to its source. Unless specified,
147 the path on the image will be the same as the source. Files will be scanned for
148 library dependencies which will also be added to the image.
149
150 =item B<add_dir> I<path> [I<mode>]
151
152 Add a directory, specified by its absolute path on the image. Unless specified,
153 the permissions of the directory will be 755.
154
155 =item B<add_driver_classes> I<class>...
156
157 Add one or more classifications of modules to the image, specified as a
158 directory relative to C</lib/modules/KERNELVERSION/kernel>, e.g. 'drivers/scsi'
159 or 'crypto'. Modules can be filtered by name by adding glob (including extended
7682d99 @falconindy modulefilter => MODFILTER
authored
160 glob) patterns to the I<MODFILTER> array prior to calling
cb48ffc @falconindy document public API
authored
161 B<add_driver_classes>. This filter is cleared after the parsing of each hook,
162 although you are free to call B<unset> from within the builder, if desired.
163
164 Additionally, if the autodetect builder is used as part of image generation,
165 only the intersection of the autodetect module list and the results of the
166 add_driver_classes call will be added to the resulting image.
167
168 =item B<add_file> I<source> [I<path>]
169
170 Add a plain file, specified by the absolute path to its source. Unless
171 specified, the path on the image will be the same as the source. No
172 type checking of the file is done.
173
174 =item B<add_module> I<module_name>
175
176 Add a kernel module to the image, specified by its name (with or without
3b43e58 @falconindy add_module will also find firmware
authored
177 extension). Modules will be scanned for dependencies and firmware which will
178 also be added to the image.
cb48ffc @falconindy document public API
authored
179
180 =item B<add_path_to_file> I<file>
181
512b081 @falconindy seriously, learn to spell components
authored
182 Add all leading path components to a file to the image.
cb48ffc @falconindy document public API
authored
183
184 =item B<add_pipe> I<path> [I<mode>]
185
186 Add a FIFO device to the image, specified by its absolute path. Unless
187 specified, the permissions of the FIFO will be 644.
188
189 =item B<add_symlink> I<target> I<link>
190
191 Add a symlink to the image, located at the absolute path specified by link,
8c04a8f @falconindy Cleanup README
authored
192 and pointing to the path specified by target.
cb48ffc @falconindy document public API
authored
193
4d2713d @falconindy allow specifying a alternate name for the hookscript
authored
194 =item B<use_hookscript> [I<script>]
cb48ffc @falconindy document public API
authored
195
0fde32b @falconindy and that doesn't even make sense...
authored
196 Indicate that a script should be added to be run during bootstrap. Unless
197 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
198
199 =back
200
201 =head1 FILES AND DIRECTORIES
202
203 =over 4
204
205 =item C</etc/geninit.conf>
206
207 Default config file
208
209 =item C</etc/geninit.d>
210
211 Location of geninit preset files
212
213 =item C</usr/share/geninit/geninit.api>
214
215 Builder API file
216
217 =item C</usr/share/geninit/builders>
218
219 Location of builders
220
221 =item C</usr/share/geninit/hooks>
222
223 Location of hookscripts
cb48ffc @falconindy document public API
authored
224
225 =back
226
855cefa @falconindy add the beginnings of a man page
authored
227 =head1 AUTHOR
228
229 Dave Reisner E<lt>d@falconindy.comE<gt>
230
Something went wrong with that request. Please try again.