# Configuring FFX

Last updated 2025-01-27

The `ffx` tool supports many configuration values to tweak its behaviour. This
is an attempt to centralize the available configuration values and document
them.

Note this document is (for now) manually updated and as such may be out of date.

When updating, please add the value in alphabetical order.

    | Configuration Value                     | Documentation                      |
    | --------------------------------------- | ---------------------------------- |
    | `connectivity.direct`                   | Support direct target connections. |
    |                                         | Defaults to `false`.               |
    | `connectivity.enable_network`           | Enable using MDNS to discover      |
    |                                         | targets and SSH to connect to      |
    |                                         | them. Defaults to `true`.          |
    | `connectivity.enable_usb`               | Allow ffx to use a USB connection. |
    |                                         | Not supported on mac. Defaults to  |
    |                                         | `false`.                           |
    | `connectivity.enable_vsock`             | Allow using a VSOCK socket to      |
    |                                         | connect to virtual machine targets |
    |                                         | where supported. Defaults to       |
    |                                         | `false`.                           |
    | `connectivity.usb_driver_autostart`     | Allow ffx to start a driver        |
    |                                         | process in the background to       |
    |                                         | enable USB connections. Defaults   |
    |                                         | to `true`, but does not apply in   |
    |                                         | strict mode, isolates, or when USB |
    |                                         | connections are disabled.          |
    | `connectivity.usb_socket_path`          | Path to the socket that will be    |
    |                                         | used to communicate with the USB   |
    |                                         | driver. Defaults to                |
    |                                         | `$XDG_RUNTIME_DIR/ffx_usb.sock`.   |
    | `daemon.autostart`                      | Determines if the daemon should    |
    |                                         | start automatically when a subtool |
    |                                         | that requires the daemon is        |
    |                                         | invoked.  Defaults to `true`.      |
    | `daemon.host_pipe_ssh_timeout`          | Time the daemon waits for an       |
    |                                         | initial response from ssh on the   |
    |                                         | target. Defaults to `50` seconds.  |
    | `discovery.cache_dir`                   | Specifies the location of the      |
    |                                         | discovery cache directory, in      |
    |                                         | which the cache and pid files will |
    |                                         | be stored. Defaults to             |
    |                                         | `$CACHE/discovery`.                |
    | `discovery.expire_targets`              | Determines if targets discovered   |
    |                                         | should expire. Defaults to `true`  |
    | `discovery.mdns.autoconnect`            | Determines whether to connect      |
    |                                         | automatically to targets           |
    |                                         | discovered through mDNS. Defaults  |
    |                                         | to `false`                         |
    | `discovery.mdns.enabled`                | Determines whether mDNS broadcasts |
    |                                         | are used to discover targets.      |
    |                                         | Default: `true`                    |
    | `discovery.timeout`                     | When doing _local_ discovery in    |
    |                                         | `ffx target list`, how long in     |
    |                                         | milliseconds to wait before        |
    |                                         | collecting responses. Defaults to  |
    |                                         | `2000`                             |
    | `discovery.zedboot.advert_port`         | Zedboot discovery port (must be a  |
    |                                         | nonzero u16). Default to `33331`   |
    | `discovery.zedboot.enabled`             | Determines if zedboot discovery is |
    |                                         | enabled. Defaults to `false`       |
    | `doctor.record_config`                  | Determines whether ffx doctor will |
    |                                         | record config data.  If unset, user|
    |                                         | will be prompted.                  |
    | `emu.console.enabled`                   | The experimental flag for the      |
    |                                         | console subcommand. Defaults to    |
    |                                         | `false`.                           |
    | `emu.device`                            | The default virtual device name to |
    |                                         | configure the emulator. Defaults   |
    |                                         | to `""` (the empty string), but can|
    |                                         | be overridden by the user.         |
    | `emu.engine`                            | The default engine to launch from  |
    |                                         | `ffx emu start`. Defaults to `femu`|
    |                                         | but can be overridden by the user. |
    | `emu.gpu`                               | The default gpu type to use in     |
    |                                         | `ffx emu start`. Defaults to       |
    |                                         | `auto`, but can be overridden by   |
    |                                         | the user.                          |
    | `emu.instance_dir`                      | The root directory for storing     |
    |                                         | instance specific data. Instances  |
    |                                         | should create a subdirectory in    |
    |                                         | this directory to store data.      |
    |                                         | Defaults to `$DATA/emu/instances`  |
    | `emu.kvm_path`                          | The filesystem path to the         |
    |                                         | system's KVM device. Must be       |
    |                                         | writable by the running process to |
    |                                         | utilize KVM for acceleration.      |
    |                                         | Defaults to `/dev/kvm`             |
    | `emu.start.timeout`                     | The duration (in seconds) to       |
    |                                         | attempt to establish an RCS        |
    |                                         | connection with a new emulator     |
    |                                         | before returning to the terminal.  |
    |                                         | Not used in --console or           |
    |                                         | ---monitor modes. Defaults to `60` |
    |                                         | seconds.                           |
    | `emu.upscript`                          | The full path to the script to run |
    |                                         | initializing any network           |
    |                                         | interfaces before starting the     |
    |                                         | emulator.                          |
    |                                         | Defaults to `""` (the empty string)|
    | `fastboot.devices_file.path`            | Path to the fastboot devices file. |
    |                                         | Defaults to                        |
    |                                         | `${HOME}/.fastboot/devices`        |
    | `fastboot.flash.min_timeout_secs`       | The minimum flash timeout (in      |
    |                                         | seconds) for flashing to a target  |
    |                                         | device. Defaults to `60` seconds   |
    | `fastboot.flash.timeout_rate`           | The timeout rate in mb/s when      |
    |                                         | communicating with the target      |
    |                                         | device. Defaults to `2` MB/sec     |
    | `fastboot.reboot.reconnect_timeout`     | Timeout in seconds to wait for     |
    |                                         | target after a reboot to fastboot  |
    |                                         | mode. Defaults to `10` seconds     |
    | `fastboot.tcp.open.retry.count`         | Number of times to retry when      |
    |                                         | connecting to a target in fastboot |
    |                                         | over TCP                           |
    | `fastboot.tcp.open.retry.wait`          | Time to wait for a response when   |
    |                                         | connecting to a target in fastboot |
    |                                         | over TCP                           |
    | `fastboot.usb.disabled`                 | Disables fastboot usb discovery if |
    |                                         | set to true. Defaults to `false`   |
    | `fidl.ir.path`                          | The path for looking up FIDL IR    |
    |                                         | encoding/decoding FIDL messages.   |
    |                                         | Default is unset                   |
    | `ffx.daemon_timeout`                    | How long to wait in milliseconds   |
    |                                         | when attempting to connect to the  |
    |                                         | daemon. Defaults to `15000`        |
    |                                         | Defaults to `false`                |
    | `ffx.isolated`                          | "Alias" for encapsulation of       |
    |                                         | config options used to request     |
    |                                         | isolation. Currently affects:      |
    |                                         | `fastboot.usb.disabled`,           |
    |                                         | `ffx.analytics.disabled`,          |
    |                                         | `discovery.mdns.enabled`,          |
    |                                         | `discovery.mdns.autoconnect`       |
    |                                         | Defaults to `false`                |
    | `ffx.subtool-search-paths`              | A list of paths to search for non- |
    |                                         | SDK subtool binaries. Defaults to  |
    |                                         | `$BUILD_DIR/host-tools`            |
    | `ffx.ui.mode`                           | Sets the ui mode for ffx and fx    |
    |                                         | options are "text" and "tui",      |
    |                                         | defaults to `text` for plaintext   |
    |                                         | output. 'tui' enables TUI mode     |
    |                                         | where available.                   |
    | `ffx.ui.overrides`                      | Allows per-command overrides of the|
    |                                         | UI mode. Commands are identified by|
    |                                         | tool-command, e.g. `fx-use`        |
    | `fuchsia.analytics.ffx_invoker`         | Optional string used to specify the|
    |                                         | invoker in analytics, e.g. "fx".   |
    |                                         | Default is to not specify an       |
    |                                         | invoker.                           |
    | `fuzzer.output`                         | Output directory when using `ffx   |
    |                                         | fuzz`. No default.                 |
    | `log.dir`                               | Location for ffx and daemon logs   |
    |                                         | Defaults to first available of:    |
    |                                         |   `$FFX_LOG_DIR`                   |
    |                                         |   `$FUCHSIA_TEST_OUTDIR/ffx_logs`  |
    |                                         |   `$CACHE/logs`                    |
    | `log.enabled`                           | Whether logging is enabled         |
    |                                         | Defaults to `true`                 |
    | `log.include_spans`                     | Whether spans (function names,     |
    |                                         | parameters, etc) are included      |
    |                                         | Defaults to `false`                |
    | `log.level`                             | Filter level for log messages      |
    |                                         | Overridable on specific components |
    |                                         | via `log.target_levels.<prefix>`.  |
    |                                         | Values are:                        |
    |                                         | `error`, `warn`, `info`, `debug`,  |
    |                                         | `trace`                            |
    |                                         | Defaults to `info`                 |
    | `log.rotate_size`                       | Limit of log size before log file  |
    |                                         | is rotated (if rotation is enabled)|
    |                                         | Defaults to no rotation            |
    | `log.rotations`                         | How many rotations of log files    |
    |                                         | to keep (0 to disable rotation)    |
    |                                         | Defaults to `5`                    |
    | `log.target_levels.<prefix>`            | Filter levels for components with  |
    |                                         | specified prefix. Values are:      |
    |                                         | `error`, `warn`, `info`, `debug`,  |
    |                                         | `trace`. No components are defined |
    |                                         | by default                         |
    | `log_cmd.color`                         | Whether to color logs based on     |
    |                                         | their severity. Defaults to `true`.|
    |                                         | Always disabled in strict mode.    |
    | `metrics.upload_timeout`                | Defaults to `2.0`                  |
    |                                         | The time in fractional seconds to  |
    |                                         | wait before giving up on uploading |
    |                                         | metrics data.                      |
    | `overnet.socket`                        | Path to the overnet socket.        |
    |                                         | Defaults to ASCENDD env variable,  |
    |                                         | or a dynamically-calculated path if|
    |                                         | unset.                             |
    | `pbms.base_urls`                        | List of base URLS (of scheme file: |
    |                                         | or gs:). Files are used directly,  |
    |                                         | gs links are used to construct     |
    |                                         | branch-specific GCS objects.       |
    | `product.path`                          | Path to a product bundle. No       |
    |                                         | default.                           |
    | `product.reboot.use_dm`                 | Specifies whether to use `dm` over |
    |                                         | `ssh` to reboot the product when in|
    |                                         | product mode. Default: false       |
    | `proxy.timeout_secs`                    | Timeout when connecting to the     |
    |                                         | target. Also settable with `ffx    |
    |                                         | --timeout <secs>.  Default: 1      |
    |                                         | second.                            |
    | `repository.connect_timeout_secs`       | Timeout when repostiroy server     |
    |                                         | connects to the target.            |
    |                                         | Default: 120 seconds               |
    | `repository.repositories`               |                                    |
    | `repository.registrations`              |                                    |
    | `repository.default`                    | Default repository name. Default to|
    |                                         | empty string                       |
    | `repository.process_dir`                | Path to directory containing       |
    |                                         | package server instances. No       |
    |                                         | default.                           |
    | `repository.server.mode`                |                                    |
    | `repository.server.enabled`             | If the repository server is        |
    |                                         | enabled. Defaults to `false`       |
    | `repository.server.listen`              |                                    |
    | `repository.server.last_used_address`   |                                    |
    | `ssh.allow_fdomain`                     | Allow FDomain to be used as a      |
    |                                         | remoting protocol. Defaults to     |
    |                                         | `false` unless ffx is in "strict"  |
    |                                         | mode.                              |
    | `ssh.auth-sock`                         | If set, the path to the            |
    |                                         | authorization socket for SSH used  |
    |                                         | by overnet. Defaults to unset      |
    | `ssh.authorized_keys_server_port`       | For debug builds, denotes the port |
    |                                         | on the device where authorized_keys|
    |                                         | are served for ssh key             |
    |                                         | verification. Defaults to 9797     |
    | `ssh.controlmaster.dir`                 | Directory for control sockets.     |
    |                                         | Defaults to                        |
    |                                         | `${XDG_RUNTIME_DIR}/ffx`.          |
    |                                         | Used in mode=managed               |
    | `ssh.controlmaster.mode`                | Sets the ControlMaster mode for    |
    |                                         | ssh. Defaults to `managed`.        |
    |                                         | Valid values are `none`, `managed` |
    |                                         | and `explicit`                     |
    | `ssh.controlmaster.path`                | Path to the control socket.        |
    |                                         | Used in mode=explicit.             |
    | `ssh.keepalive_timeout`                 | Time for an ssh connection to wait |
    |                                         | before timing out.                 |
    |                                         | Defaults to `20` seconds.          |
    | `target.discovery_cache_dir`            | Directory containing the discovery |
    |                                         | cache. Defaults to "$CACHE".       |
    | `target.host_pipe_ssh_timeout`          | Time the target waits for an       |
    |                                         | initial response from ssh on the   |
    |                                         | target (currently, only in `ffx    |
    |                                         | target list`). Defaults to `10`    |
    |                                         | seconds.                           |
    | `target.stateless_default_configuration`| Experimental flag to limit targets |
    |                                         | to those explicitly specified via  |
    |                                         | `--target` or via env variables.   |
    |                                         | Default: false                     |
    | `targets.manual`                        | Contains the list of manual        |
    |                                         | targets. Defaults to an empty list |
    | `trace.category_groups`                 | List of categories on which to     |
    |                                         | enable tracing.  Defaults to a     |
    |                                         | large list -- use `ffx config get` |
    |                                         | to see the default categories.     |
    | `triage.config_paths`                   | Contains the list of default triage|
    |                                         | configs. Must be set in out-of-tree|
    |                                         | environments.                      |
    | `tunnels`                               | Contains the list of tunnels as    |
    |                                         | specified by Tunnel::ForwardPort   |
    |                                         | requests. Default: empty           |
    | `watchdogs.host_pipe.enabled`           | Specifies whether to run           |
    |                                         | "watchdogs" on daemon host-pipes,  |
    |                                         | in order to debug whether ssh      |
    |                                         | failures are due to the Rust       |
    |                                         | executor getting stuck.            |