summaryrefslogtreecommitdiff
path: root/README
blob: 2068bc2dab5695de71648bc95c7642c6897c2ba3 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
INDEX
-----

* Boot parameters (initramfs stage)
  * hooks/archiso
  * hooks/archiso_pxe_common
  * hooks/archiso_pxe_nbd
  * hooks/archiso_pxe_http
  * hooks/archiso_pxe_nfs
  * hooks/archiso_loop_mnt
* Boot parameters (only for configs/releng)
  * etc/rc.conf
* Transfer ISO file to target medium (configs/releng)
  * To -> CD / DVD / BD
  * To -> USB-key / SD / HDD / SSD
    * PC-BIOS (MBR)
    * PC-BIOS (ISOHYBRID-MBR)
    * PC-EFI (GPT) [x86_64 only]
* Alternative boot methods (configs/releng)
  * ISO in loopback mode
  * ISO in memdisk mode
  * Network booting (PXE) [first stage]
    * DHCP + TFTP
    * DHCP + HTTP
    * HTTP/NFS/NBD [second stage]
* Build requirements
* Image types generated by mkarchiso.
* File format for aitab.
* Why the /isolinux and /arch/boot/syslinux directories?
* Know issues
* Building the most basic Arch Linux live media. (configs/baseline)
* Building official Arch Linux live media. (configs/releng)



*** Boot parameters (initramfs stage)

** hooks/archiso

* archisolabel=     Set the filesystem label where archiso files reside.
                    Default: (unset)
* archisodevice=    Set the device node where archiso medium is located.
                    Default: "/dev/disk/by-label/${archisolabel}"
* archisobasedir=   Set the base directory where all files reside.
                    Default: "arch"
* aitab=            Set the path for "aitab" file.
                    Default: ${archisobasedir}/aitab
* copytoram=        If set to "y" or just "copytoram" without arguments,
                    all SquashFS are copied to "RAM".
                    Default: (unset)
* checksum=         If set to "y" or just "checksum" without arguments,
                    performs a self-test of all files inside ${install_dir},
                    and continue booting if ok.
                    Default: (unset)
* cow_label=        Set the filesystem label where COW (dm-snapshot)
                    files must be stored.
                    Default: (unset)
* cow_device=       Set the device node where COW (dm-snapshot) files
                    must be stored.
                    Default: (unset) or "/dev/disk/by-label/${cow_label}"
* cow_directory=    Set a directory inside ${cow_device}.
                    Default: "/persistent_${archisolabel}/${arch}"
* cow_persistent=   Set if snapshots are persistent "P" or non-persistent "N".
                    Default: "N" (if no ${cow_device} is used) otherwise "P".
* cowspace_size=    Set the size of tmpfs /cowspace. This space is used for
                    Copy-On-Write files of dm-snapshot.
                    Size is in bytes (suffix with "k", "m" and "g") or
                    in percentage of available RAM.
                    Default: "75%"
* copytoram_size=   Set the size of tmpfs. This space is used for
                    copy of all SquashFS images used, if copytoram=y.
                    Size is in bytes (suffix with "k", "m" and "g") or
                    in percentage of available RAM.
                    Default: "75%"
* dm_snap_prefix=   Set a prefix for device-mapper snapshot node names.
                    Default: "arch"
* arch=             Force an architecture type (i686 | x86_64).
                    Do not set it for normal operations.
                    Useful for running a 64 bit kernel / 32 bit userspace.
                    Default: (architecture of running kernel)


** hooks/archiso_pxe_common

* ip=               This parameter is setup automatically by PXELINUX
                    when option "IPAPPEND" is set to 1 or 2 in config.
                    ip=<client-ip>:<boot-server-ip>:<gw-ip>:<netmask>
                    Default: (set via PXE server)
* BOOTIF=           This parameter is setup automatically by PXELINUX
                    when option "IPAPPEND" is set to 2 or 3 in config.
                    BOOTIF=<hardware-address-of-boot-interface>
                    Default: (set via PXELINUX)
* copy_resolvconf=  Copy /etc/resolv.conf from initramfs to live-enviroment.
                    Set to "n" to skip them.
                    Default: "y"


** hooks/archiso_pxe_nbd

* archiso_nbd_name= Set NBD export name used by the server.
                    Default: archiso
* archiso_nbd_srv=  Set an IP address where NBD reside.
                    If ${pxeserver} is used, PXE IP will be used.
                    Default: (unset)


** hooks/archiso_pxe_http

* archiso_http_srv= Set an HTTP URL (must end with /) where ${archisobasedir}
                    is found with all *.sfs files.
                    In the IP/domain part if ${pxeserver} is used, use PXE IP.
                    Default: (unset)
