Usage: ffx [-c <config...>] [-e <env>] [--machine <machine>] [--stamp <stamp>] [-t <target>] [-T <timeout>] [-l <log-level>] [--isolate-dir <isolate-dir>] [-v] [<command>] [<args>]
Fuchsia's developer tool
Options:
-c, --config override configuration values (key=value or json)
-e, --env override the path to the environment configuration file
(file path)
--machine produce output for a machine in the specified format;
available formats: "json", "json-pretty"
--stamp create a stamp file at the given path containing the exit
code
-t, --target apply operations across single or multiple targets
-T, --timeout override default proxy timeout
-l, --log-level sets the log level for ffx output (default = Debug). Other
possible values are Info, Error, Warn, and Trace. Can be
persisted via log.level config setting.
--isolate-dir turn on isolation mode using the given directory to isolate
all config and socket files into the specified directory.
This overrides the FFX_ISOLATE_DIR env variable, which can
also put ffx into this mode.
-v, --verbose logs ffx output to stdio according to log level
--help display usage information
Commands:
config View and switch default and user configurations
daemon Interact with/control the ffx daemon
schema Print out ffx schema
target Interact with a target device or emulator
version Print out ffx tool and daemon versions
net View and manage target network configuration
net-test-realm Manage a running Network Test Realm
agis Agis Service
assembly Assemble images
audio Interact with the audio subsystem.
component Discover and manage components
coverage Show coverage from test outputs
cts Build and run CTS tests.
debug Start a debugging session.
doctor Run common checks for the ffx tool and host environment
driver Support driver development workflows
efi Manipulate efi partition
emu Start and manage Fuchsia emulators.
flutter Interact with Flutter components on the target.
fuzz Start and manage fuzzers.
input Config input feature
inspect Query component nodes exposed via the Inspect API
log Display logs from a target device
overnet Interact with the Overnet mesh
package Create and publish Fuchsia packages
platform Manage platform build prerequisites
power Control system power features
process_explorer Query processes related information
product Discover and access product bundle metadata and image data.
product-bundle Discover and access product bundle metadata and image data.
profile Profile run-time information from various subsystems
repository Inspect and manage package repositories
scrutiny Audit the security of Fuchsia
sdk Modify or query the installed SDKs
self-test Execute the ffx self-test (e2e) suite
session Control the current session. See
https://fuchsia.dev/fuchsia-src/concepts/session/introduction
for details.
setui Modify and query settings.
sl4f Manage the sl4f server
starnix Control starnix processes
test Run test suite
trace Interact with the tracing subsystem.
triage Analyze Logs and Inspect in snapshots to find problems.
wlan Developer tool for manipulating WLAN state.
storage Manage Fuchsia Filesystems
agis
Usage: ffx agis <command> [<args>]
Agis Service
Options:
--help display usage information
Commands:
register register a process with AGIS for tracing
vtcs list all vulkan traceable components
listen initiate listening on |global_id|
shutdown shutdown all listeners
listen
Usage: ffx agis listen <global_id>
initiate listening on |global_id|
Positional Arguments:
global_id global id on which to listen
Options:
--help display usage information
register
Usage: ffx agis register <id> <process_koid> <process_name>
register a process with AGIS for tracing
Positional Arguments:
id unique id for this registration
process_koid process koid
process_name process name
Options:
--help display usage information
shutdown
Usage: ffx agis shutdown
shutdown all listeners
Options:
--help display usage information
vtcs
Usage: ffx agis vtcs
list all vulkan traceable components
Options:
--help display usage information
assembly
Usage: ffx assembly <command> [<args>]
Assemble images
Options:
--help display usage information
Commands:
create-system create the system images.
create-update construct an UpdatePackage using images and package.
create-flash-manifest
construct a flash manifest.
product Arguments for performing a high-level product assembly
operation.
size-check Perform size checks (on packages or product based on the
sub-command).
create-flash-manifest
Usage: ffx assembly create-flash-manifest --partitions <partitions> [--system-a <system-a>] [--system-b <system-b>] [--system-r <system-r>] --outdir <outdir>
construct a flash manifest.
Options:
--partitions path to a partitions config, which specifies where in the
partition table the images are put.
--system-a path to an images manifest, which specifies images to put in
slot A.
--system-b path to an images manifest, which specifies images to put in
slot B.
--system-r path to an images manifest, which specifies images to put in
slot R.
--outdir directory to write the UpdatePackage.
--help display usage information
create-system
Usage: ffx assembly create-system --image-assembly-config <image-assembly-config> --images <images> --outdir <outdir> [--gendir <gendir>] [--base-package-name <base-package-name>] [--mode <mode>]
create the system images.
Options:
--image-assembly-config
the configuration file that specifies the packages,
binaries, and settings specific to the product being
assembled.
--images the configuration file that specifies which images to
generate and how.
--outdir the directory to write assembled outputs to.
--gendir the directory to write generated intermediate files to.
--base-package-name
name to give the Base Package. This is useful if you must
publish multiple base packages to the same TUF repository.
--mode mode indicating where to place packages.
--help display usage information
create-update
Usage: ffx assembly create-update [--packages <packages>] --partitions <partitions> [--system-a <system-a>] [--system-r <system-r>] --board-name <board-name> --version-file <version-file> --epoch <epoch> [--update-package-name <update-package-name>] --outdir <outdir> [--gendir <gendir>]
construct an UpdatePackage using images and package.
Options:
--packages path to a packages manifest, which specifies what packages
to update.
--partitions path to a partitions config, which specifies where in the
partition table the images are put.
--system-a path to an images manifest, which specifies images to put in
slot A.
--system-r path to an images manifest, which specifies images to put in
slot R.
--board-name name of the board. Fuchsia will reject an Update Package
with a different board name.
--version-file file containing the version of the Fuchsia system.
--epoch backstop OTA version. Fuchsia will reject updates with a
lower epoch.
--update-package-name
name to give the Update Package. This is currently only used
by OTA tests to allow publishing multiple update packages to
the same amber repository without naming collisions.
--outdir directory to write the UpdatePackage.
--gendir directory to write intermediate files.
--help display usage information
product
Usage: ffx assembly product --product <product> [--board-info <board-info>] --outdir <outdir> [--gendir <gendir>] --input-bundles-dir <input-bundles-dir> --legacy-bundle-dir <legacy-bundle-dir> [--additional-packages-path <additional-packages-path>]
Arguments for performing a high-level product assembly operation.
Options:
--product the configuration file that describes the product assembly
to perform.
--board-info the file containing information about the board that the
product is being assembled to run on.
--outdir the directory to write assembled outputs to.
--gendir the directory to write generated intermediate files to.
--input-bundles-dir
the directory in which to find the platform assembly input
bundles
--legacy-bundle-dir
the directory in which to find the legacy assembly input
bundle
--additional-packages-path
a file containing a ProductPackageConfig with additional
packages to include which are not in the assembly input
bundle
--help display usage information
size-check
Usage: ffx assembly size-check <command> [<args>]
Perform size checks (on packages or product based on the sub-command).
Options:
--help display usage information
Commands:
product (Not implemented yet) Check that the set of all blobs
included in the product fit in the blobfs capacity.
package Measure package sizes and verify they fit in the specified
budgets. Exit status is 2 when one or more budgets are
exceeded, and 1 when a failure prevented the budget
verification to happen.
package
Usage: ffx assembly size-check package --budgets <budgets> [--blob-sizes <blob-sizes...>] [--blobfs-layout <blobfs-layout>] [--gerrit-output <gerrit-output>] [-v] [--verbose-json-output <verbose-json-output>]
Measure package sizes and verify they fit in the specified budgets. Exit status is 2 when one or more budgets are exceeded, and 1 when a failure prevented the budget verification to happen.
Options:
--budgets path to a JSON file containing the list of size budgets.
Each size budget has a `name`, a `size` which is the maximum
number of bytes, and `packages` a list of path to manifest
files.
--blob-sizes path to a `blobs.json` file. It provides the size of each
blob composing the package on device.
--blobfs-layout the layout of blobs in blobfs.
--gerrit-output path where to write the verification report, in JSON format.
-v, --verbose show the storage consumption of each component broken down
by package regardless of whether the component exceeded its
budget.
--verbose-json-output
path where to write the verbose JSON output.
--help display usage information
product
Usage: ffx assembly size-check product --assembly-manifest <assembly-manifest> [--base-assembly-manifest <base-assembly-manifest>] [-v] [--visualization-dir <visualization-dir>] [--gerrit-output <gerrit-output>] [--size-breakdown-output <size-breakdown-output>] [--blobfs-creep-budget <blobfs-creep-budget>]
(Not implemented yet) Check that the set of all blobs included in the product fit in the blobfs capacity.
Options:
--assembly-manifest
path to assembly_manifest.json.
--base-assembly-manifest
path to the bast assembly_manifest.json which will be used
to compare with the current assembly_manifest.json to
produce a diff.
-v, --verbose whether to show the verbose output.
--visualization-dir
path to the directory where HTML visualization should be
stored.
--gerrit-output path where to write the gerrit size report.
--size-breakdown-output
path where to write the size breakdown.
--blobfs-creep-budget
maximum amount that the size of blobfs can increase in one
CL. This value is propagated to the gerrit size report.
--help display usage information
audio
Usage: ffx audio <command> [<args>]
Interact with the audio subsystem.
Options:
--help display usage information
Commands:
gen Generate an audio signal. Outputs a WAV file written to
stdout.
Examples:
Generate a 5s long audio signal with 440Hz frequency:
$ffx audio gen sine --frequency=440 --duration=5s > /tmp/sine.wav
gen
Usage: ffx audio gen <command> [<args>]
Generate an audio signal. Outputs a WAV file written to stdout.
Options:
--help display usage information
Commands:
sine Generate a sine wave signal.
Examples:
ffx audio gen sine --duration 5ms --frequency 440 --amplitude 0.5 --format 48000,int16,2ch
sine
Usage: ffx audio gen sine --duration <duration> --frequency <frequency> [--amplitude <amplitude>] --format <format>
Generate a sine wave signal.
Options:
--duration duration of output signal. Examples: 5ms or 3s.
--frequency frequency of output wave in Hz.
--amplitude signal amplitude in range (0, 1.0]. Default: 1.0.
--format output format parameters:
<SampleRate>,<SampleType>,<Channels>
SampleRate:
Integer
SampleType options: uint8, int16,
int32, float32
Channels: <uint>ch
example: --format=48000,float32,2ch
--help display usage information
component
Usage: ffx component <command> [<args>]
Discover and manage components
Options:
--help display usage information
Commands:
capability Lists component instances that expose/use a capability
create Creates a dynamic component instance, adding it to the
collection designated by <moniker>
destroy Destroys a dynamic component instance, removing it from the
collection designated by <moniker>
doctor Perform diagnostic checks on a component at runtime.
explore Spawns a shell scoped to a component instance.
graph Outputs a Graphviz dot graph for the component topology
list Lists all components in the component topology
reload Recursively stops, unresolves, and starts a component
instance, updating the code and topology while preserving
resources
resolve Resolves a component instance
run Creates and starts a component instance in an existing
collection
within the component topology.
run-legacy Runs a legacy (CMX) component instance on the target
show Shows detailed information about a component instance
start Starts a component
stop Stops a component instance
storage Manages storage capabilities of components
capability
Usage: ffx component capability <capability>
Lists component instances that expose/use a capability
Positional Arguments:
capability output all components that expose/use the capability
Options:
--help display usage information
Examples:
To show all components that expose/use a capability:
$ ffx component capability fuchsia.sys.Loader
create
Usage: ffx component create <moniker> <url>
Creates a dynamic component instance, adding it to the collection designated by <moniker>
Positional Arguments:
moniker moniker of a component instance in an existing collection.
The component instance will be added to the collection if
the command succeeds.
url url of the component to create.
Options:
--help display usage information
Examples:
To create a component instance designated by the moniker `/core/ffx-laboratory:foo`:
$ ffx component create /core/ffx-laboratory:foo fuchsia-pkg://fuchsia.com/hello-world#meta/hello-world-rust.cm
Notes:
To learn more about running components, see https://fuchsia.dev/go/components/run
destroy
Usage: ffx component destroy <moniker>
Destroys a dynamic component instance, removing it from the collection designated by <moniker>
Positional Arguments:
moniker moniker of an existing component instance in a collection.
This component instance will be removed from the collection
if this command succeeds.
Options:
--help display usage information
Examples:
To destroy a component instance designated by the moniker `/core/ffx-laboratory:foo`:
$ ffx component destroy /core/ffx-laboratory:foo
Notes:
To learn more about running components, see https://fuchsia.dev/go/components/run
doctor
Usage: ffx component doctor <moniker> [-p]
Perform diagnostic checks on a component at runtime.
Positional Arguments:
moniker the component's moniker. Example: `/core/appmgr`.
Options:
-p, --plain whether or not to display the output without color and
wrapping.
--help display usage information
Examples:
To run diagnostics:
$ ffx component doctor /core/appmgr
This will run checks on the capabilities configuration of the component, checking that all of the
`use` and `expose` capabilities can be routed successfully by the component manager.
explore
Usage: ffx component explore <moniker> [--tools <tools>] [-c <command>] [-l <layout>]
Spawns a shell scoped to a component instance.
Positional Arguments:
moniker moniker of the component instance to explore.
Options:
--tools URL of a tools package to include in the shell environment.
the PATH variable will be updated to include binaries from
this tools package.
-c, --command execute a command instead of reading from stdin. the exit
code of the command will be forwarded to the host.
-l, --layout changes the namespace layout that is created for the shell.
nested: nests all instance directories under subdirs
(default) namespace: sets the instance namespace as the root
(works better for tools)
--help display usage information
Examples:
To explore the Archivist instance interactively:
> ffx component explore /bootstrap/archivist
$ ls
exposed
ns
out
runtime
svc
$ exit
Connection to terminal closed
To run a command directly from the command line:
> ffx component explore /bootstrap/archivist -c 'printenv'
PATH=/.dash/bin:/ns/pkg/bin
PWD=/
Notes:
The environment contains the following directories of the explored instance:
* /ns The namespace of the instance
* /exposed The capabilities exposed by the instance
* /out The outgoing directory of the instance, if it is running
* /runtime The runtime directory of the instance, if it is running
The environment also contains the following directories, irrespective of the explored instance:
* /.dash/bin Basic command-line tools like ls, cat and more
* /svc Protocols required by the dash shell
graph
Usage: ffx component graph [-o <only>] [-r <orientation>]
Outputs a Graphviz dot graph for the component topology
Options:
-o, --only outputs only cmx/cml/running/stopped components depending on
the flag.
-r, --orientation changes the visual orientation of the graph's nodes. Allowed
values are "left_to_right"/"lr" and "top_to_bottom"/"tb".
--help display usage information
Examples:
To graph all components in the topology:
$ ffx component graph
To graph all cmx components in the topology:
$ ffx component graph --only cmx
To graph all cml components in the topology:
$ ffx component graph --only cml
To graph all running components in the topology:
$ ffx component graph --only running
To graph all stopped components in the topology:
$ ffx component graph --only stopped
To graph the ancestors of a component named `foo`:
$ ffx component graph --only ancestor:foo
To graph the descendants of a component named `foo`:
$ ffx component graph --only descendant:foo
To graph both the ancestors and descendants of a component named `foo`:
$ ffx component graph --only relatives:foo
To order the graph's nodes from left-to-right (instead of top-to-bottom):
$ ffx component graph --orientation left_to_right
list
Usage: ffx component list [-o <only>] [-v]
Lists all components in the component topology
Options:
-o, --only output only cmx/cml/running/stopped components depending on
the flag.
-v, --verbose whether or not to display a column showing component type, a
column showing running/stopped and a column showing the url.
--help display usage information
Examples:
To list all components in the topology:
$ ffx component list
To list all cmx components in the topology:
$ ffx component list --only cmx
To list all cml components in the topology:
$ ffx component list --only cml
To list all running components in the topology:
$ ffx component list --only running
To list all stopped components in the topology:
$ ffx component list --only stopped
To list the ancestors of a component named `foo`:
$ ffx component list --only ancestor:foo
To list the descendants of a component named `foo`:
$ ffx component list --only descendant:foo
To list both the ancestors and descendants of a component named `foo`:
$ ffx component list --only relatives:foo
reload
Usage: ffx component reload <moniker>
Recursively stops, unresolves, and starts a component instance, updating the code and topology while preserving resources
Positional Arguments:
moniker moniker of a component instance or realm
Options:
--help display usage information
Examples:
To reload a component instance designated by the moniker `/core/ffx-laboratory:foo`:
$ ffx component reload /core/ffx-laboratory:foo
Notes:
To learn more about running components, see https://fuchsia.dev/go/components/run
resolve
Usage: ffx component resolve <moniker>
Resolves a component instance
Positional Arguments:
moniker A moniker to a component instance
Options:
--help display usage information
Examples:
To resolve the component designated by the provided moniker `/core/brightness_manager`:
$ ffx component resolve /core/brightness_manager
run
Usage: ffx component run <moniker> [<url>] [-n <name>] [-r] [-f]
Creates and starts a component instance in an existing collection
within the component topology.
Positional Arguments:
moniker moniker of a component instance in an existing collection.
The component instance will be added to the collection.
url url of the component to create and then start.
Options:
-n, --name deprecated. specify a name for the component instance. if
this flag is not set, the instance name is derived from the
component URL.
-r, --recreate destroy and recreate the component instance if it already
exists
-f, --follow-logs start printing logs from the started component after it has
started
--help display usage information
Examples:
To create a component instance from the `hello-world-rust` component URL:
$ ffx component run /core/ffx-laboratory:hello-world fuchsia-pkg://fuchsia.com/hello-world#meta/hello-world-rust.cm
Notes:
This command is a shorthand for the following:
$ ffx component create <moniker> <component-url>
$ ffx component start <moniker>
To learn more about running components, see https://fuchsia.dev/go/components/run
run-legacy
Usage: ffx component run-legacy <url> [<args...>] [-b]
Runs a legacy (CMX) component instance on the target
Positional Arguments:
url url of component to run
args args for the component
Options:
-b, --background switch to turn on background info
--help display usage information
Examples:
To run the 'hello_world_rust' component:
$ ffx component run-legacy \
fuchsia-pkg://fuchsia.com/hello_world_rust#meta/hello_world_rust.cmx
Notes:
To learn more, see https://fuchsia.dev/go/components/url
show
Usage: ffx component show <filter>
Shows detailed information about a component instance
Positional Arguments:
filter URL or moniker of component instance. Partial matches
allowed.
Options:
--help display usage information
Examples:
To show information about the `brightness_manager` component instance, all of the
following commands are valid:
$ ffx component show /core/brightness_manager
$ ffx component show fuchsia-pkg://fuchsia.com/brightness_manager#meta/brightness_manager.cm
$ ffx component show meta/brightness_manager.cm
$ ffx component show brightness_manager
Notes:
This command supports partial matches over the moniker and URL
start
Usage: ffx component start <moniker>
Starts a component
Positional Arguments:
moniker A moniker to a component instance
Options:
--help display usage information
Examples:
To start the component instance designated by the moniker `/core/brightness_manager`:
$ ffx component start /core/brightness_manager
Notes:
To learn more about running components, see https://fuchsia.dev/go/components/run
stop
Usage: ffx component stop <moniker> [-r]
Stops a component instance
Positional Arguments:
moniker A moniker to a component instance
Options:
-r, --recursive whether or not to stop the component recursively
--help display usage information
Examples:
To stop the component instance designated by the moniker `/core/brightness_manager`:
$ ffx component stop /core/brightness_manager
Notes:
To learn more about running components, see https://fuchsia.dev/go/components/run
storage
Usage: ffx component storage [--provider <provider>] [--capability <capability>] <command> [<args>]
Manages storage capabilities of components
Options:
--provider the moniker of the storage provider component. Defaults to
"/core"
--capability the capability name of the storage to use. Examples: "data",
"cache", "tmp" Defaults to "data"
--help display usage information
Commands:
copy Copy files to/from a component's storage. If the file
already exists at the destination it is overwritten.
delete Delete files from a component's storage.
list List the contents of a component's storage.
make-directory Create a new directory in a component's storage. If the
directory already exists, this operation is a no-op.
copy
Usage: ffx component storage copy <source_path> <destination_path>
Copy files to/from a component's storage. If the file already exists at the destination it is overwritten.
Positional Arguments:
source_path the source path of the file to be copied
destination_path the destination path of the file to be copied
Options:
--help display usage information
Examples:
To copy `credentials.json` from the current working directory on the host to the `settings` directory of a component's storage:
$ ffx component storage copy ./credentials.json 2042425d4b16ac396ebdb70e40845dc51516dd25754741a209d1972f126a7520::settings/credentials.json
To copy `credentials.json` from the current working directory on the host to the `settings` directory from a different provider and capability:
$ ffx component storage --provider /core/test_manager --capability data copy ./credentials.json f1a52f7b4d7081060a3295fd36df7b68fb0518f80aae0eae8a3fc1d55231375f::settings/credentials.json
Note: 2042425d4b16ac396ebdb70e40845dc51516dd25754741a209d1972f126a7520 is the instance ID of
the component whose storage is being accessed.
To learn about component instance IDs, see https://fuchsia.dev/go/components/instance-id
delete
Usage: ffx component storage delete <path>
Delete files from a component's storage.
Positional Arguments:
path the path of the file to be deleted
Options:
--help display usage information
Examples:
To delete `credentials.json` from the root directory of a component's persistent storage:
$ ffx component storage delete 2042425d4b16ac396ebdb70e40845dc51516dd25754741a209d1972f126a7520::credentials.json
Note: 2042425d4b16ac396ebdb70e40845dc51516dd25754741a209d1972f126a7520 is the instance ID of
the component whose storage is being accessed.
To learn about component instance IDs, see https://fuchsia.dev/go/components/instance-id
list
Usage: ffx component storage list <path>
List the contents of a component's storage.
Positional Arguments:
path a path to a remote directory
Options:
--help display usage information
Examples:
To list the contents of the `settings` directory in a component's storage:
$ ffx component storage list 2042425d4b16ac396ebdb70e40845dc51516dd25754741a209d1972f126a7520::settings
To list the contents of the root directory of a component's storage:
$ ffx component storage list 2042425d4b16ac396ebdb70e40845dc51516dd25754741a209d1972f126a7520::/
To list the contents of a directory using a different provider and capability:
$ ffx component storage --provider /core/test_manager --capability data list f1a52f7b4d7081060a3295fd36df7b68fb0518f80aae0eae8a3fc1d55231375f::/
Note: 2042425d4b16ac396ebdb70e40845dc51516dd25754741a209d1972f126a7520 is the instance ID of
the component whose storage is being accessed.
To learn about component instance IDs, see https://fuchsia.dev/go/components/instance-id
make-directory
Usage: ffx component storage make-directory <path>
Create a new directory in a component's storage. If the directory already exists, this operation is a no-op.
Positional Arguments:
path a path to a non-existent remote directory
Options:
--help display usage information
Examples:
To make a `settings` directory in a storage:
$ ffx component storage make-directory 2042425d4b16ac396ebdb70e40845dc51516dd25754741a209d1972f126a7520::settings
To make a `settings` directory in a storage from a different provider and capability:
$ ffx component storage --provider /core/test_manager --capability data make-directory f1a52f7b4d7081060a3295fd36df7b68fb0518f80aae0eae8a3fc1d55231375f::settings
Note: 2042425d4b16ac396ebdb70e40845dc51516dd25754741a209d1972f126a7520 is the instance ID of
the component whose storage is being accessed.
To learn about component instance IDs, see https://fuchsia.dev/go/components/instance-id
config
Usage: ffx config <command> [<args>]
View and switch default and user configurations
Options:
--help display usage information
Commands:
env list environment settings
get display config values
set set config settings
remove remove config for a given level
add add config value the end of an array
analytics enable or disable analytics
add
Usage: ffx config add <name> <value> [-l <level>] [-b <build-dir>]
add config value the end of an array
Positional Arguments:
name name of the property to set
value value to add to name
Options:
-l, --level config level. Possible values are "user", "build", "global".
Defaults to "user".
-b, --build-dir an optional build directory to associate the build config
provided - used for "build" configs. If not provided, it may
attempt to autodiscover your active build directory.
--help display usage information
Notes:
This will always add to the end of an array. Adding to a subtree is not supported. If the current value is not an array, it will convert the value to an array. If you want to insert a value in a different position, consider editing the configuration file directly. Configuration file locations can be found by running `ffx config env get` command.
analytics
Usage: ffx config analytics <command> [<args>]
enable or disable analytics
Options:
--help display usage information
Commands:
enable enable analytics
disable disable analytics
show show analytics
disable
Usage: ffx config analytics disable
disable analytics
Options:
--help display usage information
enable
Usage: ffx config analytics enable
enable analytics
Options:
--help display usage information
show
Usage: ffx config analytics show
show analytics
Options:
--help display usage information
env
Usage: ffx config env [<command>] [<args>]
list environment settings
Options:
--help display usage information
Commands:
set set environment settings
get list environment for a given level
get
Usage: ffx config env get [<level>]
list environment for a given level
Positional Arguments:
level config level. Possible values are "user", "build", "global".
Options:
--help display usage information
set
Usage: ffx config env set <file> [-l <level>] [-b <build-dir>]
set environment settings
Positional Arguments:
file path to the config file for the configuration level provided
Options:
-l, --level config level. Possible values are "user", "build", "global".
Defaults to "user".
-b, --build-dir an optional build directory to associate the build config
provided - used for "build" configs. If not provided, it may
attempt to autodiscover your active build directory.
--help display usage information
get
Usage: ffx config get [<name>] [-p <process>] [-s <select>] [-b <build-dir>]
display config values
Positional Arguments:
name name of the config property
Options:
-p, --process how to process results. Possible values are "r/raw",
"s/sub/substitute", or "f/file". Defaults to "substitute".
Currently only supported if a name is given.
-s, --select how to collect results. Possible values are "first" and
"all". Defaults to "first". If the value is "first", the
first value found in terms of priority is returned. If the
value is "all", all values across all configuration levels
are aggregrated and returned. Currently only supported if a
name is given.
-b, --build-dir an optional build directory to associate the build config
provided - used for "build" configs. If not provided, it may
attempt to autodiscover your active build directory.
--help display usage information
Error codes:
2 No value found
remove
Usage: ffx config remove <name> [-l <level>] [-b <build-dir>]
remove config for a given level
Positional Arguments:
name name of the config property
Options:
-l, --level config level. Possible values are "user", "build", "global".
Defaults to "user".
-b, --build-dir an optional build directory to associate the build config
provided - used for "build" configs. If not provided, it may
attempt to autodiscover your active build directory.
--help display usage information
Notes:
This will remove the entire value for the given name. If the value is a subtree or array, the entire subtree or array will be removed. If you want to remove a specific value from an array, consider editing the configuration file directly. Configuration file locations can be found by running `ffx config env get` command.
set
Usage: ffx config set <name> <value> [-l <level>] [-b <build-dir>]
set config settings
Positional Arguments:
name name of the property to set
value value to associate with name
Options:
-l, --level config level. Possible values are "user", "build", "global".
Defaults to "user".
-b, --build-dir an optional build directory to associate the build config
provided - used for "build" configs. If not provided, it may
attempt to autodiscover your active build directory.
--help display usage information
coverage
Usage: ffx coverage [<src_files...>] --test-output-dir <test-output-dir> --clang-dir <clang-dir> [--symbol-index-json <symbol-index-json>] [--export-html <export-html>] [--export-lcov <export-lcov>] [--path-remappings <path-remappings...>] [--compilation-dir <compilation-dir>]
Show coverage from test outputs
Positional Arguments:
src_files paths to source files to show coverage for
Options:
--test-output-dir path to ffx test output directory
--clang-dir path to clang directory, llvm-profdata and llvm-cov are
expected in clang_dir/bin
--symbol-index-json
path to symbol index json to load symbol index from
--export-html directory to export HTML reports to
--export-lcov path to export LCOV file to
--path-remappings "<from>,<to>" remapping of source file paths passed through
to llvm-cov
--compilation-dir path to the directory used as a base for relative coverage
mapping paths, passed through to llvm-cov
--help display usage information
cts
Usage: ffx cts <command> [<args>]
Build and run CTS tests.
Options:
--help display usage information
Commands:
run Run CTS tests.
run
Usage: ffx cts run [--cts-version <cts-version>] [--tests <tests>]
Run CTS tests.
Options:
--cts-version string, version of CTS to run.
--tests string, comma-separated list of tests to run.
--help display usage information
daemon
Usage: ffx daemon <command> [<args>]
Interact with/control the ffx daemon
Options:
--help display usage information
Commands:
crash crash the daemon
echo run echo test against the daemon
hang hang the daemon
log Dumps the daemon log
socket query information about the daemon socket without connecting
to it
start run as daemon
stop stops a running daemon
crash
Usage: ffx daemon crash
crash the daemon
Options:
--help display usage information
echo
Usage: ffx daemon echo [<text>]
run echo test against the daemon
Positional Arguments:
text text string to echo back and forth
Options:
--help display usage information
hang
Usage: ffx daemon hang
hang the daemon
Options:
--help display usage information
log
Usage: ffx daemon log [-f] [-l <line-count>]
Dumps the daemon log
Options:
-f, --follow print appended logs as they happen
-l, --line-count display most recent log lines.
--help display usage information
socket
Usage: ffx daemon socket
query information about the daemon socket without connecting to it
Options:
--help display usage information
start
Usage: ffx daemon start [--path <path>]
run as daemon
Options:
--path override the path the socket will be bound to
--help display usage information
stop
Usage: ffx daemon stop
stops a running daemon
Options:
--help display usage information
debug
Usage: ffx debug <command> [<args>]
Start a debugging session.
Options:
--help display usage information
Commands:
connect start the debugger and connect to the target
core start the debugger and open a minidump
fidl monitor FIDL traffic on the target
limbo control the process limbo on the target
symbol-index manage symbol sources used by other debug commands
symbolize symbolize backtraces in markup format
connect
Usage: ffx debug connect [<zxdb_args...>] [--debugger <debugger>] [--agent-only] [-n]
start the debugger and connect to the target
Positional Arguments:
zxdb_args extra arguments passed to zxdb. Any arguments starting with
"-" must be after a "--" separator.
Options:
--debugger start zxdb in another debugger. Valid options are lldb
(preferred) and gdb.
--agent-only only start the debug agent but not the zxdb. The path to the
UNIX socket will be printed and can be connected via
"connect -u" in zxdb shell.
-n, --no-auto-attach-limbo
do not automatically attach to processes found in Process
Limbo upon successful connection. convenience switch for the
zxdb option of the same name.
--help display usage information
core
Usage: ffx debug core [<minidump>] [--zxdb-args <zxdb-args...>]
start the debugger and open a minidump
Positional Arguments:
minidump minidump.dmp file to open. If left empty, the tool will list
available minidumps on the device and ask for a choice to
open.
Options:
--zxdb-args extra arguments passed to zxdb.
--help display usage information
fidl
Usage: ffx debug fidl [<extra_args...>] [--from <from>] [--to <to>] [--format <format>] [--with <with...>] [--with-process-info] [--stack <stack>] [--syscalls <syscalls...>] [--exclude-syscalls <exclude-syscalls...>] [--messages <messages...>] [--exclude-messages <exclude-messages...>] [--trigger <trigger...>] [--thread <thread...>] [--dump-messages] [--remote-pid <remote-pid...>] [-f <remote-name...>] [--extra-name <extra-name...>] [-c <remote-component...>] [--extra-component <extra-component...>] [--fidl-ir-path <fidl-ir-path...>]
monitor FIDL traffic on the target
Positional Arguments:
extra_args extra arguments passed to fidlcat. Any arguments starting
with "-" must be after a "--" separator.
Options:
--from specifies the source. Source can be: device: this is the
default input. The input comes from the live monitoring of
one or several processes. At least one of '--remote-pid',
'--remote-name', '--remote-job-id', --'remote-job-name',
'run' must be specified. dump: The input comes from stdin
which is the log output of one or several programs. The
lines in the log which dump syscalls are decoded and
replaced by the decoded version. All other lines are
unchanged. <path>: playback. Used to replay a session
previously recorded with --to <path> (protobuf format). Path
gives the name of the file to read. If path is '-' then the
standard input is used. This option must be used at most
once.
--to the session is saved to the specified file (binary protobuf
format). When a session is saved, you can replay it using
"--from <path>". The raw data is saved. That means that the
data saved is independent from what is displayed.
--format the display format for the session dump. The available
formats are: pretty: the session is pretty printed (with
colors). This is the default output if --with is not used.
json: the session is printed using a json format. textproto:
the session is printed using a text protobuf format. none:
nothing is displayed on the standard output (this option
only makes sense when used with `--to` or with `--with`).
When there is no output, fidlcat is faster (this is better
to monitor real time components). This is the default output
when --with is used.
--with specifies an extra summarized output. summary: at the end of
the session, a summary of the session is displayed on the
standard output. top: at the end of the session, generate a
view that groups the output by process, protocol, and
method. The groups are sorted by number of events, so groups
with more associated events are listed earlier.
group-by-thread: for each thread display a short version of
all the events. An equal sign followed by a path can be
concatanated to the option to output the result in a file
instead of the standard output (for example: --with
summary=/tmp/x). This option can be used several times.
--with-process-info
display the process name, process id and thread id on each
line (useful for grep).
--stack define the amount of stack frame to display 0: none (default
value) 1: call site (1 to 4 levels) 2: full stack frame
(adds some overhead)
--syscalls a regular expression which selects the syscalls to decode
and display. This option can be specified multiple times. By
default, only zx_channel_.* syscalls are displayed. To
display all the syscalls, use: --syscalls ".*"
--exclude-syscalls
a regular expression which selects the syscalls to not
decode and display. This option can be specified multiple
times. To be displayed, a syscall must verify --syscalls and
not verify --exclude-syscalls. To display all the syscalls
but the zx_handle syscalls, use: --syscalls ".*"
--exclude-syscalls "zx_handle_.*"
--messages a regular expression which selects the messages to display.
To display a message, the method name must satisfy the
regexp. This option can be specified multiple times. Message
filtering works on the method's fully qualified name.
--exclude-messages
a regular expression which selects the messages to not
display. If a message method name satisfy the regexp, the
message is not displayed (even if it satisfies --messages).
This option can be specified multiple times. Message
filtering works on the method's fully qualified name.
--trigger start displaying messages and syscalls only when a message
for which the method name satisfies the filter is found.
This option can be specified multiple times. Message
filtering works on the method's fully qualified name.
--thread only display the events for the specified thread. This
option can be specified multiple times. By default all the
events are displayed.
--dump-messages always does a hexadecimal dump of the messages even if we
can decode them.
--remote-pid the koid of the remote process to trace.
-f, --remote-name the <name> of a process. Fidlcat will monitor all existing
and future processes whose names includes <name> (<name> is
a substring of the process name). This option can be
specified multiple times. When used with --remote-job-id or
--remote-job-name, only the processes from the selected jobs
are taken into account.
--extra-name like "--remote-name" but for these processes, monitoring
starts only when one of the "--remote-name" or
"--remote-component" is launched. Also, fidlcat stops when
the last "--remote-name" or "--remote-component" stops, even
if some "--extra-name" processes are still running. You must
specify at least one filter with "--remote-name" or
"--remote-component" if you use this option. This option can
be specified multiple times.
-c, --remote-component
the URL or the moniker of a component for which we want to
monitor. All processes running in the component will be
monitered. This option can be specified multiple times.
--extra-component like "--remote-component" but for these components,
monitoring starts only when one of the "--remote-name" or
"--remote-component" is launched. Also, fidlcat stops when
the last "--remote-name" or "--remote-component" stops, even
if some "--extra-component" are still running. You must
specify at least one filter with "--remote-name" or
"--remote-component" if you use this option. This option can
be specified multiple times.
--fidl-ir-path add the given path as a repository for FIDL IR, in the form
of .fidl.json files. Passing a file adds the given file.
Passing a directory adds all of the .fidl.json files in that
directory and any directory transitively reachable from
there. An argfile contains a newline-separated list of
.fidl.json files relative to the directory containing the
argfile; passing an argfile (starting with the '@'
character) adds all files listed in that argfile. This
option can be specified multiple times.
--help display usage information
limbo
Usage: ffx debug limbo <command> [<args>]
control the process limbo on the target
Options:
--help display usage information
Commands:
status query the status of the process limbo.
enable enable the process limbo. It will now begin to capture
crashing processes.
disable disable the process limbo. Will free any pending processes
waiting in it.
list lists the processes currently waiting on limbo. The limbo
must be active.
release release a process from limbo. The limbo must be active.
disable
Usage: ffx debug limbo disable
disable the process limbo. Will free any pending processes waiting in it.
Options:
--help display usage information
enable
Usage: ffx debug limbo enable
enable the process limbo. It will now begin to capture crashing processes.
Options:
--help display usage information
list
Usage: ffx debug limbo list
lists the processes currently waiting on limbo. The limbo must be active.
Options:
--help display usage information
release
Usage: ffx debug limbo release <pid>
release a process from limbo. The limbo must be active.
Positional Arguments:
pid the koid of the process to release.
Options:
--help display usage information
status
Usage: ffx debug limbo status
query the status of the process limbo.
Options:
--help display usage information
symbol-index
Usage: ffx debug symbol-index <command> [<args>]
manage symbol sources used by other debug commands
Options:
--help display usage information
Commands:
list show the content in symbol index
add add a path to the symbol index
remove remove a path from the symbol index
clean remove all non-existent paths
Notes:
symbol-index is a global configuration used by debugging tools to locate
symbol files.
add
Usage: ffx debug symbol-index add <path> [--build-dir <build-dir>]
add a path to the symbol index
Positional Arguments:
path the path to add
Options:
--build-dir optional build directory used by zxdb to locate the source
code
--help display usage information
Notes:
Add a path to the symbol index. The path could be
- A build-id directory, with an optional build directory.
- An ids.txt file, with an optional build directory.
- A file that ends with .symbol-index.json.
Duplicated adding of the same path is a no-op, regardless of the optional
build directory.
clean
Usage: ffx debug symbol-index clean
remove all non-existent paths
Options:
--help display usage information
Notes:
Remove all non-existent paths from the symbol index, useful as a garbage
collection.
list
Usage: ffx debug symbol-index list [-a]
show the content in symbol index
Options:
-a, --aggregated show the aggregated symbol index
--help display usage information
remove
Usage: ffx debug symbol-index remove <path>
remove a path from the symbol index
Positional Arguments:
path the path to remove
Options:
--help display usage information
Notes:
Remove a path from the symbol index. The path could be
- A build-id directory.
- An ids.txt file.
- A file that ends with .symbol-index.json.
symbolize
Usage: ffx debug symbolize [<symbolizer_args...>] [--auth]
symbolize backtraces in markup format
Positional Arguments:
symbolizer_args extra arguments passed to the symbolizer. Any arguments
starting with "-" must be after a "--" separator.
Options:
--auth start the authentication process.
--help display usage information
doctor
Usage: ffx doctor [--record] [--no-config] [--retry-count <retry-count>] [--retry-delay <retry-delay>] [--restart-daemon] [-v] [--output-dir <output-dir>]
Run common checks for the ffx tool and host environment
Options:
--record generates an output zip file with logs
--no-config do not include the ffx configuration file
--retry-count number of times to retry failed connection attempts
--retry-delay timeout delay in ms during connection attempt
--restart-daemon force restart the daemon, even if the connection is working
-v, --verbose verbose, display all steps
--output-dir override the default output directory for doctor records
--help display usage information
Examples:
To run diagnostics:
$ ffx doctor
To capture the output and additional logs:
$ ffx doctor --record
By default, this outputs the zip in the current directory.
To override output dir:
$ ffx doctor --record --output-dir /tmp/ffx
Notes:
The `doctor` subcommand automatically attempts to repair common target
interaction issues and provides useful diagnostic information to the user.
By default, running `ffx doctor` attempts to establish a connection with
the daemon, and restarts the daemon if there is no connection. The default
`retry_count` is '3' and the default 'retry_delay` is '2000' milliseconds.
driver
Usage: ffx driver <command> [<args>]
Support driver development workflows
Options:
--help display usage information
Commands:
conformance Download or run driver conformance tests.
debug-bind Allows you to debug bind decisions.
device Performs specified subcommand on device
dump Dump device tree
i2c Perform reads and writes on an I2C device
list List drivers
list-devices List devices
list-hosts List driver hosts and drivers loaded within them
lsblk Prints out block device info
lspci Prints out pci device info
lsusb Print the device tree of the target to stdout
print-input-report
Prints input reports and other information of input devices
register Informs the driver manager that a new driver package is
available. The driver manager will cache a copy of the
driver
restart Restart all driver hosts containing the driver specified by
driver_path.
run-tool Runs a driver tool executable in the driver_playground.
test-node Commands to interact with test nodes.
conformance
Usage: ffx driver conformance <command> [<args>]
Download or run driver conformance tests.
Options:
--help display usage information
Commands:
test Runs driver conformance tests.
Examples:
To run all tests for a given device:
$ ffx driver conformance device /dev/pci-00:05.0
To run all tests of a given categor(ies) for a given device:
$ ffx driver conformance category --device /dev/pci-00:05.0 functional,performance
To run an arbitrary test(s) against a given device:
$ ffx driver conformance test custom --device /dev/pci-00:05.0 fuchsia-pkg://fuchsia.com/my-test#meta/my-test.cm
test
Usage: ffx driver conformance test <command> [<args>]
Runs driver conformance tests.
Options:
--help display usage information
Commands:
device Run all relevant tests against a given device.
category Run tests for a given category. e.g. functional
custom Run the tests listed. comma-separated list of test component
URLs.
category
Usage: ffx driver conformance test category <category_name> [--cache <cache>] -d <device>
Run tests for a given category. e.g. functional
Positional Arguments:
category_name category of tests to run against the driver. e.g.
performance
Options:
--cache local directory storing the resources required for offline
testing.
-d, --device device ID, e.g. /dev/pci-00:0a.0
--help display usage information
custom
Usage: ffx driver conformance test custom <custom_list> [--cache <cache>] -d <device>
Run the tests listed. comma-separated list of test component URLs.
Positional Arguments:
custom_list comma-separated list of test components. e.g.
fuchsia-pkg://fuchsia.dev/sometest#meta/sometest.cm
Options:
--cache local directory storing the resources required for offline
testing.
-d, --device device ID, e.g. /dev/pci-00:0a.0
--help display usage information
device
Usage: ffx driver conformance test device <device> [--cache <cache>]
Run all relevant tests against a given device.
Positional Arguments:
device device ID. e.g. /dev/pci-00:0a.0
Options:
--cache local directory storing the resources required for offline
testing.
--help display usage information
debug-bind
Usage: ffx driver debug-bind <driver_path> <device_path> [-p] [-i] [-s]
Allows you to debug bind decisions.
Positional Arguments:
driver_path the path of the driver to debug, e.g.
"/system/driver/usb_video.so"
device_path the path of the device to debug, relative to the /dev
directory. E.g. "sys/platform/pci/00:1f.6" or
"class/usb-device/000"
Options:
-p, --print-properties
print out the device properties.
-i, --print-instructions
print out the bind program instructions.
-s, --select if this exists, the user will be prompted for a component to
select.
--help display usage information
Examples:
To debug why a driver did or didn't bind to a particular device:
$ driver debug-bind '/boot/driver/usb_video.so' 'sys/platform/pci/00:1f.6'
Error codes:
1 Failed to connect to the bind debugger service
device
Usage: ffx driver device [-s] <command> [<args>]
Performs specified subcommand on device
Options:
-s, --select if this exists, the user will be prompted for a component to
select.
--help display usage information
Commands:
bind Binds the driver specified to the specified device.
unbind Unbinds the driver bound to the specified device.
rebind Unbinds the driver bound to a device and then attempts to
bind a new driver.
log-level Sets or prints the log level for the specified device. If
log_level is not specified, will print current log level.
Examples:
To unbind a driver
$ driver device unbind 'sys/platform/pci:00:01.6'
Error codes:
1 Failed to open device
bind
Usage: ffx driver device bind <driver_path> <device_path>
Binds the driver specified to the specified device.
Positional Arguments:
driver_path the path of the driver to debug, e.g.
"/system/driver/usb_video.so"
device_path the path of the device to unbind, relative to the /dev
directory. E.g. "sys/platform/pci/00:1f.6" or
"class/usb-device/000"
Options:
--help display usage information
bind
Usage: ffx driver device bind <driver_path> <device_path>
Binds the driver specified to the specified device.
Positional Arguments:
driver_path the path of the driver to debug, e.g.
"/system/driver/usb_video.so"
device_path the path of the device to unbind, relative to the /dev
directory. E.g. "sys/platform/pci/00:1f.6" or
"class/usb-device/000"
Options:
--help display usage information
log-level
Usage: ffx driver device log-level <device_path> [<log_level>]
Sets or prints the log level for the specified device. If log_level is not specified, will print current log level.
Positional Arguments:
device_path the path of the device to unbind, relative to the /dev
directory. E.g. "sys/platform/pci/00:1f.6" or
"class/usb-device/000"
log_level the log level to set
Options:
--help display usage information
rebind
Usage: ffx driver device rebind <driver_path> <device_path>
Unbinds the driver bound to a device and then attempts to bind a new driver.
Positional Arguments:
driver_path the path of the driver to debug, e.g.
"/system/driver/usb_video.so"
device_path the path of the device to unbind, relative to the /dev
directory. E.g. "sys/platform/pci/00:1f.6" or
"class/usb-device/000"
Options:
--help display usage information
unbind
Usage: ffx driver device unbind <device_path>
Unbinds the driver bound to the specified device.
Positional Arguments:
device_path the path of the device to unbind, relative to the /dev
directory. E.g. "sys/platform/pci/00:1f.6" or
"class/usb-device/000"
Options:
--help display usage information
dump
Usage: ffx driver dump [-g] [-s]
Dump device tree
Options:
-g, --graph output device graph in dot language so that it may be viewed
-s, --select if this exists, the user will be prompted for a component to
select.
--help display usage information
Examples:
To dump the device tree:
$ driver dump
To graph device tree:
$ driver dump --graph | dot -Tpng | display
Error codes:
1 Failed to connect to the driver development service
i2c
Usage: ffx driver i2c <command> [<args>]
Perform reads and writes on an I2C device
Options:
--help display usage information
Commands:
ping Pings all I2C devices found in /dev/class/i2c/
read Reads a single byte from the address of an I2C device
transact Sends a sequence of I2C transactions to an I2C device in the
order they are written
write Writes data to an I2C device
ping
Usage: ffx driver i2c ping
Pings all I2C devices found in /dev/class/i2c/
Options:
--help display usage information
Examples:
Ping all I2C devices found in /dev/class/i2c/:
$ driver i2cutil ping
read
Usage: ffx driver i2c read <device_path> [<address...>]
Reads a single byte from the address of an I2C device
Positional Arguments:
device_path path of the I2C device relative to devfs
address space-separated bytes, in decimal format, that represent the
address of the byte to read
Options:
--help display usage information
Examples:
Read a single byte from the address 0xff04 of the I2C device 000:
$ driver i2cutil read class/i2c/000 255 4
transact
Usage: ffx driver i2c transact <device_path> [<transactions...>]
Sends a sequence of I2C transactions to an I2C device in the order they are written
Positional Arguments:
device_path path of the I2C device relative to devfs
transactions transactions to send to I2C device
Options:
--help display usage information
Examples:
Send transactions to read 100 bytes, then write the bytes 0xab, 0x02, and 0xff; and then read 4 bytes to I2C device 004:
$ driver i2cutil transact r 100 w 171 2 255 r 4
write
Usage: ffx driver i2c write <device_path> [<data...>]
Writes data to an I2C device
Positional Arguments:
device_path path of the I2C device relative to devfs
data spaces-separated bytes, in decimal format, to be written to
the I2C device
Options:
--help display usage information
Examples:
Write the bytes 0xab and 0x01 to I2C device 001:
$ driver i2cutil write class/i2c/001 171 1
list
Usage: ffx driver list [-v] [--loaded] [-s]
List drivers
Options:
-v, --verbose list all driver properties
--loaded only list loaded drivers
-s, --select if this exists, the user will be prompted for a component to
select.
--help display usage information
Examples:
To list all drivers with properties:
$ driver list -v
To list only loaded drivers:
$ driver list --loaded
Error codes:
1 Failed to connect to the driver development service
list-devices
Usage: ffx driver list-devices [<device>] [-s] [-v]
List devices
Positional Arguments:
device specific device to list information about.
Options:
-s, --select if this exists, the user will be prompted for a component to
select.
-v, --verbose list all device properties.
--help display usage information
Examples:
To list all devices:
$ driver list-devices -v
Error codes:
1 Failed to connect to the driver development service
list-hosts
Usage: ffx driver list-hosts [-s]
List driver hosts and drivers loaded within them
Options:
-s, --select if this exists, the user will be prompted for a component to
select.
--help display usage information
Examples:
To list all driver hosts:
$ driver list-hosts
Error codes:
1 Failed to connect to the driver development service
lsblk
Usage: ffx driver lsblk [-s]
Prints out block device info
Options:
-s, --select if this exists, the user will be prompted for a component to
select.
--help display usage information
Examples:
To show the all block devices:
$ driver lsblk
Error codes:
1 Failed to connect to the device manager service
lspci
Usage: ffx driver lspci [<service>] [-v] [-q] [-x] [-n] [-N] [-s <filter>] [--select]
Prints out pci device info
Positional Arguments:
service path to the fuchsia.hardware.pci service
Options:
-v, --verbose print verbose device configuration
-q, --quiet don't print errors found trying to parse the database
-x, --print-config
dump raw configuration space
-n, --print-numeric
print numeric IDs.
-N, --only-print-numeric
only print numeric IDs.
-s, --filter [[<bus>]:][slot][.[<func>]] Show only devices in selected
slots
--select if this exists, the user will be prompted for a component to
select.
--help display usage information
Examples:
To show the device tree:
$ driver lspci
Error codes:
1 Failed to connect to the device manager service
lsusb
Usage: ffx driver lsusb [-t] [-v] [-c <configuration>] [-d <device>]
Print the device tree of the target to stdout
Options:
-t, --tree prints USB device tree
-v, --verbose verbose output (prints descriptors)
-c, --configuration
prints configuration descriptor for specified configuration
(rather than current configuration)
-d, --device shows only devices with the specified vendor and product ID
numbers (in hexadecimal) UsbDevice must be in format
vendor[:product]
--help display usage information
Examples:
To show the device tree:
$ driver lsusb
Error codes:
1 Failed to connect to the device manager service
print-input-report
Usage: ffx driver print-input-report <command> [<args>]
Prints input reports and other information of input devices
Options:
--help display usage information
Commands:
descriptor Prints the descriptors of all input devices
feature Prints the features of a given input device
get Gets and prints an input report from an input device
read Prints the input reports of all input devices in real-time
descriptor
Usage: ffx driver print-input-report descriptor [<device_path>]
Prints the descriptors of all input devices
Positional Arguments:
device_path print the descriptor of only the input device specified by
this device path which is relative to the /dev directory.
Options:
--help display usage information
Examples:
Print the descriptors of all input devices:
$ driver print-input-report descriptor
Print the descriptor of input device 001:
$ driver print-input-report descriptor class/input-report/001
feature
Usage: ffx driver print-input-report feature <device_path>
Prints the features of a given input device
Positional Arguments:
device_path print the features of only the input device specified by
this device path which is relative to the /dev directory.
Options:
--help display usage information
Examples:
Print the features of input device 001:
$ driver print-input-report feature class/input-report/001
get
Usage: ffx driver print-input-report get <device_path> <device_type>
Gets and prints an input report from an input device
Positional Arguments:
device_path get and print the input report of only the input device
specified by this device path which is relative to the /dev
directory.
device_type mouse, sensor, touch, keyboard, or consumer_control.
Options:
--help display usage information
Examples:
Get and print the touch input report of input device 001:
$ driver print-input-report get class/input-report/001 touch
read
Usage: ffx driver print-input-report read [<command>] [<args>]
Prints the input reports of all input devices in real-time
Options:
--help display usage information
Commands:
devpath Prints the input reports of only a specified input device
Examples:
Print the input reports of all input devices in real-time:
$ driver print-input-report read
devpath
Usage: ffx driver print-input-report read devpath <device_path> [--num-reads <num-reads>]
Prints the input reports of only a specified input device
Positional Arguments:
device_path device path of the device, relative to the /dev directory.
Options:
--num-reads how many input reports to read.
--help display usage information
Examples:
Print the next 5 input reports of the input device 001:
$ driver print-input-report read class/input-report/001 --num-reads 5
register
Usage: ffx driver register <url> [-s]
Informs the driver manager that a new driver package is available. The driver manager will cache a copy of the driver
Positional Arguments:
url component URL of the driver to be registered.
Options:
-s, --select if this exists, the user will be prompted for a component to
select.
--help display usage information
Examples:
To register a driver
$ driver register 'fuchsia-pkg://fuchsia.com/example_driver#meta/example_driver.cmx'
Error codes:
1 Failed to connect to the driver registrar service
restart
Usage: ffx driver restart <driver_path> [-s]
Restart all driver hosts containing the driver specified by driver_path.
Positional Arguments:
driver_path path of the driver to be restarted.
Options:
-s, --select if this exists, the user will be prompted for a component to
select.
--help display usage information
Examples:
To restart a driver:
$ driver restart fuchsia-boot:///#driver/e1000.so
Error codes:
1 Failed to connect to the driver manager service
run-tool
Usage: ffx driver run-tool <tool> [<args...>]
Runs a driver tool executable in the driver_playground.
Positional Arguments:
tool path of the driver tool binary.
args the arguments to pass to the tool.
Options:
--help display usage information
Examples:
To run a tool:
$ driver runtool fuchsia-pkg://fuchsiasamples.com/eductl#bin/eductl -- fact 5
Error codes:
1 Failed to connect to the driver playground service
test-node
Usage: ffx driver test-node [-s] <command> [<args>]
Commands to interact with test nodes.
Options:
-s, --select if this exists, the user will be prompted for a component to
select.
--help display usage information
Commands:
add Add a test node with a given bind property
remove Remove a test node.
add
Usage: ffx driver test-node add <name> <property>
Add a test node with a given bind property
Positional Arguments:
name the name of the test node.
property the test node's property. Should be in the format key=value.
Options:
--help display usage information
Examples:
To add a test node to the driver framework:
$ driver test-node add my-node my-key-string=my-value-string
Error codes:
1 Failed to connect to the driver development service
remove
Usage: ffx driver test-node remove <name>
Remove a test node.
Positional Arguments:
name the name of the test node.
Options:
--help display usage information
Examples:
To remove a test node to the driver framework:
$ driver test-node remove my-node
Error codes:
1 Failed to connect to the driver development service
efi
Usage: ffx efi <command> [<args>]
Manipulate efi partition
Options:
--help display usage information
Commands:
create Creates efi partition, copies zircon.bin, bootdata.bin,
EFI/BOOT/BOOTX64.EFI, zedboot.bin, etc...
create
Usage: ffx efi create -o <output> [--zircon <zircon>] [--bootdata <bootdata>] [--efi-bootloader <efi-bootloader>] [--zedboot <zedboot>] [--cmdline <cmdline>]
Creates efi partition, copies zircon.bin, bootdata.bin, EFI/BOOT/BOOTX64.EFI, zedboot.bin, etc...
Options:
-o, --output target file/disk to write EFI partition to
--zircon optional path to source file for zircon.bin
--bootdata optional path to source file for bootdata.bin
--efi-bootloader optional path to source file for EFI/BOOT/BOOTX64.EFI
--zedboot optional path to a source file for zedboot.bin
--cmdline optional bootloader cmdline file
--help display usage information
emu
Usage: ffx emu <command> [<args>]
Start and manage Fuchsia emulators.
Options:
--help display usage information
Commands:
console [EXPERIMENTAL] Connect to a running Fuchsia emulator's
console.
list List running Fuchsia emulators.
show Show Fuchsia emulator details.
start Start the Fuchsia emulator.
stop Shut down a running Fuchsia emulator.
Notes:
The emu command is used to start up, manage, and shut down Fuchsia emulators.
The `start` subcommand launches an emulator according to the configuration in
the Product Bundle. Once one or more emulators are running, you can use the
`list` subcommand to see the name and status of all running emulators, and the
`show` subcommand to get a printout of the configuration for a specific
emulator. When you're done with an emulator, use the `stop` subcommand to
cleanly terminate that emulator.
For more information on the Fuchsia emulator, see the Getting Started page at
https://fuchsia.dev/fuchsia-src/get-started/set_up_femu.
console
Usage: ffx emu console [<name>] [--console-type <console-type>] [-c] [-m] [-s]
[EXPERIMENTAL] Connect to a running Fuchsia emulator's console.
Positional Arguments:
name name of the emulator to connect to, as specified to the
start command. See a list of available instances by running
`ffx emu list`. If no name is specified, and only one
emulator is running, it will be selected.
Options:
--console-type selector for which console to attach to. Accepted values
are: command machine serial
-c, --command attach to the user-interactive command console. Equivalent
to "--console-type command".
-m, --machine attach to the machine-readable command console. Equivalent
to "--console-type machine".
-s, --serial attach to the Fuchsia serial console. Equivalent to
"--console-type serial".
--help display usage information
Examples:
ffx emu console -s
ffx emu console fuchsia-emulator --console-type serial
list
Usage: ffx emu list
List running Fuchsia emulators.
Options:
--help display usage information
show
Usage: ffx emu show [<name>] [--all] [--cmd] [--config] [--net] [--raw]
Show Fuchsia emulator details.
Positional Arguments:
name name of the emulator instance to show details for. See a
list of available instances by running `ffx emu list`. If
only one instance is running, this defaults to that instance
name.
Options:
--all show all of the available details, excluding the raw
internal format.
--cmd show the command line used to launch the emulator.
--config show the configuration in a format consistent with the
'start' command's --config flag.
--net switch to show network details.
--raw show the entire config output. This is the default output if
no other switches are invoked.
--help display usage information
start
Usage: ffx emu start [<product_bundle>] [--accel <accel>] [--config <config>] [--console] [--debugger] [--dry-run] [--edit] [--engine <engine>] [--gpu <gpu>] [-H] [--hidpi-scaling <hidpi-scaling>] [-c <kernel-args...>] [-l <log>] [-m] [--name <name>] [--net <net>] [--port-map <port-map...>] [--device <device>] [--device-list] [--reuse] [-s <startup-timeout>] [-V]
Start the Fuchsia emulator.
Positional Arguments:
product_bundle use named product information from Product Bundle Metadata
(PBM). If no product bundle is specified and there is an
obvious choice, that will be used (e.g. if there is only one
PBM available).
Options:
--accel virtualization acceleration. Valid choices are "none" to
disable acceleration, "hyper" to use the host's hypervisor
interface (KVM on Linux and HVF on MacOS), or "auto" to use
the hypervisor if detected. The default value is "auto".
--config specify a configuration file to populate the command line
flags for the emulator. Defaults to a Handlebars config
specified in the Product Bundle manifest.
--console launch the emulator in serial console mode. This redirects
the virtual serial port to the host's input/output streams,
then maintains a connection to those streams rather than
returning control to the host terminal. This is especially
useful when the guest is running without networking enabled.
--debugger pause on launch and wait for a debugger process to attach
before resuming. The guest operating system will not begin
execution until a debugger, such as gdb or lldb, attaches to
the emulator process and signals the emulator to continue.
--dry-run sets up the emulation, but doesn't start the emulator. The
command line arguments that the current configuration
generates will be printed to stdout for review.
--edit open the user's default editor to modify the command line
flags for the emulator.
--engine emulation engine to use for this instance. Allowed values
are "femu" which is based on Android Emulator, and "qemu"
which uses the version of Qemu packaged with Fuchsia.
Default is "femu". This can be overridden by running `ffx
config set emu.engine <type>`.
--gpu GPU acceleration mode. Allowed values are "host", "guest",
"swiftshader_indirect", or "auto". Default is "auto". Note:
this is unused when using the "qemu" engine type. See
https://developer.android.com/studio/run/emulator-acceleration#command-gpu
for details on the available options.
-H, --headless run the emulator without a GUI. The guest system may still
initialize graphics drivers, but no graphics interface will
be presented to the user.
--hidpi-scaling enable pixel scaling on HiDPI devices. Defaults to true for
MacOS, false otherwise.
-c, --kernel-args experimental(for https://fxbug.dev/95278). Passes the given
string to the emulator executable, appended after all other
arguments (since duplicated values favor the later value).
This means command-line values will override
configuration-provided values for any of these kernel
arguments. Can be repeated arbitrarily many times for
multiple additional kernel arguments.
-l, --log store the emulator log at the provided filesystem path. By
default, all output goes to a log file in the emulator
working directory. The path to this file is printed onscreen
during start-up.
-m, --monitor launch the emulator in Qemu monitor console mode. See
https://qemu-project.gitlab.io/qemu/system/monitor.html for
more information on the Qemu monitor console.
--name name of this emulator instance. This is used to identify the
instance in other commands and tools. Default is
"fuchsia-emulator".
--net specify the networking mode for the emulator. Allowed values
are "none" which disables networking, "tap" which attaches
to a Tun/Tap interface, "user" which sets up mapped ports
via SLiRP, and "auto" which will check the host system's
capabilities and select "tap" if it is available and "user"
otherwise. Default is "auto".
--port-map specify a host port mapping for user-networking mode.
Ignored in other networking modes. Syntax is "--port-map
<portname>:<port>". The <portname> must be one of those
specified in the virtual device specification. This flag may
be repeated for multiple port mappings.
--device specify the virtual device specification to use from the
product bundle. If no device is specified then the first
device listed in the PBM is used.
--device-list print the list of available virtual devices.
--reuse reuse a persistent emulator's state when starting up. If an
emulator with the same name as this instance has been
previously started and then stopped without cleanup, this
instance will reuse the images from the previous instance.
If no previous instance is found, or if the old instance is
still running, the new emulator will not attempt to start.
-s, --startup-timeout
the maximum time (in seconds) to wait on an emulator to boot
before returning control to the user. A value of 0 will skip
the check entirely. Default is 60 seconds. This can be
overridden with `ffx config set emu.start.timeout
<seconds>`.
-V, --verbose enables extra logging for debugging.
--help display usage information
Examples:
ffx emu start
ffx emu start workstation_eng.qemu-x64 --name my-emulator --engine femu
Notes:
The `start` subcommand is the starting point for all emulator interactions.
The name provided here will be used for all later interactions to indicate
which emulator to target. Emulator names must be unique.
The start command will compile all of the necessary configuration for an
emulator, launch the emulator, and then store the configuration on disk for
future reference. The configuration comes from the Product Bundle, which
includes a virtual device specification and a start-up flag template. See
https://fuchsia.dev/fuchsia-src/contribute/governance/rfcs/0100_product_metadata
for more information.
stop
Usage: ffx emu stop [<name>] [--all] [-p]
Shut down a running Fuchsia emulator.
Positional Arguments:
name name of the emulator to shutdown, as specified to the start
command. See a list of available instances by running `ffx
emu list`. If no name is specified, and only one emulator is
running, it will be terminated.
Options:
--all shut down and clean up all emulator instances running on the
device.
-p, --persist don't remove the state directory on stop, just terminate the
emulator.
--help display usage information
Examples:
ffx emu stop
ffx emu stop --all
ffx emu stop fuchsia-emulator --persist
Notes:
By default, the stop command will remove an emulator's on-disk
working directory, which contains emulator state, staged image files, etc.
Use the --persist flag if you need to leave the working directory intact while
shutting down the emulator, for debugging or troubleshooting purposes. The
working directory will be left in place, and the emulator will be marked
[Inactive] in `ffx emu list` results until stop is called for that instance
without the --persist flag.
flutter
Usage: ffx flutter <command> [<args>]
Interact with Flutter components on the target.
Options:
--help display usage information
Commands:
tunnel Establishes a port forward between the local host and the
dart vm service port.
Notes:
The `flutter` subcommand is an entry workflow and contains various subcommands
for flutter component management and interaction.
tunnel
Usage: ffx flutter tunnel
Establishes a port forward between the local host and the dart vm service port.
Options:
--help display usage information
Notes:
Determines the vm_service_port in the Flutter runner on the target Fuchsia device. An ssh
tunnel is then established between localhost(127.0.0.1) at an available port and the target device at
the vm_service_port.
A url for the location of the listening socket is printed out for users.
fuzz
Usage: ffx fuzz <command> [<args>]
Start and manage fuzzers.
Options:
--help display usage information
Commands:
shell Starts an interactive fuzzing session.
list Lists available fuzzers.
get Gets option(s) from a fuzzer.
set Sets options on a fuzzer.
add Adds an input to a fuzzer's corpus.
try Tests a specific input with a fuzzer.
run Generates inputs and fuzz the target.
cleanse Clears extraneous bytes from an error input.
minimize Reduce the size of an error input.
merge Compacts the attached fuzzer's corpus.
status Gets a fuzzer's execution status.
fetch Retrieves the attached fuzzer's corpus.
stop Stops a fuzzer.
add
Usage: ffx fuzz add <url> <input> [-o <output>] [-q] [-s]
Adds an input to a fuzzer's corpus.
Positional Arguments:
url package URL for the fuzzer
input input(s) to add; may be a filename, a directory path or a
hex string
Options:
-o, --output where to send fuzzer logs and artifacts; default is stdout
and the current directory
-q, --quiet if present, suppress non-error output from the ffx tool
itself
-s, --seed add to the seed corpus; default is to add to live corpus
--help display usage information
cleanse
Usage: ffx fuzz cleanse <url> <input> [-o <output>] [-q]
Clears extraneous bytes from an error input.
Positional Arguments:
url package URL for the fuzzer
input input to cleanse.
Options:
-o, --output where to send fuzzer logs and artifacts; default is stdout
and the current directory
-q, --quiet if present, suppress non-error output from the ffx tool
itself
--help display usage information
fetch
Usage: ffx fuzz fetch <url> [-o <output>] [-q] [-s]
Retrieves the attached fuzzer's corpus.
Positional Arguments:
url package URL for the fuzzer
Options:
-o, --output where to send fuzzer logs and artifacts; default is stdout
and the current directory
-q, --quiet if present, suppress non-error output from the ffx tool
itself
-s, --seed fetch the seed corpus; default is to fetch the live corpus
--help display usage information
get
Usage: ffx fuzz get <url> [<name>] [-o <output>] [-q]
Gets option(s) from a fuzzer.
Positional Arguments:
url package URL for the fuzzer
name option name; default is to display all values
Options:
-o, --output where to send fuzzer logs and artifacts; default is stdout
and the current directory
-q, --quiet if present, suppress non-error output from the ffx tool
itself
--help display usage information
list
Usage: ffx fuzz list [-j <json-file>] [-p <pattern>]
Lists available fuzzers.
Options:
-j, --json-file path to JSON file describing fuzzers; looks for tests.json
under $FUCHSIA_DIR by default
-p, --pattern list all fuzzers matching shell-style glob pattern; default
is to list all fuzzers
--help display usage information
merge
Usage: ffx fuzz merge <url> [-o <output>] [-q]
Compacts the attached fuzzer's corpus.
Positional Arguments:
url package URL for the fuzzer
Options:
-o, --output where to send fuzzer logs and artifacts; default is stdout
and the current directory
-q, --quiet if present, suppress non-error output from the ffx tool
itself
--help display usage information
minimize
Usage: ffx fuzz minimize <url> <input> [-o <output>] [-q] [-r <runs>] [-t <time>]
Reduce the size of an error input.
Positional Arguments:
url package URL for the fuzzer
input input to minimize.
Options:
-o, --output where to send fuzzer logs and artifacts; default is stdout
and the current directory
-q, --quiet if present, suppress non-error output from the ffx tool
itself
-r, --runs convenient shortcut for "set runs <n>"
-t, --time convenient shortcut for "set max_total_time <n>"
--help display usage information
run
Usage: ffx fuzz run <url> [-o <output>] [-q] [-r <runs>] [-t <time>]
Generates inputs and fuzz the target.
Positional Arguments:
url package URL for the fuzzer
Options:
-o, --output where to send fuzzer logs and artifacts; default is stdout
and the current directory
-q, --quiet if present, suppress non-error output from the ffx tool
itself
-r, --runs convenient shortcut for "set runs <n>"
-t, --time convenient shortcut for "set max_total_time <n>"
--help display usage information
set
Usage: ffx fuzz set <url> <name> <value> [-o <output>] [-q]
Sets options on a fuzzer.
Positional Arguments:
url package URL for the fuzzer
name option name
value option value
Options:
-o, --output where to send fuzzer logs and artifacts; default is stdout
and the current directory
-q, --quiet if present, suppress non-error output from the ffx tool
itself
--help display usage information
shell
Usage: ffx fuzz shell [-j <json-file>]
Starts an interactive fuzzing session.
Options:
-j, --json-file path to JSON file describing fuzzers; looks for tests.json
under $FUCHSIA_DIR by default
--help display usage information
status
Usage: ffx fuzz status <url> [-o <output>] [-q]
Gets a fuzzer's execution status.
Positional Arguments:
url package URL for the fuzzer
Options:
-o, --output where to send fuzzer logs and artifacts; default is stdout
and the current directory
-q, --quiet if present, suppress non-error output from the ffx tool
itself
--help display usage information
stop
Usage: ffx fuzz stop [<url>] [-q]
Stops a fuzzer.
Positional Arguments:
url package URL for the fuzzer. The attached fuzzer is stopped
by default.
Options:
-q, --quiet if present, suppress non-error output from the ffx tool
itself
--help display usage information
try
Usage: ffx fuzz try <url> <input> [-o <output>] [-q]
Tests a specific input with a fuzzer.
Positional Arguments:
url package URL for the fuzzer
input input to execute; may be a filename or hex string
Options:
-o, --output where to send fuzzer logs and artifacts; default is stdout
and the current directory
-q, --quiet if present, suppress non-error output from the ffx tool
itself
--help display usage information
input
Usage: ffx input [--enable <enable>] [--disable <disable>]
Config input feature
Options:
--enable enable a feature.
--disable disable a feature.
--help display usage information
Examples:
To enable / disable touchpad_mode:
$ ffx component input --enable touchpad_mode
$ ffx component input --disable touchpad_mode
inspect
Usage: ffx inspect <command> [<args>]
Query component nodes exposed via the Inspect API
Options:
--help display usage information
Commands:
apply-selectors Apply selectors from a file interactively.
list List components that expose inspect
list-accessors List ArchiveAccessor files.
selectors List available selectors
show Print inspect hierarchies
apply-selectors
Usage: ffx inspect apply-selectors <selector_file> [--snapshot-file <snapshot-file>] [--moniker <moniker>] [--accessor-path <accessor-path>]
Apply selectors from a file interactively.
Positional Arguments:
selector_file path to the selector file to apply to the snapshot.
Options:
--snapshot-file path to the inspect json file to read this file contains
inspect.json data from snapshot.zip. If not provided,
DiagnosticsProvider will be used to get inspect data.
--moniker moniker of the component to apply the command.
--accessor-path the path from where to get the ArchiveAccessor connection.
If the given path is a directory, the command will look for
a `fuchsia.diagnostics.ArchiveAccessor` service file. If the
given path is a service file, the command will attempt to
connect to it as an ArchiveAccessor.
--help display usage information
list
Usage: ffx inspect list [--manifest <manifest>] [--with-url] [--accessor-path <accessor-path>]
List components that expose inspect
Options:
--manifest the name of the manifest file that we are interested in. If
this is provided, the output will only contain monikers for
components whose url contains the provided name.
--with-url also print the URL of the component.
--accessor-path the path from where to get the ArchiveAccessor connection.
If the given path is a directory, the command will look for
a `fuchsia.diagnostics.ArchiveAccessor` service file. If the
given path is a service file, the command will attempt to
connect to it as an ArchiveAccessor.
--help display usage information
Notes:
Lists all components (relative to the scope where the archivist receives events from)
of components that expose inspect.
For v1: this is the realm path plus the realm name
For v2: this is the moniker without the instances ids.
list-accessors
Usage: ffx inspect list-accessors [<paths...>]
List ArchiveAccessor files.
Positional Arguments:
paths paths from where to list files.
Options:
--help display usage information
Notes:
Lists all ArchiveAccessor files under the provided paths.
All paths are implicitly rooted under `/hub-v2`.
If no paths are provided, it'll list everything under /hub-v2.
It is possible to reach v1 components by starting with the path prefix
children/core/children/appmgr/exec/out/hub.
selectors
Usage: ffx inspect selectors [<selectors...>] [--manifest <manifest>] [--accessor-path <accessor-path>]
List available selectors
Positional Arguments:
selectors selectors for which the selectors should be queried. If no
selectors are provided, inspect data for the whole system
will be returned. If `--manifest` is provided then the
selectors should be tree selectors, otherwise component
selectors or full selectors.
Options:
--manifest the name of the manifest file that we are interested in. If
this is provided, the output will only contain monikers for
components whose url contains the provided name.
--accessor-path the path from where to get the ArchiveAccessor connection.
If the given path is a directory, the command will look for
a `fuchsia.diagnostics.ArchiveAccessor` service file. If the
given path is a service file, the command will attempt to
connect to it as an ArchiveAccessor.
--help display usage information
Notes:
Lists all available full selectors (component selector + tree selector).
If a selector is provided, it’ll only print selectors for that component.
If a full selector (component + tree) is provided, it lists all selectors under the given node.
show
Usage: ffx inspect show [<selectors...>] [--manifest <manifest>] [--accessor-path <accessor-path>]
Print inspect hierarchies
Positional Arguments:
selectors selectors for which the selectors should be queried. If no
selectors are provided, inspect data for the whole system
will be returned. If `--manifest` is provided then the
selectors should be tree selectors, otherwise component
selectors or full selectors.
Options:
--manifest the name of the manifest file that we are interested in. If
this is provided, the output will only contain monikers for
components whose url contains the provided name.
--accessor-path the path from where to get the ArchiveAccessor connection.
If the given path is a directory, the command will look for
a `fuchsia.diagnostics.ArchiveAccessor` service file. If the
given path is a service file, the command will attempt to
connect to it as an ArchiveAccessor.
--help display usage information
Notes:
Prints the inspect hierarchies that match the given selectors.
log
Usage: ffx log [--filter <filter...>] [--exclude <exclude...>] [--tags <tags...>] [--exclude-tags <exclude-tags...>] [--severity <severity>] [--kernel] [--since <since>] [--since-monotonic <since-monotonic>] [--until <until>] [--until-monotonic <until-monotonic>] [--hide-tags] [--hide-file] [--no-color] [--show-metadata] [--show-full-moniker] [--clock <clock>] [--no-symbols] [--select <select...>] [--spam-list-path <spam-list-path>] [--disable-spam-filter] [--enable-spam-highlight] [<command>] [<args>]
Display logs from a target device
Options:
--filter filter for a string in either the message, component or url.
May be repeated.
--exclude exclude a string in either the message, component or url.
May be repeated.
--tags filter for only logs with a given tag. May be repeated.
--exclude-tags exclude logs with a given tag. May be repeated.
--severity set the minimum severity
--kernel outputs only kernel logs.
--since show only logs after a certain time
--since-monotonic show only logs after a certain time (as a monotonic
timestamp: seconds from the target's boot time).
--until show only logs until a certain time
--until-monotonic show only logs until a certain time (as a monotonic
timestamp: seconds since the target's boot time).
--hide-tags hide the tag field from output (does not exclude any log
messages)
--hide-file hide the file and line number field from output (does not
exclude any log messages)
--no-color disable coloring logs according to severity. Note that you
can permanently disable this with `ffx config set
log_cmd.color false`
--show-metadata shows process-id and thread-id in log output
--show-full-moniker
shows the full moniker in log output. By default this is
false and only the last segment of the moniker is printed.
--clock how to display log timestamps. Options are "utc", "local",
or "monotonic" (i.e. nanos since target boot). Default is
monotonic.
--no-symbols if provided, logs will not be symbolized
--select configure the log settings on the target device for
components matching the given selector. This modifies the
minimum log severity level emitted by components during the
logging session. Specify using the format
<component-selector>#<log-level>, with level as one of
FATAL|ERROR|WARN|INFO|DEBUG|TRACE. May be repeated.
--spam-list-path if provided, overrides the default log spam list path that's
optionally specified in FFX config under the
"log_cmd.spam_filepath" key.
--disable-spam-filter
if set, disable log spam filtering
--enable-spam-highlight
if set and spam filter is enabled, spams will be displayed
and highlighted
--help display usage information
Commands:
watch Watches for and prints logs from a target. Default if no
sub-command is specified.
dump Dumps all log from a given target's session.
Examples:
Dump the most recent logs and stream new ones as they happen:
$ ffx log
Stream new logs starting from the current time, filtering for severity of at least "WARN":
$ ffx log --severity warn --since now
Stream logs where the source moniker, component url and message do not include "sys":
$ ffx log --exclude sys
Stream ERROR logs with source moniker, component url or message containing either
"netstack" or "remote-control.cm", but not containing "sys":
$ ffx log --severity error --filter netstack --filter remote-control.cm --exclude sys
Dump all available logs where the source moniker, component url, or message contains
"remote-control":
$ ffx log --filter remote-control dump
Dump all logs from the last 30 minutes logged before 5 minutes ago:
$ ffx log --since "30m ago" --until "5m ago" dump
Enable DEBUG logs from the "core/audio" component while logs are streaming:
$ ffx log --select core/audio#DEBUG
Notes:
Logs are proactively retrieved from target devices and cached on the host.
Symbolization is performed in the background using the symbolizer host tool. You can pass
additional arguments to the symbolizer tool (for example, to add a remote symbol server) using:
$ ffx config set proactive_log.symbolize.extra_args "--symbol-server gs://some-url/path --symbol-server gs://some-other-url/path ..."
To learn more about configuring the log viewer, visit https://fuchsia.dev/fuchsia-src/development/tools/ffx/commands/log
dump
Usage: ffx log dump [<session>]
Dumps all log from a given target's session.
Positional Arguments:
session A specifier indicating which session you'd like to retrieve
logs for. For example, providing ~1 retrieves the
most-recent session, ~2 the second-most-recent, and so on.
Defaults to the most recent session.
Options:
--help display usage information
watch
Usage: ffx log watch
Watches for and prints logs from a target. Default if no sub-command is specified.
Options:
--help display usage information
net
Usage: ffx net [--realm <realm>] <command> [<args>]
View and manage target network configuration
Options:
--realm a realm to target when sending commands. Defaults to the
core network realm.
--help display usage information
Commands:
filter commands for packet filter
if commands for network interfaces
log commands for logging
neigh commands for neighbor tables
route commands for routing tables
dhcp commands for an interfaces dhcp client
dhcpd commands to control a dhcp server
dns commands to control the dns resolver
dhcp
Usage: ffx net dhcp <command> [<args>]
commands for an interfaces dhcp client
Options:
--help display usage information
Commands:
start starts a dhcp client on the interface
stop stops the dhcp client on the interface
start
Usage: ffx net dhcp start <nicid or name:ifname>
starts a dhcp client on the interface
Positional Arguments:
nicid or name:ifname
Options:
--help display usage information
stop
Usage: ffx net dhcp stop <nicid or name:ifname>
stops the dhcp client on the interface
Positional Arguments:
nicid or name:ifname
Options:
--help display usage information
dhcpd
Usage: ffx net dhcpd <command> [<args>]
commands to control a dhcp server
Options:
--help display usage information
Commands:
start A primary command to start the DHCP server.
stop A primary command to stop the DHCP server.
get A primary command to retrieve the value of a DHCP option or
server parameter.
set A primary command to set the value of a DHCP option or
server parameter.
list A primary command to list the values of all DHCP options or
server parameters.
reset A primary command to reset the values of all DHCP options or
server parameters.
clear-leases A primary command to clear the leases maintained by dhcpd.
clear-leases
Usage: ffx net dhcpd clear-leases
A primary command to clear the leases maintained by dhcpd.
Options:
--help display usage information
get
Usage: ffx net dhcpd get <command> [<args>]
A primary command to retrieve the value of a DHCP option or server parameter.
Options:
--help display usage information
Commands:
option A secondary command indicating a DHCP option argument.
parameter A secondary command indicating a server parameter argument.
option
Usage: ffx net dhcpd get option <command> [<args>]
A secondary command indicating a DHCP option argument.
Options:
--help display usage information
Commands:
subnet-mask The client's subnet mask.
time-offset The client's offset from UTC.
router The routers within a client's subnet.
time-server Time Protocol servers available to the client.
name-server IEN 116 Name servers available to the client.
domain-name-server
Domain Name System servers available to the client.
log-server MIT-LCS UDP Log servers available to the client.
cookie-server RFC 865 Cookie servers available to the client.
lpr-server RFC 1179 Line Printer servers available to the client.
impress-server Imagen Impress servers available to the client.
resource-location-server
RFC 887 Resource Location servers available to the client.
host-name Name of the client.
boot-file-size Size of the default boot image for the client.
merit-dump-file Path name of a core dump file.
domain-name Domain name of the client.
swap-server Address of the client's swap server.
root-path Path name to a TFTP-retrievable file containing
vendor-extension information.
extensions-path Path name to a TFTP-retrievable file containing
vendor-extension information.
ip-forwarding Flag enabling/disabling IP layer packet forwarding.
non-local-source-routing
Flag enabling/disabling forwarding of IP packets with
non-local source routes.
policy-filter Policy filters for non-local source routing.
max-datagram-reassembly-size
Maximum sized datagram that the client should be able to
reassemble.
default-ip-ttl Default time-to-live to use on outgoing IP datagrams.
path-mtu-aging-timeout
Timeout to use when aging Path MTU values.
path-mtu-plateau-table
Table of MTU sizes for Path MTU Discovery.
interface-mtu MTU for the client's interface.
all-subnets-local Flag indicating if all subnets of the connected network have
the same MTU.
broadcast-address Broadcast address of the client's subnet.
perform-mask-discovery
Flag indicating whether the client should perform subnet
mask discovery via ICMP.
mask-supplier Flag indicating whether the client should respond to subnet
mask discovery requests via ICMP.
perform-router-discovery
Flag indicating whether the client should solicit routers
using Router Discovery.
router-solicitation-address
Destination address for Router Solicitation requests.
static-route Static Routes which the client should put in its routing
cache.
trailer-encapsulation
Flag specifying whether the client should negotiate the use
of trailers in ARP.
arp-cache-timeout Timeout for ARP cache entries.
ethernet-encapsulation
Flag specifying whether the client should use Ethernet v2 or
IEEE 802.3 encapsulation.
tcp-default-ttl Default time-to-live for outgoing TCP segments.
tcp-keepalive-interval
Interval the client should wait before sending a TCP
keepalive message.
tcp-keepalive-garbage
Flag specifying whether the client should send TCP keepalive
messages with an octet of garbage.
network-information-service-domain
Name of the client's Network Information Service domain.
network-information-servers
Network Information Service servers available to the client.
network-time-protocol-servers
Network Time Protocol servers available to the client.
vendor-specific-information
Option for exchanging vendor-specific information between
the DHCP client and DHCP server.
net-bios-over-tcpip-name-server
NetBIOS name servers available to the client.
net-bios-over-tcpip-distribution-server
NetBIOS datagram distribution servers available to the
client.
net-bios-over-tcpip-node-type
The NetBIOS node type which should be used by the client.
net-bios-over-tcpip-scope
NetBIOS scope parameter for the client.
x-window-system-font-server
X Window System Font servers available to the client.
x-window-system-display-manager
X window System Display Manager systems available to the
client.
network-information-service-plus-domain
Network Information System+ domain name.
network-information-service-plus-servers
Network Information System+ servers available to the client.
mobile-ip-home-agent
Mobile IP home agents available to the client.
smtp-server SMTP servers available to the client.
pop3-server POP3 servers available to the client.
nntp-server NNTP servers available to the client.
default-www-server
Default WWW servers available to the client.
default-finger-server
Default Finger servers available to the client.
default-irc-server
Default IRC servers available to the client.
street-talk-server
StreetTalk servers available to the client.
stda-server StreetTalk Directory Assistance servers available to the
client.
tftp-server-name TFTP server available to the client.
bootfile-name Bootfile name for the client.
renewal-time-value
Maximum length of a DHCP message that the participant is
willing to accept.
renewal-time-value
Time interval from address assignment at which the client
transitions to a Renewing state.
rebinding-time-value
Time interval from address assignment at which the client
transitions to a Rebinding state.
all-subnets-local
Usage: ffx net dhcpd get option all-subnets-local [--local]
Flag indicating if all subnets of the connected network have the same MTU.
Options:
--local a flag indicating if all subents of the IP network to which
the client is connected have the same MTU.
--help display usage information
arp-cache-timeout
Usage: ffx net dhcpd get option arp-cache-timeout [--timeout <timeout>]
Timeout for ARP cache entries.
Options:
--timeout the timeout for ARP cache entries, in seconds.
--help display usage information
boot-file-size
Usage: ffx net dhcpd get option boot-file-size [--size <size>]
Size of the default boot image for the client.
Options:
--size the size of the client's default boot image in 512-octet
blocks.
--help display usage information
bootfile-name
Usage: ffx net dhcpd get option bootfile-name [--name <name>]
Bootfile name for the client.
Options:
--name the bootfile name for the client. This option should be used
when the `file` field has been overloaded to carry options.
--help display usage information
broadcast-address
Usage: ffx net dhcpd get option broadcast-address [--addr <addr>]
Broadcast address of the client's subnet.
Options:
--addr the broadcast address of the client's subnet. Legal values
are defined in RFC 1122.
--help display usage information
cookie-server
Usage: ffx net dhcpd get option cookie-server [--cookie-servers <cookie-servers...>]
RFC 865 Cookie servers available to the client.
Options:
--cookie-servers a list of RFC 865 Cookie servers available to the client, in
order of preference.
--help display usage information
default-finger-server
Usage: ffx net dhcpd get option default-finger-server [--finger-servers <finger-servers...>]
Default Finger servers available to the client.
Options:
--finger-servers a list of default Finger server addresses available to the
client, listed in order of preference.
--help display usage information
default-ip-ttl
Usage: ffx net dhcpd get option default-ip-ttl [--ttl <ttl>]
Default time-to-live to use on outgoing IP datagrams.
Options:
--ttl the default time-to-live to use on outgoing IP datagrams.
The value must be between 1 and 255.
--help display usage information
default-irc-server
Usage: ffx net dhcpd get option default-irc-server [--irc-servers <irc-servers...>]
Default IRC servers available to the client.
Options:
--irc-servers a list of Internet Relay Chat server addresses available to
the client, listed in order of preference.
--help display usage information
default-www-server
Usage: ffx net dhcpd get option default-www-server [--www-servers <www-servers...>]
Default WWW servers available to the client.
Options:
--www-servers a list of default World Wide Web (WWW) server addresses
available to the client, listed in order of preference.
--help display usage information
domain-name
Usage: ffx net dhcpd get option domain-name [--name <name>]
Domain name of the client.
Options:
--name the client's domain name for use in resolving hostnames in
the DNS.
--help display usage information
domain-name-server
Usage: ffx net dhcpd get option domain-name-server [--domain-name-servers <domain-name-servers...>]
Domain Name System servers available to the client.
Options:
--domain-name-servers
a list of DNS servers available to the client, in order of
preference;
--help display usage information
ethernet-encapsulation
Usage: ffx net dhcpd get option ethernet-encapsulation [--encapsulate]
Flag specifying whether the client should use Ethernet v2 or IEEE 802.3 encapsulation.
Options:
--encapsulate a flag specifying that the client should use Ethernet v2
encapsulation when false, and IEEE 802.3 encapsulation when
true.
--help display usage information
extensions-path
Usage: ffx net dhcpd get option extensions-path [--path <path>]
Path name to a TFTP-retrievable file containing vendor-extension information.
Options:
--path the path name to a TFTP-retrievable file. This file contains
data which can be interpreted as the BOOTP vendor-extension
field. Unlike the BOOTP vendor-extension field, this file
has an unconstrained length and any references to Tag 18 are
ignored.
--help display usage information
host-name
Usage: ffx net dhcpd get option host-name [--name <name>]
Name of the client.
Options:
--name the name of client, which may or may not be qualified with
the local domain name.
--help display usage information
impress-server
Usage: ffx net dhcpd get option impress-server [--impress-servers <impress-servers...>]
Imagen Impress servers available to the client.
Options:
--impress-servers a list of Imagen Impress servers available to the client, in
order of preference.
--help display usage information
interface-mtu
Usage: ffx net dhcpd get option interface-mtu [--mtu <mtu>]
MTU for the client's interface.
Options:
--mtu the MTU for the client's interface. Minimum value of 68.
--help display usage information
ip-forwarding
Usage: ffx net dhcpd get option ip-forwarding [--enabled]
Flag enabling/disabling IP layer packet forwarding.
Options:
--enabled a flag which will enabled IP layer packet forwarding when
true.
--help display usage information
log-server
Usage: ffx net dhcpd get option log-server [--log-servers <log-servers...>]
MIT-LCS UDP Log servers available to the client.
Options:
--log-servers a list of MIT-LCS UDP Log servers available to the client,
in order of preference.
--help display usage information
lpr-server
Usage: ffx net dhcpd get option lpr-server [--lpr-servers <lpr-servers...>]
RFC 1179 Line Printer servers available to the client.
Options:
--lpr-servers a list of RFC 1179 Line Printer servers available to the
client, in order of preference.
--help display usage information
mask-supplier
Usage: ffx net dhcpd get option mask-supplier [--supplier]
Flag indicating whether the client should respond to subnet mask discovery requests via ICMP.
Options:
--supplier a flag indicating whether the client should respond to
subnet mask discovery requests via ICMP.
--help display usage information
max-datagram-reassembly-size
Usage: ffx net dhcpd get option max-datagram-reassembly-size [--size <size>]
Maximum sized datagram that the client should be able to reassemble.
Options:
--size the maximum sized datagram that the client should be able to
reassemble, in octets. The minimum legal value is 576.
--help display usage information
merit-dump-file
Usage: ffx net dhcpd get option merit-dump-file [--path <path>]
Path name of a core dump file.
Options:
--path the path name to the client's core dump in the event the
client crashes.
--help display usage information
mobile-ip-home-agent
Usage: ffx net dhcpd get option mobile-ip-home-agent [--home-agents <home-agents...>]
Mobile IP home agents available to the client.
Options:
--home-agents a list of mobile IP home agent addresses available to the
client, listed in order of preference.
--help display usage information
name-server
Usage: ffx net dhcpd get option name-server [--name-servers <name-servers...>]
IEN 116 Name servers available to the client.
Options:
--name-servers a list of IEN 116 Name servers available to the client, in
order of preference.
--help display usage information
net-bios-over-tcpip-distribution-server
Usage: ffx net dhcpd get option net-bios-over-tcpip-distribution-server [--servers <servers...>]
NetBIOS datagram distribution servers available to the client.
Options:
--servers a list of NetBIOS datagram distribution servers available to
the client, listed in order of preference.
--help display usage information
net-bios-over-tcpip-name-server
Usage: ffx net dhcpd get option net-bios-over-tcpip-name-server [--servers <servers...>]
NetBIOS name servers available to the client.
Options:
--servers a list of NetBIOS name server addresses available to the
client, listed in order of preference.
--help display usage information
net-bios-over-tcpip-node-type
Usage: ffx net dhcpd get option net-bios-over-tcpip-node-type [<command>] [<args>]
The NetBIOS node type which should be used by the client.
Options:
--help display usage information
Commands:
b-node A B node type.
p-node A P node type.
m-node A M node type.
h-node A H node type.
# b-node
Usage: ffx net dhcpd get option net-bios-over-tcpip-node-type b-node
A B node type.
Options:
--help display usage information
# h-node
Usage: ffx net dhcpd get option net-bios-over-tcpip-node-type h-node
A H node type.
Options:
--help display usage information
# m-node
Usage: ffx net dhcpd get option net-bios-over-tcpip-node-type m-node
A M node type.
Options:
--help display usage information
# p-node
Usage: ffx net dhcpd get option net-bios-over-tcpip-node-type p-node
A P node type.
Options:
--help display usage information
net-bios-over-tcpip-scope
Usage: ffx net dhcpd get option net-bios-over-tcpip-scope [--scope <scope>]
NetBIOS scope parameter for the client.
Options:
--scope the NetBIOS over TCP/IP scope parameter, as defined in RFC
1001, for the client.
--help display usage information
network-information-servers
Usage: ffx net dhcpd get option network-information-servers [--servers <servers...>]
Network Information Service servers available to the client.
Options:
--servers a list of Network Information Service server addresses
available to the client, listed in order of preference.
--help display usage information
network-information-service-domain
Usage: ffx net dhcpd get option network-information-service-domain [--domain-name <domain-name>]
Name of the client's Network Information Service domain.
Options:
--domain-name the name of the client's Network Information Service domain.
--help display usage information
network-information-service-plus-domain
Usage: ffx net dhcpd get option network-information-service-plus-domain [--domain-name <domain-name>]
Network Information System+ domain name.
Options:
--domain-name the name of the client's Network Information System+ domain.
--help display usage information
network-information-service-plus-servers
Usage: ffx net dhcpd get option network-information-service-plus-servers [--servers <servers...>]
Network Information System+ servers available to the client.
Options:
--servers a list of Network Information System+ server addresses
available to the client, listed in order of preference.
--help display usage information
network-time-protocol-servers
Usage: ffx net dhcpd get option network-time-protocol-servers [--servers <servers...>]
Network Time Protocol servers available to the client.
Options:
--servers a list of Network Time Protocol (NTP) server addresses
available to the client, listed in order of preference.
--help display usage information
nntp-server
Usage: ffx net dhcpd get option nntp-server [--nntp-servers <nntp-servers...>]
NNTP servers available to the client.
Options:
--nntp-servers a list Network News Transport Protocol (NNTP) server
addresses available to the client, listed in order of
preference.
--help display usage information
non-local-source-routing
Usage: ffx net dhcpd get option non-local-source-routing [--enabled]
Flag enabling/disabling forwarding of IP packets with non-local source routes.
Options:
--enabled a flag which will enable forwarding of IP packets with
non-local source routes.
--help display usage information
path-mtu-aging-timeout
Usage: ffx net dhcpd get option path-mtu-aging-timeout [--timeout <timeout>]
Timeout to use when aging Path MTU values.
Options:
--timeout the timeout, in seconds, to be used when again Path MTU
values by the mechanism in RFC 1191.
--help display usage information
path-mtu-plateau-table
Usage: ffx net dhcpd get option path-mtu-plateau-table [--mtu-sizes <mtu-sizes...>]
Table of MTU sizes for Path MTU Discovery.
Options:
--mtu-sizes A list of MTU sizes, ordered from smallest to largest. The
smallest value cannot be smaller than 68.
--help display usage information
perform-mask-discovery
Usage: ffx net dhcpd get option perform-mask-discovery [--do-discovery]
Flag indicating whether the client should perform subnet mask discovery via ICMP.
Options:
--do-discovery a flag indicating whether the client should perform subnet
mask discovery via ICMP.
--help display usage information
perform-router-discovery
Usage: ffx net dhcpd get option perform-router-discovery [--do-discovery]
Flag indicating whether the client should solicit routers using Router Discovery.
Options:
--do-discovery A flag indicating whether the client should solicit routers
using Router Discovery as defined in RFC 1256.
--help display usage information
policy-filter
Usage: ffx net dhcpd get option policy-filter [--addresses <addresses...>]
Policy filters for non-local source routing.
Options:
--addresses a list of IP Address and Subnet Mask pairs. If an incoming
source-routed packet has a next-hop that does not match one
of these pairs, then the packet will be dropped.
--help display usage information
pop3-server
Usage: ffx net dhcpd get option pop3-server [--pop3-servers <pop3-servers...>]
POP3 servers available to the client.
Options:
--pop3-servers a list of Post Office Protocol (POP3) server addresses
available to the client, listed in order of preference.
--help display usage information
rebinding-time-value
Usage: ffx net dhcpd get option rebinding-time-value [--interval <interval>]
Time interval from address assignment at which the client transitions to a Rebinding state.
Options:
--interval the time interval, in seconds, after address assignment at
which the client will transition to the Rebinding state.
--help display usage information
renewal-time-value
Usage: ffx net dhcpd get option renewal-time-value [--length <length>]
Maximum length of a DHCP message that the participant is willing to accept.
Options:
--length the maximum length in octets of a DHCP message that the
participant is willing to accept. The minimum value is 576.
--help display usage information
renewal-time-value
Usage: ffx net dhcpd get option renewal-time-value [--length <length>]
Maximum length of a DHCP message that the participant is willing to accept.
Options:
--length the maximum length in octets of a DHCP message that the
participant is willing to accept. The minimum value is 576.
--help display usage information
resource-location-server
Usage: ffx net dhcpd get option resource-location-server [--resource-location-servers <resource-location-servers...>]
RFC 887 Resource Location servers available to the client.
Options:
--resource-location-servers
a list of RFC 887 Resource Location servers available to the
client, in order of preference.
--help display usage information
root-path
Usage: ffx net dhcpd get option root-path [--path <path>]
Path name to a TFTP-retrievable file containing vendor-extension information.
Options:
--path the path name to a TFTP-retrievable file. This file contains
data which can be interpreted as the BOOTP vendor-extension
field. Unlike the BOOTP vendor-extension field, this file
has an unconstrained length and any references to Tag 18 are
ignored.
--help display usage information
router
Usage: ffx net dhcpd get option router [--routers <routers...>]
The routers within a client's subnet.
Options:
--routers a list of the routers in a client's subnet, listed in order
of preference.
--help display usage information
router-solicitation-address
Usage: ffx net dhcpd get option router-solicitation-address [--addr <addr>]
Destination address for Router Solicitation requests.
Options:
--addr the address to which the client should transmit Router
Solicitation requests.
--help display usage information
smtp-server
Usage: ffx net dhcpd get option smtp-server [--smtp-servers <smtp-servers...>]
SMTP servers available to the client.
Options:
--smtp-servers a list of Simple Mail Transport Protocol (SMTP) server
address available to the client, listed in order of
preference.
--help display usage information
static-route
Usage: ffx net dhcpd get option static-route [--routes <routes...>]
Static Routes which the client should put in its routing cache.
Options:
--routes a list of Destination address/Next-hop address pairs
defining static routes for the client's routing table. The
routes should be listed in descending order of priority. It
is illegal to use 0.0.0.0 as the destination in a static
route.
--help display usage information
stda-server
Usage: ffx net dhcpd get option stda-server [--stda-servers <stda-servers...>]
StreetTalk Directory Assistance servers available to the client.
Options:
--stda-servers a list of StreetTalk Directory Assistance server addresses
available to the client, listed in order of preference.
--help display usage information
street-talk-server
Usage: ffx net dhcpd get option street-talk-server [--streettalk-servers <streettalk-servers...>]
StreetTalk servers available to the client.
Options:
--streettalk-servers
a list of StreetTalk server addresses available to the
client, listed in order of preference.
--help display usage information
subnet-mask
Usage: ffx net dhcpd get option subnet-mask [--mask <mask>]
The client's subnet mask.
Options:
--mask a 32-bit IPv4 subnet mask.
--help display usage information
swap-server
Usage: ffx net dhcpd get option swap-server [--address <address>]
Address of the client's swap server.
Options:
--address the address of the client's swap server.
--help display usage information
tcp-default-ttl
Usage: ffx net dhcpd get option tcp-default-ttl [--ttl <ttl>]
Default time-to-live for outgoing TCP segments.
Options:
--ttl the default time-to-live that the client should use for
outgoing TCP segments. The minimum value is 1.
--help display usage information
tcp-keepalive-garbage
Usage: ffx net dhcpd get option tcp-keepalive-garbage [--send-garbage]
Flag specifying whether the client should send TCP keepalive messages with an octet of garbage.
Options:
--send-garbage a flag specifying whether the client should send TCP
keepalive messages with an octet of garbage for
compatibility with older implementations.
--help display usage information
tcp-keepalive-interval
Usage: ffx net dhcpd get option tcp-keepalive-interval [--interval <interval>]
Interval the client should wait before sending a TCP keepalive message.
Options:
--interval the interval, in seconds, the client should wait before
sending a TCP keepalive message. A value of 0 indicates that
the client should not send keepalive messages unless
specifically requested by an application.
--help display usage information
tftp-server-name
Usage: ffx net dhcpd get option tftp-server-name [--name <name>]
TFTP server available to the client.
Options:
--name the TFTP server name available to the client. This option
should be used when the `sname` field has been overloaded to
carry options.
--help display usage information
time-offset
Usage: ffx net dhcpd get option time-offset [--offset <offset>]
The client's offset from UTC.
Options:
--offset the client's offset from UTC in seconds. A positive offset
is east of the zero meridian, and a negative offset is west
of the zero meridian.
--help display usage information
time-server
Usage: ffx net dhcpd get option time-server [--time-servers <time-servers...>]
Time Protocol servers available to the client.
Options:
--time-servers a list of time servers available to the client, in order of
preference.
--help display usage information
trailer-encapsulation
Usage: ffx net dhcpd get option trailer-encapsulation [--trailers]
Flag specifying whether the client should negotiate the use of trailers in ARP.
Options:
--trailers a flag specifying whether the client negotiate the use of
trailers when using ARP, per RFC 893.
--help display usage information
vendor-specific-information
Usage: ffx net dhcpd get option vendor-specific-information [--data <data...>]
Option for exchanging vendor-specific information between the DHCP client and DHCP server.
Options:
--data an opaque object of octets for exchanging vendor-specific
information.
--help display usage information
x-window-system-display-manager
Usage: ffx net dhcpd get option x-window-system-display-manager [--display-servers <display-servers...>]
X window System Display Manager systems available to the client.
Options:
--display-servers a list of X Window System Display Manager system addresses
available to the client, listed in order of preference.
--help display usage information
x-window-system-font-server
Usage: ffx net dhcpd get option x-window-system-font-server [--servers <servers...>]
X Window System Font servers available to the client.
Options:
--servers a list of X Window System Font server addresses available to
the client, listed in order of preference.
--help display usage information
parameter
Usage: ffx net dhcpd get parameter <command> [<args>]
A secondary command indicating a server parameter argument.
Options:
--help display usage information
Commands:
ip-addrs The IPv4 addresses to which the server is bound.
address-pool The pool of addresses which the DHCP server manages.
lease-length The duration of leases offered by the server.
permitted-macs The client MAC addresses which the server will issue leases
to.
statically-assigned-addrs
Addresses in the AddressPool which will only be leased to
specified clients. Assigned addresses will be paired with
hosts in order, e.g. hosts (A, B, C) and addresses (1, 2, 3)
pair as ((A, 1), (B, 2), (C, 3)).
arp-probe Enables server behavior where the server ARPs an IP address
prior to issuing it in a lease.
bound-device-names
The names of the network devices on which the server will
listen.
address-pool
Usage: ffx net dhcpd get parameter address-pool [--prefix-length <prefix-length>] [--range-start <range-start>] [--range-stop <range-stop>]
The pool of addresses which the DHCP server manages.
Options:
--prefix-length the prefix length of the network's subnet mask
--range-start the starting address, inclusive, of the range of addresses
which the DHCP server will lease to clients
--range-stop the ending address, inclusive, of the range of addresses
which the server will to clients
--help display usage information
arp-probe
Usage: ffx net dhcpd get parameter arp-probe [--enabled]
Enables server behavior where the server ARPs an IP address prior to issuing it in a lease.
Options:
--enabled enables server behavior where the server ARPs an IP address
prior to issuing it in a lease. If the server receives a
response, the server will mark the address as in-use and try
again with a different address. By default, this behavior is
disabled.
--help display usage information
bound-device-names
Usage: ffx net dhcpd get parameter bound-device-names [<names...>]
The names of the network devices on which the server will listen.
Positional Arguments:
names the names of the network devices on which the server will
listen. If this vector is empty, the server will listen on
all devices and will process incoming DHCP messages
regardless of the device on which they arrive. If this
vector is not empty, then the server will only listen for
incoming DHCP messages on the named network devices
contained by this vector.
Options:
--help display usage information
ip-addrs
Usage: ffx net dhcpd get parameter ip-addrs [--addrs <addrs...>]
The IPv4 addresses to which the server is bound.
Options:
--addrs A list of IPv4 Addresses to which the server is bound.
--help display usage information
lease-length
Usage: ffx net dhcpd get parameter lease-length [--default <default>] [--max <max>]
The duration of leases offered by the server.
Options:
--default the default lease length, in seconds, to be issued to
clients.
--max the maximum lease length value, in seconds, which the server
will issue to clients who have requested a specific lease
length. With the default value of 0, the max lease length is
equivalent to the default lease length.
--help display usage information
permitted-macs
Usage: ffx net dhcpd get parameter permitted-macs [--macs <macs...>]
The client MAC addresses which the server will issue leases to.
Options:
--macs the client MAC addresses which the server will issue leases
to. By default, the server will not have a permitted MAC
list, in which case it will attempt to issue a lease to
every client which requests one. If permitted_macs has a
non-zero length then the server will only respond to lease
requests from clients with a MAC in the list.
--help display usage information
statically-assigned-addrs
Usage: ffx net dhcpd get parameter statically-assigned-addrs [--hosts <hosts...>] [--assigned-addrs <assigned-addrs...>]
Addresses in the AddressPool which will only be leased to specified clients. Assigned addresses will be paired with hosts in order, e.g. hosts (A, B, C) and addresses (1, 2, 3) pair as ((A, 1), (B, 2), (C, 3)).
Options:
--hosts hosts which will be leased the addresses reserved by
`assigned_addrs`.
--assigned-addrs addresses in the AddressPool which will not be leased to
clients. Typically, a network administrator will statically
assign these addresses to always-on network devices which
should always have the same IP address, such as network
printers.
--help display usage information
list
Usage: ffx net dhcpd list <command> [<args>]
A primary command to list the values of all DHCP options or server parameters.
Options:
--help display usage information
Commands:
option Perform the command on DHCP options.
parameter Perform the command on server parameters.
option
Usage: ffx net dhcpd list option
Perform the command on DHCP options.
Options:
--help display usage information
parameter
Usage: ffx net dhcpd list parameter
Perform the command on server parameters.
Options:
--help display usage information
reset
Usage: ffx net dhcpd reset <command> [<args>]
A primary command to reset the values of all DHCP options or server parameters.
Options:
--help display usage information
Commands:
option Perform the command on DHCP options.
parameter Perform the command on server parameters.
option
Usage: ffx net dhcpd reset option
Perform the command on DHCP options.
Options:
--help display usage information
parameter
Usage: ffx net dhcpd reset parameter
Perform the command on server parameters.
Options:
--help display usage information
set
Usage: ffx net dhcpd set <command> [<args>]
A primary command to set the value of a DHCP option or server parameter.
Options:
--help display usage information
Commands:
option A secondary command indicating a DHCP option argument.
parameter A secondary command indicating a server parameter argument.
option
Usage: ffx net dhcpd set option <command> [<args>]
A secondary command indicating a DHCP option argument.
Options:
--help display usage information
Commands:
subnet-mask The client's subnet mask.
time-offset The client's offset from UTC.
router The routers within a client's subnet.
time-server Time Protocol servers available to the client.
name-server IEN 116 Name servers available to the client.
domain-name-server
Domain Name System servers available to the client.
log-server MIT-LCS UDP Log servers available to the client.
cookie-server RFC 865 Cookie servers available to the client.
lpr-server RFC 1179 Line Printer servers available to the client.
impress-server Imagen Impress servers available to the client.
resource-location-server
RFC 887 Resource Location servers available to the client.
host-name Name of the client.
boot-file-size Size of the default boot image for the client.
merit-dump-file Path name of a core dump file.
domain-name Domain name of the client.
swap-server Address of the client's swap server.
root-path Path name to a TFTP-retrievable file containing
vendor-extension information.
extensions-path Path name to a TFTP-retrievable file containing
vendor-extension information.
ip-forwarding Flag enabling/disabling IP layer packet forwarding.
non-local-source-routing
Flag enabling/disabling forwarding of IP packets with
non-local source routes.
policy-filter Policy filters for non-local source routing.
max-datagram-reassembly-size
Maximum sized datagram that the client should be able to
reassemble.
default-ip-ttl Default time-to-live to use on outgoing IP datagrams.
path-mtu-aging-timeout
Timeout to use when aging Path MTU values.
path-mtu-plateau-table
Table of MTU sizes for Path MTU Discovery.
interface-mtu MTU for the client's interface.
all-subnets-local Flag indicating if all subnets of the connected network have
the same MTU.
broadcast-address Broadcast address of the client's subnet.
perform-mask-discovery
Flag indicating whether the client should perform subnet
mask discovery via ICMP.
mask-supplier Flag indicating whether the client should respond to subnet
mask discovery requests via ICMP.
perform-router-discovery
Flag indicating whether the client should solicit routers
using Router Discovery.
router-solicitation-address
Destination address for Router Solicitation requests.
static-route Static Routes which the client should put in its routing
cache.
trailer-encapsulation
Flag specifying whether the client should negotiate the use
of trailers in ARP.
arp-cache-timeout Timeout for ARP cache entries.
ethernet-encapsulation
Flag specifying whether the client should use Ethernet v2 or
IEEE 802.3 encapsulation.
tcp-default-ttl Default time-to-live for outgoing TCP segments.
tcp-keepalive-interval
Interval the client should wait before sending a TCP
keepalive message.
tcp-keepalive-garbage
Flag specifying whether the client should send TCP keepalive
messages with an octet of garbage.
network-information-service-domain
Name of the client's Network Information Service domain.
network-information-servers
Network Information Service servers available to the client.
network-time-protocol-servers
Network Time Protocol servers available to the client.
vendor-specific-information
Option for exchanging vendor-specific information between
the DHCP client and DHCP server.
net-bios-over-tcpip-name-server
NetBIOS name servers available to the client.
net-bios-over-tcpip-distribution-server
NetBIOS datagram distribution servers available to the
client.
net-bios-over-tcpip-node-type
The NetBIOS node type which should be used by the client.
net-bios-over-tcpip-scope
NetBIOS scope parameter for the client.
x-window-system-font-server
X Window System Font servers available to the client.
x-window-system-display-manager
X window System Display Manager systems available to the
client.
network-information-service-plus-domain
Network Information System+ domain name.
network-information-service-plus-servers
Network Information System+ servers available to the client.
mobile-ip-home-agent
Mobile IP home agents available to the client.
smtp-server SMTP servers available to the client.
pop3-server POP3 servers available to the client.
nntp-server NNTP servers available to the client.
default-www-server
Default WWW servers available to the client.
default-finger-server
Default Finger servers available to the client.
default-irc-server
Default IRC servers available to the client.
street-talk-server
StreetTalk servers available to the client.
stda-server StreetTalk Directory Assistance servers available to the
client.
tftp-server-name TFTP server available to the client.
bootfile-name Bootfile name for the client.
renewal-time-value
Maximum length of a DHCP message that the participant is
willing to accept.
renewal-time-value
Time interval from address assignment at which the client
transitions to a Renewing state.
rebinding-time-value
Time interval from address assignment at which the client
transitions to a Rebinding state.
all-subnets-local
Usage: ffx net dhcpd set option all-subnets-local [--local]
Flag indicating if all subnets of the connected network have the same MTU.
Options:
--local a flag indicating if all subents of the IP network to which
the client is connected have the same MTU.
--help display usage information
arp-cache-timeout
Usage: ffx net dhcpd set option arp-cache-timeout [--timeout <timeout>]
Timeout for ARP cache entries.
Options:
--timeout the timeout for ARP cache entries, in seconds.
--help display usage information
boot-file-size
Usage: ffx net dhcpd set option boot-file-size [--size <size>]
Size of the default boot image for the client.
Options:
--size the size of the client's default boot image in 512-octet
blocks.
--help display usage information
bootfile-name
Usage: ffx net dhcpd set option bootfile-name [--name <name>]
Bootfile name for the client.
Options:
--name the bootfile name for the client. This option should be used
when the `file` field has been overloaded to carry options.
--help display usage information
broadcast-address
Usage: ffx net dhcpd set option broadcast-address [--addr <addr>]
Broadcast address of the client's subnet.
Options:
--addr the broadcast address of the client's subnet. Legal values
are defined in RFC 1122.
--help display usage information
cookie-server
Usage: ffx net dhcpd set option cookie-server [--cookie-servers <cookie-servers...>]
RFC 865 Cookie servers available to the client.
Options:
--cookie-servers a list of RFC 865 Cookie servers available to the client, in
order of preference.
--help display usage information
default-finger-server
Usage: ffx net dhcpd set option default-finger-server [--finger-servers <finger-servers...>]
Default Finger servers available to the client.
Options:
--finger-servers a list of default Finger server addresses available to the
client, listed in order of preference.
--help display usage information
default-ip-ttl
Usage: ffx net dhcpd set option default-ip-ttl [--ttl <ttl>]
Default time-to-live to use on outgoing IP datagrams.
Options:
--ttl the default time-to-live to use on outgoing IP datagrams.
The value must be between 1 and 255.
--help display usage information
default-irc-server
Usage: ffx net dhcpd set option default-irc-server [--irc-servers <irc-servers...>]
Default IRC servers available to the client.
Options:
--irc-servers a list of Internet Relay Chat server addresses available to
the client, listed in order of preference.
--help display usage information
default-www-server
Usage: ffx net dhcpd set option default-www-server [--www-servers <www-servers...>]
Default WWW servers available to the client.
Options:
--www-servers a list of default World Wide Web (WWW) server addresses
available to the client, listed in order of preference.
--help display usage information
domain-name
Usage: ffx net dhcpd set option domain-name [--name <name>]
Domain name of the client.
Options:
--name the client's domain name for use in resolving hostnames in
the DNS.
--help display usage information
domain-name-server
Usage: ffx net dhcpd set option domain-name-server [--domain-name-servers <domain-name-servers...>]
Domain Name System servers available to the client.
Options:
--domain-name-servers
a list of DNS servers available to the client, in order of
preference;
--help display usage information
ethernet-encapsulation
Usage: ffx net dhcpd set option ethernet-encapsulation [--encapsulate]
Flag specifying whether the client should use Ethernet v2 or IEEE 802.3 encapsulation.
Options:
--encapsulate a flag specifying that the client should use Ethernet v2
encapsulation when false, and IEEE 802.3 encapsulation when
true.
--help display usage information
extensions-path
Usage: ffx net dhcpd set option extensions-path [--path <path>]
Path name to a TFTP-retrievable file containing vendor-extension information.
Options:
--path the path name to a TFTP-retrievable file. This file contains
data which can be interpreted as the BOOTP vendor-extension
field. Unlike the BOOTP vendor-extension field, this file
has an unconstrained length and any references to Tag 18 are
ignored.
--help display usage information
host-name
Usage: ffx net dhcpd set option host-name [--name <name>]
Name of the client.
Options:
--name the name of client, which may or may not be qualified with
the local domain name.
--help display usage information
impress-server
Usage: ffx net dhcpd set option impress-server [--impress-servers <impress-servers...>]
Imagen Impress servers available to the client.
Options:
--impress-servers a list of Imagen Impress servers available to the client, in
order of preference.
--help display usage information
interface-mtu
Usage: ffx net dhcpd set option interface-mtu [--mtu <mtu>]
MTU for the client's interface.
Options:
--mtu the MTU for the client's interface. Minimum value of 68.
--help display usage information
ip-forwarding
Usage: ffx net dhcpd set option ip-forwarding [--enabled]
Flag enabling/disabling IP layer packet forwarding.
Options:
--enabled a flag which will enabled IP layer packet forwarding when
true.
--help display usage information
log-server
Usage: ffx net dhcpd set option log-server [--log-servers <log-servers...>]
MIT-LCS UDP Log servers available to the client.
Options:
--log-servers a list of MIT-LCS UDP Log servers available to the client,
in order of preference.
--help display usage information
lpr-server
Usage: ffx net dhcpd set option lpr-server [--lpr-servers <lpr-servers...>]
RFC 1179 Line Printer servers available to the client.
Options:
--lpr-servers a list of RFC 1179 Line Printer servers available to the
client, in order of preference.
--help display usage information
mask-supplier
Usage: ffx net dhcpd set option mask-supplier [--supplier]
Flag indicating whether the client should respond to subnet mask discovery requests via ICMP.
Options:
--supplier a flag indicating whether the client should respond to
subnet mask discovery requests via ICMP.
--help display usage information
max-datagram-reassembly-size
Usage: ffx net dhcpd set option max-datagram-reassembly-size [--size <size>]
Maximum sized datagram that the client should be able to reassemble.
Options:
--size the maximum sized datagram that the client should be able to
reassemble, in octets. The minimum legal value is 576.
--help display usage information
merit-dump-file
Usage: ffx net dhcpd set option merit-dump-file [--path <path>]
Path name of a core dump file.
Options:
--path the path name to the client's core dump in the event the
client crashes.
--help display usage information
mobile-ip-home-agent
Usage: ffx net dhcpd set option mobile-ip-home-agent [--home-agents <home-agents...>]
Mobile IP home agents available to the client.
Options:
--home-agents a list of mobile IP home agent addresses available to the
client, listed in order of preference.
--help display usage information
name-server
Usage: ffx net dhcpd set option name-server [--name-servers <name-servers...>]
IEN 116 Name servers available to the client.
Options:
--name-servers a list of IEN 116 Name servers available to the client, in
order of preference.
--help display usage information
net-bios-over-tcpip-distribution-server
Usage: ffx net dhcpd set option net-bios-over-tcpip-distribution-server [--servers <servers...>]
NetBIOS datagram distribution servers available to the client.
Options:
--servers a list of NetBIOS datagram distribution servers available to
the client, listed in order of preference.
--help display usage information
net-bios-over-tcpip-name-server
Usage: ffx net dhcpd set option net-bios-over-tcpip-name-server [--servers <servers...>]
NetBIOS name servers available to the client.
Options:
--servers a list of NetBIOS name server addresses available to the
client, listed in order of preference.
--help display usage information
net-bios-over-tcpip-node-type
Usage: ffx net dhcpd set option net-bios-over-tcpip-node-type [<command>] [<args>]
The NetBIOS node type which should be used by the client.
Options:
--help display usage information
Commands:
b-node A B node type.
p-node A P node type.
m-node A M node type.
h-node A H node type.
# b-node
Usage: ffx net dhcpd set option net-bios-over-tcpip-node-type b-node
A B node type.
Options:
--help display usage information
# h-node
Usage: ffx net dhcpd set option net-bios-over-tcpip-node-type h-node
A H node type.
Options:
--help display usage information
# m-node
Usage: ffx net dhcpd set option net-bios-over-tcpip-node-type m-node
A M node type.
Options:
--help display usage information
# p-node
Usage: ffx net dhcpd set option net-bios-over-tcpip-node-type p-node
A P node type.
Options:
--help display usage information
net-bios-over-tcpip-scope
Usage: ffx net dhcpd set option net-bios-over-tcpip-scope [--scope <scope>]
NetBIOS scope parameter for the client.
Options:
--scope the NetBIOS over TCP/IP scope parameter, as defined in RFC
1001, for the client.
--help display usage information
network-information-servers
Usage: ffx net dhcpd set option network-information-servers [--servers <servers...>]
Network Information Service servers available to the client.
Options:
--servers a list of Network Information Service server addresses
available to the client, listed in order of preference.
--help display usage information
network-information-service-domain
Usage: ffx net dhcpd set option network-information-service-domain [--domain-name <domain-name>]
Name of the client's Network Information Service domain.
Options:
--domain-name the name of the client's Network Information Service domain.
--help display usage information
network-information-service-plus-domain
Usage: ffx net dhcpd set option network-information-service-plus-domain [--domain-name <domain-name>]
Network Information System+ domain name.
Options:
--domain-name the name of the client's Network Information System+ domain.
--help display usage information
network-information-service-plus-servers
Usage: ffx net dhcpd set option network-information-service-plus-servers [--servers <servers...>]
Network Information System+ servers available to the client.
Options:
--servers a list of Network Information System+ server addresses
available to the client, listed in order of preference.
--help display usage information
network-time-protocol-servers
Usage: ffx net dhcpd set option network-time-protocol-servers [--servers <servers...>]
Network Time Protocol servers available to the client.
Options:
--servers a list of Network Time Protocol (NTP) server addresses
available to the client, listed in order of preference.
--help display usage information
nntp-server
Usage: ffx net dhcpd set option nntp-server [--nntp-servers <nntp-servers...>]
NNTP servers available to the client.
Options:
--nntp-servers a list Network News Transport Protocol (NNTP) server
addresses available to the client, listed in order of
preference.
--help display usage information
non-local-source-routing
Usage: ffx net dhcpd set option non-local-source-routing [--enabled]
Flag enabling/disabling forwarding of IP packets with non-local source routes.
Options:
--enabled a flag which will enable forwarding of IP packets with
non-local source routes.
--help display usage information
path-mtu-aging-timeout
Usage: ffx net dhcpd set option path-mtu-aging-timeout [--timeout <timeout>]
Timeout to use when aging Path MTU values.
Options:
--timeout the timeout, in seconds, to be used when again Path MTU
values by the mechanism in RFC 1191.
--help display usage information
path-mtu-plateau-table
Usage: ffx net dhcpd set option path-mtu-plateau-table [--mtu-sizes <mtu-sizes...>]
Table of MTU sizes for Path MTU Discovery.
Options:
--mtu-sizes A list of MTU sizes, ordered from smallest to largest. The
smallest value cannot be smaller than 68.
--help display usage information
perform-mask-discovery
Usage: ffx net dhcpd set option perform-mask-discovery [--do-discovery]
Flag indicating whether the client should perform subnet mask discovery via ICMP.
Options:
--do-discovery a flag indicating whether the client should perform subnet
mask discovery via ICMP.
--help display usage information
perform-router-discovery
Usage: ffx net dhcpd set option perform-router-discovery [--do-discovery]
Flag indicating whether the client should solicit routers using Router Discovery.
Options:
--do-discovery A flag indicating whether the client should solicit routers
using Router Discovery as defined in RFC 1256.
--help display usage information
policy-filter
Usage: ffx net dhcpd set option policy-filter [--addresses <addresses...>]
Policy filters for non-local source routing.
Options:
--addresses a list of IP Address and Subnet Mask pairs. If an incoming
source-routed packet has a next-hop that does not match one
of these pairs, then the packet will be dropped.
--help display usage information
pop3-server
Usage: ffx net dhcpd set option pop3-server [--pop3-servers <pop3-servers...>]
POP3 servers available to the client.
Options:
--pop3-servers a list of Post Office Protocol (POP3) server addresses
available to the client, listed in order of preference.
--help display usage information
rebinding-time-value
Usage: ffx net dhcpd set option rebinding-time-value [--interval <interval>]
Time interval from address assignment at which the client transitions to a Rebinding state.
Options:
--interval the time interval, in seconds, after address assignment at
which the client will transition to the Rebinding state.
--help display usage information
renewal-time-value
Usage: ffx net dhcpd set option renewal-time-value [--length <length>]
Maximum length of a DHCP message that the participant is willing to accept.
Options:
--length the maximum length in octets of a DHCP message that the
participant is willing to accept. The minimum value is 576.
--help display usage information
renewal-time-value
Usage: ffx net dhcpd set option renewal-time-value [--length <length>]
Maximum length of a DHCP message that the participant is willing to accept.
Options:
--length the maximum length in octets of a DHCP message that the
participant is willing to accept. The minimum value is 576.
--help display usage information
resource-location-server
Usage: ffx net dhcpd set option resource-location-server [--resource-location-servers <resource-location-servers...>]
RFC 887 Resource Location servers available to the client.
Options:
--resource-location-servers
a list of RFC 887 Resource Location servers available to the
client, in order of preference.
--help display usage information
root-path
Usage: ffx net dhcpd set option root-path [--path <path>]
Path name to a TFTP-retrievable file containing vendor-extension information.
Options:
--path the path name to a TFTP-retrievable file. This file contains
data which can be interpreted as the BOOTP vendor-extension
field. Unlike the BOOTP vendor-extension field, this file
has an unconstrained length and any references to Tag 18 are
ignored.
--help display usage information
router
Usage: ffx net dhcpd set option router [--routers <routers...>]
The routers within a client's subnet.
Options:
--routers a list of the routers in a client's subnet, listed in order
of preference.
--help display usage information
router-solicitation-address
Usage: ffx net dhcpd set option router-solicitation-address [--addr <addr>]
Destination address for Router Solicitation requests.
Options:
--addr the address to which the client should transmit Router
Solicitation requests.
--help display usage information
smtp-server
Usage: ffx net dhcpd set option smtp-server [--smtp-servers <smtp-servers...>]
SMTP servers available to the client.
Options:
--smtp-servers a list of Simple Mail Transport Protocol (SMTP) server
address available to the client, listed in order of
preference.
--help display usage information
static-route
Usage: ffx net dhcpd set option static-route [--routes <routes...>]
Static Routes which the client should put in its routing cache.
Options:
--routes a list of Destination address/Next-hop address pairs
defining static routes for the client's routing table. The
routes should be listed in descending order of priority. It
is illegal to use 0.0.0.0 as the destination in a static
route.
--help display usage information
stda-server
Usage: ffx net dhcpd set option stda-server [--stda-servers <stda-servers...>]
StreetTalk Directory Assistance servers available to the client.
Options:
--stda-servers a list of StreetTalk Directory Assistance server addresses
available to the client, listed in order of preference.
--help display usage information
street-talk-server
Usage: ffx net dhcpd set option street-talk-server [--streettalk-servers <streettalk-servers...>]
StreetTalk servers available to the client.
Options:
--streettalk-servers
a list of StreetTalk server addresses available to the
client, listed in order of preference.
--help display usage information
subnet-mask
Usage: ffx net dhcpd set option subnet-mask [--mask <mask>]
The client's subnet mask.
Options:
--mask a 32-bit IPv4 subnet mask.
--help display usage information
swap-server
Usage: ffx net dhcpd set option swap-server [--address <address>]
Address of the client's swap server.
Options:
--address the address of the client's swap server.
--help display usage information
tcp-default-ttl
Usage: ffx net dhcpd set option tcp-default-ttl [--ttl <ttl>]
Default time-to-live for outgoing TCP segments.
Options:
--ttl the default time-to-live that the client should use for
outgoing TCP segments. The minimum value is 1.
--help display usage information
tcp-keepalive-garbage
Usage: ffx net dhcpd set option tcp-keepalive-garbage [--send-garbage]
Flag specifying whether the client should send TCP keepalive messages with an octet of garbage.
Options:
--send-garbage a flag specifying whether the client should send TCP
keepalive messages with an octet of garbage for
compatibility with older implementations.
--help display usage information
tcp-keepalive-interval
Usage: ffx net dhcpd set option tcp-keepalive-interval [--interval <interval>]
Interval the client should wait before sending a TCP keepalive message.
Options:
--interval the interval, in seconds, the client should wait before
sending a TCP keepalive message. A value of 0 indicates that
the client should not send keepalive messages unless
specifically requested by an application.
--help display usage information
tftp-server-name
Usage: ffx net dhcpd set option tftp-server-name [--name <name>]
TFTP server available to the client.
Options:
--name the TFTP server name available to the client. This option
should be used when the `sname` field has been overloaded to
carry options.
--help display usage information
time-offset
Usage: ffx net dhcpd set option time-offset [--offset <offset>]
The client's offset from UTC.
Options:
--offset the client's offset from UTC in seconds. A positive offset
is east of the zero meridian, and a negative offset is west
of the zero meridian.
--help display usage information
time-server
Usage: ffx net dhcpd set option time-server [--time-servers <time-servers...>]
Time Protocol servers available to the client.
Options:
--time-servers a list of time servers available to the client, in order of
preference.
--help display usage information
trailer-encapsulation
Usage: ffx net dhcpd set option trailer-encapsulation [--trailers]
Flag specifying whether the client should negotiate the use of trailers in ARP.
Options:
--trailers a flag specifying whether the client negotiate the use of
trailers when using ARP, per RFC 893.
--help display usage information
vendor-specific-information
Usage: ffx net dhcpd set option vendor-specific-information [--data <data...>]
Option for exchanging vendor-specific information between the DHCP client and DHCP server.
Options:
--data an opaque object of octets for exchanging vendor-specific
information.
--help display usage information
x-window-system-display-manager
Usage: ffx net dhcpd set option x-window-system-display-manager [--display-servers <display-servers...>]
X window System Display Manager systems available to the client.
Options:
--display-servers a list of X Window System Display Manager system addresses
available to the client, listed in order of preference.
--help display usage information
x-window-system-font-server
Usage: ffx net dhcpd set option x-window-system-font-server [--servers <servers...>]
X Window System Font servers available to the client.
Options:
--servers a list of X Window System Font server addresses available to
the client, listed in order of preference.
--help display usage information
parameter
Usage: ffx net dhcpd set parameter <command> [<args>]
A secondary command indicating a server parameter argument.
Options:
--help display usage information
Commands:
ip-addrs The IPv4 addresses to which the server is bound.
address-pool The pool of addresses which the DHCP server manages.
lease-length The duration of leases offered by the server.
permitted-macs The client MAC addresses which the server will issue leases
to.
statically-assigned-addrs
Addresses in the AddressPool which will only be leased to
specified clients. Assigned addresses will be paired with
hosts in order, e.g. hosts (A, B, C) and addresses (1, 2, 3)
pair as ((A, 1), (B, 2), (C, 3)).
arp-probe Enables server behavior where the server ARPs an IP address
prior to issuing it in a lease.
bound-device-names
The names of the network devices on which the server will
listen.
address-pool
Usage: ffx net dhcpd set parameter address-pool [--prefix-length <prefix-length>] [--range-start <range-start>] [--range-stop <range-stop>]
The pool of addresses which the DHCP server manages.
Options:
--prefix-length the prefix length of the network's subnet mask
--range-start the starting address, inclusive, of the range of addresses
which the DHCP server will lease to clients
--range-stop the ending address, inclusive, of the range of addresses
which the server will to clients
--help display usage information
arp-probe
Usage: ffx net dhcpd set parameter arp-probe [--enabled]
Enables server behavior where the server ARPs an IP address prior to issuing it in a lease.
Options:
--enabled enables server behavior where the server ARPs an IP address
prior to issuing it in a lease. If the server receives a
response, the server will mark the address as in-use and try
again with a different address. By default, this behavior is
disabled.
--help display usage information
bound-device-names
Usage: ffx net dhcpd set parameter bound-device-names [<names...>]
The names of the network devices on which the server will listen.
Positional Arguments:
names the names of the network devices on which the server will
listen. If this vector is empty, the server will listen on
all devices and will process incoming DHCP messages
regardless of the device on which they arrive. If this
vector is not empty, then the server will only listen for
incoming DHCP messages on the named network devices
contained by this vector.
Options:
--help display usage information
ip-addrs
Usage: ffx net dhcpd set parameter ip-addrs [--addrs <addrs...>]
The IPv4 addresses to which the server is bound.
Options:
--addrs A list of IPv4 Addresses to which the server is bound.
--help display usage information
lease-length
Usage: ffx net dhcpd set parameter lease-length [--default <default>] [--max <max>]
The duration of leases offered by the server.
Options:
--default the default lease length, in seconds, to be issued to
clients.
--max the maximum lease length value, in seconds, which the server
will issue to clients who have requested a specific lease
length. With the default value of 0, the max lease length is
equivalent to the default lease length.
--help display usage information
permitted-macs
Usage: ffx net dhcpd set parameter permitted-macs [--macs <macs...>]
The client MAC addresses which the server will issue leases to.
Options:
--macs the client MAC addresses which the server will issue leases
to. By default, the server will not have a permitted MAC
list, in which case it will attempt to issue a lease to
every client which requests one. If permitted_macs has a
non-zero length then the server will only respond to lease
requests from clients with a MAC in the list.
--help display usage information
statically-assigned-addrs
Usage: ffx net dhcpd set parameter statically-assigned-addrs [--hosts <hosts...>] [--assigned-addrs <assigned-addrs...>]
Addresses in the AddressPool which will only be leased to specified clients. Assigned addresses will be paired with hosts in order, e.g. hosts (A, B, C) and addresses (1, 2, 3) pair as ((A, 1), (B, 2), (C, 3)).
Options:
--hosts hosts which will be leased the addresses reserved by
`assigned_addrs`.
--assigned-addrs addresses in the AddressPool which will not be leased to
clients. Typically, a network administrator will statically
assign these addresses to always-on network devices which
should always have the same IP address, such as network
printers.
--help display usage information
start
Usage: ffx net dhcpd start
A primary command to start the DHCP server.
Options:
--help display usage information
stop
Usage: ffx net dhcpd stop
A primary command to stop the DHCP server.
Options:
--help display usage information
dns
Usage: ffx net dns <command> [<args>]
commands to control the dns resolver
Options:
--help display usage information
Commands:
lookup performs dns resolution on the specified hostname
lookup
Usage: ffx net dns lookup <hostname> [--ipv4 <ipv4>] [--ipv6 <ipv6>] [--sort <sort>]
performs dns resolution on the specified hostname
Positional Arguments:
hostname
Options:
--ipv4 include ipv4 results (defaults to true)
--ipv6 include ipv6 results (defaults to true)
--sort sort addresses in order of preference (defaults to true)
--help display usage information
filter
Usage: ffx net filter <command> [<args>]
commands for packet filter
Options:
--help display usage information
Commands:
get-nat-rules gets nat rules
get-rdr-rules gets rdr rules
get-rules gets filter rules
set-nat-rules sets nat rules (see the netfilter::parser library for the
NAT rules format)
set-rdr-rules sets rdr rules (see the netfilter::parser library for the
RDR rules format)
set-rules sets filter rules (see the netfilter::parser library for the
rules format)
get-nat-rules
Usage: ffx net filter get-nat-rules
gets nat rules
Options:
--help display usage information
get-rdr-rules
Usage: ffx net filter get-rdr-rules
gets rdr rules
Options:
--help display usage information
get-rules
Usage: ffx net filter get-rules
gets filter rules
Options:
--help display usage information
set-nat-rules
Usage: ffx net filter set-nat-rules <rules>
sets nat rules (see the netfilter::parser library for the NAT rules format)
Positional Arguments:
rules
Options:
--help display usage information
set-rdr-rules
Usage: ffx net filter set-rdr-rules <rules>
sets rdr rules (see the netfilter::parser library for the RDR rules format)
Positional Arguments:
rules
Options:
--help display usage information
set-rules
Usage: ffx net filter set-rules <rules>
sets filter rules (see the netfilter::parser library for the rules format)
Positional Arguments:
rules
Options:
--help display usage information
if
Usage: ffx net if <command> [<args>]
commands for network interfaces
Options:
--help display usage information
Commands:
add adds a network interface by path
addr commands for updating network interface addresses
bridge creates a bridge between network interfaces
del removes a network interface
disable disables a network interface
enable enables a network interface
get queries a network interface
ip-forward get or set IP forwarding for an interface
list lists network interfaces
add
Usage: ffx net if add <path>
adds a network interface by path
Positional Arguments:
path
Options:
--help display usage information
addr
Usage: ffx net if addr <command> [<args>]
commands for updating network interface addresses
Options:
--help display usage information
Commands:
add adds an address to the network interface
del deletes an address from the network interface
add
Usage: ffx net if addr add <nicid or name:ifname> <addr> <prefix> [--no-subnet-route]
adds an address to the network interface
Positional Arguments:
nicid or name:ifname
addr
prefix
Options:
--no-subnet-route skip adding a local subnet route for this interface and
address
--help display usage information
del
Usage: ffx net if addr del <nicid or name:ifname> <addr> [<prefix>]
deletes an address from the network interface
Positional Arguments:
nicid or name:ifname
addr
prefix
Options:
--help display usage information
bridge
Usage: ffx net if bridge [<nicid or name:ifname...>]
creates a bridge between network interfaces
Positional Arguments:
nicid or name:ifname
Options:
--help display usage information
del
Usage: ffx net if del <nicid or name:ifname>
removes a network interface
Positional Arguments:
nicid or name:ifname
Options:
--help display usage information
disable
Usage: ffx net if disable <nicid or name:ifname>
disables a network interface
Positional Arguments:
nicid or name:ifname
Options:
--help display usage information
enable
Usage: ffx net if enable <nicid or name:ifname>
enables a network interface
Positional Arguments:
nicid or name:ifname
Options:
--help display usage information
get
Usage: ffx net if get <nicid or name:ifname>
queries a network interface
Positional Arguments:
nicid or name:ifname
Options:
--help display usage information
ip-forward
Usage: ffx net if ip-forward <command> [<args>]
get or set IP forwarding for an interface
Options:
--help display usage information
Commands:
show get IP forwarding for an interface
set set IP forwarding for an interface
set
Usage: ffx net if ip-forward set <nicid or name:ifname> <ip_version> <enable>
set IP forwarding for an interface
Positional Arguments:
nicid or name:ifname
ip_version
enable
Options:
--help display usage information
show
Usage: ffx net if ip-forward show <nicid or name:ifname> <ip_version>
get IP forwarding for an interface
Positional Arguments:
nicid or name:ifname
ip_version
Options:
--help display usage information
list
Usage: ffx net if list [<name_pattern>] [--json]
lists network interfaces
Positional Arguments:
name_pattern
Options:
--json format output as JSON
--help display usage information
log
Usage: ffx net log <command> [<args>]
commands for logging
Options:
--help display usage information
Commands:
set-packets log packets to stdout
set-packets
Usage: ffx net log set-packets <enabled>
log packets to stdout
Positional Arguments:
enabled
Options:
--help display usage information
neigh
Usage: ffx net neigh <command> [<args>]
commands for neighbor tables
Options:
--help display usage information
Commands:
add adds an entry to the neighbor table
clear removes all entries associated with a network interface from
the neighbor table
del removes an entry from the neighbor table
list lists neighbor table entries
watch watches neighbor table entries for state changes
config commands for the Neighbor Unreachability Detection
configuration
add
Usage: ffx net neigh add <nicid or name:ifname> <ip> <mac>
adds an entry to the neighbor table
Positional Arguments:
nicid or name:ifname
ip
mac
Options:
--help display usage information
clear
Usage: ffx net neigh clear <nicid or name:ifname> <ip_version>
removes all entries associated with a network interface from the neighbor table
Positional Arguments:
nicid or name:ifname
ip_version
Options:
--help display usage information
config
Usage: ffx net neigh config <command> [<args>]
commands for the Neighbor Unreachability Detection configuration
Options:
--help display usage information
Commands:
get returns the current NUD configuration options for the
provided interface
update updates the current NUD configuration options for the
provided interface
get
Usage: ffx net neigh config get <nicid or name:ifname> <ip_version>
returns the current NUD configuration options for the provided interface
Positional Arguments:
nicid or name:ifname
ip_version
Options:
--help display usage information
update
Usage: ffx net neigh config update <nicid or name:ifname> <ip_version> [--base-reachable-time <base-reachable-time>] [--learn-base-reachable-time <learn-base-reachable-time>] [--min-random-factor <min-random-factor>] [--max-random-factor <max-random-factor>] [--retransmit-timer <retransmit-timer>] [--learn-retransmit-timer <learn-retransmit-timer>] [--delay-first-probe-time <delay-first-probe-time>] [--max-multicast-probes <max-multicast-probes>] [--max-unicast-probes <max-unicast-probes>] [--max-anycast-delay-time <max-anycast-delay-time>] [--max-reachability-confirmations <max-reachability-confirmations>]
updates the current NUD configuration options for the provided interface
Positional Arguments:
nicid or name:ifname
ip_version
Options:
--base-reachable-time
a base duration, in nanoseconds, for computing the random
reachable time
--learn-base-reachable-time
learn `base_reachable_time` during runtime from the neighbor
discovery protocol, if supported
--min-random-factor
the minimum value of the random factor used for computing
reachable time
--max-random-factor
the maximum value of the random factor used for computing
reachable time
--retransmit-timer
duration, in nanoseconds, between retransmissions of
reachability probes in the PROBE state
--learn-retransmit-timer
learn `retransmit_timer` during runtime from the neighbor
discovery protocol, if supported
--delay-first-probe-time
duration, in nanoseconds, to wait for a
non-Neighbor-Discovery related protocol to reconfirm
reachability after entering the DELAY state
--max-multicast-probes
the number of reachability probes to send before concluding
negative reachability and deleting the entry from the
INCOMPLETE state
--max-unicast-probes
the number of reachability probes to send before concluding
retransmissions from within the PROBE state should cease and
the entry SHOULD be deleted
--max-anycast-delay-time
if the target address is an anycast address, the stack
SHOULD delay sending a response for a random time between 0
and this duration, in nanoseconds
--max-reachability-confirmations
a node MAY send up to this amount of unsolicited
reachability confirmations messages to all-nodes multicast
address when a node determines its link-layer address has
changed
--help display usage information
del
Usage: ffx net neigh del <nicid or name:ifname> <ip>
removes an entry from the neighbor table
Positional Arguments:
nicid or name:ifname
ip
Options:
--help display usage information
list
Usage: ffx net neigh list [--json]
lists neighbor table entries
Options:
--json format output as JSON
--help display usage information
watch
Usage: ffx net neigh watch [--json-lines]
watches neighbor table entries for state changes
Options:
--json-lines format output as newline-delimited JSON
--help display usage information
route
Usage: ffx net route <command> [<args>]
commands for routing tables
Options:
--help display usage information
Commands:
list lists devices
add adds a route to the route table
del deletes a route from the route table
add
Usage: ffx net route add --destination <destination> --netmask <netmask or prefix length> [--gateway <gateway>] [--nicid <nicid or name:ifname>] [--metric <metric>]
adds a route to the route table
Options:
--destination the network id of the destination network
--netmask the netmask or prefix length corresponding to destination
--gateway the ip address of the first hop router
--nicid the outgoing network interface of the route
--metric the metric for the route
--help display usage information
del
Usage: ffx net route del --destination <destination> --netmask <netmask or prefix length> [--gateway <gateway>] [--nicid <nicid or name:ifname>] [--metric <metric>]
deletes a route from the route table
Options:
--destination the network id of the destination network
--netmask the netmask or prefix length corresponding to destination
--gateway the ip address of the first hop router
--nicid the outgoing network interface of the route
--metric the metric for the route
--help display usage information
list
Usage: ffx net route list [--json]
lists devices
Options:
--json format output as JSON
--help display usage information
net-test-realm
Usage: ffx net-test-realm <component_moniker> <command> [<args>]
Manage a running Network Test Realm
Positional Arguments:
component_moniker the moniker of the component that corresponds to the Network
Test Realm instance (e.g.
"core/network/test-components\:net_test_realm_controller").
Options:
--help display usage information
Commands:
add-interface Attaches an interface to the hermetic Netstack.
join-multicast-group
Joins a multicast group.
leave-multicast-group
Leaves a multicast group that was previously joined.
ping Sends an ICMP echo request to a target using a socket
provided by the hermetic Netstack.
poll-udp Polls the specified socket address with UDP datagrams
containing the specified payload. Waits for a single reply
from the target address and prints it to stdout.
start-hermetic-network-realm
Starts a hermetic network realm.
start-stub Starts a test stub within the hermetic network realm.
stop-hermetic-network-realm
Stops a running hermetic network realm.
stop-stub Stops the currently running test stub.
dhcpv6-client DHCPv6 client commands.
Notes:
This plugin acts as a thin wrapper around the Network Test Realm Controller protocol.
For more specific information regarding each subcommand, see the underlying protocol definition:
https://osscs.corp.google.com/fuchsia/fuchsia/+/main:src/connectivity/network/testing/network-test-realm/fidl/controller.fidl
Joins
Usage: ffx net-test-realm <component_moniker> <command> [<args>]
Manage a running Network Test Realm
Positional Arguments:
component_moniker the moniker of the component that corresponds to the Network
Test Realm instance (e.g.
"core/network/test-components\:net_test_realm_controller").
Options:
--help display usage information
Commands:
add-interface Attaches an interface to the hermetic Netstack.
join-multicast-group
Joins a multicast group.
leave-multicast-group
Leaves a multicast group that was previously joined.
ping Sends an ICMP echo request to a target using a socket
provided by the hermetic Netstack.
poll-udp Polls the specified socket address with UDP datagrams
containing the specified payload. Waits for a single reply
from the target address and prints it to stdout.
start-hermetic-network-realm
Starts a hermetic network realm.
start-stub Starts a test stub within the hermetic network realm.
stop-hermetic-network-realm
Stops a running hermetic network realm.
stop-stub Stops the currently running test stub.
dhcpv6-client DHCPv6 client commands.
Notes:
This plugin acts as a thin wrapper around the Network Test Realm Controller protocol.
For more specific information regarding each subcommand, see the underlying protocol definition:
https://osscs.corp.google.com/fuchsia/fuchsia/+/main:src/connectivity/network/testing/network-test-realm/fidl/controller.fidl
add-interface
Usage: ffx net-test-realm add-interface <mac_address> <name> [--wait-any-ip-address]
Attaches an interface to the hermetic Netstack.
Positional Arguments:
mac_address address of the interface to be added to the hermetic
Netstack. This should correspond to the address of an
existing system interface.
name the name to assign to the new interface.
Options:
--wait-any-ip-address
whether to wait for any IP address to be assigned to the
interface before returning. This is helpful for tests that
want to ensure the autoconfigured IP address is assigned and
has completed duplicate address detection before proceeding.
--help display usage information
dhcpv6-client
Usage: ffx net-test-realm dhcpv6-client <command> [<args>]
DHCPv6 client commands.
Options:
--help display usage information
Commands:
start Start a DHCPv6 client.
stop Stops all DHCPv6 clients.
start
Usage: ffx net-test-realm dhcpv6-client start <interface_id> <address> --stateful <stateful> [--request-dns-servers]
Start a DHCPv6 client.
Positional Arguments:
interface_id the interface to run the DHCPv6 client on
address the link-local address the DHCPv6 client uses to communicate
with servers
Options:
--stateful whether the DHCPv6 client should run in stateful or
stateless mode
--request-dns-servers
request DNS servers configuration from servers
--help display usage information
stop
Usage: ffx net-test-realm dhcpv6-client stop
Stops all DHCPv6 clients.
Options:
--help display usage information
join-multicast-group
Usage: ffx net-test-realm join-multicast-group <address> <interface_id>
Joins a multicast group.
Positional Arguments:
address the group address to join.
interface_id the ID of the interface that should be used to join the
group.
Options:
--help display usage information
leave-multicast-group
Usage: ffx net-test-realm leave-multicast-group <address> <interface_id>
Leaves a multicast group that was previously joined.
Positional Arguments:
address the group address to leave.
interface_id the ID of the interface that should be used to leave the
group.
Options:
--help display usage information
ping
Usage: ffx net-test-realm ping <target> <payload_length> <timeout> [--interface-name <interface-name>]
Sends an ICMP echo request to a target using a socket provided by the hermetic Netstack.
Positional Arguments:
target the address to ping.
payload_length the body size of the ICMP packet. Specifically, the packet
body will be filled with zeros of the provided length.
timeout a timeout in nanoseconds to wait for a reply. If less than
or equal to 0, then returns success immediately after the
ping is sent.
Options:
--interface-name the name of the source interface.
--help display usage information
poll-udp
Usage: ffx net-test-realm poll-udp <target> <payload> <timeout> <num_retries>
Polls the specified socket address with UDP datagrams containing the specified payload. Waits for a single reply from the target address and prints it to stdout.
Positional Arguments:
target the socket to which to send datagrams
payload the datagram to send
timeout the timeout in nanos to wait for a reply, per retry.
num_retries the number of attempts to make
Options:
--help display usage information
start-hermetic-network-realm
Usage: ffx net-test-realm start-hermetic-network-realm <netstack>
Starts a hermetic network realm.
Positional Arguments:
netstack the Netstack version to start.
Options:
--help display usage information
start-stub
Usage: ffx net-test-realm start-stub <component_url>
Starts a test stub within the hermetic network realm.
Positional Arguments:
component_url the url of the component to start.
Options:
--help display usage information
stop-hermetic-network-realm
Usage: ffx net-test-realm stop-hermetic-network-realm
Stops a running hermetic network realm.
Options:
--help display usage information
stop-stub
Usage: ffx net-test-realm stop-stub
Stops the currently running test stub.
Options:
--help display usage information
Leaves
Usage: ffx net-test-realm <component_moniker> <command> [<args>]
Manage a running Network Test Realm
Positional Arguments:
component_moniker the moniker of the component that corresponds to the Network
Test Realm instance (e.g.
"core/network/test-components\:net_test_realm_controller").
Options:
--help display usage information
Commands:
add-interface Attaches an interface to the hermetic Netstack.
join-multicast-group
Joins a multicast group.
leave-multicast-group
Leaves a multicast group that was previously joined.
ping Sends an ICMP echo request to a target using a socket
provided by the hermetic Netstack.
poll-udp Polls the specified socket address with UDP datagrams
containing the specified payload. Waits for a single reply
from the target address and prints it to stdout.
start-hermetic-network-realm
Starts a hermetic network realm.
start-stub Starts a test stub within the hermetic network realm.
stop-hermetic-network-realm
Stops a running hermetic network realm.
stop-stub Stops the currently running test stub.
dhcpv6-client DHCPv6 client commands.
Notes:
This plugin acts as a thin wrapper around the Network Test Realm Controller protocol.
For more specific information regarding each subcommand, see the underlying protocol definition:
https://osscs.corp.google.com/fuchsia/fuchsia/+/main:src/connectivity/network/testing/network-test-realm/fidl/controller.fidl
add-interface
Usage: ffx net-test-realm add-interface <mac_address> <name> [--wait-any-ip-address]
Attaches an interface to the hermetic Netstack.
Positional Arguments:
mac_address address of the interface to be added to the hermetic
Netstack. This should correspond to the address of an
existing system interface.
name the name to assign to the new interface.
Options:
--wait-any-ip-address
whether to wait for any IP address to be assigned to the
interface before returning. This is helpful for tests that
want to ensure the autoconfigured IP address is assigned and
has completed duplicate address detection before proceeding.
--help display usage information
dhcpv6-client
Usage: ffx net-test-realm dhcpv6-client <command> [<args>]
DHCPv6 client commands.
Options:
--help display usage information
Commands:
start Start a DHCPv6 client.
stop Stops all DHCPv6 clients.
start
Usage: ffx net-test-realm dhcpv6-client start <interface_id> <address> --stateful <stateful> [--request-dns-servers]
Start a DHCPv6 client.
Positional Arguments:
interface_id the interface to run the DHCPv6 client on
address the link-local address the DHCPv6 client uses to communicate
with servers
Options:
--stateful whether the DHCPv6 client should run in stateful or
stateless mode
--request-dns-servers
request DNS servers configuration from servers
--help display usage information
stop
Usage: ffx net-test-realm dhcpv6-client stop
Stops all DHCPv6 clients.
Options:
--help display usage information
join-multicast-group
Usage: ffx net-test-realm join-multicast-group <address> <interface_id>
Joins a multicast group.
Positional Arguments:
address the group address to join.
interface_id the ID of the interface that should be used to join the
group.
Options:
--help display usage information
leave-multicast-group
Usage: ffx net-test-realm leave-multicast-group <address> <interface_id>
Leaves a multicast group that was previously joined.
Positional Arguments:
address the group address to leave.
interface_id the ID of the interface that should be used to leave the
group.
Options:
--help display usage information
ping
Usage: ffx net-test-realm ping <target> <payload_length> <timeout> [--interface-name <interface-name>]
Sends an ICMP echo request to a target using a socket provided by the hermetic Netstack.
Positional Arguments:
target the address to ping.
payload_length the body size of the ICMP packet. Specifically, the packet
body will be filled with zeros of the provided length.
timeout a timeout in nanoseconds to wait for a reply. If less than
or equal to 0, then returns success immediately after the
ping is sent.
Options:
--interface-name the name of the source interface.
--help display usage information
poll-udp
Usage: ffx net-test-realm poll-udp <target> <payload> <timeout> <num_retries>
Polls the specified socket address with UDP datagrams containing the specified payload. Waits for a single reply from the target address and prints it to stdout.
Positional Arguments:
target the socket to which to send datagrams
payload the datagram to send
timeout the timeout in nanos to wait for a reply, per retry.
num_retries the number of attempts to make
Options:
--help display usage information
start-hermetic-network-realm
Usage: ffx net-test-realm start-hermetic-network-realm <netstack>
Starts a hermetic network realm.
Positional Arguments:
netstack the Netstack version to start.
Options:
--help display usage information
start-stub
Usage: ffx net-test-realm start-stub <component_url>
Starts a test stub within the hermetic network realm.
Positional Arguments:
component_url the url of the component to start.
Options:
--help display usage information
stop-hermetic-network-realm
Usage: ffx net-test-realm stop-hermetic-network-realm
Stops a running hermetic network realm.
Options:
--help display usage information
stop-stub
Usage: ffx net-test-realm stop-stub
Stops the currently running test stub.
Options:
--help display usage information
Starts
Usage: ffx net-test-realm <component_moniker> <command> [<args>]
Manage a running Network Test Realm
Positional Arguments:
component_moniker the moniker of the component that corresponds to the Network
Test Realm instance (e.g.
"core/network/test-components\:net_test_realm_controller").
Options:
--help display usage information
Commands:
add-interface Attaches an interface to the hermetic Netstack.
join-multicast-group
Joins a multicast group.
leave-multicast-group
Leaves a multicast group that was previously joined.
ping Sends an ICMP echo request to a target using a socket
provided by the hermetic Netstack.
poll-udp Polls the specified socket address with UDP datagrams
containing the specified payload. Waits for a single reply
from the target address and prints it to stdout.
start-hermetic-network-realm
Starts a hermetic network realm.
start-stub Starts a test stub within the hermetic network realm.
stop-hermetic-network-realm
Stops a running hermetic network realm.
stop-stub Stops the currently running test stub.
dhcpv6-client DHCPv6 client commands.
Notes:
This plugin acts as a thin wrapper around the Network Test Realm Controller protocol.
For more specific information regarding each subcommand, see the underlying protocol definition:
https://osscs.corp.google.com/fuchsia/fuchsia/+/main:src/connectivity/network/testing/network-test-realm/fidl/controller.fidl
add-interface
Usage: ffx net-test-realm add-interface <mac_address> <name> [--wait-any-ip-address]
Attaches an interface to the hermetic Netstack.
Positional Arguments:
mac_address address of the interface to be added to the hermetic
Netstack. This should correspond to the address of an
existing system interface.
name the name to assign to the new interface.
Options:
--wait-any-ip-address
whether to wait for any IP address to be assigned to the
interface before returning. This is helpful for tests that
want to ensure the autoconfigured IP address is assigned and
has completed duplicate address detection before proceeding.
--help display usage information
dhcpv6-client
Usage: ffx net-test-realm dhcpv6-client <command> [<args>]
DHCPv6 client commands.
Options:
--help display usage information
Commands:
start Start a DHCPv6 client.
stop Stops all DHCPv6 clients.
start
Usage: ffx net-test-realm dhcpv6-client start <interface_id> <address> --stateful <stateful> [--request-dns-servers]
Start a DHCPv6 client.
Positional Arguments:
interface_id the interface to run the DHCPv6 client on
address the link-local address the DHCPv6 client uses to communicate
with servers
Options:
--stateful whether the DHCPv6 client should run in stateful or
stateless mode
--request-dns-servers
request DNS servers configuration from servers
--help display usage information
stop
Usage: ffx net-test-realm dhcpv6-client stop
Stops all DHCPv6 clients.
Options:
--help display usage information
join-multicast-group
Usage: ffx net-test-realm join-multicast-group <address> <interface_id>
Joins a multicast group.
Positional Arguments:
address the group address to join.
interface_id the ID of the interface that should be used to join the
group.
Options:
--help display usage information
leave-multicast-group
Usage: ffx net-test-realm leave-multicast-group <address> <interface_id>
Leaves a multicast group that was previously joined.
Positional Arguments:
address the group address to leave.
interface_id the ID of the interface that should be used to leave the
group.
Options:
--help display usage information
ping
Usage: ffx net-test-realm ping <target> <payload_length> <timeout> [--interface-name <interface-name>]
Sends an ICMP echo request to a target using a socket provided by the hermetic Netstack.
Positional Arguments:
target the address to ping.
payload_length the body size of the ICMP packet. Specifically, the packet
body will be filled with zeros of the provided length.
timeout a timeout in nanoseconds to wait for a reply. If less than
or equal to 0, then returns success immediately after the
ping is sent.
Options:
--interface-name the name of the source interface.
--help display usage information
poll-udp
Usage: ffx net-test-realm poll-udp <target> <payload> <timeout> <num_retries>
Polls the specified socket address with UDP datagrams containing the specified payload. Waits for a single reply from the target address and prints it to stdout.
Positional Arguments:
target the socket to which to send datagrams
payload the datagram to send
timeout the timeout in nanos to wait for a reply, per retry.
num_retries the number of attempts to make
Options:
--help display usage information
start-hermetic-network-realm
Usage: ffx net-test-realm start-hermetic-network-realm <netstack>
Starts a hermetic network realm.
Positional Arguments:
netstack the Netstack version to start.
Options:
--help display usage information
start-stub
Usage: ffx net-test-realm start-stub <component_url>
Starts a test stub within the hermetic network realm.
Positional Arguments:
component_url the url of the component to start.
Options:
--help display usage information
stop-hermetic-network-realm
Usage: ffx net-test-realm stop-hermetic-network-realm
Stops a running hermetic network realm.
Options:
--help display usage information
stop-stub
Usage: ffx net-test-realm stop-stub
Stops the currently running test stub.
Options:
--help display usage information
Stops
Usage: ffx net-test-realm <component_moniker> <command> [<args>]
Manage a running Network Test Realm
Positional Arguments:
component_moniker the moniker of the component that corresponds to the Network
Test Realm instance (e.g.
"core/network/test-components\:net_test_realm_controller").
Options:
--help display usage information
Commands:
add-interface Attaches an interface to the hermetic Netstack.
join-multicast-group
Joins a multicast group.
leave-multicast-group
Leaves a multicast group that was previously joined.
ping Sends an ICMP echo request to a target using a socket
provided by the hermetic Netstack.
poll-udp Polls the specified socket address with UDP datagrams
containing the specified payload. Waits for a single reply
from the target address and prints it to stdout.
start-hermetic-network-realm
Starts a hermetic network realm.
start-stub Starts a test stub within the hermetic network realm.
stop-hermetic-network-realm
Stops a running hermetic network realm.
stop-stub Stops the currently running test stub.
dhcpv6-client DHCPv6 client commands.
Notes:
This plugin acts as a thin wrapper around the Network Test Realm Controller protocol.
For more specific information regarding each subcommand, see the underlying protocol definition:
https://osscs.corp.google.com/fuchsia/fuchsia/+/main:src/connectivity/network/testing/network-test-realm/fidl/controller.fidl
add-interface
Usage: ffx net-test-realm add-interface <mac_address> <name> [--wait-any-ip-address]
Attaches an interface to the hermetic Netstack.
Positional Arguments:
mac_address address of the interface to be added to the hermetic
Netstack. This should correspond to the address of an
existing system interface.
name the name to assign to the new interface.
Options:
--wait-any-ip-address
whether to wait for any IP address to be assigned to the
interface before returning. This is helpful for tests that
want to ensure the autoconfigured IP address is assigned and
has completed duplicate address detection before proceeding.
--help display usage information
dhcpv6-client
Usage: ffx net-test-realm dhcpv6-client <command> [<args>]
DHCPv6 client commands.
Options:
--help display usage information
Commands:
start Start a DHCPv6 client.
stop Stops all DHCPv6 clients.
start
Usage: ffx net-test-realm dhcpv6-client start <interface_id> <address> --stateful <stateful> [--request-dns-servers]
Start a DHCPv6 client.
Positional Arguments:
interface_id the interface to run the DHCPv6 client on
address the link-local address the DHCPv6 client uses to communicate
with servers
Options:
--stateful whether the DHCPv6 client should run in stateful or
stateless mode
--request-dns-servers
request DNS servers configuration from servers
--help display usage information
stop
Usage: ffx net-test-realm dhcpv6-client stop
Stops all DHCPv6 clients.
Options:
--help display usage information
join-multicast-group
Usage: ffx net-test-realm join-multicast-group <address> <interface_id>
Joins a multicast group.
Positional Arguments:
address the group address to join.
interface_id the ID of the interface that should be used to join the
group.
Options:
--help display usage information
leave-multicast-group
Usage: ffx net-test-realm leave-multicast-group <address> <interface_id>
Leaves a multicast group that was previously joined.
Positional Arguments:
address the group address to leave.
interface_id the ID of the interface that should be used to leave the
group.
Options:
--help display usage information
ping
Usage: ffx net-test-realm ping <target> <payload_length> <timeout> [--interface-name <interface-name>]
Sends an ICMP echo request to a target using a socket provided by the hermetic Netstack.
Positional Arguments:
target the address to ping.
payload_length the body size of the ICMP packet. Specifically, the packet
body will be filled with zeros of the provided length.
timeout a timeout in nanoseconds to wait for a reply. If less than
or equal to 0, then returns success immediately after the
ping is sent.
Options:
--interface-name the name of the source interface.
--help display usage information
poll-udp
Usage: ffx net-test-realm poll-udp <target> <payload> <timeout> <num_retries>
Polls the specified socket address with UDP datagrams containing the specified payload. Waits for a single reply from the target address and prints it to stdout.
Positional Arguments:
target the socket to which to send datagrams
payload the datagram to send
timeout the timeout in nanos to wait for a reply, per retry.
num_retries the number of attempts to make
Options:
--help display usage information
start-hermetic-network-realm
Usage: ffx net-test-realm start-hermetic-network-realm <netstack>
Starts a hermetic network realm.
Positional Arguments:
netstack the Netstack version to start.
Options:
--help display usage information
start-stub
Usage: ffx net-test-realm start-stub <component_url>
Starts a test stub within the hermetic network realm.
Positional Arguments:
component_url the url of the component to start.
Options:
--help display usage information
stop-hermetic-network-realm
Usage: ffx net-test-realm stop-hermetic-network-realm
Stops a running hermetic network realm.
Options:
--help display usage information
stop-stub
Usage: ffx net-test-realm stop-stub
Stops the currently running test stub.
Options:
--help display usage information
add-interface
Usage: ffx net-test-realm add-interface <mac_address> <name> [--wait-any-ip-address]
Attaches an interface to the hermetic Netstack.
Positional Arguments:
mac_address address of the interface to be added to the hermetic
Netstack. This should correspond to the address of an
existing system interface.
name the name to assign to the new interface.
Options:
--wait-any-ip-address
whether to wait for any IP address to be assigned to the
interface before returning. This is helpful for tests that
want to ensure the autoconfigured IP address is assigned and
has completed duplicate address detection before proceeding.
--help display usage information
containing
Usage: ffx net-test-realm <component_moniker> <command> [<args>]
Manage a running Network Test Realm
Positional Arguments:
component_moniker the moniker of the component that corresponds to the Network
Test Realm instance (e.g.
"core/network/test-components\:net_test_realm_controller").
Options:
--help display usage information
Commands:
add-interface Attaches an interface to the hermetic Netstack.
join-multicast-group
Joins a multicast group.
leave-multicast-group
Leaves a multicast group that was previously joined.
ping Sends an ICMP echo request to a target using a socket
provided by the hermetic Netstack.
poll-udp Polls the specified socket address with UDP datagrams
containing the specified payload. Waits for a single reply
from the target address and prints it to stdout.
start-hermetic-network-realm
Starts a hermetic network realm.
start-stub Starts a test stub within the hermetic network realm.
stop-hermetic-network-realm
Stops a running hermetic network realm.
stop-stub Stops the currently running test stub.
dhcpv6-client DHCPv6 client commands.
Notes:
This plugin acts as a thin wrapper around the Network Test Realm Controller protocol.
For more specific information regarding each subcommand, see the underlying protocol definition:
https://osscs.corp.google.com/fuchsia/fuchsia/+/main:src/connectivity/network/testing/network-test-realm/fidl/controller.fidl
add-interface
Usage: ffx net-test-realm add-interface <mac_address> <name> [--wait-any-ip-address]
Attaches an interface to the hermetic Netstack.
Positional Arguments:
mac_address address of the interface to be added to the hermetic
Netstack. This should correspond to the address of an
existing system interface.
name the name to assign to the new interface.
Options:
--wait-any-ip-address
whether to wait for any IP address to be assigned to the
interface before returning. This is helpful for tests that
want to ensure the autoconfigured IP address is assigned and
has completed duplicate address detection before proceeding.
--help display usage information
dhcpv6-client
Usage: ffx net-test-realm dhcpv6-client <command> [<args>]
DHCPv6 client commands.
Options:
--help display usage information
Commands:
start Start a DHCPv6 client.
stop Stops all DHCPv6 clients.
start
Usage: ffx net-test-realm dhcpv6-client start <interface_id> <address> --stateful <stateful> [--request-dns-servers]
Start a DHCPv6 client.
Positional Arguments:
interface_id the interface to run the DHCPv6 client on
address the link-local address the DHCPv6 client uses to communicate
with servers
Options:
--stateful whether the DHCPv6 client should run in stateful or
stateless mode
--request-dns-servers
request DNS servers configuration from servers
--help display usage information
stop
Usage: ffx net-test-realm dhcpv6-client stop
Stops all DHCPv6 clients.
Options:
--help display usage information
join-multicast-group
Usage: ffx net-test-realm join-multicast-group <address> <interface_id>
Joins a multicast group.
Positional Arguments:
address the group address to join.
interface_id the ID of the interface that should be used to join the
group.
Options:
--help display usage information
leave-multicast-group
Usage: ffx net-test-realm leave-multicast-group <address> <interface_id>
Leaves a multicast group that was previously joined.
Positional Arguments:
address the group address to leave.
interface_id the ID of the interface that should be used to leave the
group.
Options:
--help display usage information
ping
Usage: ffx net-test-realm ping <target> <payload_length> <timeout> [--interface-name <interface-name>]
Sends an ICMP echo request to a target using a socket provided by the hermetic Netstack.
Positional Arguments:
target the address to ping.
payload_length the body size of the ICMP packet. Specifically, the packet
body will be filled with zeros of the provided length.
timeout a timeout in nanoseconds to wait for a reply. If less than
or equal to 0, then returns success immediately after the
ping is sent.
Options:
--interface-name the name of the source interface.
--help display usage information
poll-udp
Usage: ffx net-test-realm poll-udp <target> <payload> <timeout> <num_retries>
Polls the specified socket address with UDP datagrams containing the specified payload. Waits for a single reply from the target address and prints it to stdout.
Positional Arguments:
target the socket to which to send datagrams
payload the datagram to send
timeout the timeout in nanos to wait for a reply, per retry.
num_retries the number of attempts to make
Options:
--help display usage information
start-hermetic-network-realm
Usage: ffx net-test-realm start-hermetic-network-realm <netstack>
Starts a hermetic network realm.
Positional Arguments:
netstack the Netstack version to start.
Options:
--help display usage information
start-stub
Usage: ffx net-test-realm start-stub <component_url>
Starts a test stub within the hermetic network realm.
Positional Arguments:
component_url the url of the component to start.
Options:
--help display usage information
stop-hermetic-network-realm
Usage: ffx net-test-realm stop-hermetic-network-realm
Stops a running hermetic network realm.
Options:
--help display usage information
stop-stub
Usage: ffx net-test-realm stop-stub
Stops the currently running test stub.
Options:
--help display usage information
dhcpv6-client
Usage: ffx net-test-realm dhcpv6-client <command> [<args>]
DHCPv6 client commands.
Options:
--help display usage information
Commands:
start Start a DHCPv6 client.
stop Stops all DHCPv6 clients.
start
Usage: ffx net-test-realm dhcpv6-client start <interface_id> <address> --stateful <stateful> [--request-dns-servers]
Start a DHCPv6 client.
Positional Arguments:
interface_id the interface to run the DHCPv6 client on
address the link-local address the DHCPv6 client uses to communicate
with servers
Options:
--stateful whether the DHCPv6 client should run in stateful or
stateless mode
--request-dns-servers
request DNS servers configuration from servers
--help display usage information
stop
Usage: ffx net-test-realm dhcpv6-client stop
Stops all DHCPv6 clients.
Options:
--help display usage information
from
Usage: ffx net-test-realm <component_moniker> <command> [<args>]
Manage a running Network Test Realm
Positional Arguments:
component_moniker the moniker of the component that corresponds to the Network
Test Realm instance (e.g.
"core/network/test-components\:net_test_realm_controller").
Options:
--help display usage information
Commands:
add-interface Attaches an interface to the hermetic Netstack.
join-multicast-group
Joins a multicast group.
leave-multicast-group
Leaves a multicast group that was previously joined.
ping Sends an ICMP echo request to a target using a socket
provided by the hermetic Netstack.
poll-udp Polls the specified socket address with UDP datagrams
containing the specified payload. Waits for a single reply
from the target address and prints it to stdout.
start-hermetic-network-realm
Starts a hermetic network realm.
start-stub Starts a test stub within the hermetic network realm.
stop-hermetic-network-realm
Stops a running hermetic network realm.
stop-stub Stops the currently running test stub.
dhcpv6-client DHCPv6 client commands.
Notes:
This plugin acts as a thin wrapper around the Network Test Realm Controller protocol.
For more specific information regarding each subcommand, see the underlying protocol definition:
https://osscs.corp.google.com/fuchsia/fuchsia/+/main:src/connectivity/network/testing/network-test-realm/fidl/controller.fidl
add-interface
Usage: ffx net-test-realm add-interface <mac_address> <name> [--wait-any-ip-address]
Attaches an interface to the hermetic Netstack.
Positional Arguments:
mac_address address of the interface to be added to the hermetic
Netstack. This should correspond to the address of an
existing system interface.
name the name to assign to the new interface.
Options:
--wait-any-ip-address
whether to wait for any IP address to be assigned to the
interface before returning. This is helpful for tests that
want to ensure the autoconfigured IP address is assigned and
has completed duplicate address detection before proceeding.
--help display usage information
dhcpv6-client
Usage: ffx net-test-realm dhcpv6-client <command> [<args>]
DHCPv6 client commands.
Options:
--help display usage information
Commands:
start Start a DHCPv6 client.
stop Stops all DHCPv6 clients.
start
Usage: ffx net-test-realm dhcpv6-client start <interface_id> <address> --stateful <stateful> [--request-dns-servers]
Start a DHCPv6 client.
Positional Arguments:
interface_id the interface to run the DHCPv6 client on
address the link-local address the DHCPv6 client uses to communicate
with servers
Options:
--stateful whether the DHCPv6 client should run in stateful or
stateless mode
--request-dns-servers
request DNS servers configuration from servers
--help display usage information
stop
Usage: ffx net-test-realm dhcpv6-client stop
Stops all DHCPv6 clients.
Options:
--help display usage information
join-multicast-group
Usage: ffx net-test-realm join-multicast-group <address> <interface_id>
Joins a multicast group.
Positional Arguments:
address the group address to join.
interface_id the ID of the interface that should be used to join the
group.
Options:
--help display usage information
leave-multicast-group
Usage: ffx net-test-realm leave-multicast-group <address> <interface_id>
Leaves a multicast group that was previously joined.
Positional Arguments:
address the group address to leave.
interface_id the ID of the interface that should be used to leave the
group.
Options:
--help display usage information
ping
Usage: ffx net-test-realm ping <target> <payload_length> <timeout> [--interface-name <interface-name>]
Sends an ICMP echo request to a target using a socket provided by the hermetic Netstack.
Positional Arguments:
target the address to ping.
payload_length the body size of the ICMP packet. Specifically, the packet
body will be filled with zeros of the provided length.
timeout a timeout in nanoseconds to wait for a reply. If less than
or equal to 0, then returns success immediately after the
ping is sent.
Options:
--interface-name the name of the source interface.
--help display usage information
poll-udp
Usage: ffx net-test-realm poll-udp <target> <payload> <timeout> <num_retries>
Polls the specified socket address with UDP datagrams containing the specified payload. Waits for a single reply from the target address and prints it to stdout.
Positional Arguments:
target the socket to which to send datagrams
payload the datagram to send
timeout the timeout in nanos to wait for a reply, per retry.
num_retries the number of attempts to make
Options:
--help display usage information
start-hermetic-network-realm
Usage: ffx net-test-realm start-hermetic-network-realm <netstack>
Starts a hermetic network realm.
Positional Arguments:
netstack the Netstack version to start.
Options:
--help display usage information
start-stub
Usage: ffx net-test-realm start-stub <component_url>
Starts a test stub within the hermetic network realm.
Positional Arguments:
component_url the url of the component to start.
Options:
--help display usage information
stop-hermetic-network-realm
Usage: ffx net-test-realm stop-hermetic-network-realm
Stops a running hermetic network realm.
Options:
--help display usage information
stop-stub
Usage: ffx net-test-realm stop-stub
Stops the currently running test stub.
Options:
--help display usage information
join-multicast-group
Usage: ffx net-test-realm join-multicast-group <address> <interface_id>
Joins a multicast group.
Positional Arguments:
address the group address to join.
interface_id the ID of the interface that should be used to join the
group.
Options:
--help display usage information
leave-multicast-group
Usage: ffx net-test-realm leave-multicast-group <address> <interface_id>
Leaves a multicast group that was previously joined.
Positional Arguments:
address the group address to leave.
interface_id the ID of the interface that should be used to leave the
group.
Options:
--help display usage information
ping
Usage: ffx net-test-realm ping <target> <payload_length> <timeout> [--interface-name <interface-name>]
Sends an ICMP echo request to a target using a socket provided by the hermetic Netstack.
Positional Arguments:
target the address to ping.
payload_length the body size of the ICMP packet. Specifically, the packet
body will be filled with zeros of the provided length.
timeout a timeout in nanoseconds to wait for a reply. If less than
or equal to 0, then returns success immediately after the
ping is sent.
Options:
--interface-name the name of the source interface.
--help display usage information
poll-udp
Usage: ffx net-test-realm poll-udp <target> <payload> <timeout> <num_retries>
Polls the specified socket address with UDP datagrams containing the specified payload. Waits for a single reply from the target address and prints it to stdout.
Positional Arguments:
target the socket to which to send datagrams
payload the datagram to send
timeout the timeout in nanos to wait for a reply, per retry.
num_retries the number of attempts to make
Options:
--help display usage information
provided
Usage: ffx net-test-realm <component_moniker> <command> [<args>]
Manage a running Network Test Realm
Positional Arguments:
component_moniker the moniker of the component that corresponds to the Network
Test Realm instance (e.g.
"core/network/test-components\:net_test_realm_controller").
Options:
--help display usage information
Commands:
add-interface Attaches an interface to the hermetic Netstack.
join-multicast-group
Joins a multicast group.
leave-multicast-group
Leaves a multicast group that was previously joined.
ping Sends an ICMP echo request to a target using a socket
provided by the hermetic Netstack.
poll-udp Polls the specified socket address with UDP datagrams
containing the specified payload. Waits for a single reply
from the target address and prints it to stdout.
start-hermetic-network-realm
Starts a hermetic network realm.
start-stub Starts a test stub within the hermetic network realm.
stop-hermetic-network-realm
Stops a running hermetic network realm.
stop-stub Stops the currently running test stub.
dhcpv6-client DHCPv6 client commands.
Notes:
This plugin acts as a thin wrapper around the Network Test Realm Controller protocol.
For more specific information regarding each subcommand, see the underlying protocol definition:
https://osscs.corp.google.com/fuchsia/fuchsia/+/main:src/connectivity/network/testing/network-test-realm/fidl/controller.fidl
add-interface
Usage: ffx net-test-realm add-interface <mac_address> <name> [--wait-any-ip-address]
Attaches an interface to the hermetic Netstack.
Positional Arguments:
mac_address address of the interface to be added to the hermetic
Netstack. This should correspond to the address of an
existing system interface.
name the name to assign to the new interface.
Options:
--wait-any-ip-address
whether to wait for any IP address to be assigned to the
interface before returning. This is helpful for tests that
want to ensure the autoconfigured IP address is assigned and
has completed duplicate address detection before proceeding.
--help display usage information
dhcpv6-client
Usage: ffx net-test-realm dhcpv6-client <command> [<args>]
DHCPv6 client commands.
Options:
--help display usage information
Commands:
start Start a DHCPv6 client.
stop Stops all DHCPv6 clients.
start
Usage: ffx net-test-realm dhcpv6-client start <interface_id> <address> --stateful <stateful> [--request-dns-servers]
Start a DHCPv6 client.
Positional Arguments:
interface_id the interface to run the DHCPv6 client on
address the link-local address the DHCPv6 client uses to communicate
with servers
Options:
--stateful whether the DHCPv6 client should run in stateful or
stateless mode
--request-dns-servers
request DNS servers configuration from servers
--help display usage information
stop
Usage: ffx net-test-realm dhcpv6-client stop
Stops all DHCPv6 clients.
Options:
--help display usage information
join-multicast-group
Usage: ffx net-test-realm join-multicast-group <address> <interface_id>
Joins a multicast group.
Positional Arguments:
address the group address to join.
interface_id the ID of the interface that should be used to join the
group.
Options:
--help display usage information
leave-multicast-group
Usage: ffx net-test-realm leave-multicast-group <address> <interface_id>
Leaves a multicast group that was previously joined.
Positional Arguments:
address the group address to leave.
interface_id the ID of the interface that should be used to leave the
group.
Options:
--help display usage information
ping
Usage: ffx net-test-realm ping <target> <payload_length> <timeout> [--interface-name <interface-name>]
Sends an ICMP echo request to a target using a socket provided by the hermetic Netstack.
Positional Arguments:
target the address to ping.
payload_length the body size of the ICMP packet. Specifically, the packet
body will be filled with zeros of the provided length.
timeout a timeout in nanoseconds to wait for a reply. If less than
or equal to 0, then returns success immediately after the
ping is sent.
Options:
--interface-name the name of the source interface.
--help display usage information
poll-udp
Usage: ffx net-test-realm poll-udp <target> <payload> <timeout> <num_retries>
Polls the specified socket address with UDP datagrams containing the specified payload. Waits for a single reply from the target address and prints it to stdout.
Positional Arguments:
target the socket to which to send datagrams
payload the datagram to send
timeout the timeout in nanos to wait for a reply, per retry.
num_retries the number of attempts to make
Options:
--help display usage information
start-hermetic-network-realm
Usage: ffx net-test-realm start-hermetic-network-realm <netstack>
Starts a hermetic network realm.
Positional Arguments:
netstack the Netstack version to start.
Options:
--help display usage information
start-stub
Usage: ffx net-test-realm start-stub <component_url>
Starts a test stub within the hermetic network realm.
Positional Arguments:
component_url the url of the component to start.
Options:
--help display usage information
stop-hermetic-network-realm
Usage: ffx net-test-realm stop-hermetic-network-realm
Stops a running hermetic network realm.
Options:
--help display usage information
stop-stub
Usage: ffx net-test-realm stop-stub
Stops the currently running test stub.
Options:
--help display usage information
start-hermetic-network-realm
Usage: ffx net-test-realm start-hermetic-network-realm <netstack>
Starts a hermetic network realm.
Positional Arguments:
netstack the Netstack version to start.
Options:
--help display usage information
start-stub
Usage: ffx net-test-realm start-stub <component_url>
Starts a test stub within the hermetic network realm.
Positional Arguments:
component_url the url of the component to start.
Options:
--help display usage information
stop-hermetic-network-realm
Usage: ffx net-test-realm stop-hermetic-network-realm
Stops a running hermetic network realm.
Options:
--help display usage information
stop-stub
Usage: ffx net-test-realm stop-stub
Stops the currently running test stub.
Options:
--help display usage information
overnet
Usage: ffx overnet <command> [<args>]
Interact with the Overnet mesh
Options:
--help display usage information
Commands:
list-peers List known peer nodes
list-links List links on a particular peer
host-pipe Use stdin/stdout as a link to another overnet instance
full-map Construct a detailed graphviz map of the Overnet mesh -
experts only!
full-map
Usage: ffx overnet full-map --exclude-self <exclude-self>
Construct a detailed graphviz map of the Overnet mesh - experts only!
Options:
--exclude-self if set, exclude the onet tool from output
--help display usage information
host-pipe
Usage: ffx overnet host-pipe
Use stdin/stdout as a link to another overnet instance
Options:
--help display usage information
list-links
Usage: ffx overnet list-links <nodes>
List links on a particular peer
Positional Arguments:
nodes list of nodes to display links for, or 'all' to display
links from all nodes
Options:
--help display usage information
list-peers
Usage: ffx overnet list-peers
List known peer nodes
Options:
--help display usage information
package
Usage: ffx package <command> [<args>]
Create and publish Fuchsia packages
Options:
--help display usage information
Commands:
archive Archive Fuchsia packages
build Builds a package.
download download Package from TUF package server.
archive
Usage: ffx package archive <command> [<args>]
Archive Fuchsia packages
Options:
--help display usage information
Commands:
cat write the contents of <far_path> inside the Fuchia package
archive file to stdout
create create a package archive from a package_manifest.json
extract extract the contents of <far_path> inside the Fuchia
package archive file to the output directory
list List the contents of Fuchia package archive file
cat
Usage: ffx package archive cat <archive> <far_path> [--as-hash]
write the contents of <far_path> inside the Fuchia package archive file to stdout
Positional Arguments:
archive package archive
far_path path of the file within the archive to write
Options:
--as-hash treat filename as a blob hash
--help display usage information
create
Usage: ffx package archive create <package_manifest> -o <output> [-r <root-dir>]
create a package archive from a package_manifest.json
Positional Arguments:
package_manifest package_manifest.json to archive
Options:
-o, --output output package archive
-r, --root-dir root directory for paths in package_manifest.json
--help display usage information
extract
Usage: ffx package archive extract <archive> [<far_paths...>] [-v] [-o <output-dir>] [--as-hash]
extract the contents of <far_path> inside the Fuchia package archive file to the output directory
Positional Arguments:
archive package archive
far_paths files to extract
Options:
-v, --verbose verbose output. Print file names as they are extracted
-o, --output-dir output directory for writing the extracted files. Defaults
to the current directory.
--as-hash treat filenames as blob hashes
--help display usage information
list
Usage: ffx package archive list <archive> [-l]
List the contents of Fuchia package archive file
Positional Arguments:
archive package archive
Options:
-l, --long-format show long information for each entry
--help display usage information
build
Usage: ffx package build <creation_manifest_path> [-o <out>] [--api-level <api-level>] [--abi-revision <abi-revision>] [--published-name <published-name>] [--repository <repository>] [--depfile] [--meta-far-merkle] [--blobs-json] [--blobs-manifest] [--subpackages-manifest-path <subpackages-manifest-path>]
Builds a package.
Positional Arguments:
creation_manifest_path
path to the creation manifest file
Options:
-o, --out directory to save package artifacts
--api-level package API level
--abi-revision package ABI revision
--published-name name of the package
--repository repository of the package
--depfile produce a depfile file
--meta-far-merkle produce a meta.far.merkle file
--blobs-json produce a blobs.json file
--blobs-manifest produce a blobs.manifest file
--subpackages-manifest-path
path to the subpackages manifest file (experimental)
--help display usage information
download
Usage: ffx package download <tuf_url> <blob_url> <target_path> [-o <output-path>]
download Package from TUF package server.
Positional Arguments:
tuf_url URL of TUF repository
blob_url URL of Blobs Server
target_path target_path
Options:
-o, --output-path directory to save package
--help display usage information
platform
Usage: ffx platform <command> [<args>]
Manage platform build prerequisites
Options:
--help display usage information
Commands:
preflight Evaluate suitability for building and running Fuchsia
preflight
Usage: ffx platform preflight [--json]
Evaluate suitability for building and running Fuchsia
Options:
--json outputs json instead of human-readable text.
--help display usage information
power
Usage: ffx power <command> [<args>]
Control system power features
Options:
--help display usage information
Commands:
debugcmd Send a debug command to the Power Manager
debugcmd
Usage: ffx power debugcmd --node-name <node-name> --command <command> [--args <args...>]
Send a debug command to the Power Manager
Options:
--node-name name of target node
--command debug command to send
--args arguments for the debug command
--help display usage information
process_explorer
Usage: ffx process_explorer <command> [<args>]
Query processes related information
Options:
--help display usage information
Commands:
list outputs a list containing the name and koid of all processes
filter outputs information about the processes that correspond to
the koids input
generate-fuchsia-map
outputs the json required to generate a map of all processes
and channels
filter
Usage: ffx process_explorer filter [<process_koids...>]
outputs information about the processes that correspond to the koids input
Positional Arguments:
process_koids process koids
Options:
--help display usage information
generate-fuchsia-map
Usage: ffx process_explorer generate-fuchsia-map
outputs the json required to generate a map of all processes and channels
Options:
--help display usage information
list
Usage: ffx process_explorer list [--verbose]
outputs a list containing the name and koid of all processes
Options:
--verbose outputs all processes and the kernel objects owned by each
of them
--help display usage information
product
Usage: ffx product <command> [<args>]
Discover and access product bundle metadata and image data.
Options:
--help display usage information
Commands:
create Create a Product Bundle using the outputs of Product
Assembly.
get Retrieve image data.
verify Verify that the contents of the product bundle are valid and
ready for use.
create
Usage: ffx product create --partitions <partitions> [--system-a <system-a>] [--system-b <system-b>] [--system-r <system-r>] --out-dir <out-dir>
Create a Product Bundle using the outputs of Product Assembly.
Options:
--partitions path to a partitions config, which lists the physical
partitions of the target.
--system-a path to an assembly manifest, which specifies images to put
in slot A.
--system-b path to an assembly manifest, which specifies images to put
in slot B.
--system-r path to an assembly manifest, which specifies images to put
in slot R.
--out-dir directory to write the product bundle.
--help display usage information
get
Usage: ffx product get <product_bundle_url> [<out_dir>] [--force] [--repository <repository>]
Retrieve image data.
Positional Arguments:
product_bundle_url
url to the product bundle to download.
out_dir local directory to download the product bundle into.
Options:
--force get the data again, even if it's already present locally.
--repository repositories will be named `NAME`. Defaults to the product
bundle name.
--help display usage information
verify
Usage: ffx product verify [--product-bundle <product-bundle>] [--virtual-device <virtual-device>] [--physical-device <physical-device>] [--verified-file <verified-file>]
Verify that the contents of the product bundle are valid and ready for use.
Options:
--product-bundle local path to the product_bundle.json file.
--virtual-device local path to the virtual_device.json file.
--physical-device local path to the physical_device.json file.
--verified-file optional verified file to write after successfully
verifying, so that build systems have an output to watch.
--help display usage information
product-bundle
Usage: ffx product-bundle <command> [<args>]
Discover and access product bundle metadata and image data.
Options:
--help display usage information
Commands:
list Display a list of product bundle names.
get Retrieve image data.
create Create product bundle manifest file.
create
Usage: ffx product-bundle create -t <types> -p <packages> -i <images> [-m <multiboot-bin>] [-d <device-name>] -b <build-info> [-f <flash-manifest>] [-o <out>]
Create product bundle manifest file.
Options:
-t, --types is this product_bundle.json for emulator or flash.
-p, --packages location of packages directory.
-i, --images location of images directory.
-m, --multiboot-bin
path to multiboot.bin file.
-d, --device-name device_spec name.
-b, --build-info path to build_info.json file.
-f, --flash-manifest
path to flash manifest file.
-o, --out path to output directory.
--help display usage information
get
Usage: ffx product-bundle get [<product_bundle_name>] [--cached] [--repository <repository>]
Retrieve image data.
Positional Arguments:
product_bundle_name
get (and cache) data for specific product bundle.
Options:
--cached do no network IO, use the locally cached version or fail.
--repository repositories will be named `NAME`. Defaults to the product
bundle name.
--help display usage information
list
Usage: ffx product-bundle list [--cached]
Display a list of product bundle names.
Options:
--cached do no network IO, use the locally cached version or fail.
--help display usage information
profile
Usage: ffx profile <command> [<args>]
Profile run-time information from various subsystems
Options:
--help display usage information
Commands:
cpu Query CPU-related information
gpu Access GPU usage information
memory Query memory related information
power Access power-related information
temperature Access temperature-related information
cpu
Usage: ffx profile cpu <command> [<args>]
Query CPU-related information
Options:
--help display usage information
Commands:
load Measure CPU load over the specified duration
load
Usage: ffx profile cpu load -d <duration>
Measure CPU load over the specified duration
Options:
-d, --duration duration over which to measure the CPU load
--help display usage information
Examples:
To measure the CPU load over a two second duration
$ ffx profile cpu load --duration 2
Notes:
This command uses the GetCpuLoad method of the fuchsia.kernel.Stats service to query the
the load from each active CPU core in the system. The measured CPU load from each core is
printed in the following format:
CPU 0: 0.66%
CPU 1: 1.56%
CPU 2: 0.83%
CPU 3: 0.71%
Total: 3.76%
The valid range for each CPU load is [0-100]%. The "Total" value represents the summation
of the load percentages of all CPU cores and is valid in the range [0-100*[NUM_CPU]]%
gpu
Usage: ffx profile gpu <command> [<args>]
Access GPU usage information
Options:
--help display usage information
Commands:
usage Controls the metrics-logger component to log gpu usage.
Logged samples will be available in syslog, via iquery under
core/metrics-logger and via tracing in the gpu category.
usage
Usage: ffx profile gpu usage <command> [<args>]
Controls the metrics-logger component to log gpu usage. Logged samples will be available in syslog, via iquery under core/metrics-logger and via tracing in the gpu category.
Options:
--help display usage information
Commands:
start Start logging on the target
stop Stop logging on the target
Examples:
To poll gpu usage every 500 ms indefinitely:
$ ffx profile gpu usage start --interval 500ms
To poll gpu driver every 1 second for 30 seconds with output-to-syslog enabled:
$ ffx profile gpu usage start --interval 1s -d 30s --output-to-syslog
Notes:
If the metrics-logger component is not available to the target, then this command will not work
properly. Add --with //src/testing/metrics-logger to fx set.
start
Usage: ffx profile gpu usage start -s <interval> [--output-to-syslog] [-d <duration>]
Start logging on the target
Options:
-s, --interval interval for polling the GPU driver
--output-to-syslog
toggle for logging samples to syslog
-d, --duration duration for which to log; if omitted, logging will continue
indefinitely
--help display usage information
stop
Usage: ffx profile gpu usage stop
Stop logging on the target
Options:
--help display usage information
memory
Usage: ffx profile memory [--debug-json] [--process-koids <process-koids...>] [--interval <interval>] [--csv] [<command>] [<args>]
Query memory related information
Options:
--debug-json outputs the json returned by memory_monitor. For debug
purposes only, no garantee is made on the stability of the
output of this command.
--process-koids filters by process koids. Repeatable flag.
--interval repeats the command at the given interval (in seconds) until
terminated.
--csv outputs csv that for every process shows the device uptime
in nano seconds, the process koid, the process name, and the
private, scale, and total memory usage. This option is not
supported with other output options like --machine.
--help display usage information
Commands:
signal Signals userspace clients with specified memory pressure
level. Clients can use this command to test their response
to memory pressure. Does not affect the real memory pressure
level on the system, or trigger any kernel reclamation
tasks.
signal
Usage: ffx profile memory signal <level>
Signals userspace clients with specified memory pressure level. Clients can use this command to test their response to memory pressure. Does not affect the real memory pressure level on the system, or trigger any kernel reclamation tasks.
Positional Arguments:
level memory pressure level. Can be CRITICAL, WARNING or NORMAL.
Options:
--help display usage information
power
Usage: ffx profile power <command> [<args>]
Access power-related information
Options:
--help display usage information
Commands:
logger Controls the metrics-logger component to log power. Logged
power samples will be available in syslog, via iquery under
core/metrics-logger and via tracing in the power_logger
category.
logger
Usage: ffx profile power logger <command> [<args>]
Controls the metrics-logger component to log power. Logged power samples will be available in syslog, via iquery under core/metrics-logger and via tracing in the power_logger category.
Options:
--help display usage information
Commands:
start Start logging on the target
stop Stop logging on the target
Examples:
To poll power sensor every 500 ms indefinitely:
$ ffx profile power logger start --sampling-interval 500ms
To poll power sensor every 500 ms and summarize statistics every 1 second for 30 seconds with output-samples-to-syslog and output-stats-to-syslog enabled:
$ ffx profile power logger start --sampling-interval 500ms --statistics-interval 1s --output-stats-to-syslog --output-samples-to-syslog -d 30s
Notes:
If the metrics-logger component is not available to the target, then this command will not work
properly. Add --with //src/testing/metrics-logger to fx set.
start
Usage: ffx profile power logger start [-l <statistics-interval>] -s <sampling-interval> [--output-samples-to-syslog] [--output-stats-to-syslog] [-d <duration>]
Start logging on the target
Options:
-l, --statistics-interval
interval for summarizing statistics; if omitted, statistics
is disabled
-s, --sampling-interval
interval for polling the sensor
--output-samples-to-syslog
toggle for logging samples to syslog
--output-stats-to-syslog
toggle for logging statistics to syslog
-d, --duration duration for which to log; if omitted, logging will continue
indefinitely
--help display usage information
stop
Usage: ffx profile power logger stop
Stop logging on the target
Options:
--help display usage information
temperature
Usage: ffx profile temperature <command> [<args>]
Access temperature-related information
Options:
--help display usage information
Commands:
logger Controls the temperature-logger component
logger
Usage: ffx profile temperature logger <command> [<args>]
Controls the temperature-logger component
Options:
--help display usage information
Commands:
start Start logging on the target
stop Stop logging on the target
Examples:
To log temperatures every 100ms for 30 seconds:
$ ffx profile temperature logger start --interval 100ms --duration 30s
To log temperatures every 1s indefinitely:
$ ffx profile temperature logger start --interval 1s
Notes:
Logged temperatures are not output by this command directly; rather, they will be available via
iquery under core/temperature-logger and via tracing in the temperature_logger category.
If the temperature-logger component is not available to the target, then this command will not work
properly.
start
Usage: ffx profile temperature logger start -i <interval> [-d <duration>]
Start logging on the target
Options:
-i, --interval interval between temperature samples
-d, --duration duration for which to log; if omitted, logging will continue
indefinitely
--help display usage information
stop
Usage: ffx profile temperature logger stop
Stop logging on the target
Options:
--help display usage information
repository
Usage: ffx repository <command> [<args>]
Inspect and manage package repositories
Options:
--help display usage information
Commands:
add-from-pm Make the daemon aware of a specific pm-built repository
default Manage the default repository
list List all repositories
package List the packages inside a repository
remove
server Inspect and manage the repository server
add-from-pm
Usage: ffx repository add-from-pm <pm_repo_path> [-r <repository>]
Make the daemon aware of a specific pm-built repository
Positional Arguments:
pm_repo_path path to the pm-built package repository.
Options:
-r, --repository repositories will be named `NAME`. Defaults to `devhost`.
--help display usage information
default
Usage: ffx repository default <command> [<args>]
Manage the default repository
Options:
--help display usage information
Commands:
get Get the default configured repository
set Set the default repository
unset Clears the default configured repository
Examples:
For one-off overrides for the default use `--repository` option:
$ ffx repository <subcommand> --repository <repository name> ...
Or use the `--config` option:
$ ffx --config repository.default=<repository name> repository <subcommand>
Notes:
Manages the default configured repository for all operations. The default
repository is designated by a `*` next to the name. This is an alias for the
`repository.default` configuration key.
get
Usage: ffx repository default get
Get the default configured repository
Options:
--help display usage information
Notes:
Returns the default configured repository from the 'User Configuration'.
Returns an empty string if no default is configured.
set
Usage: ffx repository default set <name> [-l <level>] [-b <build-dir>]
Set the default repository
Positional Arguments:
name name of the repository
Options:
-l, --level config level, such as 'user', 'build', or 'global'
-b, --build-dir optional directory to associate the provided build config
--help display usage information
Examples:
To set the default repository:
$ ffx repository default set <repository name>
To set the 'repository.default` key at the global configuration:
$ ffx repository default set -l global <repository name>
To specify a default repository for a specific build directory:
$ ffx repository default set -l build -b ~/fuchsia/out <repository name>
Notes:
Sets the `repository.default` configuration key. By default sets the key in
the 'User Configuration'. Can be used in conjuction with `ffx repository list`
to list the names of the discovered repositorys.
After setting the default repository, `ffx repository list` will mark the default
with a `*` in the output list.
unset
Usage: ffx repository default unset [-l <level>] [-b <build-dir>]
Clears the default configured repository
Options:
-l, --level config level, such as 'user', 'build', or 'global'
-b, --build-dir optional directory to associate the provided build config
--help display usage information
Examples:
To clear the default repository:
$ ffx repository default unset
To clear the `repository.default` key from global configuration:
$ ffx repository default unset -l global
To specify a specific build directory:
$ ffx repository default unset -l build -b ~/fuchsia/out
Notes:
Clears the `repository.default` configuration key. By default clears the
'User Configuration'. Returns a warning if the key is already empty.
list
Usage: ffx repository list
List all repositories
Options:
--help display usage information
package
Usage: ffx repository package <command> [<args>]
List the packages inside a repository
Options:
--help display usage information
Commands:
list Inspect and manage package repositories
show Inspect content of a package
list
Usage: ffx repository package list [-r <repository>] [--full-hash] [--include-components <include-components>]
Inspect and manage package repositories
Options:
-r, --repository list packages from this repository.
--full-hash if true, package hashes will be displayed in full (i.e. not
truncated).
--include-components
toggle whether components in each package will be fetched
and shown in the output table
--help display usage information
show
Usage: ffx repository package show <package> [-r <repository>] [--full-hash]
Inspect content of a package
Positional Arguments:
package list this package's contents.
Options:
-r, --repository list package contents from this repository.
--full-hash if true, package hashes will be displayed in full (i.e. not
truncated).
--help display usage information
remove
Usage: ffx repository remove <name>
Positional Arguments:
name name of the repository to remove.
Options:
--help display usage information
server
Usage: ffx repository server <command> [<args>]
Inspect and manage the repository server
Options:
--help display usage information
Commands:
start Starts the repository server
stop Stops the repository server
start
Usage: ffx repository server start
Starts the repository server
Options:
--help display usage information
stop
Usage: ffx repository server stop
Stops the repository server
Options:
--help display usage information
schema
Usage: ffx schema
Print out ffx schema
Options:
--help display usage information
scrutiny
Usage: ffx scrutiny <command> [<args>]
Audit the security of Fuchsia
Options:
--help display usage information
Commands:
extract Extracts common Fuchsia file types
list Lists properties about build artifacts
shell Launch the scrutiny shell
verify Verify the build
extract
Usage: ffx scrutiny extract <command> [<args>]
Extracts common Fuchsia file types
Options:
--help display usage information
Commands:
blobfs Extracts a Blobfs block file
fvm Extracts a FVM file
package Extracts a Fuchsia package from a Url
structured-config Extracts the structured configuration from Fuchsia build
artifacts.
zbi Extracts the Zircon Boot Image
blobfs
Usage: ffx scrutiny extract blobfs <input> <output>
Extracts a Blobfs block file
Positional Arguments:
input
output
Options:
--help display usage information
Examples:
To extract a Blobfs block file:
$ffx scrutiny extract blobfs blob.blk /tmp/blobs
Notes:
Extracts a blobfs block file to a specific directory.
fvm
Usage: ffx scrutiny extract fvm <input> <output>
Extracts a FVM file
Positional Arguments:
input
output
Options:
--help display usage information
Examples:
To extract a FVM file:
$ffx scrutiny extract fvm fvm.blk /tmp/fvm
Notes:
Extracts a FVM to a specific directory.
package
Usage: ffx scrutiny extract package <url> <output>
Extracts a Fuchsia package from a Url
Positional Arguments:
url
output
Options:
--help display usage information
Examples:
To extract a Fuchsia package from a url:
$ ffx scrutiny extract package fuchsia-pkg://fuchsia.com/foo /tmp/foo
Notes:
Extracts a package to a specific directory.
structured-config
Usage: ffx scrutiny extract structured-config --build-path <build-path> --update <update> [--blobfs <blobfs...>] --depfile <depfile> --output <output>
Extracts the structured configuration from Fuchsia build artifacts.
Options:
--build-path path to the build directory.
--update relative path to the update package within the build
directory.
--blobfs build_path-relative paths to blobfs images.
--depfile path to a depfile that should be written for build
integration
--output path to file to which to write the extracted configuration.
--help display usage information
Notes:
Extracts structured configuration
zbi
Usage: ffx scrutiny extract zbi <input> <output>
Extracts the Zircon Boot Image
Positional Arguments:
input
output
Options:
--help display usage information
Examples:
To extract a Zircon Boot Image:
$ffx scrutiny extract zbi foo.zbi /tmp/foo
Notes:
Extracts a ZBI to a specific directory.
list
Usage: ffx scrutiny list <command> [<args>]
Lists properties about build artifacts
Options:
--help display usage information
Commands:
components Lists all the components in the build
package Lists all the files in a package
packages Lists all the packages in the build
components
Usage: ffx scrutiny list components --build-path <build-path>
Lists all the components in the build
Options:
--build-path path to the build directory.
--help display usage information
Examples:
To list all the components in the build:
$ffx scrutiny list components
Notes:
Lists all the components in the build in a json format.
package
Usage: ffx scrutiny list package --build-path <build-path> --url <url>
Lists all the files in a package
Options:
--build-path path to the build directory.
--url fuchsia url to the package.
--help display usage information
Examples:
To list all the files in a package:
$ ffx scrutiny list package fuchsia-pkg://fuchsia.com/foo
Notes:
Lists all the package contents in json format.
packages
Usage: ffx scrutiny list packages --build-path <build-path>
Lists all the packages in the build
Options:
--build-path path to the build directory.
--help display usage information
Examples:
To list all the packages in the build:
$ffx scrutiny list packages
Notes:
Lists all the packages in the build in a json format.
shell
Usage: ffx scrutiny shell [<command>] [-b <build>] [-s <script>] [-m <model>] [-l <log>] [-p <port>] [-v <verbosity>]
Launch the scrutiny shell
Positional Arguments:
command
Options:
-b, --build set a custom path to the build directory
-s, --script run a file as a scrutiny script
-m, --model set a custom path to the data model
-l, --log set a custom path output log
-p, --port set a custom port to run scrutiny on
-v, --verbosity set the verbosity level of logging
--help display usage information
Examples:
To start an interactive shell session:
$ ffx scrutiny shell
To run commands directly:
$ ffx scrutiny shell components
$ ffx scrutiny shell "search.packages --files fdio"
Notes:
Launches an interactive scrutiny shell where scrutiny specific
commands can be run. This will also launch a server on port 127.0.0.1:8080
by default that provides visual auditing tools.
Inside the shell run help for a full list of available commands. If you wish to
integrate Scrutiny as part of a wider script check out the --script option.
verify
Usage: ffx scrutiny verify [--depfile <depfile>] [--stamp <stamp>] [--tmp-dir <tmp-dir>] <command> [<args>]
Verify the build
Options:
--depfile path to depfile that gathers dependencies during execution.
--stamp path to stamp file to write to if and only if verification
succeeds.
--tmp-dir path to directory to use for temporary files.
--help display usage information
Commands:
bootfs Verifies list of files in bootfs embedded in ZBI image
against a golden file
component-resolvers
Verifies that component configured to use custom component
resolvers are permitted by an allowlist.
kernel-cmdline Verifies that kernel cmdline arguments match golden files.
route-sources Verifies that routes to designated components are routed
from designated sources.
routes Verifies capability routes in the component tree
static-pkgs Check the static packages extracted from the ZBI against
golden files
structured-config Verifies component configuration according to configured
assertions.
bootfs
Usage: ffx scrutiny verify bootfs --zbi <zbi> [--golden <golden...>] [--golden-packages <golden-packages...>]
Verifies list of files in bootfs embedded in ZBI image against a golden file
Options:
--zbi absolute or working directory-relative path to ZBI image
file that contains bootfs.
--golden absolute or working directory-relative path(s) to golden
file(s) for verifying bootfs paths.
--golden-packages absolute or working directory-relative path(s) to golden
file(s) for verifying bootfs packages.
--help display usage information
Examples:
To verify bootfs on your current build:
$ ffx scrutiny verify bootfs \
--zbi $(fx get-build-dir)/obj/build/images/fuchsia/fuchsia/fuchsia.zbi \
--golden /path/to/goldens/product.txt \
--golden /path/to/goldens/board.txt
Notes:
Verifies all file paths in bootfs.
component-resolvers
Usage: ffx scrutiny verify component-resolvers --build-path <build-path> --update <update> [--blobfs <blobfs...>] --allowlist <allowlist>
Verifies that component configured to use custom component resolvers are permitted by an allowlist.
Options:
--build-path absolute or working directory-relative path to fuchsia build
directory.
--update absolute or build path-relative path to fuchsia update
package.
--blobfs absolute or build path-relative path to one or more blobfs
archives that contain fuchsia packages and their packages.
--allowlist absolute or build path-relative path to allowlist file that
specifies which components may use particular custom
component resolvers.
--help display usage information
Examples:
To verify component resolvers on your current eng build:
$ ffx scrutiny verify component-resolvers --build-path $(fx get-build-dir) --update obj/build/images/fuchsia/update/update.far --blobfs obj/build/images/fuchsia/fuchsia/blob.blk --blobfs obj/build/images/fuchsia/update/gen/update.blob.blk --allowlist ../../src/security/policy/component_resolvers_policy.json5
Notes:
Verifies all components that use a custom component resolver.
kernel-cmdline
Usage: ffx scrutiny verify kernel-cmdline --zbi <zbi> [--golden <golden...>]
Verifies that kernel cmdline arguments match golden files.
Options:
--zbi absolute or working directory-relative path to ZBI image
file that contains bootfs.
--golden absolute or working directory-relative path(s) to golden
files to compare against during verification.
--help display usage information
Examples:
To verify kernel cmdline arguments on your current build:
$ ffx scrutiny verify kernel-cmdline \
--zbi $(fx get-build-dir)/obj/build/images/fuchsia/fuchsia/fuchsia.zbi \
--golden path/to/golden
route-sources
Usage: ffx scrutiny verify route-sources --build-path <build-path> --update <update> [--blobfs <blobfs...>] --config <config>
Verifies that routes to designated components are routed from designated sources.
Options:
--build-path absolute or working directory-relative path to root output
directory of build.
--update absolute or build path-relative path to fuchsia update
package.
--blobfs absolute or build path-relative path to one or more blobfs
archives that contain fuchsia packages and their packages.
--config absolute or build path-relative path to configuration file
that specifies components and their expected route sources.
--help display usage information
Examples:
To verify route sources according to a configuration file on your current build:
$ ffx scrutiny verify route-sources
--build-path $(fx get-build-dir) \
--update obj/build/images/fuchsia/update/update.far \
--blobfs obj/build/images/fuchsia/fuchsia/blob.blk \
--blobfs obj/build/images/fuchsia/update/gen/update.blob.blk \
--config path/to/verify_route_sources/product.board.json5
routes
Usage: ffx scrutiny verify routes [--capability-type <capability-type...>] [--response-level <response-level>] --build-path <build-path> --update <update> [--blobfs <blobfs...>] [--allowlist <allowlist...>] [--component-tree-config <component-tree-config>]
Verifies capability routes in the component tree
Options:
--capability-type capability types to verify.
--response-level response level to report from routes scrutiny plugin.
--build-path absolute or working directory-relative path to root output
directory of build.
--update absolute or build path-relative path to fuchsia update
package.
--blobfs absolute or build path-relative path to one or more blobfs
archives that contain fuchsia packages and their packages,
typically repeated for a system blobfs archive and a blobfs
archive of blobs in the update package.
--allowlist absolute or build path-relative path(s) to allowlist(s) used
to verify routes.
--component-tree-config
absolute or build path-relative path to component tree
configuration file that affects how component tree data is
gathered.
--help display usage information
Examples:
To verify routes on your current build:
$ ffx scrutiny verify routes \
--build-path $(fx get-build-dir) \
--update obj/build/images/fuchsia/update/update.far \
--blobfs obj/build/images/fuchsia/fuchsia/blob.blk \
--blobfs obj/build/images/fuchsia/update/gen/update.blob.blk \
--allowlist ../../src/security/policy/build/verify_routes_exceptions_allowlist.json5
static-pkgs
Usage: ffx scrutiny verify static-pkgs --build-path <build-path> --update <update> [--blobfs <blobfs...>] [--golden <golden...>]
Check the static packages extracted from the ZBI against golden files
Options:
--build-path path to root output directory of build.
--update path to fuchsia update package.
--blobfs path to one or more blobfs archives that contain fuchsia
packages and their packages.
--golden path(s) to golden file(s) used to verify routes.
--help display usage information
Examples:
To verify static packages on your current build:
$ ffx scrutiny verify static-pkgs --build-path $(fx get-build-dir) --blobfs-manifest path/to/blob.manifest --golden path/to/golden
structured-config
Usage: ffx scrutiny verify structured-config --policy <policy> --build-path <build-path> --update <update> [--blobfs <blobfs...>]
Verifies component configuration according to configured assertions.
Options:
--policy absolute or working directory-relative path to a policy file
for structured configuration
--build-path path to the build directory
--update build-directory-relative path to the update package manifest
--blobfs build-directory-relative paths to blobfs block images
--help display usage information
sdk
Usage: ffx sdk <command> [<args>]
Modify or query the installed SDKs
Options:
--help display usage information
Commands:
version Retrieve the version of the current SDK
set Set sdk-related configuration options
set
Usage: ffx sdk set <command> [<args>]
Set sdk-related configuration options
Options:
--help display usage information
Commands:
root Sets the path to the root of the preferred SDK
root
Usage: ffx sdk set root <path>
Sets the path to the root of the preferred SDK
Positional Arguments:
path path to the sdk root
Options:
--help display usage information
version
Usage: ffx sdk version
Retrieve the version of the current SDK
Options:
--help display usage information
self-test
Usage: ffx self-test [--timeout <timeout>] [--case-timeout <case-timeout>] [--include-target <include-target>] [--filter <filter>] [<command>] [<args>]
Execute the ffx self-test (e2e) suite
Options:
--timeout maximum runtime of entire test suite in seconds
--case-timeout maximum run time of a single test case in seconds
--include-target include target interaction tests
--filter filter test cases
--help display usage information
Commands:
experiment A fake experiment for the ffx self-test (e2e) suite
experiment
Usage: ffx self-test experiment
A fake experiment for the ffx self-test (e2e) suite
Options:
--help display usage information
session
Usage: ffx session <command> [<args>]
Control the current session. See https://fuchsia.dev/fuchsia-src/concepts/session/introduction for details.
Options:
--help display usage information
Commands:
add Add an element to the current session
launch Launch a session
restart Restart the current session. See
https://fuchsia.dev/fuchsia-src/concepts/session/introduction
for details.
show Show information about the current session
add
Usage: ffx session add <url> [<args...>] [--interactive]
Add an element to the current session
Positional Arguments:
url component URL for the element to add
args arguments passed to the element
Options:
--interactive pass to keep element alive until command exits
--help display usage information
Examples:
To add the bouncing_ball.cm component as an element:
$ ffx session add fuchsia-pkg://fuchsia.com/bouncing_ball#meta/bouncing_ball.cm
To pass arguments to a legacy (cmx) component, specify them after the component URL:
$ ffx session add fuchsia-pkg://fuchsia.com/spinning-square-rs#meta/spinning-square-rs.cmx foo --bar=baz
Arguments are not supported for modern (cm) components.
launch
Usage: ffx session launch <url>
Launch a session
Positional Arguments:
url the component URL of a session.
Options:
--help display usage information
Examples:
To use the tiling session manager:
$ fx set workstation_eng.x64 --with //src/session/examples/tiles-session
$ ffx session launch fuchsia-pkg://fuchsia.com/tiles-session#meta/tiles-session.cm
This will launch the tiling session manager if a session is not already active. For a detailed explanation of sessions, see https://fuchsia.dev/fuchsia-src/concepts/session/introduction
restart
Usage: ffx session restart
Restart the current session. See https://fuchsia.dev/fuchsia-src/concepts/session/introduction for details.
Options:
--help display usage information
show
Usage: ffx session show
Show information about the current session
Options:
--help display usage information
setui
Usage: ffx setui <command> [<args>]
Modify and query settings.
Options:
--help display usage information
Commands:
accessibility watch or set accessibility settings
audio get or set audio settings
display get or set display settings
do_not_disturb get or set DnD settings
factory_reset get or set factory reset settings
input get or set input settings
intl get or set internationalization settings
keyboard get or set keyboard settings
light get or set light settings
night_mode get or set night mode settings
privacy get or set privacy settings
setup get or set setup settings
volume_policy read or configure volume policy
accessibility
Usage: ffx setui accessibility <command> [<args>]
watch or set accessibility settings
Options:
--help display usage information
Commands:
add-caption add caption options, the configuration for which sources get
closed caption and how they look
set set other accessibility options
watch watch current accessibility settings
add-caption
Usage: ffx setui accessibility add-caption [-m <for-media>] [-t <for-tts>] [-w <window-color>] [-b <background-color>] [-f <font-family>] [-c <font-color>] [-r <relative-size>] [-e <char-edge-style>]
add caption options, the configuration for which sources get closed caption and how they look
Options:
-m, --for-media enable closed captions for media sources of audio
-t, --for-tts enable closed captions for Text-To-Speech sources of audio
-w, --window-color
border color used around the closed captions window. Valid
options are red, green, and blue
-b, --background-color
border color used around the closed captions window. Valid
options are red, green, and blue
-f, --font-family font family for captions as specified by 47 CFR §79.102(k).
Valid options are unknown, monospaced_serif,
proportional_serif, monospaced_sans_serif,
proportional_sans_serif, casual, cursive, and small_capitals
-c, --font-color color of the closed caption text. Valid options are red,
green, and blue
-r, --relative-size
size of closed captions text relative to the default
captions size, specified in the range [0.5, 2] as per 47 CFR
§79.103(c)(4)
-e, --char-edge-style
edge style for fonts as specified in 47 CFR §79.103(c)(7).
Valid options are none, drop_shadow, raised, depressed,
outline
--help display usage information
set
Usage: ffx setui accessibility set [-a <audio-description>] [-s <screen-reader>] [-i <color-inversion>] [-m <enable-magnification>] [-c <color-correction>]
set other accessibility options
Options:
-a, --audio-description
when set to 'true', will turn on an audio track for videos
that includes a description of what is occurring in the
video
-s, --screen-reader
when set to 'true', will read aloud elements of the screen
selected by the user
-i, --color-inversion
when set to 'true', will invert the colors on the screen
-m, --enable-magnification
when set to 'true', will interpret triple-taps on the
touchscreen as a command to zoom in
-c, --color-correction
configures the type of color-blindness to correct for. Valid
options are none, protanomaly, deuteranomaly, and
tritanomaly
--help display usage information
watch
Usage: ffx setui accessibility watch
watch current accessibility settings
Options:
--help display usage information
audio
Usage: ffx setui audio [-t <stream>] [-s <source>] [-l <level>] [-v <volume-muted>]
get or set audio settings
Options:
-t, --stream which stream should be modified. Valid options are
background, media, interruption, system_agent, and
communication
-s, --source which source is changing the stream. Valid options are user,
system, and system_with_feedback
-l, --level the volume level specified as a float in the range [0, 1]
-v, --volume-muted
whether or not the volume is muted
--help display usage information
display
Usage: ffx setui display <command> [<args>]
get or set display settings
Options:
--help display usage information
Commands:
set Sets display settings.
get Get the current display settings.
watch Get the current display settings and watch for changes.
get
Usage: ffx setui display get [-f <field>]
Get the current display settings.
Options:
-f, --field choose which display settings field value to return, valid
options are auto and brightness
--help display usage information
set
Usage: ffx setui display set [-b <brightness>] [-o <auto-brightness-level>] [-a <auto-brightness>] [-m <low-light-mode>] [-t <theme>] [-s <screen-enabled>]
Sets display settings.
Options:
-b, --brightness the brightness value specified as a float in the range [0,
1]
-o, --auto-brightness-level
the brightness values used to control auto brightness as a
float in the range [0, 1]
-a, --auto-brightness
when set to 'true', enables auto brightness
-m, --low-light-mode
which low light mode setting to enable. Valid options are
enable, disable, and disable_immediately
-t, --theme which theme to set for the device. Valid options are
default, dark, light, darkauto, and lightauto
-s, --screen-enabled
when set to 'true' the screen is enabled
--help display usage information
watch
Usage: ffx setui display watch
Get the current display settings and watch for changes.
Options:
--help display usage information
do_not_disturb
Usage: ffx setui do_not_disturb [-u <user-dnd>] [-n <night-mode-dnd>]
get or set DnD settings
Options:
-u, --user-dnd when set to 'true', allows the device to enter do not
disturb mode
-n, --night-mode-dnd
when set to 'true', forces the device into do not disturb
mode
--help display usage information
factory_reset
Usage: ffx setui factory_reset [-l <is-local-reset-allowed>]
get or set factory reset settings
Options:
-l, --is-local-reset-allowed
when set to 'true', factory reset can be performed on the
device
--help display usage information
input
Usage: ffx setui input [-t <device-type>] [-n <name>] [-s <state>]
get or set input settings
Options:
-t, --device-type the type of input device. Valid options are camera and
microphone
-n, --name the name of the device. Must be unique within a device type
-s, --state the device state flags, pass a comma separated string of the
values available, active, muted, disabled and error. E.g.
"-s available,active"
--help display usage information
intl
Usage: ffx setui intl [-z <time-zone>] [-u <temperature-unit>] [-l <locales...>] [-h <hour-cycle>] [--clear-locales]
get or set internationalization settings
Options:
-z, --time-zone a valid timezone matching the data available at
https://www.iana.org/time-zones
-u, --temperature-unit
the unit to use for temperature. Valid options are celsius
and fahrenheit
-l, --locales list of locales, separated by spaces, formatted by Unicode
BCP-47 Locale Identifier, e.g. en-us
-h, --hour-cycle the hour cycle to use. Valid options are h11 for 12-hour
clock with 0:10 am after midnight, h12 for 12-hour clock
with 12:10am after midnight, h23 for 24-hour clock with 0:10
after midnight, and h24 for 24-hour clock with 24:10 after
midnight
--clear-locales if set, this flag will set locales as an empty list.
Overrides the locales arguments
--help display usage information
keyboard
Usage: ffx setui keyboard [-k <keymap>] [-d <autorepeat-delay>] [-p <autorepeat-period>]
get or set keyboard settings
Options:
-k, --keymap keymap selection for the keyboard. Valid options are
UsQwerty, FrAzerty, and UsDvorak.
-d, --autorepeat-delay
delay value of autorepeat values for the keyboard. Values
should be a positive integer plus an SI time unit. Valid
units are s, ms. If this value and autorepeat_period are
zero, the autorepeat field of KeyboardSettings will be
cleaned as None.
-p, --autorepeat-period
period value of autorepeat values for the keyboard. Values
should be a positive integer plus an SI time unit. Valid
units are s, ms. If this value and autorepeat_delay are
zero, the autorepeat field of KeyboardSettings will be
cleaned as None.
--help display usage information
light
Usage: ffx setui light [-n <name>] [-s <simple...>] [-b <brightness...>] [-r <rgb...>]
get or set light settings
Options:
-n, --name name of a light group to set values for. Required if setting
the value of a light group
-s, --simple repeated parameter for a list of simple on/off values to set
for a light group.
-b, --brightness repeated parameter for a list of floating point brightness
values in the range [0, 1] for a light group
-r, --rgb repeated parameter for a list of RGB values to set for a
light group. Values should be in the range [0, 1] and
specified as a comma-separated list of the red, green, and
blue components. Ex. 0.1,0.4,0.23
--help display usage information
night_mode
Usage: ffx setui night_mode [-n <night-mode-enabled>]
get or set night mode settings
Options:
-n, --night-mode-enabled
when 'true', enables night mode
--help display usage information
privacy
Usage: ffx setui privacy [-u <user-data-sharing-consent>]
get or set privacy settings
Options:
-u, --user-data-sharing-consent
when 'true', is considered to be user giving consent to have
their data shared with product owner, e.g. for metrics
collection and crash reporting
--help display usage information
setup
Usage: ffx setui setup [-i <interfaces>]
get or set setup settings
Options:
-i, --interfaces a supported group of interfaces, specified as a
comma-delimited string of the valid values eth and wifi,
e.g. "-i eth,wifi" or "-i wifi"
--help display usage information
volume_policy
Usage: ffx setui volume_policy <command> [<args>]
read or configure volume policy
Options:
--help display usage information
Commands:
add Adds a new volume policy.
get Get the current volume policy.
remove Remove a policy transform by its policy ID.
add
Usage: ffx setui volume_policy add <target> [--min <min>] [--max <max>]
Adds a new volume policy.
Positional Arguments:
target target stream to apply the policy transform to. Valid
options are (non-case sensitive): background, b; media, m;
interruption, i; system_agent, s; communication, c.
Options:
--min the minimum allowed value for the target
--max the maximum allowed value for the target
--help display usage information
get
Usage: ffx setui volume_policy get
Get the current volume policy.
Options:
--help display usage information
remove
Usage: ffx setui volume_policy remove -p <policy-id>
Remove a policy transform by its policy ID.
Options:
-p, --policy-id removes a policy transform by its policy ID.
--help display usage information
sl4f
Usage: ffx sl4f <command> [<args>]
Manage the sl4f server
Options:
--help display usage information
Commands:
start start the host-side SL4FBridge HTTP server
start
Usage: ffx sl4f start
start the host-side SL4FBridge HTTP server
Options:
--help display usage information
starnix
Usage: ffx starnix <command> [<args>]
Control starnix processes
Options:
--help display usage information
Commands:
adb Bridge from host adb to adbd running inside starnix
shell Start a shell inside starnix
start Start a component inside starnix
adb
Usage: ffx starnix adb [-g <galaxy>]
Bridge from host adb to adbd running inside starnix
Options:
-g, --galaxy the galaxy in which to connect to adb
--help display usage information
Examples:
ffx starnix adb
shell
Usage: ffx starnix shell [-u <url>]
Start a shell inside starnix
Options:
-u, --url the URL of the shell component to connect to.
--help display usage information
Examples:
To start a shell inside starnix:
$ ffx starnix shell
start
Usage: ffx starnix start <url>
Start a component inside starnix
Positional Arguments:
url
Options:
--help display usage information
Examples:
To start a component inside starnix:
$ ffx starnix start <url>
storage
Usage: ffx storage <command> [<args>]
Manage Fuchsia Filesystems
Options:
--help display usage information
Commands:
blackout Power failure testing for the filesystems
blackout
Usage: ffx storage blackout <command> [<args>]
Power failure testing for the filesystems
Options:
--help display usage information
Commands:
step Execute a specific test step. This assumes that a blackout
target component is already running, named blackout-target,
in core/ffx-laboratory, and that it serves the
fuchsia.blackout.test.Controller protocol.
integration Run a blackout e2e integration test
blobfs-checkerboard
Run a power-failure test on blobfs with a checkerboard load
pattern
fs-tree Run a power-failure test on a mutable fs (e.g. Fxfs or
minfs). Load pattern: generate, move, and delete random
directory trees.
blobfs-checkerboard
Usage: ffx storage blackout blobfs-checkerboard [-l <device-label>] [-p <device-path>] [-s <seed>] [-r <relay>] [--dmc-reboot] [-i <iterations>] [-f] [--bootserver]
Run a power-failure test on blobfs with a checkerboard load pattern
Options:
-l, --device-label
the label of the partition the test should use. If one isn't
provided a default is used.
-p, --device-path the path of the block device on the target device to use for
testing. If one isn't provided the test will pick an
appropriate one. WARNING: the test can (and likely will!)
format this device. Don't use a main system partition!
-s, --seed a seed to use for all random operations. Tests are NOT
deterministic relative to the provided seed. The operations
will be identical, but because of the non-deterministic
timing-dependent nature of the tests, the exact time the
reboot is triggered in relation to the operations is not
guaranteed. One will be randomly generated if not provided.
When performing the same test multiple times in one run, a
new seed will be generated for each run if one was not
provided.
-r, --relay path to a power relay for cutting the power to a device.
Probably the highest-numbered /dev/ttyUSB[N]. If in doubt,
try removing it and seeing what disappears from /dev. When a
relay is provided, the harness automatically switches to use
hardware reboots.
--dmc-reboot use dmc to trigger reboots. Only works in infra.
-i, --iterations run the test N number of times, collecting statistics on the
number of failures.
-f, --run-until-failure
run the test until a verification failure is detected, then
exit.
--bootserver run a bootserver to serve netboot images to a device. This
will only work in infra!
--help display usage information
fs-tree
Usage: ffx storage blackout fs-tree [-p <device-path>] -f <format> [-s <seed>] [-r <relay>] [--dmc-reboot] [-i <iterations>] [-f] [--bootserver]
Run a power-failure test on a mutable fs (e.g. Fxfs or minfs). Load pattern: generate, move, and delete random directory trees.
Options:
-p, --device-path the path of the block device on the target device to use for
testing. If one isn't provided the test will pick an
appropriate one. WARNING: the test can (and likely will!)
format this device. Don't use a main system partition!
-f, --format which filesystem format to target.
-s, --seed a seed to use for all random operations. Tests are NOT
deterministic relative to the provided seed. The operations
will be identical, but because of the non-deterministic
timing-dependent nature of the tests, the exact time the
reboot is triggered in relation to the operations is not
guaranteed. One will be randomly generated if not provided.
When performing the same test multiple times in one run, a
new seed will be generated for each run if one was not
provided.
-r, --relay path to a power relay for cutting the power to a device.
Probably the highest-numbered /dev/ttyUSB[N]. If in doubt,
try removing it and seeing what disappears from /dev. When a
relay is provided, the harness automatically switches to use
hardware reboots.
--dmc-reboot use dmc to trigger reboots. Only works in infra.
-i, --iterations run the test N number of times, collecting statistics on the
number of failures.
-f, --run-until-failure
run the test until a verification failure is detected, then
exit.
--bootserver run a bootserver to serve netboot images to a device. This
will only work in infra!
--help display usage information
integration
Usage: ffx storage blackout integration [-i <iterations>] [--reboot] [--dmc-reboot] [--bootserver]
Run a blackout e2e integration test
Options:
-i, --iterations run the test N number of times, collecting statistics on the
number of failures.
--reboot configure the tests to add a reboot step between the load
and verification steps.
--dmc-reboot use dmc to trigger reboots. Only works in infra.
--bootserver run a bootserver in the background for serving netboot
images. This only works when the test is run by botanist, as
the environment variables and bootserver arguments are
specific to that environment.
--help display usage information
step
Usage: ffx storage blackout step <command> [<args>]
Execute a specific test step. This assumes that a blackout target component is already running, named blackout-target, in core/ffx-laboratory, and that it serves the fuchsia.blackout.test.Controller protocol.
Options:
--help display usage information
Commands:
setup Run the setup step
test Run the test step
verify Run the verify step
setup
Usage: ffx storage blackout step setup <device_label> <seed> [--device-path <device-path>]
Run the setup step
Positional Arguments:
device_label block device partition label the test is going to be run on.
Setup will likely create this partition in fvm.
seed seed to use for any random operations.
Options:
--device-path optional block device path to run the test on. If no path is
given the test will find an appropriate device.
--help display usage information
test
Usage: ffx storage blackout step test <device_label> <seed> [--device-path <device-path>] [--duration <duration>]
Run the test step
Positional Arguments:
device_label block device partition label the test is going to be run on.
seed seed to use for any random operations.
Options:
--device-path optional block device path to run the test on. If no path is
given the test will find an appropriate device.
--duration optional duration for which the test should execute. If the
duration is zero, this step will return when it's complete,
which might be never. If a non-zero duration is provided the
test command will exit after that amount of time. Note that
the test itself executes asynchronously and may continue to
run even after the test command returns. If no duration
duration is provided the default is zero. In all cases,
errors returned from the test during the duration (or at any
time, if the duration is zero) cause the command to exit
with a non-zero exit code. Information about the failure
will be present in the syslog of the target device.
--help display usage information
verify
Usage: ffx storage blackout step verify <device_label> <seed> [--device-path <device-path>]
Run the verify step
Positional Arguments:
device_label block device partition label the test is going to be run on.
seed seed to use for any random operations.
Options:
--device-path optional block device path to run the test on. If no path is
given the test will find an appropriate device.
--help display usage information
target
Usage: ffx target <command> [<args>]
Interact with a target device or emulator
Options:
--help display usage information
Commands:
add Make the daemon aware of a specific target
bootloader Communicates with the bootloader
clear-preferred-ssh-address
Clears a previously configured SSH address
default Manage the default target
echo run echo test against the target
flash Flash an image to a target device
forward Forward ports from a target
get-ssh-address Get the target's ssh address
list List all targets
off Powers off a target
reboot Reboots a target
remove Make the daemon forget a specific target
repository Interact with target repository registration
set-preferred-ssh-address
Sets the preferred SSH address
show Display relevant information for the target
snapshot Takes a snapshot of the target's state
update Update base system software on target
wait Wait until able to establish a remote control connection to
the target.
Notes:
The `target` subcommand contains various commands for target management
and interaction.
Typically, this is the entry workflow for users, allowing for target
discovery and provisioning before moving on to `component` or `session`
workflows once the system is up and running on the target.
Most of the commands depend on the RCS (Remote Control Service) on the
target.
add
Usage: ffx target add <addr> [-n]
Make the daemon aware of a specific target
Positional Arguments:
addr IP of the target.
Options:
-n, --nowait do not wait for a connection to be verified on the Fuchsia
device.
--help display usage information
Examples:
To add a remote target forwarded via ssh:
$ ffx target add 127.0.0.1:8022
Or to add a target using its IPV6:
$ ffx target add fe80::32fd:38ff:fea8:a00a
Notes:
Manually add a target based on its IP address. The command accepts IPV4
or IPV6 addresses, including a port number: `<addr> = <ip addr:port>`.
Typically, the daemon automatically discovers targets as they come online.
However, manually adding a target allows for specifying a port number or
address, often used for remote workflows.
This command will attempt to connect to the target in order to verify that RCS can
be used, allowing for typical FFX related workflows. If you do not wish to use
this, then you can run use the `--nowait` flag to return immediately. This can be
useful for debugging connection issues.
If you send SIGINT (Ctrl-C) to the command before the connection to the target is
verified, the target will be removed. If RCS cannot be connected to (e.g. some
connectivity error is encountered), the target will also be removed.
bootloader
Usage: ffx target bootloader [-m <manifest>] [-p <product>] [-b <product-bundle>] [--skip-verify] <command> [<args>]
Communicates with the bootloader
Options:
-m, --manifest path to flashing manifest or zip file containing images and
manifest
-p, --product product entry in manifest - defaults to `fuchsia`
-b, --product-bundle
optional product bundle name
--skip-verify skip hardware verification. This is dangerous, please be
sure the images you are using match the device
--help display usage information
Commands:
lock Locks a fastboot target.
unlock Unlocks a fastboot target.
boot RAM boots a fastboot target.
info Prints fastboot variables for target.
boot
Usage: ffx target bootloader boot [-z <zbi>] [-v <vbmeta>] [-s <slot>]
RAM boots a fastboot target.
Options:
-z, --zbi optional zbi image file path to use
-v, --vbmeta optional vbmeta image file path to use
-s, --slot slot corresponding to partitions in the flash manifest -
only used if zbi and vbmeta files are not present
--help display usage information
info
Usage: ffx target bootloader info
Prints fastboot variables for target.
Options:
--help display usage information
lock
Usage: ffx target bootloader lock
Locks a fastboot target.
Options:
--help display usage information
unlock
Usage: ffx target bootloader unlock [-c <cred>] [--force]
Unlocks a fastboot target.
Options:
-c, --cred optional path to credential file to use to unlock the device
--force skips the warning message that this command is dangerous
--help display usage information
clear-preferred-ssh-address
Usage: ffx target clear-preferred-ssh-address
Clears a previously configured SSH address
Options:
--help display usage information
Notes:
Clears a preferred SSH address that was set using the
set-preferred-ssh-address command on the default target. Executing this command
severs any existing connection to the target and establishes a new connection.
The newly selected address is chosen using the standard address selection
logic.
default
Usage: ffx target default <command> [<args>]
Manage the default target
Options:
--help display usage information
Commands:
get Get the default configured target
set Set the default target
unset Clears the default configured target
Examples:
For one-off overrides for the default use `--target` option:
$ ffx --target <target name> <subcommand>
Or use the `--config` option:
$ ffx --config target.default=<target name> <subcommand>
Notes:
Manages the default configured target for all operations. The default
target is designated by a `*` next to the name. This is an alias for the
`target.default` configuration key.
get
Usage: ffx target default get
Get the default configured target
Options:
--help display usage information
Notes:
Returns the default configured target from the 'User Configuration'.
Returns an empty string if no default is configured.
set
Usage: ffx target default set <nodename> [-l <level>] [-b <build-dir>]
Set the default target
Positional Arguments:
nodename node name of the target
Options:
-l, --level config level, such as 'user', 'build', or 'global'
-b, --build-dir optional directory to associate the provided build config
--help display usage information
Examples:
To set the default target:
$ ffx target default set <target name>
To set the 'target.default` key at the global configuration:
$ ffx target default set -l global <target name>
To specify a default target for a specific build directory:
$ ffx target default set -l build -b ~/fuchsia/out <target name>
Notes:
Sets the `target.default` configuration key. By default sets the key in
the 'User Configuration'. Can be used in conjuction with `ffx target list`
to list the names of the discovered targets.
After setting the default target, `ffx target list` will mark the default
with a `*` in the output list.
unset
Usage: ffx target default unset [-l <level>] [-b <build-dir>]
Clears the default configured target
Options:
-l, --level config level, such as 'user', 'build', or 'global'
-b, --build-dir optional directory to associate the provided build config
--help display usage information
Examples:
To clear the default target:
$ ffx target default unset
To clear the `target.default` key from global configuration:
$ ffx target default unset -l global
To specify a specific build directory:
$ ffx target default unset -l build -b ~/fuchsia/out
Notes:
Clears the `target.default` configuration key. By default clears the
'User Configuration'. Returns a warning if the key is already empty.
echo
Usage: ffx target echo [<text>]
run echo test against the target
Positional Arguments:
text text string to echo back and forth
Options:
--help display usage information
flash
Usage: ffx target flash [<manifest>] [-p <product>] [-b <product-bundle>] [--oem-stage <oem-stage...>] [--authorized-keys <authorized-keys>] [--no-bootloader-reboot] [--skip-verify]
Flash an image to a target device
Positional Arguments:
manifest path to flashing manifest or zip file containing images and
manifest
Options:
-p, --product product entry in manifest - defaults to `fuchsia`
-b, --product-bundle
optional product bundle name
--oem-stage oem staged file - can be supplied multiple times
--authorized-keys path to authorized keys file - will default to the value
configured for `ssh.pub` key in ffx config. If the file does
not exist, it will be created.
--no-bootloader-reboot
the device should not reboot after bootloader images are
flashed
--skip-verify skip hardware verification. This is dangerous, please be
sure the images you are flashing match the device
--help display usage information
Examples:
To flash a specific image:
$ ffx target flash $(fx get-build-dir)/flash.json --product fuchsia
To include SSH keys as well:
$ ffx target flash
--authorized-keys ~/fuchsia/.ssh/authorized_keys
$(fx get-build-dir)/flash.json
--product fuchsia
Notes:
Flashes an image to a target device using the fastboot protocol.
Requires a specific <manifest> file and <product> name as an input.
This is only applicable to a physical device and not an emulator target.
The target device is typically connected via a micro-USB connection to
the host system.
The <manifest> format is a JSON file generated when building a fuchsia
<product> and can be found in the build output directory.
The `--oem-stage` option can be supplied multiple times for several OEM
files. The format expects a single OEM command to execute after staging
the given file.
The format for the `--oem-stage` parameter is a comma separated pair:
'<OEM_COMMAND>,<FILE_TO_STAGE>'
forward
Usage: ffx target forward <command> [<args>]
Forward ports from a target
Options:
--help display usage information
Commands:
tcp Forward a TCP port from the target to the host
tcp
Usage: ffx target forward tcp <host_address> <target_address>
Forward a TCP port from the target to the host
Positional Arguments:
host_address
target_address
Options:
--help display usage information
get-ssh-address
Usage: ffx target get-ssh-address [-t <timeout>]
Get the target's ssh address
Options:
-t, --timeout the timeout in seconds [default = 1.0]
--help display usage information
Notes:
Return the SSH address of the default target defined in the
`target.default` key. By default this comes from the 'User Configuration'.
The command takes a <timeout> value in seconds with a default of `1.0`
and overrides the value in the `target.interaction.timeout` key.
Error codes:
1 Timeout while getting ssh address
2 Unable to get ssh address from target
list
Usage: ffx target list [<nodename>] [-f <format>] [--no-ipv4] [--no-ipv6]
List all targets
Positional Arguments:
nodename
Options:
-f, --format determines the output format for the list operation
--no-ipv4 do not return IPv4 addresses
--no-ipv6 do not return IPv6 addresses
--help display usage information
Examples:
To list targets in short form:
$ ffx target list --format s
fe80::4415:3606:fb52:e2bc%zx-f80ff974f283 pecan-guru-clerk-rhyme
To list targets with only their addresses:
$ ffx target list --format a
fe80::4415:3606:fb52:e2bc%zx-f80ff974f283
Notes:
List all targets that the daemon currently has in memory. This includes
manually added targets. The daemon also proactively discovers targets as
they come online. Use `ffx target list` to always get the latest list
of targets.
The default target is marked with a '*' next to the node name. The table
has the following columns:
NAME = The name of the target.
SERIAL = The serial number of the target.
TYPE = The product type of the target.
STATE = The high-level state of the target.
ADDRS/IP = The discovered and known addresses of the target.
RCS = Indicates if the Remote Control Service is running on the target.
The NAME column shows the target's advertised name. When the target is
in early boot state such as fastboot, the NAME column may be `<unknown>` with
a STATE being `fastboot` and a SERIAL attribute.
By default, the `list` command outputs in a tabular format. To override
the format, pass `--format` and can take the following options: 'simple'
, 'tabular|table|tab', 'addresses|addrs|addr', 'name-only', 'json|JSON' or
in short form 's', 't', 'a', 'n', 'j'.
By default, Zedboot discovery is disabled. To enable discovery of Zedboot
targets run:
$ ffx config set discovery.zedboot.enabled true
Error codes:
2 If a nodename is supplied, an error code of 2 will be returned if the nodename cannot be resolved
off
Usage: ffx target off
Powers off a target
Options:
--help display usage information
Notes:
Power off a target. Uses the 'fuchsia.hardware.power.statecontrol.Admin'
FIDL API to send the power off command.
The 'fuchsia.hardware.power.statecontrol.Admin' is exposed via the 'appmgr'
component. To verify that the target exposes this service, `ffx component
select` or `ffx component knock` can be used.
Error codes:
1 Timeout while powering off target.
reboot
Usage: ffx target reboot [-b] [-r]
Reboots a target
Options:
-b, --bootloader reboot to bootloader
-r, --recovery reboot to recovery
--help display usage information
Notes:
Reboot a target. Uses the 'fuchsia.hardware.power.statecontrol.Admin'
FIDL API to send the reboot command.
By default, target boots fully. This behavior can be overrided by passing
in either `--bootloader` or `--recovery` to boot into the bootloader or
recovery, respectively.
The 'fuchsia.hardware.power.statecontrol.Admin' is exposed via the 'appmgr'
component. To verify that the target exposes this service, `ffx component
select` or `ffx component knock` can be used.
Error codes:
1 Timeout while powering off target.
remove
Usage: ffx target remove <name_or_addr>
Make the daemon forget a specific target
Positional Arguments:
name_or_addr name or IP address of the target.
Options:
--help display usage information
Examples:
To remove a target by its target name:
$ ffx target remove correct-horse-battery-staple
Or to remove a target using its IP address:
$ ffx target remove fe80::32fd:38ff:fea8:a00a
Notes:
IP addresses are matched by their full string representation.
for best results, copy the exact address from ffx target list.
repository
Usage: ffx target repository <command> [<args>]
Interact with target repository registration
Options:
--help display usage information
Commands:
deregister Make the target forget a specific repository
list List all the repositories on a target
register Make the target aware of a specific repository
Notes:
The `repository` subcommand contains various commands for repository management
and interaction on targets.
Most of the commands depend on the RCS (Remote Control Service) on the target.
deregister
Usage: ffx target repository deregister [-r <repository>]
Make the target forget a specific repository
Options:
-r, --repository remove the repository named `name` from the target, rather
than the default.
--help display usage information
list
Usage: ffx target repository list
List all the repositories on a target
Options:
--help display usage information
register
Usage: ffx target repository register [-r <repository>] [--storage-type <storage-type>] [--alias <alias...>]
Make the target aware of a specific repository
Options:
-r, --repository register this repository, rather than the default.
--storage-type enable persisting this repository across reboots.
--alias set up a rewrite rule mapping each `alias` host to to the
repository identified by `name`.
--help display usage information
set-preferred-ssh-address
Usage: ffx target set-preferred-ssh-address <addr>
Sets the preferred SSH address
Positional Arguments:
addr the SSH IP address to use. This must correspond to a known
address on the target.
Options:
--help display usage information
Examples:
To set a preferred IPv4 SSH address:
$ ffx target set-preferred-ssh-address 127.0.0.1
Or to set a preferred IPv6 SSH address:
$ ffx target set-preferred-ssh-addres fe80::32fd:38ff:fea8:a00a%qemu
If provided, the scope may either correspond to the numerical ID or the
interface name.
Notes:
Manually set the preferred SSH address on the default target. If
successful, then any existing connection to the target is severed and a new
connection is established. The specified address is not persisted across daemon
version changes or restarts.
show
Usage: ffx target show [--desc] [--label] [--json] [--version]
Display relevant information for the target
Options:
--desc display descriptions of entries
--label display label of entries
--json formats output as json objects
--version display version
--help display usage information
Notes:
Displays a detailed information about the target.
The default output is intended for a human reader. This output can be
decorated with machine readable labels (--label) and descriptions of
each field (--desc).
The 'label' fields in the machine readable output (--json) will remain
stable across software updates and is not localized (compare to 'title'
which may change or be localized). The 'value' field will be one of:
'null', 'bool', 'string', or a list of strings.
Error codes:
1 Timeout retrieving target information.
snapshot
Usage: ffx target snapshot [-d <dir>] [--dump-annotations]
Takes a snapshot of the target's state
Options:
-d, --dir valid directory where the snapshot will be stored
--dump-annotations
print annotations without capturing the snapshot, ignores
`dir` flag
--help display usage information
Examples:
Store the target's snapshot in the current directory:
$ ffx target snapshot -d .
Exported ./snapshot.zip
Notes:
This command connects to a running target to acquire its snapshot, which contains
useful debugging information about the target. The `--dir` can be supplied to override the default
snapshot directory `/tmp/snapshots/YYYYMMDD_HHMMSS/`.
Snapshot contents:
- Build information and annotations
- Kernel and system logs
- Inspect data
update
Usage: ffx target update <command> [<args>]
Update base system software on target
Options:
--help display usage information
Commands:
channel View and manage update channels
check-now Check and perform the system update operation
force-install Trigger the system updater manually
Notes:
This command interfaces with system update services on the target.
channel
Usage: ffx target update channel <command> [<args>]
View and manage update channels
Options:
--help display usage information
Commands:
get-current Return the currently configured update channel
get-next Return the next or target update channel
set Sets the update channel
list List the known update channels
Notes:
Channel management commands and operations. Interfaces directly with
the 'fuchsia.update.channelcontrol.ChannelControl' service on the target
system.
get-current
Usage: ffx target update channel get-current
Return the currently configured update channel
Options:
--help display usage information
Notes:
For developer product configurations, this is by default 'devhost'.
Error codes:
1 Timeout while getting update channel.
get-next
Usage: ffx target update channel get-next
Return the next or target update channel
Options:
--help display usage information
Notes:
Returns the next or target channel. This differs from `get` when the
next successful update changes the configured update channel on the
system.
Error codes:
1 Timeout while getting update channel.
list
Usage: ffx target update channel list
List the known update channels
Options:
--help display usage information
Notes:
This lists all the known next or target update channels on the system.
Returns an empty list if no other update channels are configured.
Error codes:
1 Timeout while getting list of update channel.
set
Usage: ffx target update channel set <channel>
Sets the update channel
Positional Arguments:
channel
Options:
--help display usage information
Examples:
To list all the known update channels:
$ ffx target update channel list
Then, use a valid channel from the list:
$ ffx target update channel set <channel>
Notes:
Sets the next or target update channel on the device. When paired with
`ffx target update check-now`, ensures the update is check against the
next or target channel. When the update is successful, next or target
channel becomes the current channel.
Use `ffx target update channel list` to list known system update
channels.
Error codes:
1 Timeout while setting update channel.
check-now
Usage: ffx target update check-now [--service-initiated] [--monitor]
Check and perform the system update operation
Options:
--service-initiated
the update check was initiated by a service, in the
background.
--monitor monitor for state update.
--help display usage information
Examples:
To check for update and monitor progress:
$ ffx target update check-now --monitor
Notes:
Triggers an update check operation and performs the update if available.
Interfaces using the 'fuchsia.update Manager' protocol with the system
update service on the target.
The command takes in an optional `--monitor` switch to watch the progress
of the update. The output is displayed in `stdout`.
The command also takes an optional `--service-initiated` switch to indicate
a separate service has initiated a check for update.
force-install
Usage: ffx target update force-install <update_pkg_url> [--reboot <reboot>]
Trigger the system updater manually
Positional Arguments:
update_pkg_url the url of the update package describing the update to
install
Options:
--reboot automatically trigger a reboot into the new system
--help display usage information
Examples:
With a known update package URL, trigger an update:
$ ffx target update force-install fuchsia-pkg://fuchsia.com/update
Also trigger a reboot after update:
$ ffx target update force-install
fuchsia-pkg://fuchsia.com/update
--reboot
Notes:
Directly invoke the system updater to install the provided update,
bypassing any update checks.
Interfaces using the 'fuchsia.update.installer' protocol to update the
system. Requires an <update_pkg_url> in the following format:
`fuchsia-pkg://fuchsia.com/update`
Takes an optional `--reboot <true|false>` to trigger a system reboot
after update has been successfully applied.
wait
Usage: ffx target wait [-t <timeout>]
Wait until able to establish a remote control connection to the target.
Options:
-t, --timeout the timeout in seconds [default = 120]
--help display usage information
Error codes:
1 Timeout while getting ssh address
test
Usage: ffx test <command> [<args>]
Run test suite
Options:
--help display usage information
Commands:
run Entry point for executing tests
list-cases List test suite cases
result Manage test results
Notes:
Run tests or inspect output from a previous test run.
list-cases
Usage: ffx test list-cases <test_url>
List test suite cases
Positional Arguments:
test_url test url
Options:
--help display usage information
Notes:
Lists the set of test cases available in a test suite
result
Usage: ffx test result <command> [<args>]
Manage test results
Options:
--help display usage information
Commands:
show Display test results
list List test results
delete Delete test results
save Save test results
Notes:
Inspect and manage the results from previous test runs
delete
Usage: ffx test result delete [--index <index>] [--name <name>]
Delete test results
Options:
--index when set, display the results of a run with specified index.
--name when set, display the results of a run with specified name.
--help display usage information
Notes:
Manually delete a previous test run result.
Either --index or --name must be specified.
list
Usage: ffx test result list
List test results
Options:
--help display usage information
Notes:
Display a list of previous test runs
save
Usage: ffx test result save --index <index> --name <name>
Save test results
Options:
--index the index of the test result to save.
--name the name to assign the saved test result.
--help display usage information
Notes:
Mark a test result so it is not garbage collected.
By default, ffx test only retains the last 'n' test results, as configured
with 'test.save_count'. A test result saved and given a name using the save
command will be exempted from this cleanup and will not be counted towards the
total number of saved test results.
show
Usage: ffx test result show [--directory <directory>] [--index <index>] [--name <name>]
Display test results
Options:
--directory when set, display the results of the specified directory.
--index when set, display the results of a run with specified index.
--name when set, display the results of a run with specified name.
--help display usage information
Notes:
Display the results of a previous test run.
When no options are provided, displays the results of the most recent test run.
run
Usage: ffx test run [<test_args...>] [-t <timeout>] [--test-file <test-file>] [--test-filter <test-filter...>] [--run-disabled] [--filter-ansi] [--continue-on-timeout] [--stop-after-failures <stop-after-failures>] [--parallel <parallel>] [--count <count>] [--min-severity-logs <min-severity-logs>] [--max-severity-logs <max-severity-logs>] [--show-full-moniker-in-logs] [--output-directory <output-directory>] [--experimental-parallel-execution <experimental-parallel-execution>] [--disable-output-directory]
Entry point for executing tests
Positional Arguments:
test_args test url, and any arguments passed to tests, following `--`.
When --test-file is specified test_args should not be
specified.
Options:
-t, --timeout test timeout in seconds
--test-file read test url and options from the specified file instead of
from the command line. Stdin may be specified by passing
`--test-file -`. May not be used in conjunction with
`test_args`, `--test-file`, `--test-filter`,
`--run-disabled`, `--parallel`, `--max-severity-logs` This
option is currently unstable and the format of the file is
subject to change. For current details, see test-list.json
format at
https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/src/lib/testing/test_list/
--test-filter test filter. Glob pattern for matching tests. Can be
specified multiple times to pass in multiple patterns. Tests
may be excluded by prepending a '-' to the glob pattern.
example: --test-filter glob1 --test-filter glob2
--test-filter -glob3.
--run-disabled whether to also run tests that have been marked
disabled/ignored by the test author.
--filter-ansi whether to filter ANSI escape sequences from output
--continue-on-timeout
continue running unfinished suites if a suite times out. By
default, unfinished suites are immediately terminated if a
suite times out. This option is only relevant when multiple
suites are run.
--stop-after-failures
stop running unfinished suites after the number of provided
failures has occurred. By default, all suites are run to
completion if a suite fails.
--parallel run tests in parallel, up to the number provided.
--count number of times to run the test. By default run 1 time. If
an iteration of the test times out, no further iterations
are executed.
--min-severity-logs
when set, only logs with a severity equal to the given one
or higher will be printed.
--max-severity-logs
when set, the test will fail if any log with a higher
severity is emitted.
--show-full-moniker-in-logs
when set, shows the full moniker in unstructured log output.
--output-directory
when set, output test results to the specified directory.
--experimental-parallel-execution
enables experimental parallel test scheduler. The provided
number specifies the max number of test suites to run in
parallel. If the value provided is 0, a default value will
be chosen by the server implementation.
--disable-output-directory
when set, disables structured output to a directory.
--help display usage information
Notes:
Runs test suites implementing the `fuchsia.test.Suite` protocol.
Tests are specified either as a command line argument, or via JSON file.
For example, when specifying a test via command line:
ffx test run fuchsia-pkg://fuchsia.com/my_test#meta/my_test.cm
When specifying a test via command line and passing arguments to the test:
ffx test run fuchsia-pkg://fuchsia.com/my_test#meta/my_test.cm -- arg1 arg2
Specifying tests via JSON file is currently unstable, but may be done with the
--test-file option.
Note that if running multiple iterations of a test and an iteration times
out, no further iterations will be executed.
trace
Usage: ffx trace <command> [<args>]
Interact with the tracing subsystem.
Options:
--help display usage information
Commands:
list-categories List the target's known trace categories.
list-providers List the target's trace providers.
start Record a trace.
stop Stops an active running trace.
status Gets status of all running traces.
list-categories
Usage: ffx trace list-categories
List the target's known trace categories.
Options:
--help display usage information
list-providers
Usage: ffx trace list-providers
List the target's trace providers.
Options:
--help display usage information
start
Usage: ffx trace start [--buffering-mode <buffering-mode>] [--buffer-size <buffer-size>] [--categories <categories>] [--duration <duration>] [--output <output>] [--background] [--trigger <trigger...>]
Record a trace.
Options:
--buffering-mode the buffering to use on the trace. Defaults to "oneshot".
Accepted values are "oneshot," "circular," and "streaming."
--buffer-size size of per-provider trace buffer in MB. Defaults to 4.
--categories comma-separated list of categories to enable. Defaults to
"app,audio,benchmark,blobfs,gfx,input,kernel:meta,
kernel:sched,ledger,magma,minfs,modular,view,flutter,
dart,dart:compiler,dart:dart,dart:debugger,dart:embedder,
dart:gc,dart:isolate,dart:profiler,dart:vm"
--duration duration of trace capture in seconds.
--output name of output trace file. Defaults to trace.fxt.
--background whether to run the trace in the background. Defaults to
false, which means the trace will run in "interactive" mode.
--trigger a trigger consists of an alert leading to an action. An
alert is written into the code being traced, and an action
here is what to do when the alert has happened. The list of
supported actions are: 'terminate'. The expected format is
"<alert>:<action>" ex: -trigger "my_alert:terminate" This
can be used with a duration, but keep in mind that this
introduces a race between whether the alert leads to an
action, and when the trace stops from the duration being
reached. Triggers can only be used in the background outside
of interactive mode.
--help display usage information
status
Usage: ffx trace status
Gets status of all running traces.
Options:
--help display usage information
stop
Usage: ffx trace stop [--output <output>]
Stops an active running trace.
Options:
--output name of output trace file. Relative or absolute paths are
both supported. If this is not supplied (the default), then
the default target will be used as the method to stop the
trace.
--help display usage information
triage
Usage: ffx triage [--config <config...>] [--data <data>] [--tag <tag...>] [--exclude-tag <exclude-tag...>]
Analyze Logs and Inspect in snapshots to find problems.
Options:
--config path to config file or dir
--data path to snapshot.zip or uncompressed dir
--tag adds an action tags to include
--exclude-tag adds an action tags to exclude
--help display usage information
version
Usage: ffx version [-v]
Print out ffx tool and daemon versions
Options:
-v, --verbose if true, includes details about both ffx and the daemon
--help display usage information
wlan
Usage: ffx wlan <command> [<args>]
Developer tool for manipulating WLAN state.
Options:
--help display usage information
Commands:
ap Controls WLAN AP policy API.
client Controls WLAN client policy API.
deprecated Controls to-be-deleted WLAN functionality.
dev Warning: this tool may cause state mismatches between layers
of the WLAN
subsystem. It is intended for use by WLAN
developers only. Please reach out
to the WLAN team if your
use case relies on it.
To disable the WLAN policy
layer:
ffx wlan client stop
ffx wlan ap stop-all
To enable
WLAN policy layer and begin automated WLAN behavior:
ffx
wlan client start
ffx wlan ap start --ssid <SSID_HERE>
ap
Usage: ffx wlan ap <command> [<args>]
Controls WLAN AP policy API.
Options:
--help display usage information
Commands:
listen Listens for policy AP updates
start Start an access point interface
stop Stop an access point interface
stop-all Stops all active APs
listen
Usage: ffx wlan ap listen
Listens for policy AP updates
Options:
--help display usage information
Examples:
To begin listening for AP events
$ ffx wlan ap listen
start
Usage: ffx wlan ap start [--ssid <ssid>] [--security-type <security-type>] [--credential-type <credential-type>] [--credential <credential>]
Start an access point interface
Options:
--ssid WLAN network name
--security-type one of None, WEP, WPA, WPA2, WPA3
--credential-type one of None, PSK, Password
--credential WLAN Password or PSK
--help display usage information
Examples:
To start an AP
$ffx wlan ap start
--ssid TestNetwork
--security-type wpa2
--credential-type password
--credential "Your very secure password here"
Notes:
Only one application at a time can interact with the WLAN policy layer.
stop
Usage: ffx wlan ap stop [--ssid <ssid>] [--security-type <security-type>] [--credential-type <credential-type>] [--credential <credential>]
Stop an access point interface
Options:
--ssid WLAN network name
--security-type one of None, WEP, WPA, WPA2, WPA3
--credential-type one of None, PSK, Password
--credential WLAN Password or PSK
--help display usage information
Examples:
To stop an AP
$ffx wlan ap stop
--ssid TestNetwork
--security-type wpa2
--credential-type password
--credential "Your very secure password here"
Notes:
Only one application at a time can interact with the WLAN policy layer.
stop-all
Usage: ffx wlan ap stop-all
Stops all active APs
Options:
--help display usage information
Examples:
To stop all APs
$ ffx wlan ap stop-all
Notes:
Only one application at a time can interact with the WLAN policy layer.
client
Usage: ffx wlan client <command> [<args>]
Controls WLAN client policy API.
Options:
--help display usage information
Commands:
batch-config Allows WLAN credentials to be extracted and restored.
connect Connect to the specified WLAN network
listen Listens for policy client connections updates
list-saved-networks
Lists all networks saved by the WLAN policy layer.
remove-network WLAN policy network storage container
save-network WLAN policy network storage container
scan Scan for nearby WLAN networks.
start Allows wlancfg to automate WLAN client operation
stop Stops automated WLAN policy control of client interfaces
and
destroys all client interfaces.
batch-config
Usage: ffx wlan client batch-config <command> [<args>]
Allows WLAN credentials to be extracted and restored.
Options:
--help display usage information
Commands:
dump Extracts a structured representation of the device's saved
WLAN credentials.
restore Injects a structure representation of WLAN credentials into
a device.
dump
Usage: ffx wlan client batch-config dump
Extracts a structured representation of the device's saved WLAN credentials.
Options:
--help display usage information
Examples:
To dump WLAN client configs
$ ffx wlan client batch-config dump
Notes:
Only one application at a time can interact with the WLAN policy layer.
restore
Usage: ffx wlan client batch-config restore <serialized_config>
Injects a structure representation of WLAN credentials into a device.
Positional Arguments:
serialized_config structured representation of WLAN credentials.
Options:
--help display usage information
Examples:
To restore WLAN client configs
$ ffx wlan client batch-config restore <STRUCTURE_CONFIG_DATA>
Notes:
Only one application at a time can interact with the WLAN policy layer.
connect
Usage: ffx wlan client connect [--ssid <ssid>] [--security-type <security-type>]
Connect to the specified WLAN network
Options:
--ssid WLAN network name
--security-type one of None, WEP, WPA, WPA2, WPA3
--help display usage information
Examples:
To remove a WLAN network
$ffx wlan client connect
--ssid TestNetwork
--security-type wpa2
Notes:
Only one application at a time can interact with the WLAN policy layer.
list-saved-networks
Usage: ffx wlan client list-saved-networks
Lists all networks saved by the WLAN policy layer.
Options:
--help display usage information
Examples:
To list saved networks
$ ffx wlan client list-saved-networks
Notes:
Only one application at a time can interact with the WLAN policy
layer.
listen
Usage: ffx wlan client listen
Listens for policy client connections updates
Options:
--help display usage information
Examples:
To begin listening for client events
$ ffx wlan client listen
remove-network
Usage: ffx wlan client remove-network [--ssid <ssid>] [--security-type <security-type>] [--credential-type <credential-type>] [--credential <credential>]
WLAN policy network storage container
Options:
--ssid WLAN network name
--security-type one of None, WEP, WPA, WPA2, WPA3
--credential-type one of None, PSK, Password
--credential WLAN Password or PSK
--help display usage information
Examples:
To remove a WLAN network
$ffx wlan client remove-network
--ssid TestNetwork
--security-type wpa2
--credential-type password
--credential "Your very secure password here"
Notes:
Only one application at a time can interact with the WLAN policy layer.
save-network
Usage: ffx wlan client save-network [--ssid <ssid>] [--security-type <security-type>] [--credential-type <credential-type>] [--credential <credential>]
WLAN policy network storage container
Options:
--ssid WLAN network name
--security-type one of None, WEP, WPA, WPA2, WPA3
--credential-type one of None, PSK, Password
--credential WLAN Password or PSK
--help display usage information
Examples:
To save a WLAN network
$ffx wlan client save-network
--ssid TestNetwork
--security-type wpa2
--credential-type password
--credential "Your very secure password here"
Notes:
Only one application at a time can interact with the WLAN policy layer.
scan
Usage: ffx wlan client scan
Scan for nearby WLAN networks.
Options:
--help display usage information
Examples:
To scan
$ ffx wlan client scan
Notes:
Only one application at a time can interact with the WLAN policy
layer.
start
Usage: ffx wlan client start
Allows wlancfg to automate WLAN client operation
Options:
--help display usage information
Examples:
To start client connections
$ ffx wlan client start
Notes:
Only one application at a time can interact with the WLAN policy
layer.
stop
Usage: ffx wlan client stop
Stops automated WLAN policy control of client interfaces and
destroys all client interfaces.
Options:
--help display usage information
Examples:
To stop client connections
$ ffx wlan client stop
Notes:
Only one application at a time can interact with the WLAN policy
layer.
deprecated
Usage: ffx wlan deprecated <command> [<args>]
Controls to-be-deleted WLAN functionality.
Options:
--help display usage information
Commands:
suggest-mac Notifies WLAN policy of a MAC address that ought to be used
when creating new AP interfaces
suggest-mac
Usage: ffx wlan deprecated suggest-mac <mac>
Notifies WLAN policy of a MAC address that ought to be used when creating new AP interfaces
Positional Arguments:
mac WLAN MAC address
Options:
--help display usage information
Examples:
To suggest an AP MAC address
$ ffx wlan deprecated suggest-mac 01:02:03:04:05:06
dev
Usage: ffx wlan dev <command> [<args>]
Warning: this tool may cause state mismatches between layers of the WLAN
subsystem. It is intended for use by WLAN developers only. Please reach out
to the WLAN team if your use case relies on it.
To disable the WLAN policy layer:
ffx wlan client stop
ffx wlan ap stop-all
To enable WLAN policy layer and begin automated WLAN behavior:
ffx wlan client start
ffx wlan ap start --ssid <SSID_HERE>
Options:
--help display usage information
Commands:
phy Configure WLAN PHY device.
iface Create, destroy, and query the states of WLAN interfaces.
client Controls a WLAN client interface.
ap Controls a WLAN AP interface.
ap
Usage: ffx wlan dev ap <command> [<args>]
Controls a WLAN AP interface.
Options:
--help display usage information
Commands:
start Starts an AP interface.
stop Stops an AP interface.
start
Usage: ffx wlan dev ap start [-i <iface>] -s <ssid> [-p <password>] -c <channel>
Starts an AP interface.
Options:
-i, --iface interface ID to start AP on
-s, --ssid AP SSID
-p, --password AP password
-c, --channel channel to start AP on
--help display usage information
stop
Usage: ffx wlan dev ap stop [-i <iface>]
Stops an AP interface.
Options:
-i, --iface interface ID to stop AP on
--help display usage information
client
Usage: ffx wlan dev client <command> [<args>]
Controls a WLAN client interface.
Options:
--help display usage information
Commands:
connect Connects to the target network.
scan Scans for nearby networks.
disconnect Causes client to disconnect.
wmm_status Queries client WMM status.
connect
Usage: ffx wlan dev client connect <ssid> [-i <iface>] [-p <password>] [--hash <hash>] [-s <scan-type>]
Connects to the target network.
Positional Arguments:
ssid SSID of the target network. Connecting via only an SSID is
deprecated and will be removed; use `ffx wlan client`
instead.
Options:
-i, --iface iface ID to connect on.
-p, --password WPA2 PSK
--hash WPA2 PSK as hex string
-s, --scan-type determines the type of scan performed on non-DFS channels
when connecting.
--help display usage information
disconnect
Usage: ffx wlan dev client disconnect [-i <iface>]
Causes client to disconnect.
Options:
-i, --iface iface ID to disconnect.
--help display usage information
scan
Usage: ffx wlan dev client scan [-i <iface>] [-s <scan-type>]
Scans for nearby networks.
Options:
-i, --iface iface ID to scan on.
-s, --scan-type experimental. Default scan type on each channel. Behavior
may differ on DFS channel
--help display usage information
wmm_status
Usage: ffx wlan dev client wmm_status [-i <iface>]
Queries client WMM status.
Options:
-i, --iface iface ID to disconnect.
--help display usage information
iface
Usage: ffx wlan dev iface <command> [<args>]
Create, destroy, and query the states of WLAN interfaces.
Options:
--help display usage information
Commands:
new Create a new WLAN interface.
del Destroy a WLAN interface.
list Lists all interface IDs.
query Query the properties of a WLAN interface.
minstrel Query interface minstrel stats.
status Query status of the target interface.
del
Usage: ffx wlan dev iface del <iface_id>
Destroy a WLAN interface.
Positional Arguments:
iface_id interface ID to destroy.
Options:
--help display usage information
list
Usage: ffx wlan dev iface list
Lists all interface IDs.
Options:
--help display usage information
minstrel
Usage: ffx wlan dev iface minstrel <command> [<args>]
Query interface minstrel stats.
Options:
--help display usage information
Commands:
list List minstrel peers.
show Show stats for minstrel peers.
list
Usage: ffx wlan dev iface minstrel list [<iface_id>]
List minstrel peers.
Positional Arguments:
iface_id interface ID to query, if no ID is provided, all interfaces
are queried.
Options:
--help display usage information
show
Usage: ffx wlan dev iface minstrel show [-i <iface>] [-p <peer>]
Show stats for minstrel peers.
Options:
-i, --iface interface ID to query, if no ID is provided, all interfaces
are queried.
-p, --peer target peer address, if none is provided, all will be shown.
--help display usage information
new
Usage: ffx wlan dev iface new -p <phy> -r <role> [-m <sta-addr>]
Create a new WLAN interface.
Options:
-p, --phy PHY ID on which to create the interface.
-r, --role MAC role for the new interface.
-m, --sta-addr MAC address for the new interface.
--help display usage information
query
Usage: ffx wlan dev iface query <iface_id>
Query the properties of a WLAN interface.
Positional Arguments:
iface_id interface ID to query.
Options:
--help display usage information
status
Usage: ffx wlan dev iface status [-i <iface>]
Query status of the target interface.
Options:
-i, --iface iface ID to query status on.
--help display usage information
phy
Usage: ffx wlan dev phy <command> [<args>]
Configure WLAN PHY device.
Options:
--help display usage information
Commands:
list List WLAN PHYs
query Query WLAN PHY properties by ID.
get-country Query PHY country code by ID.
set-country Set country code for target PHY.
clear-country Clear country code on target PHY.
set-ps-mode Sets the power save state of the target PHY.
get-ps-mode Query power save mode of target PHY.
clear-country
Usage: ffx wlan dev phy clear-country <phy_id>
Clear country code on target PHY.
Positional Arguments:
phy_id PHY ID where country code should be cleared.
Options:
--help display usage information
get-country
Usage: ffx wlan dev phy get-country <phy_id>
Query PHY country code by ID.
Positional Arguments:
phy_id PHY ID to query
Options:
--help display usage information
get-ps-mode
Usage: ffx wlan dev phy get-ps-mode <phy_id>
Query power save mode of target PHY.
Positional Arguments:
phy_id PHY ID on which power save mode should be set.
Options:
--help display usage information
list
Usage: ffx wlan dev phy list
List WLAN PHYs
Options:
--help display usage information
query
Usage: ffx wlan dev phy query <phy_id>
Query WLAN PHY properties by ID.
Positional Arguments:
phy_id PHY ID to query
Options:
--help display usage information
set-country
Usage: ffx wlan dev phy set-country <phy_id> <country>
Set country code for target PHY.
Positional Arguments:
phy_id PHY ID on which country code should be set.
country two-character country code to apply to target PHY.
Options:
--help display usage information
set-ps-mode
Usage: ffx wlan dev phy set-ps-mode <phy_id> <mode>
Sets the power save state of the target PHY.
Positional Arguments:
phy_id PHY ID on which power save mode should be set.
mode desired power save mode.
Options:
--help display usage information