Home Page/News
Walkthrough
Features
Screenshots
SourceForge
Download
Running it
Distributions
Known problems
Future plans
Thanks
Contacts
Help wanted

Documentation
Command line
GUI
FAQ
Developer - General
Developer - Profile
Security

Useful stuff
Making your own UML RPMs

UML Builder

Command Line

Name

umlbuilder - install a Linux distribution for use with User Mode Linux

Version

This documentation applies to umlbuilder, version 1.50.

Synopsis

umlbuilder OPTIONS

Mandatory options are --distro, --dir, --rpmdir, --hostname. All other options are calculated from these, or have a sensible default value.

Note: You probably want to run the pointy clicky graphical version that takes you through all the steps easily with extensive online help. The command is umlbuilder_gui.

Description

umlbuilder helps you install a Linux distribution in order to get an environment to work in with User Mode Linux. Unlike mkrootfs that is distributed with User Mode Linux, this does not require you to be root, nor to have the ability to run sudo. It also runs the distributions installation process under the distribution itself. See Developer Information on the website for the nitty gritty details.

Note: umlbuilder only works on rpm based distributions. Note that Debian is not rpm based and has its own system for doing this kind of thing.

There is an example section later which is helpful if this is your first time.

--rpmdir dir [MANDATORY PARAMETER]: Location of the .rpm files for this distribution. The first time this directory is accessed, a file called rpmindex.py will be created inside it. This contains information about what rpms require from other ones, and what they provide. It will take several minutes to calculate. Once the index exists, future accesses just load the index. Note that if you add or remove any rpm files from the directory, then you must delete the rpmindex.py file so it can be recalculated.
This also means that even if you have the distribution on cdrom, you must copy it to hard disk first. Historical Note: An early prototype of this tool used the CDs directly. The problem is that on seeing CD2 of a distribution, it would then see that the files on that required some from CD1 again. A simple install would involve over 20 CD changes.
--dir dir [MANDATORY PARAMETER]: Directory that the resulting files will be created in. This directory must not exist already. A script named control will be created inside that can be used to control your guest instance. For example, the command control start will start it.
--distro dir [MANDATORY PARAMETER]: Specifies which distribution you are installing. It needs to be one of the ones we know about (use --distro list to see which ones are known). If it isn't, see the developer information section.
--modules module,module,module [OPTIONAL PARAMETER]: Which modules to install (default is only base). Use --modules list to see what is available. Typical modules are X, KDE and Gnome. They generally match the broad categories from the distributions real installed.
--hostname hostname [MANDATORY PARAMETER]: The hostname of your new guest session. Note that this should NOT be the hostname of your actual computer.
--ipaddr ipaddr [OPTIONAL PARAMETER]: The ip address of your new guest session. This should NOT be the ip address of your actual computer. By default this is found by looking up the hostname supplied.
--umlargs args [OPTIONAL PARAMETER]: Extra arguments to supply to the UML kernel when starting it. These will be placed in the control file and always be used. If you have arguments you only intend to use some of the time, you can specify them after control start
--rootpw password [OPTIONAL PARAMETER]: The password to assign the root user. Default value is root.
--memsize number [OPTIONAL PARAMETER]: The amount of memory in megabytes the guest session will have. Default is 128MB.
--fstype type [OPTIONAL PARAMETER]: The default type used for filesystems. Default value is ext2. Note that the UML kernel being used must support the type, and the distribution must include tools that understand that type, in particular mkfs and fsck.
--fssize number [OPTIONAL PARAMETER]: Default size of filesystems in megabytes, with default being 1024MB (1GB). Sparse files are used, which means that the actual physical space will be what is actually used. If you use ls -lsk filename, you will be able to see the actual space usage as the first column.
--fs mountpoint,filename,size,type,ubd# [OPTIONAL PARAMETER]: If you would like more than just a root filesystem (specified via --fstype and --fssize options), you can add them using this option. An example is --fs /var,var_fs,1024,ext2,3. This create a file "var_fs" in the install directory, sized at 1Gb (1024MB), formatted as ext2 and specified as device /dev/ubd/3. Do not use /dev/ubd/7 as this is reserved for the swap file.
--swapsize number [OPTIONAL PARAMETER]: Size of swap space in megabytes (default 128MB).
--numttys number [OPTIONAL PARAMETER]: Number of terminals to run getty/login on, default 1 Since by default these appear in xterms and most Linux distros have 7 on by default, it can get very annoying.
--profiledir dir [OPTIONAL PARAMETER]: Directory that contains various support files needed to run the installation. It is also the location use to look up distribution information if a pathname wasn't supplied as the --distro argument.
--initdefault number [OPTIONAL PARAMETER]: The runlevel to set as default. The default behaviour is to leave it as whatever the distribution does. Generally you can specify 5 to get an X based login on startup.
--tzfile filename [OPTIONAL PARAMETER]
The file containing timezone information. By default /etc/localtime on your host is used.
--initrd true|false [OPTIONAL PARAMETER]
Create and use initial ramdisk if your UML supports it.