* archiso_http_spc= Set the size of tmpfs where *.sfs files are downloaded.
                    Default: "75%"


** hooks/archiso_pxe_nfs

* archiso_nfs_srv=  Set the NFS-IP:/path of the server
                    In the IP part if ${pxeserver} is used, PXE IP will be used.
                    Default: (unset)
* archiso_nfs_opt=  Set NFS mount options separated by comma.
                    Default: (unset, see below)
                    These are the implicit options:
                      port            = as given by server portmap daemon
                      rsize           = 1024
                      wsize           = 1024
                      timeo           = 7
                      retrans         = 3
                      acregmin        = 3
                      acregmax        = 60
                      acdirmin        = 30
                      acdirmax        = 60
                      flags           = hard, nointr, noposix, cto, ac


** hooks/archiso_loop_mnt

* img_label=        Set the filesystem label where archiso-image.iso.
                    Default: (unset)
* img_dev=          Device where archiso-image.iso reside.
                    Default: (unset) or "/dev/disk/by-label/${img_label}"
* img_loop=         Full path where archiso-image.iso is located on ${img_dev}
                    Default: (unset)



*** Transfer ISO image to target medium (configs/releng)

ISO images names consist of: archlinux-<YYYY>.<MM>.<DD>-<ARCH>.iso

Where:
    <YYYY> Year
    <MM> Month
    <DD> Day
    <ARCH> i686 | x86_64 | dual(*)

(*) "dual" includes both i686 and x86_64 architectures.


** To -> CD / DVD / BD

Note: All ISO images are booteable on a PC-BIOS via "El Torito" in no-emulation mode,
      All x86_64 ISO images are booteable on a PC-EFI via "El Torito" in no-emulation mode.

Nomeclature:
    <B> scsibus number
    <T> target number
    <L> lun number
    (Note: see cdrecord -scanbus, for these numbers)


1) Write it directly using your favorite recording program.
# cdrecord dev=<B>,<T>,<L> -dao archlinux-<YYYY>.<MM>.<DD>-<ARCH>.iso


** To -> USB Flash Drive (USB-key) / Memory card (SD) /
         Hard-Disk Drive (HDD) / Solid-State Drive (SSD)

Note: These steps are the general workflow, you can skip some of them,
      using another filesystem if your bootloader supports it,
      installing to another directory than "arch/" or using more than
      one partition. Just ensure that main boot params options
      (archisolabel= and archisobasedir=) are set correctly according to your setup.

Nomeclature:
<DEV-TARGET>:   Device node of the drive where ISO contents should be copied
                (example: /dev/sdx)
<DEV-TARGET-N>: Device node of the partition on <DEV-TARGET>
                (example: /dev/sdx1)
<MNT-TARGET-N>: Mount point path where <DEV-TARGET-N> is mounted
                (example: /mnt/sdx/1)
<ISO-SOURCE>:   Path to the ISO file archlinux-<YYYY>.<MM>.<DD>-<ARCH>.iso
                (example: ~/archlinux-2012.07.22-x86_64.iso)
<FS-LABEL>:     Represents the filesystem label of the <ISO-SOURCE>
                (example: ARCH_201207 [for all ~/archlinux-2012.07.*.iso])


* PC-BIOS (MBR):

Note: Using here a MBR partition mode as example, but GPT should also works
      if machine firmware is not broken.
      Just ensure that partition is set with attribute "2: legacy BIOS bootable"
      and use gptmbr.bin instead of mbr.bin for syslinux.

1) Create one partition entry in MBR (of type "b" for FAT32 or "83" for EXTFS)
   and mark it as "active" (bootable).
# fdisk <DEV-TARGET>

2) Create a FAT32 or EXTFS filesystem on such partition and setup a label.
# mkfs.vfat -F 32 -n <FS-LABEL> <DEV-TARGET-N>
# mkfs.ext4 -L <FS-LABEL> <DEV-TARGET-N>

3) Mount target filesystem.
# mount <DEV-TARGET-N> <MNT-TARGET-N>

4) Extract ISO image on target filesystem.
# bsdtar -x --exclude=isolinux/ --exclude=EFI/ -f <ISO-SOURCE> -C <MNT-TARGET-N>

5) Install syslinux bootloader on target filesystem.
# extlinux -i <MNT-TARGET-N>/arch/boot/syslinux

6) Unmount target filesystem.
# umount <MNT-TARGET-N>

7) Install syslinux MBR boot code on target drive.
# dd bs=440 count=1 conv=notrunc if=/usr/lib/syslinux/mbr.bin of=<DEV-TARGET>


* PC-BIOS (ISOHYBRID-MBR):

Note: This method is the most easily, quick and dirty, but is the most limited
      if you want to use your target medium for other purposes.

