1LIVEMEDIA-CREATOR(1)                 Lorax                LIVEMEDIA-CREATOR(1)
2
3
4

NAME

6       livemedia-creator - Live Media Creator Documentation
7
8       Authors
9              Brian C. Lane <bcl@redhat.com>
10
11       livemedia-creator uses Anaconda, kickstart and Lorax to create bootable
12       media that use the same install path as a normal  system  installation.
13       It  can  be used to make live isos, bootable (partitioned) disk images,
14       tarfiles, and filesystem images for use with  virtualization  and  con‐
15       tainer solutions like libvirt, docker, and OpenStack.
16
17       The general idea is to use qemu with kickstart and an Anaconda boot.iso
18       to install into a disk image and then use the disk image to create  the
19       bootable media.
20
21       livemedia-creator --help will describe all of the options available. At
22       the minimum you need:
23
24       --make-iso to create a final bootable .iso or one of the other --make-*
25       options.
26
27       --iso to specify the Anaconda install media to use with qemu.
28
29       --ks to select the kickstart file describing what to install.
30
31       To use livemedia-creator with virtualization you will need to have qemu
32       installed.
33
34       If you are going to be using Anaconda directly,  with  --no-virt  mode,
35       make sure you have the anaconda-tui package installed.
36
37       Conventions used in this document:
38
39       lmc is an abbreviation for livemedia-creator.
40
41       builder is the system where livemedia-creator is being run
42
43       image is the disk image being created by running livemedia-creator
44

LIVEMEDIA-CREATOR CMDLINE ARGUMENTS

