diff options
Diffstat (limited to 'Documentation/virt/uml')
| -rw-r--r-- | Documentation/virt/uml/user_mode_linux_howto_v2.rst | 119 |
1 files changed, 62 insertions, 57 deletions
diff --git a/Documentation/virt/uml/user_mode_linux_howto_v2.rst b/Documentation/virt/uml/user_mode_linux_howto_v2.rst index 312e431695d9..2cafd3c3c6cb 100644 --- a/Documentation/virt/uml/user_mode_linux_howto_v2.rst +++ b/Documentation/virt/uml/user_mode_linux_howto_v2.rst @@ -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 |