# Fatdog64 User Mode Linux (UML) Environment

## Introduction

According to User Mode Linux website, User Mode Linux (UML for short) is:

> User-Mode Linux is a safe, secure way of running Linux versions and Linux processes. Run buggy software, experiment with new Linux kernels or distributions, and poke around in the internals of Linux, all without risking your main Linux setup.

> User-Mode Linux gives you a virtual machine that may have more hardware and software virtual resources than your actual, physical computer. Disk storage for the virtual machine is entirely contained inside a single file on your physical machine. You can assign your virtual machine only the hardware access you want it to have. With properly limited access, nothing you do on the virtual machine can change or damage your real computer, or its software.

UML is one of the earliest attempt at Linux virtualisation (the other one being lguest, which is even lighter than UML but unfortunately only runs on 32-bit kernel). It has been largely superseded by more advanced technologies Kernel-mode Virtual Machine (KVM) and Linux Containers (lxc), and is probably considered to be of only academic interest these days, however it still has life left in it. For example it can be used to provide relatively easy and safe, secure sandboxing of untrusted applications.

Fatdog (since version 620) comes with User Mode Linux (UML) environment. All you need to do to use it, is to install linux_uml and uml_utilities packages, from the Package Manager.

Note for Fatdog64 700 users: if you are familiar with UML operation in Fatdog64 600 series, please read on. The way UML is configured has changed.

## Usage

### Starting up

To start using if, after installing the packages, all you need is open a Terminal (there is no GUI for this), and type start-uml.sh. This will start a "throwaway" UML VM (or UML "guest") with 256MB of RAM. A window will open with the UML desktop in it.

### Shutting down

You can shutdown the UML VM by:

- Use the "shutdown" menu from within the UML desktop
- Run the command "poweroff" from UML console
- If you accidentally close the terminal that runs UML console, run "killall vmlinux" from your host terminal.

It is "throwaway" because as soon as you stop the UML VM, all the information in it is gone - there will be no traces left. In this way, UML is very useful for testing purposes.

### Persistent UML

To run a persistent UML session (i.e., to be able to the states between UML shutdown and restart), do the following:

1. Make an empty directory to contain the UML session. This directory must be large enough to contain UML's "savefile".
2. Start UML like this: start-uml.sh /path/to/session/directory

Once UML has run for the first time in this way, it will create a "config" file in that session directory; which you can edit later. A 128MB savefile is also automatically created for you; if you need anything bigger, just delete that savefile and edit the config to specify a larger value - the savefile will be re-created when you restart UML next time. See below for the details of the config file.

### Launching UML without graphical desktop

By default, UML will start with a graphical desktop. If you don't want the graphical desktop, start it like this:

- start-uml.sh "" pfix=nox for throwaway session, or
- start-uml.sh /path/to/session/directory pfix=nox, or
- Edit the config file by putting pfix=nox into BOOT_OPTIONS variable and then start UML the usual way.

The Xephyr window will still open (so that you can type "xwin" to launch a graphical desktop later). If you don't need it, just close it after it opens.

## UML session config options

You can put a file named config in the session directory to configure UML's behaviour. This file is automatically created (with default values) if it doesn't exist, or you can create it yourself before you start UML for the first time.

The file contains configuration variables, as follows. Any of these settings can be "blanked" by not specifying the value, e.g. you can blank RAM_SIZE by putting RAM_SIZE= inside the config file.

- RAM_SIZE (default: 256M)

  Determines the size of the RAM allocated to the VM. By default start-uml.sh will assign 256 MB of RAM to the VM. This is a reasonable size for most graphical applications. If you don't run any GUI or other memory intensive applications, you can lower this number. UML itself will happily start with 32MB of RAM (although what you probably can't do much with it).

  Note: the letter 'M' is required, it specifies "megabytes".

- SAVEFILE_SIZE (default: 128) and SAVEFILE_FS (default: ext2)

  SAVEFILE_SIZE determines the size (in megabytes) of the savefile to be created if it doesn't exist. SAVEFILE_FS determines the filesystem used when the savefile is created (you can specify ext2, ext3 or ext4). If you leave SAVEFILE_SIZE blank, no savefile will be created if it doesn't exist. These variables are ignored if you already have an existing savefile.

  Note: Do not append 'M' for SAVEFILE_SIZE, just specify the numbers.

