File: rootstrap.sgml

package info (click to toggle)
rootstrap 0.3.24-5
  • links: PTS
  • area: main
  • in suites: lenny
  • size: 156 kB
  • ctags: 41
  • sloc: sh: 260; python: 185; makefile: 68
file content (776 lines) | stat: -rw-r--r-- 23,650 bytes parent folder | download | duplicates (4)
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
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [

<!-- Process this file with docbook-to-man to generate an nroff manual
     page: `docbook-to-man manpage.sgml > manpage.1'.  You may view
     the manual page with: `docbook-to-man manpage.sgml | nroff -man |
     less'.  A typical entry in a Makefile or Makefile.am is:

manpage.1: manpage.sgml
	docbook-to-man $< > $@
  -->

  <!-- Fill in your name for FIRSTNAME and SURNAME. -->
  <!ENTITY dhfirstname "<firstname>Matt</firstname>">
  <!ENTITY dhsurname   "<surname>Zimmerman</surname>">
  <!-- Please adjust the date whenever revising the manpage. -->
  <!ENTITY dhdate      "<date>March 12, 2002</date>">
  <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
       allowed: see man(7), man(1). -->
  <!ENTITY dhsection   "<manvolnum>1</manvolnum>">
  <!ENTITY dhemail     "<email>mdz@debian.org</email>">
  <!ENTITY dhusername  "Matt Zimmerman">
  <!ENTITY dhucpackage "<refentrytitle>rootstrap</refentrytitle>">
  <!ENTITY dhpackage   "rootstrap">

  <!ENTITY debian      "<productname>Debian GNU/Linux</productname>">
  <!ENTITY gnu         "<acronym>GNU</acronym>">
]>

