# Zircon Kernel Command Line Options

See [//docs/gen/boot-options.md](/docs/gen/boot-options.md) is now the source of
truth.

The Zircon kernel receives a textual command line from the bootloader, which can
be used to alter some behaviours of the system. Kernel command line parameters
are in the form of *option* or *option=value*, separated by spaces, and may not
contain spaces.

For boolean options, *option=0*, *option=false*, or *option=off* will disable
the option. Any other form (*option*, *option=true*, *option=wheee*, etc) will
enable it.

The kernel command line is passed from the kernel to the userboot process and
the device manager, so some of the options described below apply to those
userspace processes, not the kernel itself.

If keys are repeated, the last value takes precedence, that is, later settings
override earlier ones.

Component Manager reads the file `/boot/config/additional_boot_args` (if it
exists) at startup and imports name=value lines into its environment, augmenting
or overriding the values from the kernel command line. Leading whitespace is
ignored and lines starting with # are ignored. Whitespace is not allowed in
names.

In order to specify options in the build, see
[this guide](/docs/development/kernel/build.md#options).

## bootsvc.next=\<bootfs path\>

Controls what program is executed by bootsvc to continue the boot process. If
this is not specified, the default next program will be used.

Arguments to the program can optionally be specified using a comma separator
between the program and individual arguments. For example,
'bootsvc.next=bin/mybin,arg1,arg2'.

## console.shell=\<bool\>

If this option is set to true driver_manager will launch the shell if
kernel.shell has not already been launched. Defaults to false.

If this is false, it also disables the zircon.autorun.boot and
zircon.autorun.system options.

## driver.\<name>.tests.enable=\<bool>

Enable the unit tests for an individual driver. The unit tests will run before
the driver binds any devices. If `driver.tests.enable` is true then this
defaults to enabled, otherwise the default is disabled.

Note again that the name of the driver is the "Driver" argument to the
ZIRCON\_DRIVER macro. It is not, for example, the name of the device, which for
some drivers is almost identical, except that the device may be named "foo-bar"
whereas the driver name must use underscores, e.g., "foo_bar".

## driver.tests.enable=\<bool>

Enable the unit tests for all drivers. The unit tests will run before the
drivers bind any devices. It's also possible to enable tests for an individual
driver, see `driver.\<name>.enable_tests`. The default is disabled.

### x64 specific values

On x64, some additional values are supported for configuring 8250-like UARTs:

-   If set to `legacy`, the legacy COM1 interface is used.
-   If set to `acpi`, the UART specified by the `DBG2` ACPI entry on the system
    will be used, if available.
-   A port-io UART can be specified using `ioport,\<portno>,\<irq>`.
-   An MMIO UART can be specified using `mmio,\<physaddr>,\<irq>`.

For example, `ioport,0x3f8,4` would describe the legacy COM1 interface.

All numbers may be in any base accepted by *strtoul*().

All other values are currently undefined.

## ldso.trace

This option (disabled by default) turns on dynamic linker trace output. The
output is in a form that is consumable by clients like Intel Processor Trace
support.

## zircon.autorun.boot=\<command>

This option requests that *command* be run at boot.

Commands should be absolute paths starting at the root '/'.

Any `+` characters in *command* are treated as argument separators, allowing you
to pass arguments to an executable.

This option is disabled if console.shell is false.

## zircon.autorun.system=\<command>

This option requests that *command* be run once the system partition is mounted.
If there is no system partition, it will never be launched.

Commands should be absolute paths starting at the root '/'.

Any `+` characters in *command* are treated as argument separators, allowing you
to pass arguments to an executable.

This option is disabled if console.shell is false.

## zircon.system.pkgfs.cmd=\<command>

This option requests that *command* be run once the blob partition is mounted.
Any `+` characters in *command* are treated as argument separators, allowing you
to pass arguments to an executable.

The executable and its dependencies (dynamic linker and shared libraries) are
found in the blob filesystem. The executable *path* is *command* before the
first `+`. The dynamic linker (`PT_INTERP`) and shared library (`DT_NEEDED`)
name strings sent to the loader service are prefixed with `lib/` to produce a
*path*. Each such *path* is resolved to a blob ID (i.e. merkleroot in ASCII hex)
using the `zircon.system.pkgfs.file.`*path* command line argument. In this way,
`/boot/config/additional_boot_args` contains a fixed manifest of files used to
start the process.

The new process receives a `PA_USER0` channel handle at startup that will be
used as the client filesystem handle mounted at `/pkgfs`. `/pkgfs/system` will
also be mounted as `/system`.

## zircon.system.pkgfs.file.*path*=\<blobid>

Used with [`zircon.system.pkgfs.cmd`](#zircon.system.pkgfs.cmd), above.

## netsvc.netboot=\<bool>

If true, zircon will attempt to netboot into another instance of zircon upon
booting.

More specifically, zircon will fetch a new zircon system from a bootserver on
the local link and attempt to kexec into the new image, thereby replacing the
currently running instance of zircon.

This setting implies **zircon.system.disable-automount=true**

## netsvc.disable=\<bool>

If set to true (default), `netsvc` is disabled.

## netsvc.advertise=\<bool>

If true, netsvc will seek a bootserver by sending netboot advertisements.
Defaults to true.

## netsvc.interface=\<path>

This option instructs netsvc to use only the device whose topological path ends
with the option's value, with any wildcard `*` characters matching any zero or
more characters of the topological path. All other devices are ignored by
netsvc. The topological path for a device can be determined from the shell by
running the `lsdev` command on the device e.g. `/dev/class/network/000` or
`/dev/class/ethernet/000`).

This is useful for configuring network booting for a device with multiple
ethernet ports, which may be enumerated in a non-deterministic order.

## netsvc.all-features=\<bool>

This option makes `netsvc` work normally and support all features. By default,
`netsvc` starts in a minimal mode where only device discovery is supported.

## userboot.next=\<path>

This option instructs the userboot process (the first userspace process) to
execute the specified binary within the bootfs, instead of following the normal
userspace startup process (launching the device manager, etc).

It is useful for alternate boot modes (like a factory test or system unit
tests).

The pathname used here is relative to `userboot.root` (below), if set, or else
relative to the root of the BOOTFS (which later is ordinarily seen at `/boot`).
It should not start with a `/` prefix.

If this executable uses `PT_INTERP` (i.e. the dynamic linker), the userboot
process provides a
[loader service](/docs/concepts/process/program_loading.md#the-loader-service)
to resolve the `PT_INTERP` (dynamic linker) name and any shared library names it
may request. That service simply looks in the `lib/` directory (under
`userboot.root`) in the BOOTFS.

Arguments to the next program can optionally be specified using a '+' separator
between the program and individual arguments. The next program name will always
be provided as the first argument.

Example: `userboot.next=bin/core-tests+arg1+arg2=foo`

## userboot.root=\<path>

This sets a "root" path prefix within the BOOTFS where the `userboot.next` path
and the `lib/` directory for the loader service will be found. By default, there
is no prefix so paths are treated as exact relative paths from the root of the
BOOTFS. e.g. with `userboot.root=pkg/foo` and `userboot.next=bin/app`, the names
found in the BOOTFS will be `pkg/foo/bin/app`, `pkg/foo/lib/ld.so.1`, etc.

## userboot.shutdown

If this option is set, userboot will attempt to power off the machine when the
process it launches exits. Note if `userboot.reboot` is set then
`userboot.shutdown` will be ignored.

## zircon.nodename=\<name>

Set the system nodename, as used by `bootserver`, `loglistener`, and the
`net{addr,cp,ls,runcmd}` tools. If omitted, the system will generate a nodename
from its MAC address. This cmdline is honored by GigaBoot and Zircon.

## zircon.namegen=\<num>

Set the system nodename generation style. If omitted or unknown, the system uses
style 1. It has no effect if `zircon.nodename` is set. Older name generation
styles may be removed in the future. This cmdline is honored by GigaBoot and
Zircon.

Styles: - 0: Uses a four-word-name-style using based on the MAC address. - 1:
fuchsia-0123-4567-89ab based on the MAC address.

## zvb.current\_slot=\<\_a|\_b|\_r>

Makes Fuchsia aware of the slot booted by the bootloader. Setting this also
informs the paver that ABR is supported, and that it should update the ABR
metadata.

## zvb.boot-partition-uuid=\<UUID>

An alternative to zvb.current_slot - makes Fuchsia aware of the slot booted by
the bootloader by passing the UUID of the partition containing the Zircon kernel
that was booted. Setting this also informs the paver that ABR is supported, and
that it should update the ABR metadata.

## console.device_topological_suffix=\<path>

If this is set then console launcher will connect to the console device whose
topological path matches this suffix. If not specified then console launcher
will connect to `/svc/console`. Only has effect if kernel.shell=false.

# Additional Gigaboot Command Line Options

## bootloader.timeout=\<num>

This option sets the boot timeout in the bootloader, with a default of 3
seconds. Set to zero to skip the boot menu.

## bootloader.fbres=\<w>x\<h>

This option sets the framebuffer resolution. Use the bootloader menu to display
available resolutions for the device.

Example: `bootloader.fbres=640x480`

## bootloader.default=\<network|local|zedboot>

This option sets the default boot device to netboot, use a local zircon.bin or
to netboot via zedboot.

# How to pass the command line to the kernel

## in the emulator or Qemu, using ffx emu or fx qemu

Pass each option using -c, for example:

```
ffx emu start -c gfxconsole.font=18x32 -c gfxconsole.early=false
```

## in GigaBoot20x6, when netbooting

Pass the kernel command line at the end, after a -- separator, for example:

```
bootserver zircon.bin bootfs.bin -- gfxconsole.font=18x32 gfxconsole.early=false
```

## in GigaBoot20x6, when booting from USB flash

Create a text file named "cmdline" in the root of the USB flash drive's
filesystem containing the command line.