46       Create Live Install Media
47
48
49          usage: livemedia-creator [-h] (--make-iso | --make-disk | --make-fsimage | --make-appliance | --make-ami | --make-tar | --make-tar-disk | --make-pxe-live | --make-ostree-live | --make-oci | --make-vagrant)
50                                   [--iso ISO] [--iso-only] [--iso-name ISO_NAME] [--ks KS] [--image-only] [--no-virt] [--proxy PROXY] [--anaconda-arg ANACONDA_ARGS] [--armplatform ARMPLATFORM] [--location LOCATION]
51                                   [--logfile LOGFILE] [--lorax-templates LORAX_TEMPLATES] [--tmp TMP] [--resultdir RESULT_DIR] [--macboot] [--nomacboot] [--extra-boot-args EXTRA_BOOT_ARGS] [-r RELEASE] [-t VARIANT]
52                                   [-b URL] [--isfinal] [--disk-image DISK_IMAGE] [--keep-image] [--fs-image FS_IMAGE] [--image-name IMAGE_NAME] [--tar-disk-name TAR_DISK_NAME] [--fs-label FS_LABEL]
53                                   [--image-size-align IMAGE_SIZE_ALIGN] [--image-type IMAGE_TYPE] [--qemu-arg QEMU_ARGS] [--qcow2] [--qcow2-arg QEMU_ARGS] [--compression COMPRESSION] [--compress-arg COMPRESS_ARGS]
54                                   [--app-name APP_NAME] [--app-template APP_TEMPLATE] [--app-file APP_FILE] [--ram MEMORY] [--vcpus VCPUS] [--vnc VNC] [--arch ARCH] [--kernel-args KERNEL_ARGS] [--ovmf-path OVMF_PATH]
55                                   [--virt-uefi] [--no-kvm] [--with-rng WITH_RNG] [--dracut-conf DRACUT_CONF] [--dracut-arg DRACUT_ARGS] [--live-rootfs-size LIVE_ROOTFS_SIZE] [--live-rootfs-keep-size]
56                                   [--oci-config OCI_CONFIG] [--oci-runtime OCI_RUNTIME] [--vagrant-metadata VAGRANT_METADATA] [--vagrantfile VAGRANTFILE] [--project PRODUCT] [-p PRODUCT] [--releasever RELEASEVER]
57                                   [--volid VOLID] [--squashfs-only] [--timeout TIMEOUT] [-V]
58
59   Named Arguments
60       --make-iso
61              Build a live iso
62
63              Default: False
64
65       --make-disk
66              Build a partitioned disk image
67
68              Default: False
69
70       --make-fsimage
71              Build a filesystem image
72
73              Default: False
74
75       --make-appliance
76              Build an appliance image and XML description
77
78              Default: False
79
80       --make-ami
81              Build an ami image
82
83              Default: False
84
85       --make-tar
86              Build a tar of the root filesystem
87
88              Default: False
89
90       --make-tar-disk
91              Build a tar of a partitioned disk image
92
93              Default: False
94
95       --make-pxe-live
96              Build a live pxe boot squashfs image
97
98              Default: False
99
100       --make-ostree-live
101              Build a live pxe boot squashfs image of Atomic Host
102
103              Default: False
104
105       --make-oci
106              Build an Open Container Initiative image
107
108              Default: False
109
110       --make-vagrant
111              Build a Vagrant Box image
112
113              Default: False
114
115       --iso  Anaconda installation .iso path to use for qemu
116
117       --iso-only
118              Remove  all  iso creation artifacts except the boot.iso, combine
119              with --iso-name to rename the boot.iso
120
121              Default: False
122
123       --iso-name
124              Name of output iso file for --iso-only. Default is boot.iso
125
126       --ks   Kickstart file defining the install.
127
128       --image-only
129              Exit after creating fs/disk image.
130
131              Default: False
132
133       --no-virt
134              Run anaconda directly on host instead of using qemu
135
136              Default: False
137
138       --proxy
139              proxy URL to use for the install
140
141       --anaconda-arg
142              Additional argument to pass to  anaconda  (no-virt  mode).  Pass
143              once for each argument
144
145       --armplatform
146              the  platform  to  use when creating images for ARM, i.e., high‐
147              bank, mvebu, omap, tegra, etc.
148
149       --location
150              location of iso directory tree with initrd.img and vmlinuz. Used
151              to run qemu with a newer initrd than the iso.
152
153       --logfile
154              Name and path for primary logfile, other logs will be created in
155              the same directory.
156
157              Default: ./livemedia.log
158
159       --lorax-templates
160              Path to mako templates for lorax
161
162       --tmp  Top level temporary directory
163
164              Default: /var/tmp
165
166       --resultdir
167              Directory to copy the resulting images and iso into. Defaults to
168              the temporary working directory
169
170       --macboot
171              Make the iso bootable on UEFI based Mac systems
172
173              Default: True
174
175       --nomacboot
176              Do not create a Mac bootable iso
177
178              Default: False
179
180       --extra-boot-args
181              Extra  arguments  to add to the bootloader kernel cmdline in the
182              templates
183
184              Default: ""
185
186       -r, --release
187              release information
188
189              Default: ""
190
191       -t, --variant
192              variant name
193
194              Default: ""
195
196       -b, --bugurl
197              bug reporting URL for the product
198
199              Default: "your distribution provided bug reporting tool"
200
201       --isfinal
202              Default: False
203
204       --project
205              substituted for @PRODUCT@ in bootloader config files
206
207              Default: "Linux"
208
209       -p, --product
210              Alias for --project
211
212              Default: ""
213
214       --releasever
215              substituted for @VERSION@ in bootloader config files
216
217              Default: "38"
218
219       --volid
220              volume id
221
222       --squashfs-only
223              Use a plain squashfs filesystem for the runtime.
224
225              Default: False
226
227       --timeout
228              Cancel installer after X minutes
229
230       -V     show program's version number and exit
231
232   disk/fs image arguments
233       --disk-image
234              Path to existing disk image to use for creating final image.
235
236       --keep-image
237              Keep raw disk image after .iso creation
238
239              Default: False
240
241       --fs-image
242              Path to existing filesystem image to use for creating final  im‐
243              age.
244
245       --image-name
246              Name  of output file to create. Used for tar, fs and disk image.
247              Default is a random name.
248
249       --tar-disk-name
250              Name of the archive member for make-tar-disk.
251
252       --fs-label
253              Label to set on fsimage, default is 'Anaconda'
254
255              Default: "Anaconda"
256
257       --image-size-align
258              Create a disk image with a size that is a multiple of this value
259              in MiB.
260
261              Default: 0
262
263       --image-type
264              Create an image with qemu-img. See qemu-img --help for supported
265              formats.
266
267       --qemu-arg
268              Arguments to pass to qemu-img. Pass once for each argument, they
269              will be used for ALL calls to qemu-img.
270
271              Default: []
272
273       --qcow2
274              Create  qcow2 image instead of raw sparse image when making disk
275              images.
276
277              Default: False
278
279       --qcow2-arg
280              Arguments to pass to qemu-img. Pass once for each argument, they
281              will be used for ALL calls to qemu-img.
282
283              Default: []
284
285       --compression
286              Compression  binary  for make-tar. xz, lzma, gzip, and bzip2 are
287              supported. xz is the default.
288
289              Default: "xz"
290
291       --compress-arg
292              Arguments to pass to compression. Pass once for each argument
293
294              Default: []
295
296   appliance arguments
297       --app-name
298              Name of appliance to pass to template
299
300       --app-template
301              Path to template to use for appliance data.
302
303       --app-file
304              Appliance template results file.
305
306              Default: "appliance.xml"
307
308   qemu arguments
309       --ram  Memory to allocate for installer in megabytes.
310
311              Default: 2048
312
313       --vcpus
314              Passed to qemu -smp command
315
316       --vnc  Passed to qemu -display command. eg. vnc=127.0.0.1:5, default is
317              to choose the first unused vnc port.
318
319       --arch System  arch to build for. Used to select qemu-system-* command.
320              Defaults to qemu-system-<arch>
321
322       --kernel-args
323              Additional argument to pass to the installation kernel
324
325       --ovmf-path
326              Path to OVMF firmware
327
328              Default: "/usr/share/edk2/ovmf/"
329
330       --virt-uefi
331              Use OVMF firmware to boot the VM in UEFI mode
332
333              Default: False
334
335       --no-kvm
336              Skip using kvm with qemu even if it is available.
337
338              Default: False
339
340       --with-rng
341              RNG device for QEMU (none for no RNG)
342
343              Default: "/dev/random"
344
345   dracut arguments: (default: )
346       --dracut-conf
347              Path to a dracut.conf file to use instead of the  default  argu‐
348              ments. See the dracut.conf(5) manpage.
349
350       --dracut-arg
351              Argument  to  pass to dracut when rebuilding the initramfs. Pass
352              this once for each argument. NOTE: this overrides the defaults.
353
354   pxe to live arguments
355       --live-rootfs-size
356              Size of root filesystem of live image in GiB
357
358              Default: 0
359
360       --live-rootfs-keep-size
361              Keep the original size of root filesystem in live image
362
363              Default: False
364
365   OCI arguments
366       --oci-config
367              config.json OCI configuration file
368
369       --oci-runtime
370              runtime.json OCI configuration file
371
372   Vagrant arguments
373       --vagrant-metadata
374              optional metadata.json file
375
376       --vagrantfile
377              optional vagrantfile
378