<refentry>
  <refentryinfo>
    <address>
      &dhemail;
    </address>
    <author>
      &dhfirstname;
      &dhsurname;
    </author>
    <copyright>
      <year>2002</year>
      <holder>&dhusername;</holder>
    </copyright>
    &dhdate;
  </refentryinfo>
  <refmeta>
    &dhucpackage;

    &dhsection;
  </refmeta>
  <refnamediv>
    <refname>&dhpackage;</refname>

    <refpurpose>Construct a root filesystem image in a file</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <cmdsynopsis>
      <command>rootstrap</command>
      <arg choice=opt
      rep=repeat><replaceable>options</replaceable></arg>

      <arg choice=req><replaceable>imagefile</replaceable></arg>

    </cmdsynopsis>
  </refsynopsisdiv>
  <refsect1>
    <title>DESCRIPTION</title>

    <para>
      rootstrap is a tool for creating root filesystem images.  It was
      written primarily for use with User-Mode Linux, but may be
      useful for other purposes as well.
    </para>

    <para>
      Because it uses User-Mode Linux to bootstrap itself, rootstrap
      can be used without root privileges on the host system, which
      are normally required for this task in order to use chroot(2)
      and mount and unmount filesystems.  Rootstrap boots UML and uses
      tools from the host filesystem to perform installation and
      configuration tasks.
    </para>

    <para>
      Note: since roostrap needs to access the host filesystem it requires an
      UML kernel with hostfs built-in (CONFIG_HOSTFS=y), not as module.
    </para>

  </refsect1>
  <refsect1>
    <title>OPTIONS</title>

    <variablelist>
      <varlistentry>
        <term>-s, --image-size</term>
        <listitem>
          <para>
            Sets the initial size of the image, in megabytes,
            overriding the initialsize option in rootstrap.conf.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-o <replaceable>logfile</replaceable></term>
        <listitem>
          <para>
            Log the output of the creation process to
            <replaceable>logfile</replaceable> instead of to standard
            output.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-u <replaceable>args</replaceable>, --umlargs <replaceable>args</replaceable></term>
        <listitem>
          <para>
            Pass additional arguments to user-mode linux when booting
            to create the image.  Supplements the 'umlargs' option in
            rootstrap.conf.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>

  </refsect1>

  <refsect1>
    <title>Configuration</title>

    <para>
      The configuration file consists of sections, starting with a
      "[section]" header, followed by "option=value" entries.
      Long values are allowed to span multiple lines if
      each continued line is indented with whitespace.
    </para>

    <para>
      With the exception of the special section "global", sections are
      named after a corresponding module.  When that module is
      executed, it receives the option/value pairs in its section as
      environment variables.  All modules inherit global options as
      environment variables, except where overridden by options within
      their specific section.  At least PATH must be set here, in
      addition to the required parameters listed below under [global].
    </para>

    <para>
      Documentation for configurable modules distributed with
      rootstrap is included below.  This section is currently
      incomplete.
    </para>
    <para>
      Note that the modules shipped with rootstrap have a
      recommended ordering due to their cooperation in building
      the guest OS image, equivalent modules can be used for 
      each of these tasks:
      <orderedlist>
        <listitem>
	  <para>setup guest network (if you need it for OS installation)</para>
	</listitem>
        <listitem>
	  <para>create the target filesystem</para>
	</listitem>
        <listitem>
	  <para>mount target filesystem in the guest Linux</para>
	</listitem>
        <listitem>
	  <para>OS installation</para>
	</listitem>
        <listitem>
	  <para>UML basic setup (device nodes, kernel modules, etc.)</para>
	</listitem>
        <listitem>
	  <para>Tweaking (here you should have a fully working OS to play with)</para>
	</listitem>
        <listitem>
	  <para>unmount the target filesystem</para>
	</listitem>
      </orderedlist>
    </para>

  </refsect1>

  <refsect1>
    <title>Modules</title>

    <refsect2>
      <title>[global]</title>

      <para>
        Contains configuration options that affect the operation of
        rootstrap itself, or several modules.
      </para>

      <variablelist>
        <varlistentry>
          <term>fstype</term>
          <listitem>
            <para>
              The type of filesystem to create
              (ext2, ext3, reiserfs, etc.)
              This parameter is mandatory.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>umlargs</term>
          <listitem>
            <para>
	      Additional arguments to user-mode linux passed when booting to
	      create the image.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>PATH</term>
          <listitem>
            <para>
              The PATH environment variable to pass to modules.
              This parameter is mandatory.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>initialsize</term>
          <listitem>
            <para>
              The initial size of the filesystem image (in megabytes).
              This must be large enough to contain a complete
              installed system as produced by the selected modules.
              It will be created sparsely, so additional space is not
              entirely allocated until it is used.
              This parameter is mandatory.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>freespace</term>
          <listitem>
            <para>
              The amount of free space to leave on the filesystem (in
              megabytes).  The filesystem will be resized, if
              possible, to adjust the amount of free space to
              approximately this amount.
              This parameter is optional.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>modules</term>
          <listitem>
            <para>
              The list of modules to invoke, in order.  Each module
              will be searched for in several directories, listed in
              the FILES section below, and passed environment
              variables based on the options set in the corresponding
              section of the configuration file.
              This parameter is mandatory.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>debug</term>
          <listitem>
            <para>
	      When set to "true" make rootstrap spawn a shell when a module
	      script fails allowing further debugging actions.
	      The shell will have the same environment as the failing script so
	      you could simply invoke <command>sh -x /path/to/module</command>
	      to see what's going wrong. Moreover the shell exit value will be
	      used to tell rootstrap to: re-evaluate the script when 1 (with exit 1)
	      or continue with the next one when 2 (with exit 2); all other values
	      will make rootstrap fail with an error.
              This parameter is optional.
            </para>
          </listitem>
        </varlistentry>

      </variablelist>
    </refsect2>

    <refsect2>
      <title>[network]</title>

      <para>
        Network configuration.  This module configures virtual
        networking with the user-mode Linux system used to build the
        filesystem image.  Its presence is not strictly necessary, if
        the selected modules do not require network access (for
        example, with a local package mirror) and the network module
        is not included in the global "modules" list.
      </para>

      <variablelist>
        <varlistentry>
          <term>interface</term>
          <listitem>
            <para>
              The name of the network interface to configure
              inside the UML virtual machine,
              typically "eth0".
              This parameter is mandatory.
              </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>host</term>
          <listitem>
            <para>
              The IP address of the host side of the interface
              (the host on which rootstrap is run),
              as visible to the UML virtual machine.
              This parameter is mandatory.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>uml</term>
          <listitem>
            <para>
              The IP address of the UML side of the interface (where
              the system is being built). The value "dhcp" is also accepted
	      and makes rootstrap try to configure the network interface 
	      through DHCP.
	      This parameter is mandatory.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>transport</term>
          <listitem>
            <para>
              The type of virtual networking interface to be used.
              Typically "tuntap".
              Other available transports are "slirp" and "daemon".
              This parameter is mandatory.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>netmask</term>
          <listitem>
            <para>
              The netmask for the network interface (applies to both
              sides).  This parameter is mandatory.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>hostname</term>
          <listitem>
            <para>
              The host name to use for the created UML virtual machine.
              This parameter is optional.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>gateway</term>
          <listitem>
            <para>
              A default gateway to be used by the user-mode Linux
              system.  This parameter is optional.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>domain</term>
          <listitem>
            <para>
	      The local domain name.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>nameserver</term>
          <listitem>
            <para>
              The DNS server to use for domain name resolution inside
              the UML virtual machine. This parameter is optional, but
              useful if you do not have a name server running on the host.
            </para>
          </listitem>
        </varlistentry>

      </variablelist>

    </refsect2>

    <refsect2>
	<title>[mkfs]</title>
	<para>
	  This module creates the filesystem for the rootfs.
	  It uses the <parameter>fstype</parameter> global parameter.
	</para>
    </refsect2>

    <refsect2>
	<title>[mount]</title>
	<para>
	  This module mounts the root filesystem where the OS image is going to
	  be created.
	  It uses the <parameter>fstype</parameter> global parameter.
	</para>
    </refsect2>

    <refsect2>
	<title>[umount]</title>
	<para>This module unmounts the root filesystem and /proc.</para>
    </refsect2>

    <refsect2>
      <title>[uml]</title>
      <para>
        Creates /etc/fstab and necessary device nodes, it eventually copies 
	kernel modules into the target image.
	It uses the <parameter>fstype</parameter> global parameter.
      </para>
      <variablelist>
        <varlistentry>
          <term>kernel_modules</term>
          <listitem>
            <para>
              How to deal with kernel modules for the guest Linux.
	      It can be one of <parameter>none</parameter>,
	      <parameter>hostfs</parameter> or 
	      <parameter>copy</parameter>, defaults to the latter which copies
	      the available modules in the target filesystem.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>kernel_modules_dir</term>
          <listitem>
            <para>
	      The directory where <parameter>kernel_modules</parameter>
	      are located on the host filesystem. It defaults to
	      /usr/lib/uml/modules
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>install_modules</term>
          <listitem>
            <para>
	      This parameter is superseeded by
	      <parameter>kernel_modules</parameter> and 
	      <parameter>kernel_modules_dir</parameter>. It accepts a
	      boolean value (true/false).
            </para>
          </listitem>
        </varlistentry>
      </variablelist>

    </refsect2>

    <refsect2>
      <title>[debian]</title>

      <para>
        Debian installation.  This module installs a basic Debian
        system using debootstrap.
      </para>

      <variablelist>
        <varlistentry>
          <term>dist</term>
          <listitem>
            <para>
              The distribution to install (e.g., potato, woody, etc.)
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>mirror</term>
          <listitem>
            <para>
              A URL for a Debian archive containing the base
              packages.  This must be a URL understood by debootstrap,
              which as of this writing includes URLs understood by
              wget, and file: URLs.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>exclude</term>
          <listitem>
            <para>
              A list of packages which should be excluded (never
              installed at all).  It is quite possible to produce a
              broken system, or fail to build a system at all, if this
              option is used improperly.  It is useful for excluding
              packages, such as pcmcia-cs, which are typically not
              necessary for UML and other applications.
            </para>

            <para>
              Corresponds to debootstrap's --exclude option
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>purge</term>
          <listitem>
            <para>
              A list of packages which should be removed after
              installation is complete.  Use this for packages which
              are required during installation, but may be removed
              afterward.  The same warning applies as with the exclude
              option.
            </para>

            <para>
              Packages are removed with dpkg --purge.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>include</term>
          <listitem>
            <para>
              A list of packages which should be included in the
              initial set of packages to install.
            </para>

            <para>
              Corresponds to debootstrap's --include option.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>install</term>
          <listitem>
            <para>
	      Extra packages to install via apt after initial debootstrap
	      install.
            </para>

            <para>
              See also the sources option.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>debconf_preseed_file</term>
          <listitem>
            <para>
	      A file containing a debconf DB to be used as default.
	      Read debconf documentation and see your /var/cache/debconf/config.dat
	      for examples and caveats.
            </para>

          </listitem>
        </varlistentry>

        <varlistentry>
          <term>sources</term>
          <listitem>
            <para>
	      Sources for target's sources.list. If no value is given the
	      default is the main section of <parameter>mirror</parameter>.
	      NOTE: you can provide multiple lines if each new line is indented
	      with blank spaces.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>preferences</term>
          <listitem>
            <para>
	      Preferences for target's apt preferences file (see apt_preferences(5)).
	      NOTE: you can provide multiple lines if each new line is indented
	      with blank spaces. Multiple apt_preferences stanzas are allowed provided
	      that they are separated by a line containing only a dot (".") and
	      obviously indented as specified above.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>apt_conf</term>
          <listitem>
            <para>
	      Apt configuration for target's apt.conf file (see apt.conf(5)). The file
	      will be created before installing additional packages so it will be already
	      effective then.
	      NOTE: you can provide multiple lines if each new line is indented
	      with blank spaces.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>apt_force_yes</term>
          <listitem>
            <para>
	      Will make rootstrap use the --force-yes switch to install 
	      debian packages. This useful when you need to install packages
	      from sources that don't use a Release.gpg file and thus failing
	      apt key authentication. It can be either <parameter>true</parameter>
	      or <parameter>false</parameter> and defaults to the former.
            </para>
	    <para>
	      Be careful anyway as using this option "will cause apt to
	      continue without prompting if it is doing something potentially
	      harmful" (from apt-get(8)). This option is provided standalone instead
	      of forcing its inclusion in <parameter>apt_conf</parameter> to
	      avoid causing destructive actions later when using apt-get from the
	      UML instance.
	    </para>
          </listitem>
        </varlistentry>
      </variablelist>

    </refsect2>

    <refsect2>
      <title>Custom modules</title>

      <para>
        Custom modules can very easily be used by rootstrap, in
        addition to (or in place of) the supplied modules.  See FILES
        below for locations that are searched for modules.
      </para>

      <para>
        When a module is invoked, the filesystem being created is
        mounted on $TARGET, /dev, /etc and /tmp are tmpfs filesystems
        internal to the UML system, while the root filesystem is a
	hostfs mount of the system where rootstrap is running, to have 
	access to the above shadowed directories the full host filesystem
	is available on $HOST. /lib/modules is tmpfs too and bind mounted to
	the host's /usr/lib/uml/modules to let scripts load necessary kernel
	modules.
	This means that most software on the host system should be
        available and work as expected. The working directory where
        rootstrap is run is available as $WORKDIR. The environment is
        generated from the configuration file as described above.
      </para>

      <para>
	Be careful about modules ordering (see CONFIGURATION above), you'll 
	mostly want to plug into the tweaking step to perform custom configurations.
      </para>

      <para>
        To debug modules enable the <parameter>debug</parameter> global 
	parameter, see its description fro more hints.
      </para>
    </refsect2>

  </refsect1>

  <refsect1>
    <title>FILES</title>

    <variablelist>
      <varlistentry>
        <term>/etc/rootstrap/rootstrap.conf</term>
        <listitem>
          <para>
            System-wide default configuration
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>rootstrap.conf</term>
        <listitem>
          <para>
            Local overrides
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>/usr/lib/rootstrap/modules</term>
        <listitem>
          <para>
            Modules distributed with rootstrap
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>/etc/rootstrap/modules</term>
        <listitem>
          <para>
            System-wide overrides and additional modules
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>modules</term>
        <listitem>
          <para>
            Local overrides and additional modules
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
            
  </refsect1>

  <refsect1>
    <title>SEE ALSO</title>

    <para>
      <citerefentry>
	<refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
	<refentrytitle>apt_preferences</refentrytitle><manvolnum>5</manvolnum>
      </citerefentry>,
      <citerefentry>
	<refentrytitle>apt.conf</refentrytitle><manvolnum>5</manvolnum>
      </citerefentry>,
      <citerefentry>
	<refentrytitle>debconf</refentrytitle><manvolnum>7</manvolnum>
      </citerefentry>,
      <citerefentry>
	<refentrytitle>linux</refentrytitle><manvolnum>1</manvolnum>
      </citerefentry>;
      locally installed User-Mode Linux documentation or
      <ulink url="http://user-mode-linux.sourceforge.net/">
	http://user-mode-linux.sourceforge.net/
      </ulink>
    </para>
  </refsect1>

  <refsect1>
    <title>AUTHOR</title>

    <para>Rootstrap was written by &dhusername; &dhemail;</para>

  </refsect1>
</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->