Force EFI grub installation on amd64 with uefi
[openstack-debian-images.git] / build-openstack-debian-image.1
1 .TH build\-openstack\-debian\-image 1
2 .SH NAME
3 build\-openstack\-debian\-image \- build a Debian image to be used with OpenStack
4 .SH SYNOPSIS
5 .B build\-openstack\-debian\-image
6 .B \-\-release|\-r <jessie|wheezy>
7 [ OPTIONS ]
8
9 .SH DESCRIPTION
10 .LP
11 The
12 .I build\-openstack\-debian\-image
13 shell script will build a Debian image which can be used in an OpenStack IaaS
14 cloud. The resulting (Qcow2 and raw images) contains initramfs\-growroot so
15 that the root partition will be resized (during the initramfs phase, before
16 mouting anything) to match the flavor selected when using "nova boot". Later on
17 during the boot process, cloud\-init will resize the root partition on the fly
18 (resize is performed when the partition is already mounted read\-write, since
19 recent kernel allow that for ext3).
20
21 Cloud\-init is setup to use an Ec2 metadata server, which is what OpenStack is
22 compatible with. A "debian" (configurable with the use of the
23 .B --login
24 option) user will be used to receive the ssh key from the user data blob.
25 This user is setup without a password (eg: adduser \-\-disabled\-password).
26 Once logged as this "debian" user in your new virtual machine, you can
27 "sudo" to root from that user, without needing a password. The root
28 password is "password" by default, and ssh into the root user without
29 using an ssh keypair is disabled by default (PermitRootLogin without-password
30 is set in /etc/ssh/sshd_config).
31
32 .SH "PARAMETERS"
33
34 .LP
35 .B \-\-release|\-r
36 .I wheezy|jessie
37 .IP
38
39 Sets the
40 .I release
41 name to be installed. Currently only 2 values a possible:
42 .I wheezy
43 and
44 .I jessie.
45
46 .SH "OPTIONS"
47
48 .LP
49 .B \-\-extra\-packages|\-e 
50 .I PACKAGE,PACKAGE,...
51 .IP
52
53 Select the
54 .I PACKAGE
55 you want to add to the image
56 .I default is: bash-completion,joe,most,screen,less,vim,bzip2
57 Note that this list of extra packages isn't used if you use the
58 .B --minimal
59 option.
60
61 .LP
62 .B \-\-debootstrap\-url|\-u
63 .I <debootstrap\-debian\-mirror>
64 .IP
65
66 Select the
67 .I URL
68 of the Debian mirror to use to perform the debootstrap. For example:
69 .I http://ftp.fr.debian.org/debian
70
71 .LP
72 .B \-\-boot-manager|\-bm
73 .I <grub|syslinux>
74 .IP
75
76 Select what type of boot manager to use inside the image. The default is
77 Grub, but you can as well decide to use syslinux if you prefer.
78
79 .LP
80 .B \-\-boot-type|\-bt
81 .I <mbr|uefi>
82 .IP
83
84 Select how to boot the image: using legacy MBR-style (aka BIOS or CSM)
85 boot, or UEFI. The default is mbr. Selecting uefi requires the use of
86 Grub as the boot manager, and will set up an extra EFI System
87 Partition inside the image to support UEFI boot.
88
89 .LP
90 .B \-\-architecture|\-
91 .I <amd64|arm64>
92 .IP
93
94 Select the architecture to target for the output image. This will not
95 cross build for that architecture, but will pick the right
96 architecture-specific components. Supported options are "amd64" and
97 "arm64"; "amd64" is default.
98
99 .LP
100 .B \-\-sources.list\-mirror|\-s
101 .I <source\-list\-mirror>
102 .IP
103
104 URL to use when building the sources.list inside the chroot. If this
105 option is ommited, then the global httpredir.debian.org redirector is used.
106 For example, you can use:
107 .I http://ftp.fr.debian.org/debian
108
109 .LP
110 .B \-\-minimal
111 .IP
112
113 Without this option, the following packages will also be installed:
114 bash\-completion (and /etc/bash.bashrc will be setup to use bash\-completion),
115 joe (the text editor), most, GNU screen, less and vim. If you believe that
116 more things should be added in the non\-minimal image, suggestions are
117 welcome.
118
119 .LP
120 .B \-\-azure|\-az
121 .IP
122
123 Build an image for the Microsoft Azure cloud. Note that this option
124 is incompatible with the \-\-automatic-resize|\-ar option, which will
125 be ignored.
126
127 .LP
128 .B \-\-image-size|\-is
129 .I <image\-size>
130 .IP
131
132 Select the image size (default to 2 GBytes if this option is ommited). Only
133 useful if you need to use a custom script hook (see below).
134
135 .LP
136 .B \-\-automatic-resize|\-ar
137 .IP
138
139 Reduce the image to the minimum HDD size possible. The partition of the
140 image will be first shrinked with resize2fs \-M, then the space it takes will
141 be used to do a 2nd resize2fs adding a bit of extra space for the operating
142 system to write runtime data (see below). Since this option takes a lot of
143 time, it is disabled by default.
144
145 .LP
146 .B \-\-automatic\-resize\-space|\-ars
147 .I <suplementary-space>
148 .IP
149
150 Size of the suplementary space added to the partition after it is resized
151 to the minimum. If this option is ommited, then 50G is used. If
152 .B \-\-automatic-resize
153 isn't used, then it is useless to set this option, which will be ignored.
154
155 .LP
156 .B \-\-login|\-l
157 .I <user-login>
158 .IP
159
160 Change the login name (default to debian) for the user created by Cloud-Init.
161
162 .LP
163 .B \-\-password|\-p
164 .I <root-password>
165 .IP
166
167 Defines a default root password for your image. This option is dangerous,
168 first because it will show the root password to the user of the computer
169 building the image if using "ps", then also because it is best to not set
170 a default root password at all if possible. However, this option is still
171 there, because sometimes, you need to be able to debug your image, and
172 login through the web console of horizon. In a production environment, do
173 not use this option.
174
175 .LP
176 .B \-\-hook\-script|\-hs
177 .I <hook-script>
178 .IP
179
180 If you wish to further customize the generated cloud image, you can use a
181 hook script. When called, build-openstack-debian-image will fill up some
182 BODI_* environment variable for the hook script to use as per below:
183
184 .B BODI_CHROOT_PATH
185 path where the image is mounted
186
187 .B BODI_RELEASE
188 name of the Debian release that is being bootstraped
189
190 .SH EXAMPLE
191 .IP
192
193 .IP
194 Here is an example with the short parameter names:
195
196 .LP
197 .I build\-openstack\-debian\-image \-u http://ftp.fr.debian.org/debian \-s \
198 http://ftp.fr.debian.org/debian \-is 5 \-e libapache2\-mod\-php5 \-hs \
199 ~/customize\-my\-image \-ar \-ars 100
200
201 .IP
202 And the same but with long names for options:
203
204 .LP
205 .I build-openstack-debian-image \-\-debootstrap\-url http://ftp.fr.debian.org/debian \
206 \-\-sources.list\-mirror http://ftp.fr.debian.org/debian \-\-image-size 5 \
207 \-\-extra\-packages libapache2-mod-php5 \-\-hook\-script ~/customize\-my\-image \
208 \-\-automatic-resize \-\-automatic\-resize\-space 100
209
210 .SH AUTHORS
211
212 build\-openstack\-debian\-image has been written by Thomas Goirand
213 <zigo@debian.org>, with contributions from Mehdi Abaakouk
214 <sileht@sileht.net>.