QUICKSTART

380       Run this to create a bootable live iso:
381
382          sudo livemedia-creator --make-iso \
383          --iso=/extra/iso/boot.iso --ks=./docs/fedora-livemedia.ks
384
385       You can run it directly from the lorax git repo like this:
386
387          sudo PATH=./src/sbin/:$PATH PYTHONPATH=./src/ ./src/sbin/livemedia-creator \
388          --make-iso --iso=/extra/iso/boot.iso \
389          --ks=./docs/fedora-livemedia.ks --lorax-templates=./share/
390
391       You can observe the installation using vnc. The  logs  will  show  what
392       port  was  chosen,  or  you  can use a specific port by passing it. eg.
393       --vnc vnc:127.0.0.1:5
394
395       This is usually a good idea when testing changes to the kickstart.  lmc
396       tries  to  monitor  the logs for fatal errors, but may not catch every‐
397       thing.
398

HOW ISO CREATION WORKS

400       There are 2 stages, the install stage which produces a disk or filesys‐
401       tem image as its output, and the boot media creation which uses the im‐
402       age as its input.  Normally you would run both stages, but it is possi‐
403       ble  to stop after the install stage, by using --image-only, or to skip
404       the install stage and use a previously created disk  image  by  passing
405       --disk-image or --fs-image
406
407       When creating an iso qemu boots using the passed Anaconda installer iso
408       and installs the system based on the kickstart. The  %post  section  of
409       the kickstart is used to customize the installed system in the same way
410       that current spin-kickstarts do.
411
412       livemedia-creator monitors the install process for problems by watching
413       the  install  logs. They are written to the current directory or to the
414       base directory specified by the --logfile command. You can also monitor
415       the install by using a vnc client. This is recommended when first modi‐
416       fying a kickstart, since there are still places where Anaconda may  get
417       stuck without the log monitor catching it.
418
419       The output from this process is a partitioned disk image. kpartx can be
420       used to mount and examine it when there is a problem with the  install.
421       It can also be booted using kvm.
422
423       When creating an iso the disk image's / partition is copied into a for‐
424       matted filesystem image which is then used as the input  to  lorax  for
425       creation of the final media.
426
427       The   final   image  is  created  by  lorax,  using  the  templates  in
428       /usr/share/lorax/live/ or the live directory below the directory speci‐
429       fied  by  --lorax-templates.  The  templates are written using the Mako
430       template system with some extra commands added by lorax.
431
432       NOTE:
433          The output from --make-iso includes the artifacts used to create the
434          boot.iso;  the  kernel, initrd, the squashfs filesystem, etc. If you
435          only want the boot.iso you can pass --iso-only and the  other  files
436          will  be  removed.  You  can  also  name the iso by using --iso-name
437          my-live.iso.
438

