linux.sgml 20.3 KB
Newer Older
Stefano Melchior's avatar
Stefano Melchior committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74
<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [

<!-- Process this file with docbook-to-man to generate an nroff manual
     page: `docbook-to-man manpage.sgml > manpage.1'.  You may view
     the manual page with: `docbook-to-man manpage.sgml | nroff -man |
     less'.  A typical entry in a Makefile or Makefile.am is:

manpage.1: manpage.sgml
	docbook-to-man $< > $@
  -->

  <!-- Fill in your name for FIRSTNAME and SURNAME. -->
  <!ENTITY dhfirstname "<firstname>Matt</firstname>">
  <!ENTITY dhsurname   "<surname>Zimmerman</surname>">
  <!-- Please adjust the date whenever revising the manpage. -->
  <!ENTITY dhdate      "<date>December  6, 2001</date>">
  <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
       allowed: see man(7), man(1). -->
  <!ENTITY dhsection   "<manvolnum>1</manvolnum>">
  <!ENTITY dhemail     "<email>mdz@debian.org</email>">
  <!ENTITY dhusername  "Matt Zimmerman">
  <!ENTITY dhucpackage "<refentrytitle>LINUX</refentrytitle>">
  <!ENTITY dhpackage   "linux">

  <!ENTITY debian      "<productname>Debian GNU/Linux</productname>">
  <!ENTITY gnu         "<acronym>GNU</acronym>">
]>

<refentry>
  <refentryinfo>
    <address>
      &dhemail;
    </address>
    <author>
      &dhfirstname;
      &dhsurname;
    </author>
    <copyright>
      <year>2001</year>
      <holder>&dhusername;</holder>
    </copyright>
    &dhdate;
  </refentryinfo>
  <refmeta>
    &dhucpackage;

    &dhsection;
  </refmeta>
  <refnamediv>
    <refname>&dhpackage;</refname>

    <refpurpose>User-mode Linux</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <cmdsynopsis>
      <command>linux</command>
      <arg choice=opt rep=repeat><replaceable>options</replaceable></arg>

    </cmdsynopsis>
  </refsynopsisdiv>
  <refsect1>
    <title>DESCRIPTION</title>

    <para>This manual page briefly documents User-mode Linux.</para>

    <para>This manual page was written for the &debian; distribution
      because the original program does not have a manual page.  Check
      <command>linux --help</command> for an up-to-date synopsis.</para>

  </refsect1>
  <refsect1>
    <title>OPTIONS</title>

    <variablelist>
75
    
Stefano Melchior's avatar
Stefano Melchior committed
76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111
      <varlistentry>
        <term>mem=<replaceable>memory</replaceable>
        </term>
        <listitem>
          <para>
            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.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>iomem=<replaceable>name</replaceable>,<replaceable>file</replaceable>
        </term>
        <listitem>
          <para>
            Configure <replaceable>file</replaceable> as a named IO
            memory region named <replaceable>name</replaceable>.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>gdb-pid=<replaceable>pid</replaceable></term>
        <listitem>
          <para>
            gdb-pid is used to attach an external debugger to UML.
            This may be an already-running gdb or a debugger-like
            process like strace.
          </para>
        </listitem>
      </varlistentry>
112

Stefano Melchior's avatar
Stefano Melchior committed
113 114 115 116 117 118 119 120 121 122 123
      <varlistentry>
        <term>debugtrace</term>
        <listitem>
          <para>
            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.
          </para>
        </listitem>
      </varlistentry>
124

Stefano Melchior's avatar
Stefano Melchior committed
125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153
      <varlistentry>
        <term>honeypot</term>
        <listitem>
          <para>
            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.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>debug</term>
        <listitem>
          <para>
            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.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>root=<replaceable>file</replaceable></term>
        <listitem>
          <para>
            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
154 155 156
            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.
Stefano Melchior's avatar
Stefano Melchior committed
157 158 159 160 161 162 163 164 165 166 167 168 169 170 171
          </para>

          <para>
            To use hostfs for the root filesystem, use the syntax
            "root=/dev/root rootflags=/ rootfstype=hostfs"
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>umid=<replaceable>name</replaceable></term>
        <listitem>
          <para>
            This is used to assign a unique identity to this UML
            machine This is used for naming the pid file and
172 173 174
            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.