- SAVEFILE_PATH (default: /savefile.ext2)

  The location of the savefile, relative to the location of the session directory. Set to blank if you don't want to use a savefile at all (e.g, run a "throwaway" session). Unlike the real Fatdog, if you run without savefile, you will not be prompted to create savefile at the end of the UML session - the session is simply gone after you shut it down.

- HOST_IP (default: blank) and HOST_ADAPTER (default: blank) and UML_IP (default: blank)

  These settings control the IP address assignments on the host and the UML "guest". All of these can be left blank, and start-uml.sh will provide a reasonable values for them. You can set them manually if you require some special configuration or if the automatic values does not work.

Some notes about IP addresUML_IP address is the IP address to be assigned to the UML "guest". HOST_IP sets the gateway IP address to be created on the host. It is not really used but must be assigned. Unless you want to use masquerading, this IP address

- UML_IP sets the address that will be assigned inside the UML "guest" itself. Unless you want to use masquerading, this address must be on the same subnet as the physical network that the host is attached to.

- HOST_IP sets the address that will be used as the "gateway" on the host. It is not really used, but must be assigned, and it has to be on the same subnet as the UML_IP (thus, it has to be on the same subnet as the physical network as well, unless you want to use masquerading).

- HOST_ADAPTER is only used if HOST_IP is blank.

If HOST_IP is blank, it will be set to the IP address of HOST_ADAPTER. If HOST_ADAPTER is blank, then the first active network adapter with an IP address (other than the loopback interface) will be used.

If UML_IP is blank, it will be set to the HOST_IP but with the last component increased by 100 (mod 255). E.g. If your HOST_IP is 10.0.0.5 then UML_IP will be 10.0.0.105; if your HOST_IP is 10.0.0.250 then your UML_IP will be 10.0.0.95 (that is, (250+100) mod 255).

If you leave this parameter blank, it will be set to 100 + IP address from the HOST_ADAPTER will be used. If HOST_ADAPTER is blank, then the first non-local IP address will be used. E.g. if you have both eth0 (IP: 10.0.0.50) and wlan0 (192.168.1.5) and both variables are set to blank, the HOST_IP will be set to 10.0.0.150 and the UML IP will be set to 10.0.0.149.

Note: UML supports sophisticated routing, if you wish you can create network bridges with iptables masquerade etc but these are complex things beyond the purpose of start-uml.sh. If you need to do this you probably want to write your own UML script wrapper, using start-uml.sh as a baseline.

- NAME_SERVER (default: 8.8.8.8)

  The DNS server which will be used by UML VM (this is the value that get set inside /etc/resolv.conf) to resolve host names. By default the value is 8.8.8.8, which is Google's DNS server.

- START_CMD (default: blank)

  Specifies the command to be automatically executed when UML starts. You can set this to run your own programs directly inside UML; it will be executed in the "root" login context as the last stage of rc.sysinit.

- WINDOW_SIZE (default: 1024x700)

  Sets the window size of graphical desktop of the virtual X server (Xephyr). If you leave it blank, no virtual X server will be started and you cannot launch graphical applications.

- NICE_CMD (default: blank)

  Specifies the nice command for use when running the UML kernel. It is used to lower down the process priority used by the UML kernel, if you're running as root then it can be used to make UML run faster too by giving it more priority.

- BOOT_OPTIONS (default: blank)

  Specifies additional boot options that you want to pass to the UML Linux kernel. For example if you want to load additional SFS or additional disk images, you need to pass the ubdxxx parameters; specify them here. For the full set of available boot options, run /usr/lib64/uml/vmlinux from the terminal.

  If you have custom startup script, you can also pass parameters here which can be read by your startup script by inspecting /proc/cmdline.

Note: A few of the variables you define in the config file can be overridden by putting them into the command line when you start UML, for example when starting UML without graphical desktop as above.

## Questions and Answers

Question: Why UML, why not KVM or even VirtualBox?
Answer: UML is much smaller, use less resources, makes use of your existing Fatdog installation (no need for separate ISO files), and easier to setup. You can run UML with only 32MB (for text-mode applications) - you can't do that with KVM or VirtualBox.