1) Dump ISO file to target medium.
# dd if=<ISO-SOURCE> of=<DEV-TARGET>


* PC-EFI (GPT) [x86_64 only]

Note: Using here a GPT partition mode as example, but MBR should also works
      if machine firmware is not broken.

1) Create one partition entry in GPT (of type "ef00")
# gdisk <DEV-TARGET>

2) Create a FAT32 filesystem on such partition and setup a label.
# mkfs.vfat -F 32 -n <FS-LABEL> <DEV-TARGET-N>

3) Mount target filesystem.
# mount <DEV-TARGET-N> <MNT-TARGET-N>

4) Extract ISO image on target filesystem.
# bsdtar -x --exclude=isolinux/ --exclude=arch/boot/syslinux/ -f <ISO-SOURCE> -C <MNT-TARGET-N>

5) Extract efiboot.img on EFI/ on target filesystem.
# mcopy -s -i <MNT-TARGET-N>/EFI/archiso/efiboot.img ::/EFI <MNT-TARGET-N>/

6) Remove uneeded efiboot.img
# rm <MNT-TARGET-N>/EFI/archiso/efiboot.img

7) Unmount target filesystem.
# umount <MNT-TARGET-N>



*** Alternative boot methods (configs/releng)

** ISO in loopback mode.

Note: Described method is for using with GRUB2.
      GRUB2 is installed on target media and archlinux-<YYYY>.<MM>.<DD>-<ARCH>.iso
      is at path <TARGET-PATH> on disk <D> and partition <P>,
      where filesystem is labeled as <TARGET-FS-LABEL>.

menuentry "Arch Linux (x86_64)" {
    set isofile="/<TARGET-PATH>/archlinux-<YYYY>.<MM>.<DD>-<ARCH>.iso"
    loopback loop (hd<D>,<P>)$isofile
    linux (loop)/arch/boot/x86_64/vmlinuz archisolabel=<FS-LABEL> img_label=<TARGET-FS-LABEL> img_loop=$isofile
    initrd (loop)/arch/boot/x86_64/archiso.img
}

menuentry "Arch Linux (i686)" {
    set isofile="/<TARGET-PATH>/archlinux-<YYYY>.<MM>.<DD>-<ARCH>.iso"
    loopback loop (hd<D>,<P>)$isofile
    linux (loop)/arch/boot/i686/vmlinuz archisolabel=<FS-LABEL> img_label=<TARGET-FS-LABEL> img_loop=$isofile
    initrd (loop)/arch/boot/i686/archiso.img
}


** ISO in memdisk mode.

Note: Described method is for using with SYSLINUX. Anyway MEMDISK from SYSLINUX can work
      with other bootloaders.
      SYSLINUX is installed on target media and archlinux-<YYYY>.<MM>.<DD>-<ARCH>.iso
      is at path <TARGET-PATH>.
      On 32-bit systems, is needed to pass vmalloc=nnM to the kernel, where nn is the size
      of the ISO image plus 64 MiB (or 128 MiB).


LABEL arch_x64
   LINUX memdisk
   INITRD /<TARGET-PATH>/archlinux-<YYYY>.<MM>.<DD>-<ARCH>.iso
   APPEND iso

LABEL arch_x32
   LINUX memdisk
   INITRD /<TARGET-PATH>/archlinux-<YYYY>.<MM>.<DD>-<ARCH>.iso
   APPEND iso


** Network booting (PXE).

All ISOs are ready to act as PXE server, some manual steps are needed
to setup the desired PXE boot mode.
Alternatively it is possible to use an existing PXE server following the same logic.
Note: Setup network first, adjust IP adresses, and respect all slashes "/".

First stage is for loading kernel and initramfs via PXE, two methods described here:

* DHCP + TFTP

Note: All NIC firmwares should support this.

# dnsmasq --port=0 \
          --enable-tftp \
          --tftp-root=/run/archiso/bootmnt \
          --dhcp-range=192.168.0.2,192.168.0.254,86400 \
          --dhcp-boot=/arch/boot/syslinux/gpxelinux.0 \
          --dhcp-option-force=209,boot/syslinux/archiso.cfg \
          --dhcp-option-force=210,/arch/

* DHCP + HTTP

Note: Not all NIC firmware supports HTTP and DNS (if domain name is used).
      At least this works with iPXE and gPXE.

# dnsmasq --port=0 \
          --dhcp-range=192.168.0.2,192.168.0.254,86400 \
          --dhcp-boot=http://192.168.0.7/arch/boot/syslinux/gpxelinux.0 \
          --dhcp-option-force=209,boot/syslinux/archiso.cfg \
          --dhcp-option-force=210,http://192.168.0.7/arch/