Stefano Melchior's avatar
Stefano Melchior committed
175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>uml_dir=<replaceable>directory</replaceable></term>
        <listitem>
          <para>
            The location to place the pid and umid files.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>initrd=<replaceable>file</replaceable></term>
        <listitem>
          <para>
            This is used to boot UML from an initrd image.  The
            argument is the name of the file containing the image.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>jail</term>
        <listitem>
          <para>
            Enables the protection of kernel memory from processes
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>con[0-9]*=<replaceable>description</replaceable></term>
        <listitem>
          <para>
            Attach a console to a host channel.  Examples of channels
            include ttys, ptys, pts terminals, xterms, and file
            descriptors.
          </para>
          <variablelist>
            <varlistentry>
              <term>tty</term>
              <listitem>
                <para>
                  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.
                  <userinput>con1=tty:/dev/tty3</userinput>
                </para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>pty</term>
              <listitem>
                <para>
                  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.
                  <userinput>con1=pty</userinput>
                </para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>pts terminal</term>
              <listitem>
                <para>
                  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.
                  <userinput>con1=pts</userinput>
                </para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>xterm</term>
              <listitem>
                <para>
                  UML will run an xterm and the device will be
                  attached to it.
                  <userinput>con1=xterm</userinput>
                </para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>file descriptors</term>
              <listitem>
                <para>
                  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.
                  <userinput>con0=fd:0,fd:1 con=xterm</userinput>
                </para>
              </listitem>
            </varlistentry>
          </variablelist>

          <para>You can also specify different input and output
282 283 284 285 286 287
		channels for a device by putting a comma between them:
		<userinput>ssl3=tty:/dev/tty2,xterm</userinput>
	  </para>
	  <para>See <ulink
		url="file:///usr/share/doc/user-mode-linux-doc/html/input.html">Setting
		up Serial Lines and Consoles</ulink> for a more information.
Stefano Melchior's avatar
Stefano Melchior committed
288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>ssl[0-9]*=<replaceable>description</replaceable></term>
        <listitem>
          <para>
            Attach a serial line to a host channel.  The same options
            are supported as for consoles, described above.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>fake_ide</term>
        <listitem>
          <para>
            Create ide0 entries that map onto ubd devices.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>ubd[0-7][r][s]=file</term>
        <listitem>
          <para>

            <simplelist>
              <member>
                <userinput>ubd0r=/tmp/debian-woody.ext2</userinput>
              </member>

              <member>
                <userinput>ubd0rs=/tmp/debian-woody.ext2</userinput>
              </member>

              <member>
                <userinput>ubd0=/tmp/chroot</userinput>
              </member>

            </simplelist>
            </para>

          <para>

            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).

          </para>

          <para>
            The ubd option can no longer be used to specify a hostfs
            root filesystem.  See the "root" option for a more correct
            method.
          </para>

        </listitem>
      </varlistentry>

355 356 357 358 359 360 361 362 363 364 365 366
      <varlistentry>
        <term>udb</term>
        <listitem>
          <para>
	    This option is here solely to catch ubd -&gt; 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.
          </para>
        </listitem>
      </varlistentry>

Stefano Melchior's avatar
Stefano Melchior committed
367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385
      <varlistentry>
        <term>fakehd</term>
        <listitem>
          <para>
            Change the ubd device name to "hd", allowing programs
            within UML to access UBD devices as if they were normal
            IDE disks.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>eth[0-9]+=<replaceable>transport</replaceable>,<replaceable>options</replaceable></term>
        <listitem>
          <para>
            Configure a network device.  Formats and examples follow (one 
            for each configured transport).
          </para>

386 387
          <simplelist>
          <member>
Stefano Melchior's avatar
Stefano Melchior committed
388
            eth[0-9]+=ethertap,<replaceable>device</replaceable>,<replaceable>ethernet_address</replaceable>,<replaceable>tap_ip_address</replaceable>
389 390
	  </member>
          <member>
Stefano Melchior's avatar
Stefano Melchior committed
391 392 393
            <userinput>
              eth0=ethertap,tap0,,192.168.0.1
            </userinput>
394 395
	  </member>
	  <member>
Stefano Melchior's avatar
Stefano Melchior committed
396
            eth[0-9]+=tuntap,,<replaceable>ethernet_address</replaceable>,<replaceable>ip_address</replaceable>
397 398
	  </member>
          <member>
Stefano Melchior's avatar
Stefano Melchior committed
399 400 401
            <userinput>
              eth0=tuntap,,fe:fd:0:0:0:1,192.168.0.1
            </userinput>
402 403
	  </member>
	  <member>
Stefano Melchior's avatar
Stefano Melchior committed
404
            eth[0-9]+=daemon,<replaceable>ethernet_address</replaceable>,<replaceable>type</replaceable>,<replaceable>control_socket</replaceable>,<replaceable>data_socket</replaceable>