KICKSTARTS

440       The docs/ directory includes several example kickstarts, one to  create
441       a  live  desktop  iso using GNOME, and another to create a minimal disk
442       image. When creating your own kickstarts you should start with the min‐
443       imal  example,  it includes several needed packages that are not always
444       included by dependencies.
445
446       Or you can use existing spin kickstarts to create live media with a few
447       changes. Here are the steps I used to convert the Fedora XFCE spin.
448
449       1.  Flatten the xfce kickstart using ksflatten
450
451       2.  Add zerombr so you don't get the disk init dialog
452
453       3.  Add clearpart --all
454
455       4.  Add swap partition
456
457       5.  bootloader target
458
459       6.  Add shutdown to the kickstart
460
461       7.  Add  network  --bootproto=dhcp  --activate  to activate the network
462           This works for F16 builds but for F15 and before you need  to  pass
463           something on the cmdline that activate the network, like sshd:
464              livemedia-creator --kernel-args="sshd"
465
466       8.  Add a root password:
467
468              rootpw rootme
469              network --bootproto=dhcp --activate
470              zerombr
471              clearpart --all
472              bootloader --location=mbr
473              part swap --size=512
474              shutdown
475
476       9.  In  the  livesys  script section of the %post remove the root pass‐
477           word. This really depends on how the spin wants to work. You  could
478           add  the live user that you create to the %wheel group so that sudo
479           works if you wanted to.
480              passwd -d root > /dev/null
481
482       10. Remove /etc/fstab in %post, dracut handles mounting the rootfs
483
484           cat /dev/null > /dev/fstab
485
486           Do this only for live iso's, the filesystem will  be  mounted  read
487           only if there is no /etc/fstab
488
489       11. Don't delete initramfs files from /boot in %post
490
491       12. When creating live iso's you need to have, at least, these packages
492           in the %package section:: dracut-config-generic  dracut-live  -dra‐
493           cut-config-rescue grub2-efi syslinux
494
495   User created repositories
496       If  you  are  using  your  own  repositories and installing groups (eg.
497       @core) make sure you create the repodata with  groups  like  this  cre‐
498       aterepo -g /path/to/groups.xml /path/to/rpms
499
500   Using a Proxy with repos
501       One  drawback to using qemu is that it pulls the packages from the repo
502       each time you run it. To speed things up you either need a local mirror
503       of the packages, or you can use a caching proxy. When using a proxy you
504       pass it to livemedia-creator like this:
505          --proxy=http://proxy.yourdomain.com:3128
506
507       You also need to use a specific mirror instead of mirrormanager so that
508       the packages will get cached, so your kickstart url would look like:
509          url     --url="http://dl.fedoraproject.org/pub/fedora/linux/develop
510          ment/rawhide/x86_64/os/"
511
512       You can also add an update repo, but don't name it updates. Add --proxy
513       to  it as well. You can use all of the kickstart commands in your kick‐
514       start. Make sure there is only one url command, other repos have to use
515       the repo command and cannot be named updates which is reserved for Ana‐
516       conda's use. eg.:
517
518          url --url=PRIMARY-REPO-URL --proxy=PROXY-URL
519          repo --name="repo1" --baseurl=FIRST-REPO-URL --proxy=PROXY-URL
520          repo --name="repo2" --baseurl=SECOND-REPO_URL --proxy=PROXY-URL
521

ANACONDA IMAGE INSTALL (NO-VIRT)