Once the kernel is started from PXE, SquashFS files and other misc files
inside "arch" directory must be loaded (second stage). One of the following
methods can be used to serve the rest of live-medium.

* HTTP

# darkhttpd /run/archiso/bootmnt


* NFS

# echo "/run/archiso/bootmnt 192.168.0.*(ro,no_subtree_check,no_root_squash)" >> /etc/exports
# rc.d start rpcbind nfs-common nfs-server


* NBD

Note: Adjust ARCH_201207 as needed.

# cat << EOF > /tmp/nbd-server.conf
[generic]
[archiso]
    readonly = true
    exportname = /dev/disk/by-label/ARCH_201207
EOF
# nbd-server -C /tmp/nbd-server.conf



*** Build requirements

** For mkarchiso script needs these packages (build host):
 + squashfs-tools          for mksquashfs
 + libisoburn              for xorriso
 + btrfs-progs             for mkfs.btrfs (optional)

** For configs/releng build.sh needs theses packages (build host):
 + dosfstools              for mkfs.vfat
 + patch                   for patch
 + lynx                    for fetching the latest installation guide

** For these hooks needs these packages (on target root-image)
* archiso
 + (none)
* archiso_loop_mnt
 + (none)
* archiso_pxe_common
 + mkinitcpio-nfs-utils    for ipconfig
* archiso_pxe_nbd
 + nbd                     for nbd-client
* archiso_pxe_http
 + curl                    for curl
* archiso_pxe_nfs
 + mkinitcpio-nfs-utils    for nfsmount
* archiso_shutdown
 + (none)


*** Image types generated by mkarchiso.

* image-name.sfs     SquashFS image with all files directly on it.
* image-name.fs.sfs  SquashFS with only one file inside (image-name.fs),
                     which is an image of some type of filesystem
                     (ext4, ext3, ext2, xfs), all files reside on it.


*** File format for aitab.

The aitab file holds information about the filesystems images that must be
created by mkarchiso and mounted at initramfs stage from the archiso hook.
It consists of some fields which define the behaviour of images.

# <img>         <mnt>                 <arch>   <sfs_comp>  <fs_type>  <fs_size>

<img>      Image name without extension (.fs .fs.sfs .sfs).
<mnt>      Mount point.
<arch>     Architecture { i686 | x86_64 | any }.
<sfs_comp> SquashFS compression type { gzip | lzo | xz }.
<fs_type>  Set the filesystem type of the image
           { ext4 | ext3 | ext2 | xfs | btrfs }.
           A special value of "none" denotes no usage of a filesystem.
           In that case all files are pushed directly to SquashFS filesystem.
<fs_size>  An absolute value of file system image size in MiB.
           (example: 100, 1000, 4096, etc)
           A relative value of file system free space [in percent].
           {1%..99%} (example 50%, 10%, 7%).
           This is an estimation, and calculated in a simple way.
           Space used + 10% (estimated for metadata overhead) + desired %


*** Why the /isolinux and /arch/boot/syslinux directories?

The /isolinux directory holds files needed for the ISOLINUX boot loader
module of SYSLINUX. ISOLINUX can not find config files on
/arch/boot/syslinux, like other boot loaders modules (EXTLINUX, SYSLINUX, etc).
When make your custom boot-pendrive, you need to copy /arch directory to it.
/isolinux/isolinux.cfg just holds /arch/boot/syslinux/syslinux.cfg


*** Know issues

** On shutdown there are two steps that [FAIL]:
   "Unmounting Swap-backed Filesystems" and "Unmounting Non-API Filesystems",
    These filesystem are in use at this stage by archiso, but...
    This is not a real issue since, all mounted filesystem, loopback devices
    and device mapper devices made by archiso will be "free" on "shutdown tmpfs"
    (A.K.A deinitramfs), build at initramfs by [archiso_shutdown] initcpio hook.


*** Building the most basic Arch Linux live media. (configs/baseline)

* Install needed packages.
  # pacman -S git make squashfs-tools libisoburn rsync --needed

* Install archiso.
  # git clone git://projects.archlinux.org/archiso.git
  # make -C archiso install

* Build a basic iso.
  # /usr/share/archiso/configs/baseline/build.sh

Note: If you want to customize, just see the configs/releng directory which is
used to build official images with much more things.


*** Building official Arch Linux live media. (configs/releng)

* Install needed packages.
  # pacman -S git make squashfs-tools libisoburn dosfstools lynx patch --needed

* Install archiso.
  # git clone git://projects.archlinux.org/archiso.git
  # make -C archiso install

* Build them!
  # /usr/share/archiso/configs/releng/build.sh build all

Note: See build.sh -h for more options.