linux -- User-mode Linux
linux [options ...]
This manual page briefly documents User-mode Linux.
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.
This controls how much "physical" memory the kernel allocates
for the system. The size is specified as a number followed by
one of 'k', 'K', 'm', 'M', which have the obvious meanings.
This is not related to the amount of memory in the physical
machine. It can be more, and the excess, if it's ever used,
will just be swapped out.
Configure file as a named IO memory region named name.
gdb-pid is used to attach an external debugger to UML. This
may be an already-running gdb or a debugger-like process like
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
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.
root=file This is actually used by the generic kernel in exactly the
same way as in any other kernel. If you configure a number of
block devices and want to boot off something other than ubd0,
you would use something like "root=/dev/ubd5". Another
notation is the use of the major and the minor number of the
device, i.e. root=98:0, for ubd0.
To use hostfs for the root filesystem, use the syntax
"root=/dev/root rootflags=/ rootfstype=hostfs"
umid=name This is used to assign a unique identity to this UML machine
This is used for naming the pid file and management console
socket. I.e. to access to the management console for an
already running image (i.e. umid=test), just launch
uml_mconsole test from the host command line.
The location to place the pid and umid files.
This is used to boot UML from an initrd image. The argument
is the name of the file containing the image.
jail Enables the protection of kernel memory from processes
Attach a console to a host channel. Examples of channels
include ttys, ptys, pts terminals, xterms, and file
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
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.
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
for a more information.
Attach a serial line to a host channel. The same options are
supported as for consoles, described above.
fake_ide Create ide0 entries that map onto ubd devices.
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
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.
Configure a network device. Formats and examples follow (one
for each configured transport).
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.
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
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.
This is used to set hostfs parameters. The root directory
argument is used to confine all hostfs mounts to within the
specified directory tree on the host. If this isn't
specified, then a user inside UML can mount anything on the
host that's accessible to the user that's running it. The
only flag currently supported is 'append', which specifies
that all files opened by hostfs will be opened in append
xterm=terminal emulator,title switch,exec switch
Specifies an alternate terminal emulator to use for the
debugger, consoles, and serial lines when they are attached
to the xterm channel. The values are the terminal emulator
binary, the switch it uses to set its title, and the switch
it uses to execute a subprocess, respectively. The title
switch must have the form exec switch must have the form
'<switch> command arg1 arg2 The default values are
'xterm=xterm,-T,-e'. Values for gnome-terminal are
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.
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
--help Prints syntax information.
--version Prints the version number of the kernel.
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
The UserModeLinux-HOWTO (link to URL file:///usr/share/doc/user-mode-
User-mode Linux was written by Jeff Dike and others.
This manual page was written by Matt Zimmerman email@example.com for the
Debian GNU/Linux system, based on linux --help and the user-mode-