Question: Fatdog already has sandbox, so what is this UML for?
Answer: Fatdog's sandbox isn't meant for security. It was originally devised for testing foreign packages, so while it can be used for other purposes, there is information leakages to/from the sandbox; and this is intentional - otherwise you'll face problems when testing. For example sandbox and the host shares the same "/tmp" directory. Fatdog's UML however, doesn't suffer from such problem - host and UML guest is completely separate. E.g. If you choose "shutdown" from sandbox's desktop, you will shutdown your entire system (not only the sandbox). Not so with UML. Choosing "shutdown" from UML's desktop will just shutdown UML VM.

Question: What can the UML VM do?
Answer: Almost everything the host system can do. Browse internet, run network applications (servers), etc. Probably not good enough to watch videos, though - there is no video acceleration in UML.

Question: I understand that the UML is isolated, but is there a way to pass data to/from the the UML? Otherwise how can I ever do anything worthwhile with UML?
Answer: Of course there is. The point is, these data sharing is completely under your control.

- You can setup a "savefile", which can be opened while the VM is offline; from there you can copy data to/from it.
- You can copy data using the network (e.g. using samba rox app / yassm, netcat, ssh, rsync, etc).
- You can create additional disk images which can be mounted both by the host and by the UML (using ubdxxx parameter - see below). You can open these disk images from host when they are not mounted from UML VM; and when done you can mount them and access the data from the inside the VM.

Question: UML only loads Fatdog's base sfs. Is there a way to load additional SFS too?
Answer: Yes. Specify additional SFS like this (assuming you want to use a throwaway session):

start-uml.sh "" ubd1rc=/path/to/your/sfs ubd2rc=/path/to/your/sfs, etc

where udb1rc will show up as /dev/udbb inside the UML VM, udb2rc will show up as /dev/udbc, and so on.

Then to load these SFS, once you're inside the UML VM, open terminal and type:

> load_sfs.sh /dev/udbb
> load_sfs.sh /dev/udbc

and so on. If you're using persistence then replace "" with path to your session directory.

Question: Does running UML require root access?
Answer: No. You can run UML even if you're not root. Inside UML, however, you are root ☺

Question: How do I quit the UML properly?
Answer: Choose "Shutdown" from the desktop menu if you run UML with the desktop (default). If you start UML without the desktop, terminate UML by running poweroff the console window.

- Do not close the Xephyr window unless you have no plan to run graphical applications. Closing Xephyr window does not stop the UML session (it will terminate all the graphical applications, but not the UML itself).
- Do not close the terminal window you use to start the UML. Closing this terminal does not stop the UML itself. If you accidentally close the terminal, run killall vmlinux on your host to stop the UML.

Question: OK, now that I can use console only stuff, I need more consoles. How do I get that?
Answer: Run this: setsid getty 38400 tty1 inside the UML VM. An xterm window will be opened that represents your new "console".

Replace tty1 with tty2, tty3, etc as many as you need.

Warning: Once the xterm windows are opened, do not close them; closing them will cause UML to hang. These xterms will automatically be closed when you stop your UML session.

Question: UML is slow!
Answer: Unlike other virtualisation solutions, UML does not create demand on CPU - it will simply use whatever idle power which has been given. The default CPU frequency scaling governor in Fatdog is "ondemand", which means that the CPU power will be controlled by "demand" - if the CPU power is not needed then the frequency of the CPU will lowered to save power and lower down the temperature too. If it detects that there is a "demand" or need for it, it will then increase the frequency to make the CPU more powerful so that it can do its job faster.

UML does not create this demand (even though in reality it is running slow), so the "ondemand" governor does not think it necessary to make the CPU go faster. To fix this, temporarily change the default CPU frequency scaling governor from the default "ondemand" to "performance" (which means run the CPU at full power at all times) while running UML. There is a commented script of how to do so in /etc/rc.d/rc.local.

Alternatively, you can use NICE_CMD configuration options (or run renice if you have already started the UML session) so that the UML kernel will get more priority. This can only be done when you run UML as root.

## Further information

- UML's web page here: http://user-mode-linux.sourceforge.net/old/
- See what kernel options are available by opening terminal and running this (on the host): /usr/lib64/uml/vmlinux --help
- Look at start-uml.sh and uml-init scripts source code in /usr/lib64/uml