korg/linux
0
0
Fork 0
mirror of https://mirrors.bfsu.edu.cn/git/linux.git synced 2024-11-11 12:28:41 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: UML: user_mode_linux_howto_v2 edits

Browse Source 
Fix various typos, command syntax, punctuation, capitalization,
and whitespace.

Fixes: 04301bf5b0 ("docs: replace the old User Mode Linux HowTo with a new one")
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Jeff Dike <jdike@addtoit.com>
Cc: Richard Weinberger <richard@nod.at>
Cc: Anton Ivanov <anton.ivanov@cambridgegreys.com>
Cc: linux-um@lists.infradead.org
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Acked-By: anton ivanov <anton.ivanov@cambridgegreys.com>
Link: https://lore.kernel.org/r/20211010064827.3405-1-rdunlap@infradead.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Randy Dunlap 2021-10-09 23:48:27 -07:00 committed by Jonathan Corbet
parent a9d85efb25
commit e825b29ab8
1 changed files with 62 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

119
Documentation/virt/uml/user_mode_linux_howto_v2.rst
View File

@ -128,7 +128,7 @@ Create a minimal OS installation on the mounted filesystem::
debootstrap does not set up the root password, fstab, hostname or
anything related to networking. It is up to the user to do that.
Set the root password -t he easiest way to do that is to chroot into the
Set the root password - the easiest way to do that is to chroot into the
mounted image::
# chroot /mnt
@ -144,7 +144,7 @@ will be empty and it needs an entry for the root file system::
/dev/ubd0 ext4 discard,errors=remount-ro 0 1
The image hostname will be set to the same as the host on which you
are creating it image. It is a good idea to change that to avoid
are creating its image. It is a good idea to change that to avoid
"Oh, bummer, I rebooted the wrong machine".
UML supports two classes of network devices - the older uml_net ones
@ -162,7 +162,7 @@ need entries like::
# vector UML network devices
auto vec0
iface eth0 inet dhcp
iface vec0 inet dhcp
We now have a UML image which is nearly ready to run, all we need is a
UML kernel and modules for it.
@ -179,7 +179,12 @@ directory to the mounted UML filesystem::
If you have compiled your own kernel, you need to use the usual "install
modules to a location" procedure by running::
# make install MODULES_DIR=/mnt/lib/modules
# make INSTALL_MOD_PATH=/mnt/lib/modules modules_install
This will install modules into /mnt/lib/modules/$(KERNELRELEASE).
To specify the full module installation path, use::
# make MODLIB=/mnt/lib/modules modules_install
At this point the image is ready to be brought up.
@ -188,7 +193,7 @@ Setting Up UML Networking
*************************
UML networking is designed to emulate an Ethernet connection. This
connection may be either a point-to-point (similar to a connection
connection may be either point-to-point (similar to a connection
between machines using a back-to-back cable) or a connection to a
switch. UML supports a wide variety of means to build these
connections to all of: local machine, remote machine(s), local and
@ -231,7 +236,7 @@ remote UML and other VM instances.
* All transports which have multi-packet rx and/or tx can deliver pps
rates of up to 1Mps or more.
* All legacy transports are generally limited to ~600-700MBit and 0.05Mps
* All legacy transports are generally limited to ~600-700MBit and 0.05Mps.
* GRE and L2TPv3 allow connections to all of: local machine, remote
machines, remote network devices and remote UML instances.
@ -255,7 +260,7 @@ raw sockets where needed.
This can be achieved by granting the user a particular capability instead
of running UML as root. In case of vector transport, a user can add the
capability ``CAP_NET_ADMIN`` or ``CAP_NET_RAW``, to the uml binary.
capability ``CAP_NET_ADMIN`` or ``CAP_NET_RAW`` to the uml binary.
Thenceforth, UML can be run with normal user privilges, along with
full networking.
@ -286,7 +291,7 @@ These options are common for all transports:
* ``mac=XX:XX:XX:XX:XX`` - sets the interface MAC address value.
* ``gro=[0,1]`` - sets GRO on or off. Enables receive/transmit offloads.
* ``gro=[0,1]`` - sets GRO off or on. Enables receive/transmit offloads.
The effect of this option depends on the host side support in the transport
which is being configured. In most cases it will enable TCP segmentation and
RX/TX checksumming offloads. The setting must be identical on the host side
@ -301,7 +306,7 @@ These options are common for all transports:
* ``headroom=int`` - adjusts the default headroom (32 bytes) reserved
if a packet will need to be re-encapsulated into for instance VXLAN.
* ``vec=0`` - disable multipacket io and fall back to packet at a
* ``vec=0`` - disable multipacket IO and fall back to packet at a
time mode
Shared Options
@ -331,7 +336,7 @@ Example::
This will connect vec0 to tap0 on the host. Tap0 must already exist (for example
created using tunctl) and UP.
tap0 can be configured as a point-to-point interface and given an ip
tap0 can be configured as a point-to-point interface and given an IP
address so that UML can talk to the host. Alternatively, it is possible
to connect UML to a tap interface which is connected to a bridge.
@ -358,7 +363,7 @@ Example::
This is an experimental/demo transport which couples tap for transmit
and a raw socket for receive. The raw socket allows multi-packet
receive resulting in significantly higher packet rates than normal tap
receive resulting in significantly higher packet rates than normal tap.
Privileges required: hybrid requires ``CAP_NET_RAW`` capability by
the UML user as well as the requirements for the tap transport.
@ -426,10 +431,10 @@ This will configure an Ethernet over ``GRE`` (aka ``GRETAP`` or
endpoint at host dst_host. ``GRE`` supports the following additional
options:
* ``rx_key=int`` - GRE 32 bit integer key for rx packets, if set,
* ``rx_key=int`` - GRE 32-bit integer key for rx packets, if set,
``txkey`` must be set too
* ``tx_key=int`` - GRE 32 bit integer key for tx packets, if set
* ``tx_key=int`` - GRE 32-bit integer key for tx packets, if set
``rx_key`` must be set too
* ``sequence=[0,1]`` - enable GRE sequence
@ -444,12 +449,12 @@ options:
GRE has a number of caveats:
* You can use only one GRE connection per ip address. There is no way to
* You can use only one GRE connection per IP address. There is no way to
multiplex connections as each GRE tunnel is terminated directly on
the UML instance.
* The key is not really a security feature. While it was intended as such
it's "security" is laughable. It is, however, a useful feature to
its "security" is laughable. It is, however, a useful feature to
ensure that the tunnel is not misconfigured.
An example configuration for a Linux host with a local address of
@ -489,22 +494,22 @@ the L2TPv3 UDP flavour and UDP destination port $dst_port.
L2TPv3 always requires the following additional options:
* ``rx_session=int`` - l2tpv3 32 bit integer session for rx packets
* ``rx_session=int`` - l2tpv3 32-bit integer session for rx packets
* ``tx_session=int`` - l2tpv3 32 bit integer session for tx packets
* ``tx_session=int`` - l2tpv3 32-bit integer session for tx packets
As the tunnel is fixed these are not negotiated and they are
preconfigured on both ends.
Additionally, L2TPv3 supports the following optional parameters
Additionally, L2TPv3 supports the following optional parameters.
* ``rx_cookie=int`` - l2tpv3 32 bit integer cookie for rx packets - same
* ``rx_cookie=int`` - l2tpv3 32-bit integer cookie for rx packets - same
functionality as GRE key, more to prevent misconfiguration than provide
actual security
* ``tx_cookie=int`` - l2tpv3 32 bit integer cookie for tx packets
* ``tx_cookie=int`` - l2tpv3 32-bit integer cookie for tx packets
* ``cookie64=[0,1]`` - use 64 bit cookies instead of 32 bit.
* ``cookie64=[0,1]`` - use 64-bit cookies instead of 32-bit.
* ``counter=[0,1]`` - enable l2tpv3 counter
@ -518,12 +523,12 @@ Additionally, L2TPv3 supports the following optional parameters
L2TPv3 has a number of caveats:
* you can use only one connection per ip address in raw mode. There is
* you can use only one connection per IP address in raw mode. There is
no way to multiplex connections as each L2TPv3 tunnel is terminated
directly on the UML instance. UDP mode can use different ports for
this purpose.
Here is an example of how to configure a linux host to connect to UML
Here is an example of how to configure a Linux host to connect to UML
via L2TPv3:
**/etc/network/interfaces**::
@ -586,7 +591,7 @@ distribution or a custom built kernel has been installed on the host.
These add an executable called linux to the system. This is the UML
kernel. It can be run just like any other executable.
It will take most normal linux kernel arguments as command line
arguments. Additionally, it will need some UML specific arguments
arguments. Additionally, it will need some UML-specific arguments
in order to do something useful.
Arguments
@ -595,7 +600,7 @@ Arguments
Mandatory Arguments:
--------------------
* ``mem=int[K,M,G]`` - amount of memory. By default bytes. It will
* ``mem=int[K,M,G]`` - amount of memory. By default in bytes. It will
also accept K, M or G qualifiers.
* ``ubdX[s,d,c,t]=`` virtual disk specification. This is not really
@ -603,7 +608,7 @@ Mandatory Arguments:
specify a root file system.
The simplest possible image specification is the name of the image
file for the filesystem (created using one of the methods described
in `Creating an image`_)
in `Creating an image`_).
* UBD devices support copy on write (COW). The changes are kept in
a separate file which can be discarded allowing a rollback to the
@ -613,15 +618,15 @@ Mandatory Arguments:
* UBD devices can be set to use synchronous IO. Any writes are
immediately flushed to disk. This is done by adding ``s`` after
the ``ubdX`` specification
the ``ubdX`` specification.
* UBD performs some euristics on devices specified as a single
* UBD performs some heuristics on devices specified as a single
filename to make sure that a COW file has not been specified as
the image. To turn them off, use the ``d`` flag after ``ubdX``
the image. To turn them off, use the ``d`` flag after ``ubdX``.
* UBD supports TRIM - asking the Host OS to reclaim any unused
blocks in the image. To turn it off, specify the ``t`` flag after
``ubdX``
``ubdX``.
* ``root=`` root device - most likely ``/dev/ubd0`` (this is a Linux
filesystem image)
@ -631,7 +636,7 @@ Important Optional Arguments
If UML is run as "linux" with no extra arguments, it will try to start an
xterm for every console configured inside the image (up to 6 in most
linux distributions). Each console is started inside an
Linux distributions). Each console is started inside an
xterm. This makes it nice and easy to use UML on a host with a GUI. It is,
however, the wrong approach if UML is to be used as a testing harness or run
in a text-only environment.
@ -656,10 +661,10 @@ one is input, the second one output.
* The null channel - Discard all input or output. Example ``con=null`` will set
all consoles to null by default.
* The fd channel - use file descriptor numbers for input/out. Example:
* The fd channel - use file descriptor numbers for input/output. Example:
``con1=fd:0,fd:1.``
* The port channel - listen on tcp port number. Example: ``con1=port:4321``
* The port channel - listen on TCP port number. Example: ``con1=port:4321``
* The pty and pts channels - use system pty/pts.
@ -667,7 +672,7 @@ one is input, the second one output.
will make UML use the host 8th console (usually unused).
* The xterm channel - this is the default - bring up an xterm on this channel
and direct IO to it. Note, that in order for xterm to work, the host must
and direct IO to it. Note that in order for xterm to work, the host must
have the UML distribution package installed. This usually contains the
port-helper and other utilities needed for UML to communicate with the xterm.
Alternatively, these need to be complied and installed from source. All
@ -685,7 +690,7 @@ We can now run UML.
vec0:transport=tap,ifname=tap0,depth=128,gro=1 \
root=/dev/ubda con=null con0=null,fd:2 con1=fd:0,fd:1
This will run an instance with ``2048M RAM``, try to use the image file
This will run an instance with ``2048M RAM`` and try to use the image file
called ``Filesystem.img`` as root. It will connect to the host using tap0.
All consoles except ``con1`` will be disabled and console 1 will
use standard input/output making it appear in the same terminal it was started.
@ -702,7 +707,7 @@ The UML Management Console
============================
In addition to managing the image from "the inside" using normal sysadmin tools,
it is possible to perform a number of low level operations using the UML
it is possible to perform a number of low-level operations using the UML
management console. The UML management console is a low-level interface to the
kernel on a running UML instance, somewhat like the i386 SysRq interface. Since
there is a full-blown operating system under UML, there is much greater
@ -726,7 +731,7 @@ kernel. When you boot UML, you'll see a line like::
mconsole initialized on /home/jdike/.uml/umlNJ32yL/mconsole
If you specify a unique machine id one the UML command line, i.e.
If you specify a unique machine id on the UML command line, i.e.
``umid=debian``, you'll see this::
mconsole initialized on /home/jdike/.uml/debian/mconsole
@ -881,11 +886,11 @@ be able to cache the shared data using a much smaller amount of memory,
so UML disk requests will be served from the host's memory rather than
its disks. There is a major caveat in doing this on multisocket NUMA
machines. On such hardware, running many UML instances with a shared
master image and COW changes may caise issues like NMIs from excess of
master image and COW changes may cause issues like NMIs from excess of
inter-socket traffic.
If you are running UML on high end hardware like this, make sure to
bind UML to a set of logical cpus residing on the same socket using the
If you are running UML on high-end hardware like this, make sure to
bind UML to a set of logical CPUs residing on the same socket using the
``taskset`` command or have a look at the "tuning" section.
To add a copy-on-write layer to an existing block device file, simply
@ -986,7 +991,7 @@ specify a subdirectory to mount with the -o switch to mount::
# mount none /mnt/home -t hostfs -o /home
will mount the hosts's /home on the virtual machine's /mnt/home.
will mount the host's /home on the virtual machine's /mnt/home.
hostfs as the root filesystem
-----------------------------
@ -1035,7 +1040,7 @@ The UBD driver, SIGIO and the MMU emulation do that. If the system is
idle, these threads will be migrated to other processors on a SMP host.
This, unfortunately, will usually result in LOWER performance because of
all of the cache/memory synchronization traffic between cores. As a
result, UML will usually benefit from being pinned on a single CPU
result, UML will usually benefit from being pinned on a single CPU,
especially on a large system. This can result in performance differences
of 5 times or higher on some benchmarks.
@ -1061,7 +1066,7 @@ filesystems, devices, virtualization, etc. It provides unrivalled
opportunities to create and test them without being constrained to
emulating specific hardware.
Example - want to try how linux will work with 4096 "proper" network
Example - want to try how Linux will work with 4096 "proper" network
devices?
Not an issue with UML. At the same time, this is something which
@ -1070,10 +1075,10 @@ constrained by the number of devices allowed on the hardware bus
they are trying to emulate (for example 16 on a PCI bus in qemu).
If you have something to contribute such as a patch, a bugfix, a
new feature, please send it to ``linux-um@lists.infradead.org``
new feature, please send it to ``linux-um@lists.infradead.org``.
Please follow all standard Linux patch guidelines such as cc-ing
relevant maintainers and run ``./sripts/checkpatch.pl`` on your patch.
relevant maintainers and run ``./scripts/checkpatch.pl`` on your patch.
For more details see ``Documentation/process/submitting-patches.rst``
Note - the list does not accept HTML or attachments, all emails must
@ -1082,21 +1087,21 @@ be formatted as plain text.
Developing always goes hand in hand with debugging. First of all,
you can always run UML under gdb and there will be a whole section
later on on how to do that. That, however, is not the only way to
debug a linux kernel. Quite often adding tracing statements and/or
debug a Linux kernel. Quite often adding tracing statements and/or
using UML specific approaches such as ptracing the UML kernel process
are significantly more informative.
Tracing UML
=============
When running UML consists of a main kernel thread and a number of
When running, UML consists of a main kernel thread and a number of
helper threads. The ones of interest for tracing are NOT the ones
that are already ptraced by UML as a part of its MMU emulation.
These are usually the first three threads visible in a ps display.
The one with the lowest PID number and using most CPU is usually the
kernel thread. The other threads are the disk
(ubd) device helper thread and the sigio helper thread.
(ubd) device helper thread and the SIGIO helper thread.
Running ptrace on this thread usually results in the following picture::
host$ strace -p 16566
@ -1121,21 +1126,21 @@ Running ptrace on this thread usually results in the following picture::
--- SIGALRM {si_signo=SIGALRM, si_code=SI_TIMER, si_timerid=0, si_overrun=0, si_value={int=1631716592, ptr=0x614204f0}} ---
rt_sigreturn({mask=[PIPE]}) = -1 EINTR (Interrupted system call)
This is a typical picture from a mostly idle UML instance
This is a typical picture from a mostly idle UML instance.
* UML interrupt controller uses epoll - this is UML waiting for IO
interrupts:
epoll_wait(4, [{EPOLLIN, {u32=3721159424, u64=3721159424}}], 64, 0) = 1
* The sequence of ptrace calls is part of MMU emulation and runnin the
UML userspace
* The sequence of ptrace calls is part of MMU emulation and running the
UML userspace.
* ``timer_settime`` is part of the UML high res timer subsystem mapping
timer requests from inside UML onto the host high resultion timers.
timer requests from inside UML onto the host high resolution timers.
* ``clock_nanosleep`` is UML going into idle (similar to the way a PC
will execute an ACPI idle).
As you can see UML will generate quite a bit of output even in idle.The output
As you can see UML will generate quite a bit of output even in idle. The output
can be very informative when observing IO. It shows the actual IO calls, their
arguments and returns values.
@ -1164,14 +1169,14 @@ in order to really leverage UML, one needs to write a piece of
userspace code which maps driver concepts onto actual userspace host
calls.
This forms the so called "user" portion of the driver. While it can
This forms the so-called "user" portion of the driver. While it can
reuse a lot of kernel concepts, it is generally just another piece of
userspace code. This portion needs some matching "kernel" code which
resides inside the UML image and which implements the Linux kernel part.
*Note: There are very few limitations in the way "kernel" and "user" interact*.
UML does not have a strictly defined kernel to host API. It does not
UML does not have a strictly defined kernel-to-host API. It does not
try to emulate a specific architecture or bus. UML's "kernel" and
"user" can share memory, code and interact as needed to implement
whatever design the software developer has in mind. The only
@ -1180,7 +1185,7 @@ variables having the same names, the developer should be careful
which includes and libraries they are trying to refer to.
As a result a lot of userspace code consists of simple wrappers.
F.e. ``os_close_file()`` is just a wrapper around ``close()``
E.g. ``os_close_file()`` is just a wrapper around ``close()``
which ensures that the userspace function close does not clash
with similarly named function(s) in the kernel part.
@ -1188,7 +1193,7 @@ Security Considerations
-----------------------
Drivers or any new functionality should default to not
accepting arbitrary filename, bpf code or other parameters
accepting arbitrary filename, bpf code or other parameters
which can affect the host from inside the UML instance.
For example, specifying the socket used for IPC communication
between a driver and the host at the UML command line is OK