Example

You wish to install a new Mandrake 8.1 based system. The first step is to ensure this distribution is known about.

      $ umlbuilder --distro list
      Profile Directory: /usr/lib/uml/profiles
      Caldera2.4
      CalderaDesktop3.1
      Mandrake8.1
      Redhat7.2

Yes it does. The next step is to obtain the CDS, and copy the RPM files off them into the same directory (~/RPMS-mdk81 in this case). Mandrake 8.1 has 3 CDs, and the files can be found /Mandrake/RPMS{,2,3} on the CDs.

      $ mkdir ~/RPMS-mdk81
      $ mount /mnt/cdrom   # assuming I can do this as ordinary user
      $ cp /mnt/cdrom/Mandrake/RPMS/*.rpm  ~/RPMS-mdk81
      $ umount /mnt/cdrom
      $ .. repeat mount, cp, umount for remaining 2 cdroms ...

Decide where you will be creating the new system. This will be the value of the --dir parameter. I am going to use ~/playground.

Find out your new host and ip address information. You will need to talk to your network administrator. Mine assigned playground.example.com and 192.168.0.37. These will be the --hostname and --ipaddr arguments.

Decide which modules you will install.

      $ umlbuilder --distro Mandrake8.1 --modules list
      Modules available for distribution Mandrake8.1
      X      X windows
      base   Core minimal files
      gnome  GNOME desktop environment
      kde    KDE

I want all of those, so I will have my --modules argument be base,X,gnome,kde. I also want a graphical login to start automatically, so I will supply --initdefault 5 based on information in the "Getting an X session" section above.

I am going to leave all other settings at their defaults. If you run umlbuilder without any arguments, you can see what they are.

      $ umlbuilder --distro Mandrake8.1 --modules base,X,gnome.kde \
          --hostname playground.example.com --ipaddr 192.168.0.37 \
          --initdefault 5 --rpmdir ~/RPMS-mdk81 --dir ~/playground
      Indexing RPMS
      ========================================|100% Done.
      Successful
      Calculating dependencies (this will take several minutes)
      Making directories
      Making files
      Setting up swapspace version 1, size = 134213632 bytes
      Populating install filesystem
      ========================================|100% Done.
      Successful
      Running install process
      tracing thread pid = 21901
      Linux version 2.4.15-greased-turkey-1um (jdike@uml.karaya.com) (gcc
      version 2.96 20000731 (Red Hat Linux 7.1 2.96-81)) #2 Sun Nov 25 14
      :46:34 EST 2001
      ... several more console message pass by ...
      ... the various rpms get installed ...
      ... the installation does some post-install fixups ...
      Installation complete.  Run the following command to get your
      system up and running:
      ~/playground/control start

So now I can run control start and see my new guest operating system.

Author

Written by Roger Binns rogerb@rogerbinns.com

Splash screens by Christina Lee

Original penguin design by Larry Ewing

Copyright

BSD License. Components by other parties are included. See the UML Builder credits page for more details.