405 406
	  </member>
	  <member>
Stefano Melchior's avatar
Stefano Melchior committed
407 408 409
            <userinput>
              eth0=daemon,,unix,/var/run/uml-utilities/uml_switch.ctl
            </userinput>
410 411
	  </member>
	  <member>
Stefano Melchior's avatar
Stefano Melchior committed
412
            eth[0-9]+=slip,<replaceable>slip_ip</replaceable>
413 414
	  </member>
	  <member>
Stefano Melchior's avatar
Stefano Melchior committed
415 416 417
            <userinput>
              eth0=slip,192.168.0.1
            </userinput>
418 419
	  </member>
	  <member>
Stefano Melchior's avatar
Stefano Melchior committed
420
            eth[0-9]+=mcast,<replaceable>ethernet_address</replaceable>,<replaceable>address</replaceable>,<replaceable>port</replaceable>,<replaceable>ttl</replaceable>
421 422
	  </member>
	  <member>
Stefano Melchior's avatar
Stefano Melchior committed
423 424 425
            <userinput>
              eth0=mcast,,224.2.3.4:5555,3
            </userinput>
426 427
	  </member>
	  </simplelist>
Stefano Melchior's avatar
Stefano Melchior committed
428 429 430 431 432 433 434 435 436 437 438 439 440 441 442

        </listitem>
      </varlistentry>

      <varlistentry>
        <term>mode=tt</term>
        <listitem>
          <para>
            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.
          </para>
        </listitem>
      </varlistentry>
443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573
      
      <varlistentry>
        <term>mode=skas0</term>
        <listitem>
          <para>
	    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".
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>skas0</term>
        <listitem>
          <para>
	    Disables SKAS3 usage, so that SKAS0 is used, unless
	    you specify mode=tt.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>mconsole=notify:<replaceable>socket</replaceable></term>
        <listitem>
          <para>
	    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.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>aio=2.4</term>
        <listitem>
          <para>
	    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.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>hostfs=<replaceable>rootdir</replaceable>,<replaceable>flags</replaceable></term>
        <listitem>
          <para>
	    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 mode.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>xterm=<replaceable>terminal emulator</replaceable>,<replaceable>title switch</replaceable>,<replaceable>exec switch</replaceable></term>
        <listitem>
          <para>
	    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
	    '&lt;switch&gt; title', not '&lt;switch&gt;=title'.  Similarly, the
	    exec switch must have the form '&lt;switch&gt; command arg1 arg2
	    ...'.
	    The default values are 'xterm=xterm,-T,-e'.  Values for
	    gnome-terminal are 'xterm=gnome-terminal,-t,-x'.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>noptraceldt</term>
        <listitem>
          <para>
	    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.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>noptracefaultinfo</term>
        <listitem>
          <para>
	    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.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>noprocmm</term>
        <listitem>
          <para>
	    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.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>nosysemu</term>
        <listitem>
          <para>
	    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.
          </para>
        </listitem>
      </varlistentry>
Stefano Melchior's avatar
Stefano Melchior committed
574 575 576 577 578 579 580 581 582 583 584 585 586 587

      <varlistentry>
        <term>--help</term>
        <listitem>
          <para>
            Prints syntax information.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>--version</term>
        <listitem>
          <para>
588
            Prints the version number of the kernel.
Stefano Melchior's avatar
Stefano Melchior committed
589 590 591 592
          </para>
        </listitem>
      </varlistentry>

593 594 595 596
      <varlistentry>
        <term>--showconfig</term>
        <listitem>
          <para>
597 598 599 600
           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
	   <userinput>linux --showconfig &gt; config_file</userinput>
601 602 603
          </para>
        </listitem>
      </varlistentry>
Stefano Melchior's avatar
Stefano Melchior committed
604
    </variablelist>
605 606

</refsect1>
Stefano Melchior's avatar
Stefano Melchior committed
607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642
  <refsect1>
    <title>SEE ALSO</title>

    <para>The <ulink
    url="file:///usr/share/doc/user-mode-linux-doc/html/UserModeLinux-HOWTO.html">UserModeLinux-HOWTO</ulink></para>

  </refsect1>
  <refsect1>
    <title>AUTHOR</title>

    <para>User-mode Linux was written by Jeff Dike and others.</para>

    <para>This manual page was written by &dhusername; &dhemail; for
      the &debian; system, based on <command>linux --help</command>
      and the user-mode-linux website.
    </para>

  </refsect1>
</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->