DESCRIPTION¶
This manual page was written for the Debian GNU/Linux distribution because the original program does not have a manual page. Check linux —help for an up-to-date synopsis.
OPTIONS¶
debugtrace Causes the tracing thread to pause until it is attached by a debugger and continued. This is mostly for debugging crashes early during boot, and should be pretty much obsoleted by the debug switch.
honeypot This makes UML put process stacks in the same location as they are on the host, allowing exploits such as stack smashes to work against UML.
debug Starts up the kernel under the control of gdb. See the kernel debugging tutorial and the debugging session pages in the user-mode-linux-doc package for more information.
To use hostfs for the root filesystem, use the syntax «root=/dev/root rootflags=/ rootfstype=hostfs»
jail Enables the protection of kernel memory from processes
tty This will make UML attach the device to the specified tty. If the tty that you specify is the slave end of a tty/pty pair, something else must have already opened the corresponding pty in order for this to work.
pty This will cause UML to allocate a free host pty for the device. The pty will be announced in the boot log. You would attach to it via the corresponding tty.
pts terminal This is similar to pty above, but the specified UML device will be attached to a free pts device on the host. Look at the boot log to see which one.
xterm UML will run an xterm and the device will be attached to it.
file descriptors If you set up a file descriptor on the UML command line, you can attach a UML device to it. This is most commonly used to put the main console back on stdin and stdout after assigning all the other consoles to something else.
You can also specify different input and output channels for a device by putting a comma between them:
See Setting up Serial Lines and Consoles (link to URL file:///usr/share/doc/user-mode-linux-doc/html/input.html) for a more information.
fake_ide Create ide0 entries that map onto ubd devices.
ubd0r=/tmp/debian-woody.ext2
ubd0rs=/tmp/debian-woody.ext2
This is used to associate a device with a file or in the underlying filesystem. Usually, there is a filesystem in the file, but that’s not required. Swap devices containing swap files can be specified like this. Also, a file which doesn’t contain a filesystem can have its contents read in the virtual machine by running dd on the device. Appending an ‘r’ will cause that device to be mounted read-only. Appending an ‘s’ tells UML to open the file using O_SYNC (synchronous I/O).
The ubd option can no longer be used to specify a hostfs root filesystem. See the «root» option for a more correct method.
udb This option is here solely to catch ubd -> udb typos, which can be to impossible to catch visually unless you specifically look for them. The only result of any option starting with ‘udb’ is an error in the boot output.
fakehd Change the ubd device name to «hd», allowing programs within UML to access UBD devices as if they were normal IDE disks.
eth0=ethertap,tap0,,192.168.0.1
eth5+=tuntap,,ethernet_address,ip_address
eth0=tuntap,,fe:fd:0:0:0:1,192.168.0.1
eth6+=daemon,ethernet_address,type,control_socket,data_socket
eth0=daemon,,unix,/var/run/uml-utilities/uml_switch.ctl
eth2+=mcast,ethernet_address,address,port,ttl
mode=tt When both CONFIG_MODE_TT and CONFIG_MODE_SKAS are enabled, this option forces UML to run in tt (tracing thread) mode. It is not the default because it’s slower and less secure than skas mode.
mode=skas0 Disables SKAS3 usage, so that SKAS0 is used, unless you specify mode=tt. Note that this was recently added — on older kernels you must use simply «skas0».
skas0 Disables SKAS3 usage, so that SKAS0 is used, unless you specify mode=tt.
mconsole=notify:socket Requests that the mconsole driver send a message to the named Unix socket containing the name of the mconsole socket. This also serves to notify outside processes when UML has booted far enough to respond to mconsole requests.
aio=2.4 This is used to force UML to use 2.4-style AIO even when 2.6 AIO is available. 2.4 AIO is a single thread that handles one request at a time, synchronously. 2.6 AIO is a thread which uses the 2.6 AIO interface to handle an arbitrary number of pending requests. 2.6 AIO is not available in tt mode, on 2.4 hosts, or when UML is built with /usr/include/linux/aio_abi.h not available. Many distributions don’t include aio_abi.h, so you will need to copy it from a kernel tree to your /usr/include/linux in order to build an AIO-capable UML.
noptraceldt Turns off usage of PTRACE_LDT, even if host supports it. To support PTRACE_LDT, the host needs to be patched using the current skas3 patch.
noptracefaultinfo Turns off usage of PTRACE_FAULTINFO, even if host supports it. To support PTRACE_FAULTINFO, the host needs to be patched using the current skas3 patch.
noprocmm Turns off usage of /proc/mm, even if host supports it. To support /proc/mm, the host needs to be patched using the current skas3 patch.
nosysemu Turns off syscall emulation patch for ptrace (SYSEMU) on. SYSEMU is a performance-patch introduced by Laurent Vivier. It changes behaviour of ptrace() and helps reducing host context switch rate. To make it working, you need a kernel patch for your host, too. See http://perso.wanadoo.fr/laurent.vivier/UML/ for further information.
—help Prints syntax information.
—version Prints the version number of the kernel.
—showconfig Prints the configuration used to build the kernel. To print all the options used to build the «linux» uml kernel and save them in «config_file» you can use
linux —showconfig > config_file
SEE ALSO¶
AUTHOR¶
User-mode Linux was written by Jeff Dike and others.
This manual page was written by Matt Zimmerman mdz@debian.org for the Debian GNU/Linux system, based on linux —help and the user-mode-linux website.
| Source file: | linux.uml.1.en.gz (from user-mode-linux 6.1um4+b3) |
| Source last updated: | 2023-05-18T09:00:38Z |
| Converted to HTML: | 2023-06-11T00:15:04Z |
User-mode Linux
User-mode-Linux (UML) is a method to run Linux inside Linux as a normal process. Please check [1] for in-depth information what UML is and how it works.
Why use UML?
Running UML is a safe way to run multiple instances of (Arch-)Linux at the same time. The single processes are separated from each other, which makes it secure to run, for example, a testing instance and a production instance on the same machine. If something goes wrong inside the testing instance, it does not interfere with the host Linux or the productive instance.
HOWTO
- Use hostfs with vde2 network (all UMLs use same file system)
- Use rootfs with tap network (require build image)
- Use Marionnet
Setup by hostfs + vde2
Hostfs means use the host’s file system in read-only mode.
Required packages
Launch script
- download https://pastebin.com/qDE0D7Lk script as 2vm.bash
- use normal user to launch 2vm.bash (there are two VMs named as ‘C1’ & ‘C2’)
- modify the 2vm.bash to fit your requirements
Setup by rootfs + tap
Required packages
Build rootfs image
1.) First you have to create a single, big file into which you will install Arch Linux. This command creates a single 1 GiB file, only containing zeros, which should be enough for a basic Arch Linux installation.
dd if=/dev/zero of=rootfs bs=1M count=1024
2.) After the build process you have to format the root file system image:
3.) After formatting the file, you have to mount it. Executing the following command as root does the job (you have also to load the loop module with modprobe ):
4.) Now the installation of the basic system may start:
mkdir -p /mnt/var/lib/pacman pacman -Sy base -r /mnt cd /mnt/dev mknod --mode=660 ubd0 b 98 0 chown root:disk ubd0
5.) Before the system can be booted with user-mode-Linux, some files inside the Arch basic system have to be customised. Add this line to /mnt/etc/fstab :
/dev/ubd0 / ext2 defaults 0 0
6.) Now unmount the file system.
Warning: If you change anything inside your mounted file system (e.g. /mnt ) while it is running, it may lead to significant file system corruption inside your virtual machine and kill it!
7.) Next step is to set up networking. Therefore, you create a so called tun device (Please visit the UML how-to for further information about tun/tap), and give it an IP address. The following lines load the necessary tun module, create a tun/tap device that is readable by the users group, and sets it up with the given IP address. For security, you should consider creating a certain UML group with read permissions for the network device.
modprobe tun ip tuntap add tap0 mode tap group users chown root:users /dev/net/tun ip addr add 192.168.0.100/24 dev tap0
8.) Now you can boot the image.
To use the network, you have to announce the proper device to the UML kernel. (Mind that the user running the UML command needs enough rights to access the tun device!)
vmlinux ubd0=rootfs eth0=tuntap. 192.168.0.100
The options to eth0 ( . ) mean:
eth0=transportmode,tuntap device,MAC address,hostip
Where transportmode is ‘tuntap’ in this example; the tuntap device is the device configured above; MAC address is the MAC address that the eth0 device in the UML system should get; hostip is the ip adress that the tuntap device in the host system gets. This should be an unused ip address of your hosts local network. The device and MAC address are optional and «guessed» if not supplied.
eth0=tuntap,tap0,3f:2a:bb:00:00:00,192.168.0.100
Other important options are mem for specifying the amount of RAM the guest system should be able to use (defaults to only 16MB); con to configure the virtual terminals and ubdb, ubdc, … for mounting additional filesystems.
vmlinux ubd0=rootfs eth0=tuntap. 192.168.0.100 mem=128M con=pty
9) If you are not presented with a login prompt but see something like Virtual console 1 assigned device ‘/dev/pts/4 , open the virtual console in another terminal with screen and press enter:
10) In the UML system you can configure the network manually:
ip link set dev eth0 up ip addr add 192.168.0.200/24 broadcast + dev eth0 ip route add default via 192.168.0.100 echo 'nameserver 1.1.1.1' > /etc/resolv.conf
Gateway it the address you specified in 8; the local address should be another unused address from your network.
Marionnet
Marionnet is a free application for virtual networks. For use, you must install uml_utilities AUR , and see https://bugs.launchpad.net/marionnet/+bug/1580349.
Usage
Management console
With <[ic|uml_mconsole>> you can manage running UML systems:
You can see the socket-names – also called UMID – of your UML systems in the folder ~/.uml/ :
$ ls -l ~/.uml/ drwxr-xr-x 1 michi users 16 11. Apr 19:52 I0KaOj drwxr-xr-x 1 michi users 16 11. Apr 19:14 LrPv03 drwxr-xr-x 1 michi users 16 11. Apr 19:31 o8X27c
You can also specify it on start with the umid option.
With uml_mconsole you can among others reboot/halt the system, add/remove storage devices or send special key combinations (sysrq, Ctrl-alt-del) to the system.