523       You can create images without using qemu by passing  --no-virt  on  the
524       cmdline.  This  will use Anaconda's directory install feature to handle
525       the install.  There are a couple of things to keep in mind  when  doing
526       this:
527
528       1. It  will  be most reliable when building images for the same release
529          that the host is running. Because Anaconda  has  expectations  about
530          the system it is running under you may encounter strange bugs if you
531          try to build newer or older releases.
532
533       2. It may totally trash your host. So far I haven't  had  this  happen,
534          but the possibility exists that a bug in Anaconda could result in it
535          operating on real devices. I recommend running it in a virt or on  a
536          system that you can afford to lose all data from.
537
538       The  logs  from  anaconda will be placed in an ./anaconda/ directory in
539       either the current directory or in the directory used for --logfile
540
541       Example cmdline:
542
543       sudo livemedia-creator --make-iso --no-virt --ks=./fedora-livemedia.ks
544
545       NOTE:
546          Using no-virt to create a partitioned disk image (eg. --make-disk or
547          --make-vagrant)  will  only create disks usable on the host platform
548          (BIOS or UEFI). You can create BIOS partitioned disk images on  UEFI
549          by using virt.
550
551       NOTE:
552          As  of  version  30.7  SELinux  can be set to Enforcing. The current
553          state is logged for debugging purposes and if there are SELinux  de‐
554          nials they should be reported as a bug.
555

AMI IMAGES

557       Amazon  EC2 images can be created by using the --make-ami switch and an
558       appropriate kickstart file. All of the work to customize the  image  is
559       handled  by the kickstart.  The example currently included was modified
560       from the cloud-kickstarts version so that it would  work  with  liveme‐
561       dia-creator.
562
563       Example cmdline:
564
565       sudo      livemedia-creator      --make-ami     --iso=/path/to/boot.iso
566       --ks=./docs/fedora-livemedia-ec2.ks
567
568       This will produce an ami-root.img file in the working directory.
569
570       At this time I have not tested the image with EC2.  Feedback  would  be
571       welcome.
572

APPLIANCE CREATION

574       livemedia-creator   can   now  replace  appliance-tools  by  using  the
575       --make-appliance switch. This will create the  partitioned  disk  image
576       and  an  XML  file  that can be used with virt-image to setup a virtual
577       system.
578
579       The XML is generated using the Mako template from  /usr/share/lorax/ap‐
580       pliance/libvirt.xml  You  can  use  a  different  template  by  passing
581       --app-template <template path>
582
583       Documentation on the Mako template system can be found at the Mako site
584
585       The name of the final output XML is appliance.xml, this can be  changed
586       with --app-file <file path>
587
588       The following variables are passed to the template:
589
590          disks  A list of disk_info about each disk.  Each entry has the fol‐
591                 lowing attributes:
592                     name base name of the disk image file
593
594                     format "raw"
595
596                     checksum_type "sha256"
597
598                     checksum sha256 checksum of the disk image
599
600          name Name of appliance, from --app-name argument
601
602          arch Architecture
603
604          memory Memory in KB (from --ram)
605
606          vcpus from --vcpus
607
608          networks list of networks from the kickstart or []
609
610          project from --project
611
612          releasever from --releasever
613
614       The created image can be imported into libvirt using:
615          virt-image appliance.xml
616
617       You can also create qcow2 appliance  images  using  --image-type=qcow2,
618       for example:
619
620          sudo livemedia-creator --make-appliance --iso=/path/to/boot.iso --ks=./docs/fedora-minimal.ks \
621          --image-type=qcow2 --app-file=minimal-test.xml --image-name=minimal-test.img
622

FILESYSTEM IMAGE CREATION

624       livemedia-creator can be used to create un-partitined filesystem images
625       using the --make-fsimage option. As of version  21.8  this  works  with
626       both qemu and no-virt modes of operation. Previously it was only avail‐
627       able with no-virt.
628
629       Kickstarts should have a single / partition with no extra mountpoints.
630          livemedia-creator       --make-fsimage       --iso=/path/to/boot.iso
631          --ks=./docs/fedora-minimal.ks
632
633       You  can name the output image with --image-name and set a label on the
634       filesystem with --fs-label
635

TAR FILE CREATION

637       The --make-tar command can be used to create a tar of the root filesys‐
638       tem.  By default it is compressed using xz, but this can be changed us‐
639       ing the --compression and --compress-arg  options.  This  option  works
640       with both virt and no-virt install methods.
641
642       As  with  --make-fsimage  the kickstart should be limited to a single /
643       partition.
644
645       For example:
646
647          livemedia-creator --make-tar --iso=/path/to/boot.iso --ks=./docs/fedora-minimal.ks \
648          --image-name=fedora-root.tar.xz
649

LIVE IMAGE FOR PXE BOOT

651       The --make-pxe-live command will produce squashfs image containing live
652       root  filesystem  that can be used for pxe boot. Directory with results
653       will contain the live image, kernel image, initrd image and template of
654       pxe configuration for the images.
655

ATOMIC LIVE IMAGE FOR PXE BOOT

657       The   --make-ostree-live  command  will  produce  the  same  result  as
658       --make-pxe-live for installations of Atomic  Host.   Example  kickstart
659       for such an installation using Atomic installer iso with local repo in‐
660       cluded in the image can be found in docs/rhel-atomic-pxe-live.ks.
661
662       The PXE images can also be created with --no-virt by using the  example
663       kickstart in docs/fedora-atomic-pxe-live-novirt.ks. This also works in‐
664       side the mock environment.
665

USING MOCK AND --NO-VIRT TO CREATE IMAGES

667       As of lorax version 22.2 you can  use  livemedia-creator  and  anaconda
668       version  22.15 inside of a mock chroot with --make-iso and --make-fsim‐
669       age.
670
671       NOTE:
672          As of mock version 2.0 you no longer need to pass --old-chroot.  You
673          will,  however,  need to pass --enable-network so that the mock con‐
674          tainer can download packages.
675
676          Older versions of mock, between 1.3.4 and 2.0,  will  need  to  pass
677          --old-chroot  with mock. These versions of mock now default to using
678          systemd-nspawn which cannot create the  needed  loop  device  nodes.
679          Passing  --old-chroot  will  use  the old system where /dev/loop* is
680          setup for you.
681
682          SELinux and mock do not work well together. Inside mock  SELinux  is
683          reported  as  disabled so the images produced will not have the cor‐
684          rect SELinux labels. If this is important  you  should  run  liveme‐
685          dia-creator on the host, or in a VM.
686
687       On the host system:
688
689       1. yum install -y mock
690
691       2. Add a user to the mock group to use for running mock. eg. builder
692
693       3. Create  a  new  /etc/mock/  config file based on the rawhide one, or
694          modify the existing one so that the following options are setup:
695
696             config_opts['chroot_setup_cmd'] = 'install @buildsys-build anaconda-tui lorax'
697
698             # build results go into /home/builder/results/
699             config_opts['plugin_conf']['bind_mount_opts']['dirs'].append(('/home/builder/results','/results/'))
700
701          If you are creating images for a  branched  release  of  Fedora  you
702          should  also  enable  the updates-testing repository so that you get
703          the latest builds in your mock chroot.
704
705       The following steps are run as the builder user who is a member of  the
706       mock group.
707
708       4. Make  a  directory  for  results matching the bind mount above mkdir
709          ~/results/
710
711       5. Copy the example kickstarts cp /usr/share/docs/lorax/*ks .
712
713       6. Make sure tar and dracut-network are in the  %packages  section  and
714          that the url points to the correct repo
715
716       7. Init the mock mock -r fedora-rawhide-x86_64 --init
717
718       8. Copy  the  kickstart  inside  the mock mock -r fedora-rawhide-x86_64
719          --copyin ./fedora-minimal.ks /root/
720
721       9. Make a minimal iso:
722
723             mock -r fedora-rawhide-x86_64 --enable-network --chroot -- livemedia-creator --no-virt \
724             --resultdir=/results/try-1 --logfile=/results/logs/try-1/try-1.log \
725             --make-iso --ks /root/fedora-minimal.ks
726
727       Results will be in ./results/try-1 and logs under  /results/logs/try-1/
728       including anaconda logs and livemedia-creator logs. The new iso will be
729       located at ~/results/try-1/images/boot.iso,  and  the  ~/results/try-1/
730       directory tree will also contain the vmlinuz, initrd, etc.
731

USING MOCK AND QEMU TO CREATE IMAGES

733       Version  25.0  of livemedia-creator switches to using qemu for virtual‐
734       ization.  This allows creation of all image types, and use of  the  KVM
735       on the host if /dev/kvm is present in the mock environment.
736
737       On the host system:
738
739       1. yum install -y mock
740
741       2. Add a user to the mock group to use for running mock. eg. builder
742
743       3. Create  a  new  /etc/mock/  config file based on the rawhide one, or
744          modify the existing one so that the following options are setup:
745
746             config_opts['chroot_setup_cmd'] = 'install @buildsys-build lorax qemu'
747
748             # build results go into /home/builder/results/
749             config_opts['plugin_conf']['bind_mount_opts']['dirs'].append(('/home/builder/results','/results/'))
750
751          If you are creating images for a  branched  release  of  Fedora  you
752          should  also  enable  the updates-testing repository so that you get
753          the latest builds in your mock chroot.
754
755       The following steps are run as the builder user who is a member of  the
756       mock group.
757
758       4. Make  a  directory  for  results matching the bind mount above mkdir
759          ~/results/
760
761       5. Copy the example kickstarts cp /usr/share/docs/lorax/*ks .
762
763       6. Make sure tar and dracut-network are in the  %packages  section  and
764          that the url points to the correct repo
765
766       7. Init the mock mock -r fedora-rawhide-x86_64 --init
767
768       8. Copy  the  kickstart  inside  the mock mock -r fedora-rawhide-x86_64
769          --copyin ./fedora-minimal.ks /root/
770
771       9. Copy  the  Anaconda  boot.iso  inside   the   mock   mock   -r   fe‐
772          dora-rawhide-x86_64 --copyin ./boot.iso /root/
773
774       10.
775          Make a minimal iso:
776
777             mock -r fedora-rawhide-x86_64 --enable-network --chroot -- livemedia-creator \
778             --resultdir=/results/try-1 --logfile=/results/logs/try-1/try-1.log \
779             --make-iso --ks /root/fedora-minimal.ks --iso /root/boot.iso
780
781       Results  will be in ./results/try-1 and logs under /results/logs/try-1/
782       including anaconda logs and livemedia-creator logs. The new iso will be
783       located  at  ~/results/try-1/images/boot.iso,  and the ~/results/try-1/
784       directory tree will also contain the vmlinuz, initrd, etc.
785
786       This will run qemu without kvm support, which is going to be very slow.
787       You  can  add mknod /dev/kvm c 10 232; to create the device node before
788       running lmc.
789

OPENSTACK IMAGE CREATION

791       OpenStack supports partitioned disk images so --make-disk can  be  used
792       to  create  images for importing into glance, OpenStack's image storage
793       component.  You need to have access to an OpenStack provider  that  al‐
794       lows  image  uploads, or setup your own using the instructions from the
795       RDO Project.
796
797       The example kickstart, fedora-openstack.ks, is only slightly  different
798       than   the   fedora-minimal.ks   one.    It  adds  the  cloud-init  and
799       cloud-utils-growpart packages. OpenStack supports setting up the  image
800       using  cloud-init,  and cloud-utils-growpart will grow the image to fit
801       the instance's disk size.
802
803       Create a qcow2 image using the kickstart like this:
804          sudo    livemedia-creator    --make-disk     --iso=/path/to/boot.iso
805          --ks=/path/to/fedora-openstack.ks --image-type=qcow2
806
807       NOTE:
808          On  the  RHEL7  version of lmc --image-type isn't supported. You can
809          only create a bare partitioned disk image.
810
811       Import the resulting disk image into the OpenStack system,  either  via
812       the web UI, or glance on the cmdline:
813
814          glance image-create --name "fedora-openstack" --is-public true --disk-format qcow2 \
815          --container-format bare --file ./fedora-openstack.qcow2
816
817       If qcow2 wasn't used then --disk-format should be set to raw.
818

DOCKER IMAGE CREATION

820       Use  lmc to create a tarfile as described in the TAR File Creation sec‐
821       tion, but substitute the fedora-docker.ks example kickstart  which  re‐
822       moves the requirement for core files and the kernel.
823
824       You can then import the tarfile into docker like this (as root):
825          cat /var/tmp/fedora-root.tar.xz | docker import - fedora-root
826
827       And then run bash inside of it:
828          sudo docker run -i -t fedora-root /bin/bash
829

OPEN CONTAINER INITIATIVE IMAGE CREATION

831       The  OCI  is a new specification that is still being worked on. You can
832       read more about it at the Open Container Initiative  website.  You  can
833       create OCI images using the following command:
834
835          sudo livemedia-creator --make-oci --oci-config /path/to/config.json --oci-runtime /path/to/runtime.json \
836          --iso=/path/to/boot.iso --ks=/path/to/fedora-minimal.ks
837
838       You  must provide the config.json and runtime.json files to be included
839       in the bundle, their specifications can be  found  on  the  OCI  github
840       project  output will be in the results directory with a default name of
841       bundle.tar.xz
842
843       This will work with --no-virt and inside a mock since  it  doesn't  use
844       any partitioned disk images.
845

VAGRANT IMAGE CREATION

847       Vagrant images can be created using the following command:
848
849          sudo livemedia-creator --make-vagrant --vagrant-metadata /path/to/metadata.json \
850          --iso=/path/to/boot.iso --ks=/path/to/fedora-vagrant.ks
851
852       The image created is a vagrant-libvirt provider image and needs to have
853       vagrant setup with libvirt before you can use it.
854
855       The --vagrant-metadata file is optional, it will create a  minimal  one
856       by  default,  and  if one is passed it will make sure the disk size  is
857       setup correctly. If you pass a --vagrant-vagrantfile  it  will  be  in‐
858       cluded in the image verbatim. By default no vagrantfile is created.
859
860       There  is  an example Vagrant kickstart file in the docs directory that
861       sets up the vagrant user with the default insecure SSH pubkey and a few
862       useful utilities.
863
864       This  also works with --no-virt, but will not work inside a mock due to
865       its use of partitioned disk images and qcow2.
866

CREATING UEFI DISK IMAGES WITH VIRT

868       Partitioned disk images can only be created for the  same  platform  as
869       the  host system (BIOS or UEFI). You can use virt to create BIOS images
870       on UEFI systems, and it is also possible to create UEFI images on  BIOS
871       systems using OVMF firmware and qemu.
872
873       Install the lorax-lmc-virt package, this will install qemu and the OVMF
874       firmware files.
875
876       Now you can run livemedia-creator with --virt-uefi to boot and  install
877       using UEFI:
878
879          sudo livemedia-creator --make-disk --virt-uefi --iso=/path/to/boot.iso \
880          --ks=/path/to/fedora-minimal.ks
881
882       Make  sure  that the kickstart you are using creates a /boot/efi parti‐
883       tion by including this:
884
885          part /boot/efi --fstype="efi" --size=500
886
887       Or use reqpart in the kickstart and Anaconda will create  the  required
888       partitions.
889
890       NOTE:
891          The --virt-uefi method is currently only supported on the x86_64 ar‐
892          chitecture.
893

DEBUGGING PROBLEMS

895       Sometimes an installation will get stuck. When using qemu the logs will
896       be written to ./virt-install.log and most of the time any problems that
897       happen will be near the end of the file. lmc tries to detect common er‐
898       rors  and will cancel the installation when they happen. But not every‐
899       thing can be caught.  When creating a new kickstart it  is  helpful  to
900       use  vnc so that you can monitor the installation as it happens, and if
901       it gets stuck without lmc detecting the problem you can switch to  tty1
902       and examine the system directly.
903
904       If  you  suspect  problems with %pre or %post sections you can redirect
905       the output to the terminal and examine it by logging into the VM. eg.:
906
907          %pre
908          chvt
909          exec < /dev/tty3 > /dev/tty3 2>/dev/tty3
910          #do stuff
911          echo hello world
912          %end
913
914       If it does get stuck the best way to cancel is to use kill  -9  on  the
915       qemu pid, lmc will detect that the process died and cleanup.
916
917       If  lmc  didn't  handle the cleanup for some reason you can do this: 1.
918       sudo umount /tmp/lmc-XXXX to unmount the iso from its  mountpoint.   2.
919       sudo  rm -rf /tmp/lmc-XXXX 3. sudo rm /var/tmp/lmc-disk-XXXXX to remove
920       the disk image.
921
922       Note that lmc uses the lmc- prefix for all of its temporary  files  and
923       directories to make it easier to find and clean up leftovers.
924
925       The  logs  from  the qemu run are stored in virt-install.log, logs from
926       livemedia-creator are in livemedia.log and program.log
927
928       You can add --image-only to skip the .iso creation and examine the  re‐
929       sulting  disk image. Or you can pass --keep-image to keep it around af‐
930       ter the iso has been created.
931
932       Cleaning up aborted --no-virt installs can sometimes be accomplished by
933       running  the  anaconda-cleanup  script.  As  of  Fedora  18 anaconda is
934       multi-threaded and it can sometimes become stuck and  refuse  to  exit.
935       When  this  happens  you can usually clean up by first killing the ana‐
936       conda process then running anaconda-cleanup.
937

HACKING

939       Development on this will take place as part of the lorax  project,  and
940       on the anaconda-devel-list mailing list, and on github
941
942       Feedback,  enhancements  and bugs are welcome.  You can use bugzilla to
943       report bugs against the lorax component.
944

AUTHOR

946       Weldr Team
947
949       2018, Red Hat, Inc.
950
951
952
953
95438.8                             Feb 20, 2023             LIVEMEDIA-CREATOR(1)
Impressum