Fuchsia's developer tool
Usage: ffx [-c <config...>] [-e <env>] [--machine <machine>] [--schema] [--stamp <stamp>] [-t <target>] [--timeout <timeout>] [-l <log-level>] [--isolate-dir <isolate-dir>] [-v] [-o <log-output>] [--no-environment] [--strict] [subcommand...]
| Options | |
|---|---|
| display usage information | |
| override configuration values (key=value, JSON string, or path to a JSON config file) | |
| override the path to the environment configuration file (file path) | |
| produce output for a machine in the specified format; available formats: "json", "json-pretty", "raw" | |
produce the JSON schema for the MachineWriter output. The --machine option is required when producing the schema. |
|
| create a stamp file at the given path containing the exit code | |
| apply operations across single or multiple targets | |
| override default proxy timeout (default is 1 second) | |
| sets the log level for ffx output (default = Info). Other possible values are Info, Error, Warn, and Trace. Can be persisted via log.level config setting. | |
| 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. | |
| logs ffx output to stdio according to log level | |
| specify destination of log output. "-" or "stdout" for stdout, "stderr" for stderr. If no destination is specified, log.dir will be used. If a destination is specified, then log.dir will be ignored. | |
| disables loading configuration from the file system and only uses configuration specified on the command line or the compiled in default values. Intended for use when running ffx as part of a hermetic build. | |
| switch which enables the 'strict' feature set. When set, ffx has stricter behavioual patterns. Including but not limited to: * Not doing discovery * Not starting the daemon * Communicating directly with the target from the ffx cli (not the daemon) * Configuration is read only The features in this flag are currently under active development. |
| Subcommands | |
|---|---|
| agis | Agis Service |
| assembly | Assemble images |
| audio | Interact with the audio subsystem. |
| auth | Generate Fuchsia authorization credentials. |
| bluetooth | Issue a command to Sapphire, the Bluetooth system. |
| component | Discover and manage components |
| config | View and switch default and user configurations |
| coverage | Show coverage from test outputs |
| daemon | Interact with/control the ffx daemon |
| debug | Start a debugging session. |
| doctor | Run common checks for the ffx tool and host environment |
| driver | Support driver development workflows |
| echo | run echo test against the daemon |
| efi | Manipulate efi partition |
| emu | Start and manage Fuchsia emulators. |
| forward | Forward connections between host and target device. |
| fuzz | Start and manage fuzzers. |
| inspect | Query data exposed by components via the Inspect API. |
| log | Display logs from a target device |
| net | View and manage target network configuration |
| package | Create and publish Fuchsia packages |
| platform | Manage platform build prerequisites |
| power | Control system power features |
| process | Processes related commands |
| product | Discover and access product bundle metadata and image data. |
| profile | Profile run-time information from various subsystems |
| profiler | Interact with the profiling subsystem. |
| repository | Inspect and manage package repositories |
| scrutiny | Audit the security of Fuchsia |
| sdk | Modify or query the installed SDKs |
| session | Control the session component. |
| setui | Modify and query settings. |
| speedtest | Developer tool for testing fffx latency and throughput to the target. |
| starnix | Control starnix containers |
| storage | Manage Fuchsia Filesystems. |
| target | Interact with a target device or emulator |
| test | Run test suite |
| trace | Tracing is a tool that allows you to collect, aggregate, and visualize diagnostic tracing information from both userspace processes and the Zircon kernel on a Fuchsia device. |
| triage | Analyze Logs and Inspect in snapshots to find problems. |
| version | Print out ffx tool and daemon versions |
| wlan | Developer tool for manipulating WLAN state. |
| wm | Control views presented by the window manager. |
agis
Agis Service
Usage: ffx agis [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| listen | initiate listening on |
| register | register a process with AGIS for tracing |
| shutdown | shutdown all listeners |
| vtcs | list all vulkan traceable components |
listen
initiate listening on |global_id|
Usage: ffx agis listen global_id
| Options | |
|---|---|
| display usage information |
register
register a process with AGIS for tracing
Usage: ffx agis register id process_koid process_name
| Options | |
|---|---|
| display usage information |
shutdown
shutdown all listeners
Usage: ffx agis shutdown
| Options | |
|---|---|
| display usage information |
vtcs
list all vulkan traceable components
Usage: ffx agis vtcs
| Options | |
|---|---|
| display usage information |
assembly
Assemble images
Usage: ffx assembly [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| create-system | create the system images. |
| create-update | construct an UpdatePackage using images and package. |
| 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-system
create the system images.
Usage: ffx assembly create-system --image-assembly-config <image-assembly-config> [--include-account] --outdir <outdir> --gendir <gendir> [--base-package-name <base-package-name>]
| Options | |
|---|---|
| display usage information | |
| the configuration file that specifies the packages, binaries, and settings specific to the product being assembled. | |
| whether to include an account partition in the FVMs. | |
| the directory to write the assembled system to. | |
| the directory to write generated intermediate files to. | |
| name to give the Base Package. This is useful if you must publish multiple base packages to the same TUF repository. |
create-update
construct an UpdatePackage using images and package.
Usage: ffx assembly create-update --partitions <partitions> [--system-a <system-a>] [--system-r <system-r>] --board-name <board-name> --version-file <version-file> --epoch <epoch> [--rewrite-default-repo <rewrite-default-repo>] [--subpackage-blobs-package-name <subpackage-blobs-package-name>] [--update-package-name <update-package-name>] --outdir <outdir> [--gendir <gendir>]
| Options | |
|---|---|
| display usage information | |
| path to a partitions config, which specifies where in the partition table the images are put. | |
| path to an images manifest, which specifies images to put in slot A. | |
| path to an images manifest, which specifies images to put in slot R. | |
| name of the board. Fuchsia will reject an Update Package with a different board name. | |
| file containing the version of the Fuchsia system. | |
| backstop OTA version. Fuchsia will reject updates with a lower epoch. | |
| rewrite package repository URLs to use this package URL hostname. | |
| name to give the Subpackage Blobs Package. This is currently only used by OTA tests to allow publishing multiple subpackage blob packages to the same amber repository without naming collisions. | |
| 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. | |
| directory to write the UpdatePackage. | |
| directory to write intermediate files. |
product
Arguments for performing a high-level product assembly operation.
Usage: ffx assembly product --product <product> --board-info <board-info> --outdir <outdir> [--gendir <gendir>] --input-bundles-dir <input-bundles-dir> [--package-validation <package-validation>] [--custom-kernel-aib <custom-kernel-aib>] [--custom-boot-shim-aib <custom-boot-shim-aib>] [--suppress-overrides-warning] [--developer-overrides <developer-overrides>]
| Options | |
|---|---|
| display usage information | |
| the product configuration directory. | |
| the board configuration directory. | |
| the directory to write assembled outputs to. | |
| the directory to write generated intermediate files to. | |
| the directory in which to find the platform assembly input bundles | |
| disable validation of the assembly's packages | |
| path to an AIB containing a customized kernel zbi to use instead of the one in the platform AIBs. | |
| path to an AIB containing a customized qemu_kernel boot shim to use instead of the in the platform AIBs. | |
| whether to hide the warning that shows the overrides that are enabled. This can be helpful to disable for test assemblies. | |
| path to a file specifying developer-level overrides for assembly. |
size-check
Perform size checks (on packages or product based on the sub-command).
Usage: ffx assembly size-check [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| 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. |
| 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.
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>]
| Options | |
|---|---|
| display usage information | |
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. |
|
path to a blobs.json file. It provides the size of each blob composing the package on device. |
|
| the layout of blobs in blobfs. | |
| path where to write the verification report, in JSON format. | |
| show the storage consumption of each component broken down by package regardless of whether the component exceeded its budget. | |
| path where to write the verbose JSON output. |
product
(Not implemented yet) Check that the set of all blobs included in the product fit in the blobfs capacity.
Usage: ffx assembly size-check product [--auth <auth>] --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>] [--platform-resources-budget <platform-resources-budget>]
| Options | |
|---|---|
| display usage information | |
| use specific auth mode for oauth2 (see examples; default: pkce). | |
| path to the images.json. | |
| path to the past images.json which will be used to compare with the current images.json to produce a diff. | |
| whether to show the verbose output. | |
| path to the directory where HTML visualization should be stored. | |
| path where to write the gerrit size report. | |
| path where to write the size breakdown. | |
| maximum amount that the size of blobfs can increase in one CL. This value is propagated to the gerrit size report. | |
| maximum amount of bytes the platform resources can consume. |
audio
Interact with the audio subsystem.
Usage: ffx audio [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| device | Interact directly with device hardware. |
| gen | Generate an audio signal. Outputs a WAV file written to stdout. |
| list-devices | Prints all available audio devices on target |
| play | Reads a WAV file from stdin and sends the audio data to audio_core's AudioRenderer API. |
| record | Records audio data from audio_core's AudioCapturer API and outputs a WAV file to stdout. |
Examples
Generate a 5s long audio signal with 440Hz frequency and write to a file:
$ ffx audio gen sine --frequency 440 --duration 5s --format 48000,uint8,1ch > ~/sine.wav
Play a wav file using audio_core API:
$ cat ~/sine.wav | ffx audio play
Record audio signal to a file using audio_core API:
$ ffx audio record --duration 1s --format 48000,uint8,1ch > ~/recording.wav
List available audio devices on target:
$ ffx audio device list
Print information about a specific audio device on target:
$ ffx audio device --name 3d99d780 info
Play a wav file directly to device hardware:
$ cat ~/sine.wav | ffx audio device play
Notes
Format parameters: Some commands take a --format=
argument for describing audio PCM format. The argument has the pattern: , , SampleRate: Integer SampleType options: uint8, int16, int32, float32 Channels: ch example: --format=48000,float32,2ch
device
Interact directly with device hardware.
The flags on the device command filter the list of available devices.
Commands that operate on a single device pick the first matching device,
after filtering. For example, if the target has only one device, and no
filter flags are provided, ffx audio device will use that device by default.
Usage: ffx audio device [--name <name>] [--token-id <token-id>] [--direction <direction>] [--type <type>] [subcommand...]
| Options | |
|---|---|
| display usage information | |
| device devfs node name. e.g. 3d99d780 for the devfs path /dev/class/audio-input/3d99d780. | |
| device token ID, for a device in the audio device registry. Only applies if the audio device registry is available on the target. | |
| device direction. Accepted values: input, output. Play and record will use output and input respectively by default. | |
| device type. Accepted values: StreamConfig, Composite. |
| Subcommands | |
|---|---|
| agc | Request to enable or disable automatic gain control for the stream. |
| gain | Request to set the gain of the stream, in decibels. |
| info | Show information about a specific audio device. |
| list | Lists audio devices. |
| mute | Request to mute a stream. |
| play | Send audio data directly to device ring buffer. |
| record | Capture audio data directly from ring buffer. |
| reset | Reset device hardware. |
| set | Set a device property. |
| start | Start device hardware. |
| stop | Stop device hardware. |
| unmute | Request to unmute a stream. |
Examples
Show information about a specific device:
$ ffx audio device --name 3d99d780 --direction input info
Show information about a specific device in the audio device registry:
$ ffx audio device --token-id 1 info
Play a WAV file directly to device hardware:
$ cat ~/sine.wav | ffx audio device --name a70075f2 play
$ ffx audio device --name a70075f2 play --file ~/sine.wav
Record a WAV file directly from device hardware:
$ ffx audio device --name 3d99d780 record --format 48000,uint8,1ch --duration 1s
Mute the stream of an output device:
$ ffx audio device --name a70075f2 --direction output mute
Set the gain of an output device to -20 dB:
$ ffx audio device --name a70075f2 --direction output gain -20
Turn AGC on for an input device:
$ ffx audio device --name 3d99d780 --direction input agc onagc
Request to enable or disable automatic gain control for the stream.
Usage: ffx audio device agc enable
| Options | |
|---|---|
| display usage information |
gain
Request to set the gain of the stream, in decibels.
Usage: ffx audio device gain --gain <gain>
| Options | |
|---|---|
| display usage information | |
| gain, in decibels, to set the stream to. |
info
Show information about a specific audio device.
Usage: ffx audio device info
| Options | |
|---|---|
| display usage information |
Examples
ffx audio device --type StreamConfig --direction input info
list
Lists audio devices.
Usage: ffx audio device list
| Options | |
|---|---|
| display usage information |
Examples
ffx audio device --type StreamConfig list
mute
Request to mute a stream.
Usage: ffx audio device mute
| Options | |
|---|---|
| display usage information |
play
Send audio data directly to device ring buffer.
Usage: ffx audio device play [--file <file>] [--element-id <element-id>] [--channels <channels>]
| Options | |
|---|---|
| display usage information | |
| file in WAV format containing audio signal. If not specified, ffx command will read from stdin. | |
| signal processing element ID, for an Endpoint element of type RingBuffer | |
| bitmask of channels to activate (deactivate the others). If not specified, activate all channels present in the playback format |
record
Capture audio data directly from ring buffer.
Usage: ffx audio device record [--duration <duration>] --format <format> [--element-id <element-id>]
| Options | |
|---|---|
| display usage information | |
| duration of output signal. Examples: 5ms or 3s. If not specified, press ENTER to stop recording. | |
| output format (see 'ffx audio help' for more information). | |
| signal processing element ID, for an Endpoint element of type RingBuffer |
reset
Reset device hardware.
Usage: ffx audio device reset
| Options | |
|---|---|
| display usage information |
set
Set a device property.
Usage: ffx audio device set [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| dai-format | Set the DAI format of device or signal processing element. |
dai-format
Set the DAI format of device or signal processing element.
Usage: ffx audio device set dai-format [--element-id <element-id>] format
| Options | |
|---|---|
| display usage information | |
| signal processing element ID, for an Endpoint element of type Dai |
Examples
Set the DAI format for a specific Dai Endpoint signal processing element:
$ ffx audio device set dai-format --element-id 2 48000,2ch,0x3,pcm_signed,16in16,i2sNotes
This command accepts a DAI format as a comma separated string:
Where:
Examples: 48000,2ch,0x3,pcm_signed,16in32,i2s 96000,1ch,0x1,pcm_float,32in32,custom:right_justified;falling_sclk;-1;0
start
Start device hardware.
Usage: ffx audio device start
| Options | |
|---|---|
| display usage information |
stop
Stop device hardware.
Usage: ffx audio device stop
| Options | |
|---|---|
| display usage information |
unmute
Request to unmute a stream.
Usage: ffx audio device unmute
| Options | |
|---|---|
| display usage information |
gen
Generate an audio signal. Outputs a WAV file written to stdout.
Usage: ffx audio gen [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| pink-noise | Generate pink noise. |
| sawtooth | Generate a sawtooth wave signal. |
| sine | Generate a sine wave signal. |
| square | Generate a square wave signal. |
| triangle | Generate a triangle wave signal. |
| white-noise | Generate white noise. |
Examples
ffx audio gen sine --duration 5ms --frequency 440 --amplitude 0.5 --format 48000,int16,2ch
pink-noise
Generate pink noise.
Usage: ffx audio gen pink-noise --duration <duration> [--amplitude <amplitude>] --format <format>
| Options | |
|---|---|
| display usage information | |
| duration of output signal. Examples: 5ms or 3s. | |
| signal amplitude in range [0, 1.0]. Default: 1.0. | |
| output format (see 'ffx audio help' for more information). |
sawtooth
Generate a sawtooth wave signal.
Usage: ffx audio gen sawtooth --duration <duration> --frequency <frequency> [--amplitude <amplitude>] --format <format>
| Options | |
|---|---|
| display usage information | |
| duration of output signal. Examples: 5ms or 3s. | |
| frequency of output wave in Hz. | |
| signal amplitude in range [0, 1.0]. Default: 1.0. | |
| output format (see 'ffx audio help' for more information). |
sine
Generate a sine wave signal.
Usage: ffx audio gen sine --duration <duration> --frequency <frequency> [--amplitude <amplitude>] --format <format>
| Options | |
|---|---|
| display usage information | |
| duration of output signal. Examples: 5ms or 3s. | |
| frequency of output wave in Hz. | |
| signal amplitude in range [0, 1.0]. Default: 1.0. | |
| output format (see 'ffx audio help' for more information). |
square
Generate a square wave signal.
Usage: ffx audio gen square --duration <duration> --frequency <frequency> [--amplitude <amplitude>] [--duty-cycle <duty-cycle>] --format <format>
| Options | |
|---|---|
| display usage information | |
| duration of output signal. Examples: 5ms or 3s. | |
| frequency of output wave in Hz. | |
| signal amplitude in range [0, 1.0]. Default: 1.0. | |
| duty cycle in range [0, 1.0]. Default: 0.5. | |
| output format (see 'ffx audio help' for more information). |
triangle
Generate a triangle wave signal.
Usage: ffx audio gen triangle --duration <duration> --frequency <frequency> [--amplitude <amplitude>] --format <format>
| Options | |
|---|---|
| display usage information | |
| duration of output signal. Examples: 5ms or 3s. | |
| frequency of output wave in Hz. | |
| signal amplitude in range [0, 1.0]. Default: 1.0. | |
| output format (see 'ffx audio help' for more information). |
white-noise
Generate white noise.
Usage: ffx audio gen white-noise --duration <duration> [--amplitude <amplitude>] --format <format>
| Options | |
|---|---|
| display usage information | |
| duration of output signal. Examples: 5ms or 3s. | |
| signal amplitude in range [0, 1.0]. Default: 1.0. | |
| output format (see 'ffx audio help' for more information). |
list-devices
Prints all available audio devices on target
Usage: ffx audio list-devices
| Options | |
|---|---|
| display usage information |
Examples
$ ffx audio list-devices $ ffx audio --machine json list-devices
play
Reads a WAV file from stdin and sends the audio data to audio_core's AudioRenderer API.
Usage: ffx audio play [--usage <usage>] [--buffer-size <buffer-size>] [--packet-count <packet-count>] [--gain <gain>] [--mute <mute>] [--clock <clock>] [--file <file>]
| Options | |
|---|---|
| display usage information | |
| purpose of the audio being played. Accepted values: ACCESSIBILITY (and A11Y), BACKGROUND, COMMUNICATION, INTERRUPTION, MEDIA, SYSTEM-AGENT, ULTRASOUND. Default: MEDIA. | |
| buffer size (bytes) to allocate on device VMO. Used to send audio data from ffx tool to AudioRenderer. Defaults to size to hold 1 second of audio data. | |
| how many packets to use when sending data to an AudioRenderer. Defaults to 4 packets. | |
| gain (decibels) for the renderer. Default: 0 dB | |
| mute the renderer. Default: false | |
| explicitly set the renderer's reference clock. By default, SetReferenceClock is not called, which leads to a flexible clock. Options include: 'flexible', 'monotonic', and 'custom, |
|
| file in WAV format containing audio signal. If not specified,ffx command will read from stdin. |
Examples
$ ffx audio gen sine --duration 1s --frequency 440 --amplitude 0.5 --format 48000,int16,2ch | ffx audio play $ ffx audio play --file ~/path/to/sine.wav
record
Records audio data from audio_core's AudioCapturer API and outputs a WAV file to stdout.
Usage: ffx audio record [--duration <duration>] --format <format> [--usage <usage>] [--buffer-size <buffer-size>] [--clock <clock>] [--gain <gain>] [--mute <mute>]
| Options | |
|---|---|
| display usage information | |
| duration of output signal. Examples: 5ms or 3s. If not specified, press ENTER to stop recording. | |
| output format (see 'ffx audio help' for more information). | |
| purpose of the stream being recorded. Accepted values: BACKGROUND, FOREGROUND, SYSTEM-AGENT, COMMUNICATION, ULTRASOUND, or LOOPBACK. Default: COMMUNICATION. | |
| buffer size (bytes) to allocate on device VMO. Used to retrieve audio data from AudioCapturer. Defaults to size to hold 1 second of audio data. | |
| explicitly set the capturer's reference clock. By default, SetReferenceClock is not called, which leads to a flexible clock. Options include: 'flexible', 'monotonic', and 'custom, |
|
| gain (decibels) for the capturer. Default: 0 dB | |
| mute the capturer. Default: false |
Examples
$ ffx audio record --duration 1s --format 48000,uint8,1ch --usage SYSTEM-AGENT > ~/recording.wav
auth
Generate Fuchsia authorization credentials.
Usage: ffx auth [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| generate | Generates authorization credentials for private Fuchsia artifacts |
generate
Generates authorization credentials for private Fuchsia artifacts
Usage: ffx auth generate [--auth <auth>]
| Options | |
|---|---|
| display usage information | |
| choice of authentication flow, defaults to pkce which should be acceptable for most users. |
Examples
ffx auth generate
bluetooth
Issue a command to Sapphire, the Bluetooth system.
Usage: ffx bluetooth [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| pandora | Start/stop a Pandora gRPC test interface server and bluetooth-rootcanal virtual controller. |
| peer | Show details for a known peer. |
pandora
Start/stop a Pandora gRPC test interface server and bluetooth-rootcanal virtual controller.
Usage: ffx bluetooth pandora [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| start | Start Pandora server and bluetooth-rootcanal. |
| stop | Stop Pandora server and bt-rootcanal if running. |
Examples
ffx bluetooth pandora start --rootcanal-ip 172.16.243.142
start
Start Pandora server and bluetooth-rootcanal.
Usage: ffx bluetooth pandora start [--grpc-port <grpc-port>] --rootcanal-ip <rootcanal-ip> [--rootcanal-port <rootcanal-port>]
| Options | |
|---|---|
| display usage information | |
| the Fuchsia port on which the Pandora server will listen. Default: 8042. | |
| ip address of the host running the Rootcanal server. | |
| port of Rootcanal server. Default: 6402. |
Examples
ffx bluetooth pandora start --rootcanal-ip 172.16.243.142
stop
Stop Pandora server and bt-rootcanal if running.
Usage: ffx bluetooth pandora stop
| Options | |
|---|---|
| display usage information |
peer
Show details for a known peer.
Usage: ffx bluetooth peer [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| connect | Connect to a peer. |
| disconnect | Disconnect from a peer. |
| list | Show all known peers in a summarized view (optionally filtered). |
| show | Show details for a known peer. |
Examples
ffx bluetooth peer
connect
Connect to a peer.
Usage: ffx bluetooth peer connect id_or_addr
| Options | |
|---|---|
| display usage information |
Examples
ffx bluetooth peer connect
disconnect
Disconnect from a peer.
Usage: ffx bluetooth peer disconnect id_or_addr
| Options | |
|---|---|
| display usage information |
Examples
ffx bluetooth peer disconnect
list
Show all known peers in a summarized view (optionally filtered).
Usage: ffx bluetooth peer list [--details] [filter]
| Options | |
|---|---|
| display usage information | |
| show details for all known peers |
Examples
ffx bluetooth peer list
show
Show details for a known peer.
Usage: ffx bluetooth peer show id_or_addr
| Options | |
|---|---|
| display usage information |
Examples
ffx bluetooth peer show
component
Discover and manage components
Usage: ffx component [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| capability | Lists component instances that reference a capability |
| collection | Manages collections in the component topology |
| config | Manages configuration capability override values for components |
| copy | copies files to/from directories associated with a component. |
| create | Creates a dynamic component instance, adding it to the collection designated by |
| debug | Debug a running component with zxdb. |
| destroy | Destroys a dynamic component instance, removing it from the collection designated by |
| 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 components in the component topology. Children of unresolved components are not included in this list. |
| list | Lists components in the component topology. Children of unresolved components are not included in this list. |
| reload | Recursively stops, unresolves, and starts a component instance, updating the code and topology while preserving resources |
| resolve | Resolves a component instance |
| route | Perform capability routing on a component at runtime. |
| run | Creates and starts a component instance in an existing collection |
| show | Shows detailed information about a component instance |
| start | Starts a component |
| stop | Stops a component instance |
| storage | Manages storage capabilities of components |
capability
Lists component instances that reference a capability
Usage: ffx component capability capability
| Options | |
|---|---|
| display usage information |
Examples
To show all components that reference a capability:
$ ffx component capability fuchsia.net.routescollection
Manages collections in the component topology
Usage: ffx component collection [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| list | List all collections in the component topology |
| show | Shows detailed information about a collection in the component topology |
list
List all collections in the component topology
Usage: ffx component collection list
| Options | |
|---|---|
| display usage information |
show
Shows detailed information about a collection in the component topology
Usage: ffx component collection show query
| Options | |
|---|---|
| display usage information |
config
Manages configuration capability override values for components
Usage: ffx component config [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| list | Lists structured configuration values for the specified component |
| set | Sets configuration capability override values for the specified component |
| unset | Unsets structured configuration override values for the specified component |
list
Lists structured configuration values for the specified component
Usage: ffx component config list query
| Options | |
|---|---|
| display usage information |
set
Sets configuration capability override values for the specified component
Usage: ffx component config set [-r] query [key_values...]
| Options | |
|---|---|
| display usage information | |
| if enabled, component instance will be immediately reloaded so overrides take effect. |
Examples
To override the configuration fields `bar` and `baz` for the component `/core/ffx-laboratory:foo`:
$ ffx component config set /core/ffx-laboratory:foo bar=true baz=42
Use the reload flag to cause the component to reload the component with the override in effect:
$ ffx component config set --reload /core/ffx-laboratory:foo bar=true
To override a vector configuration field, use a comma separated list:
$ ffx component config set /core/ffx-laboratory:foo "some_list=1, 2, 3"
unset
Unsets structured configuration override values for the specified component
Usage: ffx component config unset [-r] [query]
| Options | |
|---|---|
| display usage information | |
| if enabled, component instance will be immediately reloaded so overrides take effect. |
Examples
To unset overrides for the component `core/ffx-laboratory:foo`
$ ffx component config unset `core/ffx-laboratory:foo`
To unset overrides for all components with overrides:
$ ffx component config unset
copy
copies files to/from directories associated with a component. Paths may be any combination of local or remote paths.
Usage: ffx component copy [-v] [paths...]
| Options | |
|---|---|
| display usage information | |
| verbose output: outputs a line for each file copied. |
Examples
To copy from a component to a local path: ffx component copy /some/moniker::/path/file.txt /local/file.txt To copy from a local path to a component: ffx component copy /local/file.txt /some/moniker::/dir/file.txt To copy between two components: ffx component copy /some/moniker::/dir/file.txt /some/moniker::/dir/file.txt To copy multiple files: ffx component copy /some/moniker::/dir/* /some/local/dir ffx component copy /file/one.txt /file/two.txt ... /some/moniker::/dir/ To copy a file from a component's outgoing directory: ffx component copy /some/moniker::out::/path/file.txt /local/file.txt To copy a file from a component's package directory: ffx component copy /some/moniker::pkg::/meta/foo /tmp
Notes
To learn more about the command see https://fuchsia.dev/fuchsia-src/development/sdk/ffx/copy-files-to-and-from-a-component
create
Creates a dynamic component instance, adding it to the collection designated by
Usage: ffx component create [--config <config...>] moniker url
| Options | |
|---|---|
| display usage information | |
provide a configuration override to the component being run. Requires mutability: \[ "parent" ] on the configuration field. Specified in the format KEY=VALUE where VALUE is a JSON string which can be resolved as the correct type of configuration value. |
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-rust#meta/hello-world-rust.cmNotes
To learn more about running components, see https://fuchsia.dev/go/components/run
debug
Debug a running component with zxdb.
Usage: ffx component debug query
| Options | |
|---|---|
| display usage information |
Examples
To debug the `brightness_manager` component instance, all of the
following commands are valid:
$ ffx component debug /core/brightness_manager
$ ffx component debug fuchsia-pkg://fuchsia.com/brightness_manager#meta/brightness_manager.cm
$ ffx component debug meta/brightness_manager.cm
$ ffx component debug brightness_manager
If the component is not yet running, consider `ffx component start --debug`
to start the component in the debugger.Notes
This command supports partial matches over the moniker, URL and instance ID
destroy
Destroys a dynamic component instance, removing it from the collection designated by
Usage: ffx component destroy query
| Options | |
|---|---|
| display usage information |
Examples
To destroy a component instance designated by the moniker `/core/ffx-laboratory:foo`:
$ ffx component destroy /core/ffx-laboratory:fooNotes
To learn more about running components, see https://fuchsia.dev/go/components/run
doctor
Perform diagnostic checks on a component at runtime.
Usage: ffx component doctor [-p] query
| Options | |
|---|---|
| display usage information | |
| whether or not to display the output without color and wrapping. |
Examples
To run diagnostics: $ ffx component doctor /core/network/netstack 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
Spawns a shell scoped to a component instance.
Usage: ffx component explore [--tools <tools...>] [-c <command>] [-l <layout>] query
| Options | |
|---|---|
| display usage information | |
list of URLs of tools packages to include in the shell environment. the PATH variable will be updated to include binaries from these tools packages. repeat --tools url for each package to be included. The path preference is given by command line order. |
|
| execute a command instead of reading from stdin. the exit code of the command will be forwarded to the host. | |
| 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) |
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/tools/debug-dash-launcher PWD=/
Notes
When --layout=nested (the default), 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 User-added and built-in dash tools * /svc Protocols required by the dash shell
When --layout=namespace, the contents of the /ns dir above are placed at / with two protocols (fuchsia.process.Launcher and fuchsia.process.Resolver) overlayed into /svc. In this mode, the exposed, out, and runtime directories will not be accessible.
With --tools, tools in the specified package will be loaded into /.dash/tools/
--tools URLs may be package or binary URLs. If a package URL is given, tool executables are expected
to be in a bin/ dir within the package. If a specific tool URL is given, append the tool path
to the package URL. For example: --tools fuchsia-pkg://fuchsia.com/my_package#bin/my_tool. Note that
naming collisions can occur if multiple packages share a package or binary name. An error,
NonUniqueBinaryName, is returned if a binary name collision occurs.
graph
Outputs a Graphviz dot graph for the components in the component topology. Children of unresolved components are not included in this list.
Usage: ffx component graph [-o <only>] [-r <orientation>]
| Options | |
|---|---|
| display usage information | |
| filter the instance list by a criteria: ancestor, descendant, relative | |
| changes the visual orientation of the graph's nodes. Allowed values are "lefttoright"/"lr" and "toptobottom"/"tb". |
Examples
To graph components in the topology:
$ ffx component graph
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_rightlist
Lists components in the component topology. Children of unresolved components are not included in this list.
Usage: ffx component list [-o <only>] [-v]
| Options | |
|---|---|
| display usage information | |
| filter the instance list by a criteria: running, stopped, ancestors: |
|
| show detailed information about each instance |
Examples
To list components in the topology:
$ ffx component list
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:fooreload
Recursively stops, unresolves, and starts a component instance, updating the code and topology while preserving resources
Usage: ffx component reload query
| Options | |
|---|---|
| display usage information |
Examples
To reload a component instance designated by the moniker `/core/ffx-laboratory:foo`:
$ ffx component reload /core/ffx-laboratory:fooNotes
To learn more about running components, see https://fuchsia.dev/go/components/run
resolve
Resolves a component instance
Usage: ffx component resolve query
| Options | |
|---|---|
| display usage information |
Examples
To resolve the component designated by the provided moniker `/core/brightness_manager`:
$ ffx component resolve /core/brightness_managerroute
Perform capability routing on a component at runtime.
Usage: ffx component route target [filter]
| Options | |
|---|---|
| display usage information |
Examples
To route capabilities from `font_provider`: $ ffx component route /core/font_provider This will perform routing on all the capabilities used or exposed by `font_provider`, and display information for each route including its status (success or failure) and the identity of the source component providing the capability. $ ffx component route fonts.cm This does the same thing, except with a fuzzy match (on the URL). $ ffx component route /core/font_provider fuchsia.pkg.FontResolver This will perform routing on capabilities used or exposed by `font_provider` that match `fuchsia.pkg.FontResolver`. $ ffx component route /core/font_provider use:fuchsia.pkg.FontResolver,expose:fuchsia.fonts.Provider This will perform routing from `font_provider` on used capability `fuchsia.pkg.FontResolver` and exposed capability `fuchsia.fonts.Provider`. $ ffx component route /core/font_provider fuchsia.pkg Fuzzy matching by capability is also supported. This will perform routing from `font_provider` on any used or exposed capability matching *fuchsia.pkg*.
run
Creates and starts a component instance in an existing collection within the component topology.
Usage: ffx component run [-r] [-f] [--connect-stdio] [--config <config...>] moniker url
| Options | |
|---|---|
| display usage information | |
| destroy and recreate the component instance if it already exists | |
| start printing logs from the started component after it has started | |
| connect stdin, stdout, and stderr to the component (requires component to be in a collection with single_run durability) | |
provide a configuration override to the component being run. Requires mutability: \[ "parent" ] on the configuration field. Specified in the format KEY=VALUE where VALUE is a JSON string which can be resolved as the correct type of configuration value. |
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-rust#meta/hello-world-rust.cmNotes
This command is a shorthand for the following:
$ ffx component create
$ ffx component start
To learn more about running components, see https://fuchsia.dev/go/components/run
show
Shows detailed information about a component instance
Usage: ffx component show query
| Options | |
|---|---|
| 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_managerNotes
This command supports partial matches over the moniker, URL and instance ID
start
Starts a component
Usage: ffx component start [--debug] query
| Options | |
|---|---|
| display usage information | |
start the component in the debugger. To debug a component that is already running, consider ffx component debug. |
Examples
To start the component instance designated by the moniker `/core/brightness_manager`:
$ ffx component start /core/brightness_manager
The start the brightness manager in the debugger, use the --debug flag:
$ ffx component start /core/brightness_manager --debugNotes
To learn more about running components, see https://fuchsia.dev/go/components/run
stop
Stops a component instance
Usage: ffx component stop query
| Options | |
|---|---|
| display usage information |
Examples
To stop the component instance designated by the moniker `/core/brightness_manager`:
$ ffx component stop /core/brightness_managerNotes
To learn more about running components, see https://fuchsia.dev/go/components/run
storage
Manages storage capabilities of components
Usage: ffx component storage [--provider <provider>] [--capability <capability>] [subcommand...]
| Options | |
|---|---|
| display usage information | |
| the moniker of the storage provider component. Defaults to "/core" | |
| the capability name of the storage to use. Examples: "data", "cache", "tmp" Defaults to "data" |
| Subcommands | |
|---|---|
| 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. |
| delete-all | Delete the contents of the storage for a specific component. |
| 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
Copy files to/from a component's storage. If the file already exists at the destination it is overwritten.
Usage: ffx component storage copy source_path destination_path
| Options | |
|---|---|
| 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-iddelete
Delete files from a component's storage.
Usage: ffx component storage delete path
| Options | |
|---|---|
| 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-iddelete-all
Delete the contents of the storage for a specific component.
Usage: ffx component storage delete-all moniker
| Options | |
|---|---|
| display usage information |
Examples
To delete the contents of the storage for a component with moniker `foo`:
$ ffx component storage delete-all foo
Note: although unusual, the user may specify internal instance IDs in the moniker such as `foo:0/bar:2`.list
List the contents of a component's storage.
Usage: ffx component storage list path
| Options | |
|---|---|
| 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-idmake-directory
Create a new directory in a component's storage. If the directory already exists, this operation is a no-op.
Usage: ffx component storage make-directory path
| Options | |
|---|---|
| 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-idconfig
View and switch default and user configurations
Usage: ffx config [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| add | add config value the end of an array |
| analytics | enable or disable analytics |
| check-ssh-keys | check the ssh key configuration and create keys if needed. |
| env | list environment settings |
| get | display config values |
| remove | remove user level config values |
| set | set config settings |
add
add config value the end of an array
Usage: ffx config add name value
| Options | |
|---|---|
| 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 getcommand.
analytics
enable or disable analytics
Usage: ffx config analytics [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| disable | disable analytics |
| enable | enable basic (redacted) analytics |
| enable-enhanced | enable enhanced analytics (Googlers only) |
| show | show analytics |
disable
disable analytics
Usage: ffx config analytics disable
| Options | |
|---|---|
| display usage information |
enable
enable basic (redacted) analytics
Usage: ffx config analytics enable
| Options | |
|---|---|
| display usage information |
enable-enhanced
enable enhanced analytics (Googlers only)
Usage: ffx config analytics enable-enhanced
| Options | |
|---|---|
| display usage information |
show
show analytics
Usage: ffx config analytics show
| Options | |
|---|---|
| display usage information |
check-ssh-keys
check the ssh key configuration and create keys if needed.
Usage: ffx config check-ssh-keys
| Options | |
|---|---|
| display usage information |
env
list environment settings
Usage: ffx config env [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| get | list environment for a given level |
| set | set environment settings |
get
list environment for a given level
Usage: ffx config env get [level]
| Options | |
|---|---|
| display usage information |
set
set environment settings
Usage: ffx config env set [-l <level>] file
| Options | |
|---|---|
| display usage information | |
| config level. Possible values are "user", "build", "global". Defaults to "user". |
get
display config values
Usage: ffx config get [-p <process>] [-s <select>] [name]
| Options | |
|---|---|
| display usage information | |
| 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. The process type "file" returns a scalar value. In the case of the configuration being a list, it is treated as an ordered list of alternatives and takes the first value that exists. | |
| 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. |
| Errors | |
|---|---|
| 2 | No value found |
remove
remove user level config values
Usage: ffx config remove name
| Options | |
|---|---|
| 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 getcommand.
set
set config settings
Usage: ffx config set name value
| Options | |
|---|---|
| display usage information |
coverage
Show coverage from test outputs
Usage: ffx coverage --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>] [src_files...]
| Options | |
|---|---|
| display usage information | |
| path to ffx test output directory | |
| path to clang directory, llvm-profdata and llvm-cov are expected in clang_dir/bin | |
| path to symbol index json to load symbol index from | |
| directory to export HTML reports to | |
| path to export LCOV file to | |
| " |
|
| path to the directory used as a base for relative coverage mapping paths, passed through to llvm-cov |
daemon
Interact with/control the ffx daemon
Usage: ffx daemon [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| crash | crash the daemon |
| disconnect | Disconnect from a target |
| 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 -- normally unnecessary, as the daemon is automatically started on demand. Used primarily for debugging |
| stop | stops a running daemon |
crash
crash the daemon
Usage: ffx daemon crash
| Options | |
|---|---|
| display usage information |
disconnect
Disconnect from a target
Usage: ffx daemon disconnect
| Options | |
|---|---|
| display usage information |
Notes
Tells the daemon to disconnect from the specified target. Useful when the client knows the connection is no longer valid, e.g. in a test in which the target has been rebooted.
echo
run echo test against the daemon
Usage: ffx daemon echo [text]
| Options | |
|---|---|
| display usage information |
hang
hang the daemon
Usage: ffx daemon hang
| Options | |
|---|---|
| display usage information |
log
Dumps the daemon log
Usage: ffx daemon log [-f] [-l <line-count>]
| Options | |
|---|---|
| display usage information | |
| print appended logs as they happen | |
| display most recent log lines. |
socket
query information about the daemon socket without connecting to it
Usage: ffx daemon socket
| Options | |
|---|---|
| display usage information |
start
run as daemon -- normally unnecessary, as the daemon is automatically started on demand. Used primarily for debugging
Usage: ffx daemon start [--path <path>] [-b]
| Options | |
|---|---|
| display usage information | |
| override the path the socket will be bound to | |
| runs the daemon in the background. Returns after verifying daemon connection. No-op if the daemon is already running. |
stop
stops a running daemon
Usage: ffx daemon stop [-w] [--no-wait] [-t <timeout-ms>]
| Options | |
|---|---|
| display usage information | |
| wait indefinitely for the daemon to stop before exiting (should not be used in automated systems) | |
| do not wait for daemon to stop (default behavior -- eventually to be deprecated) | |
| optional timeout (in milliseconds) to wait for the daemon to stop. Will try killing the daemon if it does not exit on its own. |
debug
Start a debugging session.
Usage: ffx debug [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| connect | start the debugger and connect to the target |
| core | start the debugger and open a minidump |
| crash | catch a crashing process on the target |
| 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
start the debugger and connect to the target
Usage: ffx debug connect [--debugger <debugger>] [--agent-only] [-a <attach...>] [-e <execute...>] [--new-agent] [zxdb_args...]
| Options | |
|---|---|
| display usage information | |
| start zxdb in another debugger. Currently, the only valid option is "lldb". | |
| 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. | |
| attaches to given processes. The argument will be parsed in the same way as the "attach" command in the console. | |
| execute one zxdb command. Multiple commands will be executed sequentially. | |
| always spawn a new DebugAgent instance for this zxdb invocation. |
core
start the debugger and open a minidump
Usage: ffx debug core [--zxdb-args <zxdb-args...>] [minidump]
| Options | |
|---|---|
| display usage information | |
| extra arguments passed to zxdb. |
crash
catch a crashing process on the target
Usage: ffx debug crash
| Options | |
|---|---|
| display usage information |
fidl
monitor FIDL traffic on the target
Usage: ffx debug fidl [--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...>] [extra_args...]
| Options | |
|---|---|
| display usage information | |
| 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. |
|
| the session is saved to the specified file (binary protobuf format). When a session is saved, you can replay it using "--from |
|
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. |
|
| 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. | |
| display the process name, process id and thread id on each line (useful for grep). | |
| 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) | |
| a regular expression which selects the syscalls to decode and display. This option can be specified multiple times. By default, only zxchannel.* syscalls are displayed. To display all the syscalls, use: --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 "zxhandle." | |
| 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. | |
| 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. | |
| 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. | |
| only display the events for the specified thread. This option can be specified multiple times. By default all the events are displayed. | |
| always does a hexadecimal dump of the messages even if we can decode them. | |
| the koid of the remote process to trace. | |
| the |
|
| 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. | |
| 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. | |
| 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. | |
| 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. |
limbo
control the process limbo on the target
Usage: ffx debug limbo [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| disable | disable the process limbo. Will free any pending processes waiting in it. |
| enable | enable the process limbo. It will now begin to capture crashing processes. |
| list | lists the processes currently waiting on limbo. The limbo must be active. |
| release | release a process from limbo. The limbo must be active. |
| status | query the status of the process limbo. |
disable
disable the process limbo. Will free any pending processes waiting in it.
Usage: ffx debug limbo disable
| Options | |
|---|---|
| display usage information |
enable
enable the process limbo. It will now begin to capture crashing processes.
Usage: ffx debug limbo enable
| Options | |
|---|---|
| display usage information |
list
lists the processes currently waiting on limbo. The limbo must be active.
Usage: ffx debug limbo list
| Options | |
|---|---|
| display usage information |
release
release a process from limbo. The limbo must be active.
Usage: ffx debug limbo release pid
| Options | |
|---|---|
| display usage information |
status
query the status of the process limbo.
Usage: ffx debug limbo status
| Options | |
|---|---|
| display usage information |
symbol-index
manage symbol sources used by other debug commands
Usage: ffx debug symbol-index [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| add | add a path or url to the symbol index |
| clean | remove all non-existent paths |
| list | show the content in symbol index |
| remove | remove a path from the symbol index |
Notes
symbol-index is a global configuration used by debugging tools to locate symbol files.
add
add a path or url to the symbol index
Usage: ffx debug symbol-index add [--build-dir <build-dir>] source
| Options | |
|---|---|
| display usage information | |
| optional build directory used by zxdb to locate the source code |
Notes
Add a path or a debuginfod server to the symbol index, e.g.,
- 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.
- https://debuginfod.debian.net
Duplicated adding of the same path or url is a no-op, regardless of the optional build directory.
clean
remove all non-existent paths
Usage: ffx debug symbol-index clean
| Options | |
|---|---|
| display usage information |
Notes
Remove all non-existent paths from the symbol index, useful as a garbage collection.
list
show the content in symbol index
Usage: ffx debug symbol-index list [-a]
| Options | |
|---|---|
| display usage information | |
| show the aggregated symbol index |
remove
remove a path from the symbol index
Usage: ffx debug symbol-index remove source
| Options | |
|---|---|
| display usage information |
Notes
Remove a path or a debuginfod server from the symbol index, e.g.,
- A build-id directory.
- An ids.txt file.
- A file that ends with .symbol-index.json.
- https://debuginfod.debian.net
symbolize
symbolize backtraces in markup format
Usage: ffx debug symbolize [--auth] [--no-prettify] [symbolizer_args...]
| Options | |
|---|---|
| display usage information | |
| start the authentication process. | |
| do not prettify the backtraces. |
doctor
Run common checks for the ffx tool and host environment
Usage: ffx doctor [--record] [--no-config] [--retry-count <retry-count>] [--retry-delay <retry-delay>] [--restart-daemon] [-v] [--output-dir <output-dir>] [--repair-keys]
| Options | |
|---|---|
| display usage information | |
| generates an output zip file with logs | |
| do not include the ffx configuration file | |
| number of times to retry failed connection attempts | |
| timeout delay in ms during connection attempt | |
| force restart the daemon, even if the connection is working | |
| verbose, display all steps | |
| override the default output directory for doctor records | |
| checks SSH key consistency and repairs them if needed. This may cause any devices to be reflashed. |
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. Enabling `--record`
also sets the `--verbose` flag to true.
To override output dir:
$ ffx doctor --record --output-dir /tmp/ffxNotes
The
doctorsubcommand 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
Support driver development workflows
Usage: ffx driver [-s] [subcommand...]
| Options | |
|---|---|
| display usage information | |
| if this exists, the user will be prompted for a component to select. |
| Subcommands | |
|---|---|
| disable | Disables the given driver, and restart its nodes with rematching. |
| dump | Dump device tree |
| list | List drivers |
| list-composite-node-specs | List composite node specs. |
| list-composites | List composites |
| list-devices | List devices |
| list-hosts | List driver hosts and drivers loaded within them |
| node | Commands to interact with driver framework nodes. |
| 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. |
| static-checks | Run static checks against a driver file. |
| test-node | Commands to interact with test nodes. |
disable
Disables the given driver, and restart its nodes with rematching.
Usage: ffx driver disable [-s] url
| Options | |
|---|---|
| display usage information | |
| if this exists, the user will be prompted for a component to select. |
Examples
To disable a driver
$ driver disable 'fuchsia-pkg://fuchsia.com/example_driver#meta/example_driver.cm'
This can also be used with boot drivers, but keep in mind if the driver being disabled is
critical to the system, the system will become unstable.
$ driver disable 'fuchsia-boot:///#meta/example_driver.cm'Notes
After this call, nodes that were bound to the requested driver will either have another driver (specifically a fallback driver) bound to them, or the node becomes an unbound node ready to bind to a driver later, which is generally done with a register call. If there is a fallback driver that might take the place of the driver being disabled, and you want to register your own driver for the node, the fallback driver should be disabled as well.
| Errors | |
|---|---|
| 1 | Failed to connect to the driver development service |
dump
Dump device tree
Usage: ffx driver dump [-g] [-s] [device]
| Options | |
|---|---|
| display usage information | |
| output device graph in dot language so that it may be viewed | |
| if this exists, the user will be prompted for a component to select. |
Examples
To dump the device tree:
$ driver dump
To dump the subtree of the device tree under a node:
$ driver dump my-node-name
To graph device tree:
$ driver dump --graph | dot -Tpng | display| Errors | |
|---|---|
| 1 | Failed to connect to the driver development service |
list
List drivers
Usage: ffx driver list [-v] [--loaded] [-s]
| Options | |
|---|---|
| display usage information | |
| list all driver properties | |
| only list loaded drivers | |
| if this exists, the user will be prompted for a component to select. |
Examples
To list all drivers with properties:
$ driver list -v
To list only loaded drivers:
$ driver list --loaded| Errors | |
|---|---|
| 1 | Failed to connect to the driver development service |
list-composite-node-specs
List composite node specs.
Usage: ffx driver list-composite-node-specs [-v] [-n <name>] [-s]
| Options | |
|---|---|
| display usage information | |
| list all driver properties. | |
| only show the spec with this name. | |
| if this exists, the user will be prompted for a component to select. |
Examples
To list all composite node specs with properties:
$ driver list-composite-node-specs -v
To show a specific composite nod spec, specify a `--name` or `-n` for short:
$ driver list-composite-node-specs -n example_group| Errors | |
|---|---|
| 1 | Failed to connect to the driver development service |
list-composites
List composites
Usage: ffx driver list-composites [-v] [-s]
| Options | |
|---|---|
| display usage information | |
| list all the properties of a composite. | |
| if this exists, the user will be prompted for a component to select. |
Examples
To list all composites:
$ driver list-composites -v| Errors | |
|---|---|
| 1 | Failed to connect to the driver development service |
list-devices
List devices
Usage: ffx driver list-devices [-s] [-v] [--exact] [--fail-on-missing] [-u] [device]
| Options | |
|---|---|
| display usage information | |
| if this exists, the user will be prompted for a component to select. | |
| list all device properties. | |
| require an exact match on the device filter, instead of a substring match. | |
| return a non-zero exit code if no matching devices are found. | |
| list only unbound nodes. |
Examples
To list all devices:
$ driver list-devices -v| Errors | |
|---|---|
| 1 | Failed to connect to the driver development service |
list-hosts
List driver hosts and drivers loaded within them
Usage: ffx driver list-hosts [-s]
| Options | |
|---|---|
| display usage information | |
| if this exists, the user will be prompted for a component to select. |
Examples
To list all driver hosts:
$ driver list-hosts| Errors | |
|---|---|
| 1 | Failed to connect to the driver development service |
node
Commands to interact with driver framework nodes.
Usage: ffx driver node [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| add | Add a node with a given bind property |
| graph | Outputs a Graphviz dot graph for the nodes in the node topology. |
| list | List nodes in the driver framework |
| remove | Remove a node that was previously added using driver node add. |
| show | Show a specific node in the driver framework |
add
Add a node with a given bind property
Usage: ffx driver node add name property
| Options | |
|---|---|
| display usage information |
Examples
To add a node to the driver framework:
$ driver node add my-node my-key-string=my-value-string| Errors | |
|---|---|
| 1 | Failed to connect to the driver development service |
graph
Outputs a Graphviz dot graph for the nodes in the node topology.
Usage: ffx driver node graph [-o <only>] [-r <orientation>]
| Options | |
|---|---|
| display usage information | |
| filter the nodes by a criteria: bound, unbound, ancestors: |
|
| changes the visual orientation of the graph's nodes. Allowed values are "lefttoright"/"lr" and "toptobottom"/"tb". |
Examples
To graph all nodes:
$ driver node graph
| Errors | |
|---|---|
| 1 | Failed to connect to the driver development service |
list
List nodes in the driver framework
Usage: ffx driver node list [-v] [-f] [-o <only>]
| Options | |
|---|---|
| display usage information | |
| shows the node's state and bound driver url if one exists. | |
| return a non-zero exit code if no matching devices are found. | |
| filter the instance list by a criteria: bound, unbound, ancestors: |
Examples
To list all nodes:
$ driver node list
To list nodes that match a name or driver:
$ driver node list my_node
| Errors | |
|---|---|
| 1 | Failed to connect to the driver development service |
remove
Remove a node that was previously added using driver node add.
Usage: ffx driver node remove name
| Options | |
|---|---|
| display usage information |
Examples
To remove a node to the driver framework:
$ driver node remove my-node| Errors | |
|---|---|
| 1 | Failed to connect to the driver development service |
show
Show a specific node in the driver framework
Usage: ffx driver node show query
| Options | |
|---|---|
| display usage information |
Examples
To show a node:
$ driver node show dev.sys.my_node
Notes
This command supports partial matches over the node moniker and driver URL. If the query matches more than one node, the user will be prompted to be more specific.
| Errors | |
|---|---|
| 1 | Failed to connect to the driver development service |
register
Informs the driver manager that a new driver package is available. The driver manager will cache a copy of the driver
Usage: ffx driver register [-s] url
| Options | |
|---|---|
| display usage information | |
| if this exists, the user will be prompted for a component to select. |
Examples
To register a driver
$ driver register 'fuchsia-pkg://fuchsia.com/example_driver#meta/example_driver.cm'| Errors | |
|---|---|
| 1 | Failed to connect to the driver registrar service |
restart
Restart all driver hosts containing the driver specified by driver_path.
Usage: ffx driver restart [-s] driver_path
| Options | |
|---|---|
| display usage information | |
| if this exists, the user will be prompted for a component to select. |
Examples
To restart a driver:
$ driver restart fuchsia-boot:///#driver/e1000.so| Errors | |
|---|---|
| 1 | Failed to connect to the driver manager service |
static-checks
Run static checks against a driver file.
Usage: ffx driver static-checks --driver <driver>
| Options | |
|---|---|
| display usage information | |
| the path to the driver's FAR file |
test-node
Commands to interact with test nodes.
Usage: ffx driver test-node [-s] [subcommand...]
| Options | |
|---|---|
| display usage information | |
| if this exists, the user will be prompted for a component to select. |
| Subcommands | |
|---|---|
| add | Add a test node with a given bind property |
| remove | Remove a test node. |
add
Add a test node with a given bind property
Usage: ffx driver test-node add name property
| Options | |
|---|---|
| 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| Errors | |
|---|---|
| 1 | Failed to connect to the driver development service |
remove
Remove a test node.
Usage: ffx driver test-node remove name
| Options | |
|---|---|
| display usage information |
Examples
To remove a test node to the driver framework:
$ driver test-node remove my-node| Errors | |
|---|---|
| 1 | Failed to connect to the driver development service |
echo
run echo test against the daemon
Usage: ffx echo [text]
| Options | |
|---|---|
| display usage information |
efi
Manipulate efi partition
Usage: ffx efi [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| create | Creates efi partition, copies zircon.bin, bootdata.bin, the efi bootloader file, zedboot.bin, etc... |
create
Creates efi partition, copies zircon.bin, bootdata.bin, the efi bootloader file, zedboot.bin, etc...
Usage: ffx efi create -o <output> [--zircon <zircon>] [--bootdata <bootdata>] [--arch <arch>] [--efi-bootloader <efi-bootloader>] [--zedboot <zedboot>] [--cmdline <cmdline>]
| Options | |
|---|---|
| display usage information | |
| target file/disk to write EFI partition to | |
| optional path to source file for zircon.bin | |
| optional path to source file for bootdata.bin | |
| cpu architecture of the target | |
| optional path to source file for the efi bootloader file (e.g. EFI/BOOT/BOOTX64.EFI for X64) | |
| optional path to a source file for zedboot.bin | |
| optional bootloader cmdline file |
emu
Start and manage Fuchsia emulators.
Usage: ffx emu [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| 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
[EXPERIMENTAL] Connect to a running Fuchsia emulator's console.
Usage: ffx emu console [--console-type <console-type>] [-c] [-m] [-s] [name]
| Options | |
|---|---|
| display usage information | |
| selector for which console to attach to. Accepted values are: command machine serial | |
| attach to the user-interactive command console. Equivalent to "--console-type command". | |
| attach to the machine-readable command console. Equivalent to "--console-type machine". | |
| attach to the Fuchsia serial console. Equivalent to "--console-type serial". |
Examples
ffx emu console -s ffx emu console fuchsia-emulator --console-type serial
list
List running Fuchsia emulators.
Usage: ffx emu list [-r]
| Options | |
|---|---|
| display usage information | |
| list only the emulators that are currently in the "running" state. |
show
Show Fuchsia emulator details.
Usage: ffx emu show [--all] [--cmd] [--config] [--device] [--net] [name]
| Options | |
|---|---|
| display usage information | |
| show all of the available details, which is the default. | |
| show the command line used to launch the emulator. | |
| show the configuration in a format consistent with the 'start' command's --config flag. | |
| show the virtual device information used to launch this emulator, in a format consistent with the 'start' command's --device flag. | |
| switch to show network details. |
start
Start the Fuchsia emulator.
Usage: ffx emu start [--accel <accel>] [--config <config>] [--dev-config <dev-config>] [--console] [--debugger] [--device <device>] [--device-list] [--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...>] [--reuse] [--reuse-with-check] [--stage] [-s <startup-timeout>] [--uefi] [--vbmeta-key <vbmeta-key>] [--vbmeta-key-metadata <vbmeta-key-metadata>] [-V] [product_bundle]
| Options | |
|---|---|
| display usage information | |
| 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". | |
| specify a configuration file to populate the command line flags for the emulator. Defaults to a Handlebars config specified in the Product Bundle manifest. | |
| specify developer config file to append onto the configuration. This is a JSON file with the object structure: {{ "args": [], "kernel_args": [], "env" : {{"key": "value"}} }} | |
| launch the emulator in serial console mode. This redirects the virtual serial port to the host's input/output streams, multi-plexed with the QEMU monitor console, 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. Note: Control sequences are passed through to the guest system in this mode, so Crtl-c will terminate the guest system's shell, rather than the emulator process itself. If you need to hard-kill the emulator, use the QEMU sequence 'Ctrl-a x' instead. | |
| 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. | |
the virtual device specification used to configure the emulator. This can be the name of a device listed in the product bundle, or the path to a custom virtual device file. A default for this flag can be set by running ffx config set emu.device <type>. If --device is not specified and no default is set, then ffx emu will attempt to use the product bundle's recommended device. |
|
| print the list of available virtual devices. | |
| sets up the emulation configuration, but doesn't stage files or start the emulator. The command line arguments that the current configuration generates will be printed to stdout for review. | |
| open the user's default editor to modify the command line flags for the emulator. | |
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", which can be overridden by running ffx config set emu.engine <type>. Engine defaults are overridden to "qemu" in cases of incompatibility (cross cpu or uefi emulation). |
|
GPU acceleration mode. Allowed values are "swiftshader_indirect", "host", or "auto". Default is "swiftshader_indirect". "host" and "auto" are for experimental use only and are not officially supported by the Fuchsia emulator team; graphics artifacts, test failures and emulator crashes may occur. 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. This can be overridden by running ffx config set emu.gpu <type>. |
|
| run the emulator without a GUI. The guest system may still initialize graphics drivers, but no graphics interface will be presented to the user. | |
| enable pixel scaling on HiDPI devices. Defaults to true for MacOS, false otherwise. | |
| 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. | |
| 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. | |
| 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 of this emulator instance. This is used to identify the instance in other commands and tools. Default is "fuchsia-emulator". This value can also be set via configuration using the key emu.name. Note that when using the --uefi flag, the visible target name in ffx target list will be overwritten by a name "fuchsia-X-Y-Z" where X,Y,Z are derived from the generated mac address for this emulator. This is currently required to support a seamless OTA testing workflow. |
|
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". This can be overridden by running ffx config set emu.net <type>. |
|
| specify a host port mapping for user-networking mode. Ignored in other networking modes. Syntax is "--port-map |
|
reuse a persistent emulator's (i.e. stopped with ffx emu stop --persist) 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. |
|
reuse a persistent emulator's (i.e. stopped with ffx emu stop --persist) state when starting up after version check. If an emulator with the same name as this instance has been previously started and then stopped without cleanup, the zbi and disk volume files are compared against the original. If they match, the instance will reuse the images from the previous instance. If the files do not match, the instance is started using the latest files. If there is no staged instance, the emulator is started using the latest files and the hash information is recorded so this instance can take advantage of this option. |
|
| sets up the emulation configuration and stages files, but doesn't start the emulator. The command line arguments that the staged configuration generates will be printed to stdout for review. | |
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>. |
|
create and start an emulator with a full GPT disk including UEFI boot environment and all partitions in one flat file. This approximates a physical device as closely as possible. Note that this is currently only enabled for x64 and arm64 targets. RISC-V is unsupported. Note that for full GPT disks, it is also required to provide the --vbmeta-key and --vbmeta-key-metadata arguments, otherwise the resulting GPT image will not be able to boot into its A and B slots. |
|
path to the key (a PEM file) that should be used to sign a vbmeta file for the ZBI after embedding the SSH keys, for example: https://cs.opensource.google/fuchsia/fuchsia/+/main:boards/x64/BUILD.gn;l=44-46;drc=04892e7f8875e2d16c3fcda89bc462dc6b0f35f8) Note that this is only required when using --uefi. Also, when an emulator is --reused after it was stopped with the --persist flag, this argument is not necessary as the previously created images will be used. |
|
path to the key metadata (a binary file accompanying the PEM, for example https://cs.opensource.google/fuchsia/fuchsia/+/main:boards/x64/BUILD.gn;l=44-46;drc=04892e7f8875e2d16c3fcda89bc462dc6b0f35f8) that should be used to sign a vbmeta file for the ZBI after embedding the SSH keys. Note that this is only required when using --uefi. Also, when an emulator is --reused after it was stopped with the --persist flag, this argument is not necessary as the |
|
| enables extra logging for debugging. |
Examples
ffx emu start
Notes
The
startsubcommand 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
Shut down a running Fuchsia emulator.
Usage: ffx emu stop [--all] [-p] [name]
| Options | |
|---|---|
| display usage information | |
| shut down and clean up all emulator instances running on the device. | |
| don't remove the state directory on stop, just terminate the emulator. |
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.
forward
Forward connections between host and target device.
Usage: ffx forward [-q] [-i <ui-interval>] [spec...]
| Options | |
|---|---|
| display usage information | |
| omits all interactive terminal output | |
| UI refresh interval in ms |
Examples
forward '8080=>8081' # forward TCP host port 8080 to target port 8081 forward 'tcp:\[::1]:8080<=80' # forward TCP target port 80 to host port 8080 over IPv6
fuzz
Start and manage fuzzers.
Usage: ffx fuzz [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| add | Adds an input to a fuzzer's corpus. |
| cleanse | Clears extraneous bytes from an error input. |
| fetch | Retrieves the attached fuzzer's corpus. |
| get | Gets option(s) from a fuzzer. |
| list | Lists available fuzzers. |
| merge | Compacts the attached fuzzer's corpus. |
| minimize | Reduce the size of an error input. |
| run | Generates inputs and fuzz the target. |
| set | Sets options on a fuzzer. |
| shell | Starts an interactive fuzzing session. |
| status | Gets a fuzzer's execution status. |
| stop | Stops a fuzzer. |
| try | Tests a specific input with a fuzzer. |
add
Adds an input to a fuzzer's corpus.
Usage: ffx fuzz add [-o <output>] [-q] [--no-stdout] [--no-stderr] [--no-syslog] [-s] url input
| Options | |
|---|---|
| display usage information | |
| where to send fuzzer logs and artifacts; default is stdout and the current directory | |
| if present, suppress non-error output from the ffx tool itself | |
| disables forwarding standard output from the fuzzer | |
| disables forwarding standard error from the fuzzer | |
| disables forwarding system logs from the fuzzer | |
| add to the seed corpus; default is to add to live corpus |
cleanse
Clears extraneous bytes from an error input.
Usage: ffx fuzz cleanse [-o <output>] [-q] [--no-stdout] [--no-stderr] [--no-syslog] url input
| Options | |
|---|---|
| display usage information | |
| where to send fuzzer logs and artifacts; default is stdout and the current directory | |
| if present, suppress non-error output from the ffx tool itself | |
| disables forwarding standard output from the fuzzer | |
| disables forwarding standard error from the fuzzer | |
| disables forwarding system logs from the fuzzer |
fetch
Retrieves the attached fuzzer's corpus.
Usage: ffx fuzz fetch [-o <output>] [-q] [--no-stdout] [--no-stderr] [--no-syslog] [-s] url
| Options | |
|---|---|
| display usage information | |
| where to send fuzzer logs and artifacts; default is stdout and the current directory | |
| if present, suppress non-error output from the ffx tool itself | |
| disables forwarding standard output from the fuzzer | |
| disables forwarding standard error from the fuzzer | |
| disables forwarding system logs from the fuzzer | |
| fetch the seed corpus; default is to fetch the live corpus |
get
Gets option(s) from a fuzzer.
Usage: ffx fuzz get [-o <output>] [-q] [--no-stdout] [--no-stderr] [--no-syslog] url [name]
| Options | |
|---|---|
| display usage information | |
| where to send fuzzer logs and artifacts; default is stdout and the current directory | |
| if present, suppress non-error output from the ffx tool itself | |
| disables forwarding standard output from the fuzzer | |
| disables forwarding standard error from the fuzzer | |
| disables forwarding system logs from the fuzzer |
list
Lists available fuzzers.
Usage: ffx fuzz list [-j <json-file>] [-p <pattern>]
| Options | |
|---|---|
| display usage information | |
| path to JSON file describing fuzzers; looks for tests.json under $FUCHSIA_DIR by default | |
| list all fuzzers matching shell-style glob pattern; default is to list all fuzzers |
merge
Compacts the attached fuzzer's corpus.
Usage: ffx fuzz merge [-o <output>] [-q] [--no-stdout] [--no-stderr] [--no-syslog] url
| Options | |
|---|---|
| display usage information | |
| where to send fuzzer logs and artifacts; default is stdout and the current directory | |
| if present, suppress non-error output from the ffx tool itself | |
| disables forwarding standard output from the fuzzer | |
| disables forwarding standard error from the fuzzer | |
| disables forwarding system logs from the fuzzer |
minimize
Reduce the size of an error input.
Usage: ffx fuzz minimize [-o <output>] [-q] [--no-stdout] [--no-stderr] [--no-syslog] [-r <runs>] [-t <time>] url input
| Options | |
|---|---|
| display usage information | |
| where to send fuzzer logs and artifacts; default is stdout and the current directory | |
| if present, suppress non-error output from the ffx tool itself | |
| disables forwarding standard output from the fuzzer | |
| disables forwarding standard error from the fuzzer | |
| disables forwarding system logs from the fuzzer | |
| convenient shortcut for "set runs |
|
| convenient shortcut for "set max_total_time |
run
Generates inputs and fuzz the target.
Usage: ffx fuzz run [-o <output>] [-q] [--no-stdout] [--no-stderr] [--no-syslog] [-r <runs>] [-t <time>] url
| Options | |
|---|---|
| display usage information | |
| where to send fuzzer logs and artifacts; default is stdout and the current directory | |
| if present, suppress non-error output from the ffx tool itself | |
| disables forwarding standard output from the fuzzer | |
| disables forwarding standard error from the fuzzer | |
| disables forwarding system logs from the fuzzer | |
| convenient shortcut for "set runs |
|
| convenient shortcut for "set max_total_time |
set
Sets options on a fuzzer.
Usage: ffx fuzz set [-o <output>] [-q] [--no-stdout] [--no-stderr] [--no-syslog] url name value
| Options | |
|---|---|
| display usage information | |
| where to send fuzzer logs and artifacts; default is stdout and the current directory | |
| if present, suppress non-error output from the ffx tool itself | |
| disables forwarding standard output from the fuzzer | |
| disables forwarding standard error from the fuzzer | |
| disables forwarding system logs from the fuzzer |
shell
Starts an interactive fuzzing session.
Usage: ffx fuzz shell [-j <json-file>]
| Options | |
|---|---|
| display usage information | |
| path to JSON file describing fuzzers; looks for tests.json under $FUCHSIA_DIR by default |
status
Gets a fuzzer's execution status.
Usage: ffx fuzz status [-o <output>] [-q] [--no-stdout] [--no-stderr] [--no-syslog] url
| Options | |
|---|---|
| display usage information | |
| where to send fuzzer logs and artifacts; default is stdout and the current directory | |
| if present, suppress non-error output from the ffx tool itself | |
| disables forwarding standard output from the fuzzer | |
| disables forwarding standard error from the fuzzer | |
| disables forwarding system logs from the fuzzer |
stop
Stops a fuzzer.
Usage: ffx fuzz stop [-q] [url]
| Options | |
|---|---|
| display usage information | |
| if present, suppress non-error output from the ffx tool itself |
try
Tests a specific input with a fuzzer.
Usage: ffx fuzz try [-o <output>] [-q] [--no-stdout] [--no-stderr] [--no-syslog] url input
| Options | |
|---|---|
| display usage information | |
| where to send fuzzer logs and artifacts; default is stdout and the current directory | |
| if present, suppress non-error output from the ffx tool itself | |
| disables forwarding standard output from the fuzzer | |
| disables forwarding standard error from the fuzzer | |
| disables forwarding system logs from the fuzzer |
inspect
Query data exposed by components via the Inspect API.
Usage: ffx inspect [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| apply-selectors | Apply selectors from a file interactively. |
| list | Lists all components (relative to the scope where the archivist receives events from) of components that expose inspect. |
| list-accessors | Lists all available ArchiveAccessor in the system and their selector for use in "accessor" arguments in other sub-commands. |
| selectors | Lists all available selectors for the given input of component queries or partial selectors. |
| show | Prints the inspect hierarchies that match the given selectors. See https://fuchsia.dev/fuchsia-src/development/diagnostics/inspect#userspace_tools for more. |
Examples
If you wish to see the JSON format of Inspect, you must pass `--machine json` to the `ffx` command. For example to see the Inspect JSON of all components running in the system, run: ``` ffx --machine json inspect show ```
apply-selectors
Apply selectors from a file interactively.
Usage: ffx inspect apply-selectors [--snapshot-file <snapshot-file>] [--moniker <moniker>] [--accessor-path <accessor-path>] selector_file
| Options | |
|---|---|
| display usage information | |
| 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 of the component to apply the command. | |
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. |
list
Lists all components (relative to the scope where the archivist receives events from) of components that expose inspect.
Usage: ffx inspect list [--component <component>] [--with-url] [--accessor <accessor>]
| Options | |
|---|---|
| display usage information | |
| a fuzzy-search query. May include URL, moniker, or manifest fragments. a fauzzy-search query for the component we are interested in. May include URL, moniker, or manifest fragments. If this is provided, the output will only contain monikers for components that matched the query. | |
| also print the URL of the component. | |
A selector specifying what fuchsia.diagnostics.ArchiveAccessor to connect to. The selector will be in the form of: iquery list-accessors. For example: bootstrap/archivist:fuchsia.diagnostics.ArchiveAccessor.feedback means that the command will connect to the ArchiveAccecssor filtered by the feedback pipeline exposed by bootstrap/archivist. |
list-accessors
Lists all available ArchiveAccessor in the system and their selector for use in "accessor" arguments in other sub-commands.
Usage: ffx inspect list-accessors
| Options | |
|---|---|
| display usage information |
selectors
Lists all available selectors for the given input of component queries or partial selectors.
Usage: ffx inspect selectors [--data <data...>] [--accessor <accessor>] [selectors...]
| Options | |
|---|---|
| display usage information | |
tree selectors to splice onto a component query specified as a positional argument For example, show foo.cm --data root:bar becomes the selector path/to/foo:root:bar. |
|
A string specifying what fuchsia.diagnostics.ArchiveAccessor to connect to. This can be copied from the output of ffx inspect list-accessors. The selector will be in the form of: |
show
Prints the inspect hierarchies that match the given selectors. See https://fuchsia.dev/fuchsia-src/development/diagnostics/inspect#userspace_tools for more.
Usage: ffx inspect show [--data <data...>] [--accessor <accessor>] [--name <name>] [selectors...]
| Options | |
|---|---|
| display usage information | |
tree selectors to splice onto a component query specified as a positional argument For example, show foo.cm --data root:bar becomes the selector path/to/foo:root:bar. |
|
string specifying what fuchsia.diagnostics.ArchiveAccessor to connect to. This can be copied from the output of ffx inspect list-accessors. The selector will be in the form of: |
|
| specifies a tree published by a component by name. If a selector is also provided, the specified name will be added to the selector. |
log
Display logs from a target device
Usage: ffx log [--filter <filter...>] [--moniker <moniker...>] [--component <component...>] [--exclude <exclude...>] [--tag <tag...>] [--exclude-tags <exclude-tags...>] [--severity <severity>] [--kernel] [--since <since>] [--since-boot <since-boot>] [--until <until>] [--until-boot <until-boot>] [--hide-tags] [--hide-file] [--no-color] [--case-sensitive] [--show-metadata] [--show-full-moniker] [--clock <clock>] [--symbolize <symbolize>] [--set-severity <set-severity...>] [--pid <pid>] [--tid <tid>] [--force-set-severity] [--disable-reconnect] [subcommand...]
| Options | |
|---|---|
| display usage information | |
| filter for a string in either the message, component or url. May be repeated. | |
| DEPRECATED: use --component | |
| fuzzy search for a component by moniker or url. May be repeated. | |
| exclude a string in either the message, component or url. May be repeated. | |
| filter for only logs with a given tag. May be repeated. | |
| exclude logs with a given tag. May be repeated. | |
| set the minimum severity. Accepted values (from lower to higher) are: trace, debug, info, warn (or warning), error, fatal. This field is case insensitive. | |
| outputs only kernel logs, unless combined with --component. | |
| show only logs after a certain time (exclusive) | |
| show only logs after a certain time (as a boot timestamp: seconds from the target's boot time). | |
| show only logs until a certain time (exclusive) | |
| show only logs until a certain time (as a a boot timestamp: seconds since the target's boot time). | |
| hide the tag field from output (does not exclude any log messages) | |
| hide the file and line number field from output (does not exclude any log messages) | |
disable coloring logs according to severity. Note that you can permanently disable this with ffx config set log_cmd.color false |
|
| if enabled, text filtering options are case-sensitive this applies to --filter, --exclude, --tag, and --exclude-tag. | |
| shows process-id and thread-id in log output | |
| shows the full moniker in log output. By default this is false and only the last segment of the moniker is printed. | |
| how to display log timestamps. Options are "utc", "local", or "boot" (i.e. nanos since target boot). Default is boot. | |
| configure symbolization options. Valid options are: - pretty (default): pretty concise symbolization - off: disables all symbolization - classic: traditional, non-prettified symbolization | |
| 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 |
|
| filters by pid | |
| filters by tid | |
| if enabled, selectors will be passed directly to Archivist without any filtering. If disabled and no matching components are found, the user will be prompted to either enable this or be given a list of selectors to choose from. This applies to both --set-severity and --set-severity-persist. | |
| disable automatic reconnect |
| Subcommands | |
|---|---|
| dump | Dumps all log from a given target's session. |
| set-severity | Sets the severity, but doesn't view any logs. |
| watch | Watches for and prints logs from a target. Default if no sub-command is specified. |
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 --set-severity core/audio#DEBUG
Notes
Logs are retrieve from the target at the moment this command is called.
You may see some additional information attached to the log line:
dropped=N: this means that N logs attributed to the component were dropped when the component wrote to the log socket. This can happen when archivist cannot keep up with the rate of logs being emitted by the component and the component filled the log socket buffer in the kernel.rolled=N: this means that N logs rolled out from the archivist buffer and ffx never saw them. This can happen when more logs are being ingested by the archivist across all components and the ffx couldn't retrieve them fast enough.
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
Dumps all log from a given target's session.
Usage: ffx log dump
| Options | |
|---|---|
| display usage information |
set-severity
Sets the severity, but doesn't view any logs.
Usage: ffx log set-severity [--no-persist] [--force] [interest_selector...]
| Options | |
|---|---|
| display usage information | |
| if true, doesn't persist the interest setting and blocks forever, keeping the connection open. Interest settings will be reset when the command exits. | |
| if enabled, selectors will be passed directly to Archivist without any filtering. If disabled and no matching components are found, the user will be prompted to either enable this or be given a list of selectors to choose from. |
watch
Watches for and prints logs from a target. Default if no sub-command is specified.
Usage: ffx log watch
| Options | |
|---|---|
| display usage information |
net
View and manage target network configuration
Usage: ffx net [--realm <realm>] [subcommand...]
| Options | |
|---|---|
| display usage information | |
| a realm to target when sending commands. Defaults to the core network realm. |
| Subcommands | |
|---|---|
| dhcp | commands for an interfaces dhcp client |
| dhcpd | commands to control a dhcp server |
| dns | commands to control the dns resolver |
| filter | commands for configuring packet filtering |
| filter-deprecated | commands for configuring packet filtering with the deprecated API |
| if | commands for network interfaces |
| log | commands for logging |
| migration | controls netstack selection for migration from netstack2 to netstack3 |
| neigh | commands for neighbor tables |
| route | commands for routing tables |
| rule | commands for policy-based-routing rules |
dhcp
commands for an interfaces dhcp client
Usage: ffx net dhcp [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| start | starts a dhcp client on the interface |
| stop | stops the dhcp client on the interface |
start
starts a dhcp client on the interface
Usage: ffx net dhcp start nicid or name:ifname
| Options | |
|---|---|
| display usage information |
stop
stops the dhcp client on the interface
Usage: ffx net dhcp stop nicid or name:ifname
| Options | |
|---|---|
| display usage information |
dhcpd
commands to control a dhcp server
Usage: ffx net dhcpd [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| clear-leases | A primary command to clear the leases maintained by dhcpd. |
| get | A primary command to retrieve 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. |
| set | A primary command to set the value of a DHCP option or server parameter. |
| start | A primary command to start the DHCP server. |
| stop | A primary command to stop the DHCP server. |
clear-leases
A primary command to clear the leases maintained by dhcpd.
Usage: ffx net dhcpd clear-leases
| Options | |
|---|---|
| display usage information |
get
A primary command to retrieve the value of a DHCP option or server parameter.
Usage: ffx net dhcpd get [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| option | A secondary command indicating a DHCP option argument. |
| parameter | A secondary command indicating a server parameter argument. |
option
A secondary command indicating a DHCP option argument.
Usage: ffx net dhcpd get option [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| all-subnets-local | Flag indicating if all subnets of the connected network have the same MTU. |
| arp-cache-timeout | Timeout for ARP cache entries. |
| boot-file-size | Size of the default boot image for the client. |
| bootfile-name | Bootfile name for the client. |
| broadcast-address | Broadcast address of the client's subnet. |
| cookie-server | RFC 865 Cookie servers available to the client. |
| default-finger-server | Default Finger servers available to the client. |
| default-ip-ttl | Default time-to-live to use on outgoing IP datagrams. |
| default-irc-server | Default IRC servers available to the client. |
| default-www-server | Default WWW servers available to the client. |
| domain-name | Domain name of the client. |
| domain-name-server | Domain Name System servers available to the client. |
| ethernet-encapsulation | Flag specifying whether the client should use Ethernet v2 or IEEE 802.3 encapsulation. |
| extensions-path | Path name to a TFTP-retrievable file containing vendor-extension information. |
| host-name | Name of the client. |
| impress-server | Imagen Impress servers available to the client. |
| interface-mtu | MTU for the client's interface. |
| ip-forwarding | Flag enabling/disabling IP layer packet forwarding. |
| log-server | MIT-LCS UDP Log servers available to the client. |
| lpr-server | RFC 1179 Line Printer servers available to the client. |
| mask-supplier | Flag indicating whether the client should respond to subnet mask discovery requests via ICMP. |
| max-datagram-reassembly-size | Maximum sized datagram that the client should be able to reassemble. |
| max-message-size | Maximum length of a DHCP message that the participant is willing to accept. |
| merit-dump-file | Path name of a core dump file. |
| mobile-ip-home-agent | Mobile IP home agents available to the client. |
| name-server | IEN 116 Name servers available to the client. |
| net-bios-over-tcpip-distribution-server | NetBIOS datagram distribution servers available to the client. |
| net-bios-over-tcpip-name-server | NetBIOS name 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. |
| network-information-servers | Network Information Service servers available to the client. |
| network-information-service-domain | Name of the client's Network Information Service domain. |
| network-information-service-plus-domain | Network Information System+ domain name. |
| network-information-service-plus-servers | Network Information System+ servers available to the client. |
| network-time-protocol-servers | Network Time Protocol servers available to the client. |
| nntp-server | NNTP servers available to the client. |
| non-local-source-routing | Flag enabling/disabling forwarding of IP packets with non-local source routes. |
| path-mtu-aging-timeout | Timeout to use when aging Path MTU values. |
| path-mtu-plateau-table | Table of MTU sizes for Path MTU Discovery. |
| perform-mask-discovery | Flag indicating whether the client should perform subnet mask discovery via ICMP. |
| perform-router-discovery | Flag indicating whether the client should solicit routers using Router Discovery. |
| policy-filter | Policy filters for non-local source routing. |
| pop3-server | POP3 servers available to the client. |
| rebinding-time-value | Time interval from address assignment at which the client transitions to a Rebinding state. |
| renewal-time-value | Time interval from address assignment at which the client transitions to a Renewing state. |
| resource-location-server | RFC 887 Resource Location servers available to the client. |
| root-path | Path name to a TFTP-retrievable file containing vendor-extension information. |
| router | The routers within a client's subnet. |
| router-solicitation-address | Destination address for Router Solicitation requests. |
| smtp-server | SMTP servers available to the client. |
| static-route | Static Routes which the client should put in its routing cache. |
| stda-server | StreetTalk Directory Assistance servers available to the client. |
| street-talk-server | StreetTalk servers available to the client. |
| subnet-mask | The client's subnet mask. |
| swap-server | Address of the client's swap server. |
| tcp-default-ttl | Default time-to-live for outgoing TCP segments. |
| tcp-keepalive-garbage | Flag specifying whether the client should send TCP keepalive messages with an octet of garbage. |
| tcp-keepalive-interval | Interval the client should wait before sending a TCP keepalive message. |
| tftp-server-name | TFTP server available to the client. |
| time-offset | The client's offset from UTC. |
| time-server | Time Protocol servers available to the client. |
| trailer-encapsulation | Flag specifying whether the client should negotiate the use of trailers in ARP. |
| vendor-specific-information | Option for exchanging vendor-specific information between the DHCP client and DHCP server. |
| x-window-system-display-manager | X window System Display Manager systems available to the client. |
| x-window-system-font-server | X Window System Font servers available to the client. |
all-subnets-local
Flag indicating if all subnets of the connected network have the same MTU.
Usage: ffx net dhcpd get option all-subnets-local [--local]
| Options | |
|---|---|
| display usage information | |
| a flag indicating if all subents of the IP network to which the client is connected have the same MTU. |
arp-cache-timeout
Timeout for ARP cache entries.
Usage: ffx net dhcpd get option arp-cache-timeout [--timeout <timeout>]
| Options | |
|---|---|
| display usage information | |
| the timeout for ARP cache entries, in seconds. |
boot-file-size
Size of the default boot image for the client.
Usage: ffx net dhcpd get option boot-file-size [--size <size>]
| Options | |
|---|---|
| display usage information | |
| the size of the client's default boot image in 512-octet blocks. |
bootfile-name
Bootfile name for the client.
Usage: ffx net dhcpd get option bootfile-name [--name <name>]
| Options | |
|---|---|
| display usage information | |
the bootfile name for the client. This option should be used when the file field has been overloaded to carry options. |
broadcast-address
Broadcast address of the client's subnet.
Usage: ffx net dhcpd get option broadcast-address [--addr <addr>]
| Options | |
|---|---|
| display usage information | |
| the broadcast address of the client's subnet. Legal values are defined in RFC 1122. |
cookie-server
RFC 865 Cookie servers available to the client.
Usage: ffx net dhcpd get option cookie-server [--cookie-servers <cookie-servers...>]
| Options | |
|---|---|
| display usage information | |
| a list of RFC 865 Cookie servers available to the client, in order of preference. |
default-finger-server
Default Finger servers available to the client.
Usage: ffx net dhcpd get option default-finger-server [--finger-servers <finger-servers...>]
| Options | |
|---|---|
| display usage information | |
| a list of default Finger server addresses available to the client, listed in order of preference. |
default-ip-ttl
Default time-to-live to use on outgoing IP datagrams.
Usage: ffx net dhcpd get option default-ip-ttl [--ttl <ttl>]
| Options | |
|---|---|
| display usage information | |
| the default time-to-live to use on outgoing IP datagrams. The value must be between 1 and 255. |
default-irc-server
Default IRC servers available to the client.
Usage: ffx net dhcpd get option default-irc-server [--irc-servers <irc-servers...>]
| Options | |
|---|---|
| display usage information | |
| a list of Internet Relay Chat server addresses available to the client, listed in order of preference. |
default-www-server
Default WWW servers available to the client.
Usage: ffx net dhcpd get option default-www-server [--www-servers <www-servers...>]
| Options | |
|---|---|
| display usage information | |
| a list of default World Wide Web (WWW) server addresses available to the client, listed in order of preference. |
domain-name
Domain name of the client.
Usage: ffx net dhcpd get option domain-name [--name <name>]
| Options | |
|---|---|
| display usage information | |
| the client's domain name for use in resolving hostnames in the DNS. |
domain-name-server
Domain Name System servers available to the client.
Usage: ffx net dhcpd get option domain-name-server [--domain-name-servers <domain-name-servers...>]
| Options | |
|---|---|
| display usage information | |
| a list of DNS servers available to the client, in order of preference; |
ethernet-encapsulation
Flag specifying whether the client should use Ethernet v2 or IEEE 802.3 encapsulation.
Usage: ffx net dhcpd get option ethernet-encapsulation [--encapsulate]
| Options | |
|---|---|
| display usage information | |
| a flag specifying that the client should use Ethernet v2 encapsulation when false, and IEEE 802.3 encapsulation when true. |
extensions-path
Path name to a TFTP-retrievable file containing vendor-extension information.
Usage: ffx net dhcpd get option extensions-path [--path <path>]
| Options | |
|---|---|
| display usage information | |
| 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. |
host-name
Name of the client.
Usage: ffx net dhcpd get option host-name [--name <name>]
| Options | |
|---|---|
| display usage information | |
| the name of client, which may or may not be qualified with the local domain name. |
impress-server
Imagen Impress servers available to the client.
Usage: ffx net dhcpd get option impress-server [--impress-servers <impress-servers...>]
| Options | |
|---|---|
| display usage information | |
| a list of Imagen Impress servers available to the client, in order of preference. |
interface-mtu
MTU for the client's interface.
Usage: ffx net dhcpd get option interface-mtu [--mtu <mtu>]
| Options | |
|---|---|
| display usage information | |
| the MTU for the client's interface. Minimum value of 68. |
ip-forwarding
Flag enabling/disabling IP layer packet forwarding.
Usage: ffx net dhcpd get option ip-forwarding [--enabled]
| Options | |
|---|---|
| display usage information | |
| a flag which will enabled IP layer packet forwarding when true. |
log-server
MIT-LCS UDP Log servers available to the client.
Usage: ffx net dhcpd get option log-server [--log-servers <log-servers...>]
| Options | |
|---|---|
| display usage information | |
| a list of MIT-LCS UDP Log servers available to the client, in order of preference. |
lpr-server
RFC 1179 Line Printer servers available to the client.
Usage: ffx net dhcpd get option lpr-server [--lpr-servers <lpr-servers...>]
| Options | |
|---|---|
| display usage information | |
| a list of RFC 1179 Line Printer servers available to the client, in order of preference. |
mask-supplier
Flag indicating whether the client should respond to subnet mask discovery requests via ICMP.
Usage: ffx net dhcpd get option mask-supplier [--supplier]
| Options | |
|---|---|
| display usage information | |
| a flag indicating whether the client should respond to subnet mask discovery requests via ICMP. |
max-datagram-reassembly-size
Maximum sized datagram that the client should be able to reassemble.
Usage: ffx net dhcpd get option max-datagram-reassembly-size [--size <size>]
| Options | |
|---|---|
| display usage information | |
| the maximum sized datagram that the client should be able to reassemble, in octets. The minimum legal value is 576. |
max-message-size
Maximum length of a DHCP message that the participant is willing to accept.
Usage: ffx net dhcpd get option max-message-size [--length <length>]
| Options | |
|---|---|
| display usage information | |
| the maximum length in octets of a DHCP message that the participant is willing to accept. The minimum value is 576. |
merit-dump-file
Path name of a core dump file.
Usage: ffx net dhcpd get option merit-dump-file [--path <path>]
| Options | |
|---|---|
| display usage information | |
| the path name to the client's core dump in the event the client crashes. |
mobile-ip-home-agent
Mobile IP home agents available to the client.
Usage: ffx net dhcpd get option mobile-ip-home-agent [--home-agents <home-agents...>]
| Options | |
|---|---|
| display usage information | |
| a list of mobile IP home agent addresses available to the client, listed in order of preference. |
name-server
IEN 116 Name servers available to the client.
Usage: ffx net dhcpd get option name-server [--name-servers <name-servers...>]
| Options | |
|---|---|
| display usage information | |
| a list of IEN 116 Name servers available to the client, in order of preference. |
net-bios-over-tcpip-distribution-server
NetBIOS datagram distribution servers available to the client.
Usage: ffx net dhcpd get option net-bios-over-tcpip-distribution-server [--servers <servers...>]
| Options | |
|---|---|
| display usage information | |
| a list of NetBIOS datagram distribution servers available to the client, listed in order of preference. |
net-bios-over-tcpip-name-server
NetBIOS name servers available to the client.
Usage: ffx net dhcpd get option net-bios-over-tcpip-name-server [--servers <servers...>]
| Options | |
|---|---|
| display usage information | |
| a list of NetBIOS name server addresses available to the client, listed in order of preference. |
net-bios-over-tcpip-node-type
The NetBIOS node type which should be used by the client.
Usage: ffx net dhcpd get option net-bios-over-tcpip-node-type [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| b-node | A B node type. |
| h-node | A H node type. |
| m-node | A M node type. |
| p-node | A P node type. |
# b-node
A B node type.
Usage: ffx net dhcpd get option net-bios-over-tcpip-node-type b-node
| Options | |
|---|---|
| display usage information |
# h-node
A H node type.
Usage: ffx net dhcpd get option net-bios-over-tcpip-node-type h-node
| Options | |
|---|---|
| display usage information |
# m-node
A M node type.
Usage: ffx net dhcpd get option net-bios-over-tcpip-node-type m-node
| Options | |
|---|---|
| display usage information |
# p-node
A P node type.
Usage: ffx net dhcpd get option net-bios-over-tcpip-node-type p-node
| Options | |
|---|---|
| display usage information |
net-bios-over-tcpip-scope
NetBIOS scope parameter for the client.
Usage: ffx net dhcpd get option net-bios-over-tcpip-scope [--scope <scope>]
| Options | |
|---|---|
| display usage information | |
| the NetBIOS over TCP/IP scope parameter, as defined in RFC 1001, for the client. |
network-information-servers
Network Information Service servers available to the client.
Usage: ffx net dhcpd get option network-information-servers [--servers <servers...>]
| Options | |
|---|---|
| display usage information | |
| a list of Network Information Service server addresses available to the client, listed in order of preference. |
network-information-service-domain
Name of the client's Network Information Service domain.
Usage: ffx net dhcpd get option network-information-service-domain [--domain-name <domain-name>]
| Options | |
|---|---|
| display usage information | |
| the name of the client's Network Information Service domain. |
network-information-service-plus-domain
Network Information System+ domain name.
Usage: ffx net dhcpd get option network-information-service-plus-domain [--domain-name <domain-name>]
| Options | |
|---|---|
| display usage information | |
| the name of the client's Network Information System+ domain. |
network-information-service-plus-servers
Network Information System+ servers available to the client.
Usage: ffx net dhcpd get option network-information-service-plus-servers [--servers <servers...>]
| Options | |
|---|---|
| display usage information | |
| a list of Network Information System+ server addresses available to the client, listed in order of preference. |
network-time-protocol-servers
Network Time Protocol servers available to the client.
Usage: ffx net dhcpd get option network-time-protocol-servers [--servers <servers...>]
| Options | |
|---|---|
| display usage information | |
| a list of Network Time Protocol (NTP) server addresses available to the client, listed in order of preference. |
nntp-server
NNTP servers available to the client.
Usage: ffx net dhcpd get option nntp-server [--nntp-servers <nntp-servers...>]
| Options | |
|---|---|
| display usage information | |
| a list Network News Transport Protocol (NNTP) server addresses available to the client, listed in order of preference. |
non-local-source-routing
Flag enabling/disabling forwarding of IP packets with non-local source routes.
Usage: ffx net dhcpd get option non-local-source-routing [--enabled]
| Options | |
|---|---|
| display usage information | |
| a flag which will enable forwarding of IP packets with non-local source routes. |
path-mtu-aging-timeout
Timeout to use when aging Path MTU values.
Usage: ffx net dhcpd get option path-mtu-aging-timeout [--timeout <timeout>]
| Options | |
|---|---|
| display usage information | |
| the timeout, in seconds, to be used when again Path MTU values by the mechanism in RFC 1191. |
path-mtu-plateau-table
Table of MTU sizes for Path MTU Discovery.
Usage: ffx net dhcpd get option path-mtu-plateau-table [--mtu-sizes <mtu-sizes...>]
| Options | |
|---|---|
| display usage information | |
| A list of MTU sizes, ordered from smallest to largest. The smallest value cannot be smaller than 68. |
perform-mask-discovery
Flag indicating whether the client should perform subnet mask discovery via ICMP.
Usage: ffx net dhcpd get option perform-mask-discovery [--do-discovery]
| Options | |
|---|---|
| display usage information | |
| a flag indicating whether the client should perform subnet mask discovery via ICMP. |
perform-router-discovery
Flag indicating whether the client should solicit routers using Router Discovery.
Usage: ffx net dhcpd get option perform-router-discovery [--do-discovery]
| Options | |
|---|---|
| display usage information | |
| A flag indicating whether the client should solicit routers using Router Discovery as defined in RFC 1256. |
policy-filter
Policy filters for non-local source routing.
Usage: ffx net dhcpd get option policy-filter [--addresses <addresses...>]
| Options | |
|---|---|
| display usage information | |
| 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. |
pop3-server
POP3 servers available to the client.
Usage: ffx net dhcpd get option pop3-server [--pop3-servers <pop3-servers...>]
| Options | |
|---|---|
| display usage information | |
| a list of Post Office Protocol (POP3) server addresses available to the client, listed in order of preference. |
rebinding-time-value
Time interval from address assignment at which the client transitions to a Rebinding state.
Usage: ffx net dhcpd get option rebinding-time-value [--interval <interval>]
| Options | |
|---|---|
| display usage information | |
| the time interval, in seconds, after address assignment at which the client will transition to the Rebinding state. |
renewal-time-value
Time interval from address assignment at which the client transitions to a Renewing state.
Usage: ffx net dhcpd get option renewal-time-value [--interval <interval>]
| Options | |
|---|---|
| display usage information | |
| the time interval, in seconds, after address assignment at which the client will transition to the Renewing state. |
resource-location-server
RFC 887 Resource Location servers available to the client.
Usage: ffx net dhcpd get option resource-location-server [--resource-location-servers <resource-location-servers...>]
| Options | |
|---|---|
| display usage information | |
| a list of RFC 887 Resource Location servers available to the client, in order of preference. |
root-path
Path name to a TFTP-retrievable file containing vendor-extension information.
Usage: ffx net dhcpd get option root-path [--path <path>]
| Options | |
|---|---|
| display usage information | |
| 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. |
router
The routers within a client's subnet.
Usage: ffx net dhcpd get option router [--routers <routers...>]
| Options | |
|---|---|
| display usage information | |
| a list of the routers in a client's subnet, listed in order of preference. |
router-solicitation-address
Destination address for Router Solicitation requests.
Usage: ffx net dhcpd get option router-solicitation-address [--addr <addr>]
| Options | |
|---|---|
| display usage information | |
| the address to which the client should transmit Router Solicitation requests. |
smtp-server
SMTP servers available to the client.
Usage: ffx net dhcpd get option smtp-server [--smtp-servers <smtp-servers...>]
| Options | |
|---|---|
| display usage information | |
| a list of Simple Mail Transport Protocol (SMTP) server address available to the client, listed in order of preference. |
static-route
Static Routes which the client should put in its routing cache.
Usage: ffx net dhcpd get option static-route [--routes <routes...>]
| Options | |
|---|---|
| display usage information | |
| 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. |
stda-server
StreetTalk Directory Assistance servers available to the client.
Usage: ffx net dhcpd get option stda-server [--stda-servers <stda-servers...>]
| Options | |
|---|---|
| display usage information | |
| a list of StreetTalk Directory Assistance server addresses available to the client, listed in order of preference. |
street-talk-server
StreetTalk servers available to the client.
Usage: ffx net dhcpd get option street-talk-server [--streettalk-servers <streettalk-servers...>]
| Options | |
|---|---|
| display usage information | |
| a list of StreetTalk server addresses available to the client, listed in order of preference. |
subnet-mask
The client's subnet mask.
Usage: ffx net dhcpd get option subnet-mask [--mask <mask>]
| Options | |
|---|---|
| display usage information | |
| a 32-bit IPv4 subnet mask. |
swap-server
Address of the client's swap server.
Usage: ffx net dhcpd get option swap-server [--address <address>]
| Options | |
|---|---|
| display usage information | |
| the address of the client's swap server. |
tcp-default-ttl
Default time-to-live for outgoing TCP segments.
Usage: ffx net dhcpd get option tcp-default-ttl [--ttl <ttl>]
| Options | |
|---|---|
| display usage information | |
| the default time-to-live that the client should use for outgoing TCP segments. The minimum value is 1. |
tcp-keepalive-garbage
Flag specifying whether the client should send TCP keepalive messages with an octet of garbage.
Usage: ffx net dhcpd get option tcp-keepalive-garbage [--send-garbage]
| Options | |
|---|---|
| display usage information | |
| a flag specifying whether the client should send TCP keepalive messages with an octet of garbage for compatibility with older implementations. |
tcp-keepalive-interval
Interval the client should wait before sending a TCP keepalive message.
Usage: ffx net dhcpd get option tcp-keepalive-interval [--interval <interval>]
| Options | |
|---|---|
| display usage information | |
| 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. |
tftp-server-name
TFTP server available to the client.
Usage: ffx net dhcpd get option tftp-server-name [--name <name>]
| Options | |
|---|---|
| display usage information | |
the TFTP server name available to the client. This option should be used when the sname field has been overloaded to carry options. |
time-offset
The client's offset from UTC.
Usage: ffx net dhcpd get option time-offset [--offset <offset>]
| Options | |
|---|---|
| display usage information | |
| 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. |
time-server
Time Protocol servers available to the client.
Usage: ffx net dhcpd get option time-server [--time-servers <time-servers...>]
| Options | |
|---|---|
| display usage information | |
| a list of time servers available to the client, in order of preference. |
trailer-encapsulation
Flag specifying whether the client should negotiate the use of trailers in ARP.
Usage: ffx net dhcpd get option trailer-encapsulation [--trailers]
| Options | |
|---|---|
| display usage information | |
| a flag specifying whether the client negotiate the use of trailers when using ARP, per RFC 893. |
vendor-specific-information
Option for exchanging vendor-specific information between the DHCP client and DHCP server.
Usage: ffx net dhcpd get option vendor-specific-information [--data <data...>]
| Options | |
|---|---|
| display usage information | |
| an opaque object of octets for exchanging vendor-specific information. |
x-window-system-display-manager
X window System Display Manager systems available to the client.
Usage: ffx net dhcpd get option x-window-system-display-manager [--display-servers <display-servers...>]
| Options | |
|---|---|
| display usage information | |
| a list of X Window System Display Manager system addresses available to the client, listed in order of preference. |
x-window-system-font-server
X Window System Font servers available to the client.
Usage: ffx net dhcpd get option x-window-system-font-server [--servers <servers...>]
| Options | |
|---|---|
| display usage information | |
| a list of X Window System Font server addresses available to the client, listed in order of preference. |
parameter
A secondary command indicating a server parameter argument.
Usage: ffx net dhcpd get parameter [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| address-pool | The pool of addresses which the DHCP server manages. |
| 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. |
| ip-addrs | The IPv4 addresses to which the server is bound. |
| 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)). |
address-pool
The pool of addresses which the DHCP server manages.
Usage: ffx net dhcpd get parameter address-pool [--prefix-length <prefix-length>] [--range-start <range-start>] [--range-stop <range-stop>]
| Options | |
|---|---|
| display usage information | |
| the prefix length of the network's subnet mask | |
| the starting address, inclusive, of the range of addresses which the DHCP server will lease to clients | |
| the ending address, inclusive, of the range of addresses which the server will to clients |
arp-probe
Enables server behavior where the server ARPs an IP address prior to issuing it in a lease.
Usage: ffx net dhcpd get parameter arp-probe [--enabled]
| Options | |
|---|---|
| display usage information | |
| 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. |
bound-device-names
The names of the network devices on which the server will listen.
Usage: ffx net dhcpd get parameter bound-device-names [names...]
| Options | |
|---|---|
| display usage information |
ip-addrs
The IPv4 addresses to which the server is bound.
Usage: ffx net dhcpd get parameter ip-addrs [--addrs <addrs...>]
| Options | |
|---|---|
| display usage information | |
| A list of IPv4 Addresses to which the server is bound. |
lease-length
The duration of leases offered by the server.
Usage: ffx net dhcpd get parameter lease-length [--default <default>] [--max <max>]
| Options | |
|---|---|
| display usage information | |
| the default lease length, in seconds, to be issued to clients. | |
| 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. |
permitted-macs
The client MAC addresses which the server will issue leases to.
Usage: ffx net dhcpd get parameter permitted-macs [--macs <macs...>]
| Options | |
|---|---|
| display usage information | |
| 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. |
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)).
Usage: ffx net dhcpd get parameter statically-assigned-addrs [--hosts <hosts...>] [--assigned-addrs <assigned-addrs...>]
| Options | |
|---|---|
| display usage information | |
hosts which will be leased the addresses reserved by 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. |
list
A primary command to list the values of all DHCP options or server parameters.
Usage: ffx net dhcpd list [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| option | Perform the command on DHCP options. |
| parameter | Perform the command on server parameters. |
option
Perform the command on DHCP options.
Usage: ffx net dhcpd list option
| Options | |
|---|---|
| display usage information |
parameter
Perform the command on server parameters.
Usage: ffx net dhcpd list parameter
| Options | |
|---|---|
| display usage information |
reset
A primary command to reset the values of all DHCP options or server parameters.
Usage: ffx net dhcpd reset [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| option | Perform the command on DHCP options. |
| parameter | Perform the command on server parameters. |
option
Perform the command on DHCP options.
Usage: ffx net dhcpd reset option
| Options | |
|---|---|
| display usage information |
parameter
Perform the command on server parameters.
Usage: ffx net dhcpd reset parameter
| Options | |
|---|---|
| display usage information |
set
A primary command to set the value of a DHCP option or server parameter.
Usage: ffx net dhcpd set [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| option | A secondary command indicating a DHCP option argument. |
| parameter | A secondary command indicating a server parameter argument. |
option
A secondary command indicating a DHCP option argument.
Usage: ffx net dhcpd set option [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| all-subnets-local | Flag indicating if all subnets of the connected network have the same MTU. |
| arp-cache-timeout | Timeout for ARP cache entries. |
| boot-file-size | Size of the default boot image for the client. |
| bootfile-name | Bootfile name for the client. |
| broadcast-address | Broadcast address of the client's subnet. |
| cookie-server | RFC 865 Cookie servers available to the client. |
| default-finger-server | Default Finger servers available to the client. |
| default-ip-ttl | Default time-to-live to use on outgoing IP datagrams. |
| default-irc-server | Default IRC servers available to the client. |
| default-www-server | Default WWW servers available to the client. |
| domain-name | Domain name of the client. |
| domain-name-server | Domain Name System servers available to the client. |
| ethernet-encapsulation | Flag specifying whether the client should use Ethernet v2 or IEEE 802.3 encapsulation. |
| extensions-path | Path name to a TFTP-retrievable file containing vendor-extension information. |
| host-name | Name of the client. |
| impress-server | Imagen Impress servers available to the client. |
| interface-mtu | MTU for the client's interface. |
| ip-forwarding | Flag enabling/disabling IP layer packet forwarding. |
| log-server | MIT-LCS UDP Log servers available to the client. |
| lpr-server | RFC 1179 Line Printer servers available to the client. |
| mask-supplier | Flag indicating whether the client should respond to subnet mask discovery requests via ICMP. |
| max-datagram-reassembly-size | Maximum sized datagram that the client should be able to reassemble. |
| max-message-size | Maximum length of a DHCP message that the participant is willing to accept. |
| merit-dump-file | Path name of a core dump file. |
| mobile-ip-home-agent | Mobile IP home agents available to the client. |
| name-server | IEN 116 Name servers available to the client. |
| net-bios-over-tcpip-distribution-server | NetBIOS datagram distribution servers available to the client. |
| net-bios-over-tcpip-name-server | NetBIOS name 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. |
| network-information-servers | Network Information Service servers available to the client. |
| network-information-service-domain | Name of the client's Network Information Service domain. |
| network-information-service-plus-domain | Network Information System+ domain name. |
| network-information-service-plus-servers | Network Information System+ servers available to the client. |
| network-time-protocol-servers | Network Time Protocol servers available to the client. |
| nntp-server | NNTP servers available to the client. |
| non-local-source-routing | Flag enabling/disabling forwarding of IP packets with non-local source routes. |
| path-mtu-aging-timeout | Timeout to use when aging Path MTU values. |
| path-mtu-plateau-table | Table of MTU sizes for Path MTU Discovery. |
| perform-mask-discovery | Flag indicating whether the client should perform subnet mask discovery via ICMP. |
| perform-router-discovery | Flag indicating whether the client should solicit routers using Router Discovery. |
| policy-filter | Policy filters for non-local source routing. |
| pop3-server | POP3 servers available to the client. |
| rebinding-time-value | Time interval from address assignment at which the client transitions to a Rebinding state. |
| renewal-time-value | Time interval from address assignment at which the client transitions to a Renewing state. |
| resource-location-server | RFC 887 Resource Location servers available to the client. |
| root-path | Path name to a TFTP-retrievable file containing vendor-extension information. |
| router | The routers within a client's subnet. |
| router-solicitation-address | Destination address for Router Solicitation requests. |
| smtp-server | SMTP servers available to the client. |
| static-route | Static Routes which the client should put in its routing cache. |
| stda-server | StreetTalk Directory Assistance servers available to the client. |
| street-talk-server | StreetTalk servers available to the client. |
| subnet-mask | The client's subnet mask. |
| swap-server | Address of the client's swap server. |
| tcp-default-ttl | Default time-to-live for outgoing TCP segments. |
| tcp-keepalive-garbage | Flag specifying whether the client should send TCP keepalive messages with an octet of garbage. |
| tcp-keepalive-interval | Interval the client should wait before sending a TCP keepalive message. |
| tftp-server-name | TFTP server available to the client. |
| time-offset | The client's offset from UTC. |
| time-server | Time Protocol servers available to the client. |
| trailer-encapsulation | Flag specifying whether the client should negotiate the use of trailers in ARP. |
| vendor-specific-information | Option for exchanging vendor-specific information between the DHCP client and DHCP server. |
| x-window-system-display-manager | X window System Display Manager systems available to the client. |
| x-window-system-font-server | X Window System Font servers available to the client. |
all-subnets-local
Flag indicating if all subnets of the connected network have the same MTU.
Usage: ffx net dhcpd set option all-subnets-local [--local]
| Options | |
|---|---|
| display usage information | |
| a flag indicating if all subents of the IP network to which the client is connected have the same MTU. |
arp-cache-timeout
Timeout for ARP cache entries.
Usage: ffx net dhcpd set option arp-cache-timeout [--timeout <timeout>]
| Options | |
|---|---|
| display usage information | |
| the timeout for ARP cache entries, in seconds. |
boot-file-size
Size of the default boot image for the client.
Usage: ffx net dhcpd set option boot-file-size [--size <size>]
| Options | |
|---|---|
| display usage information | |
| the size of the client's default boot image in 512-octet blocks. |
bootfile-name
Bootfile name for the client.
Usage: ffx net dhcpd set option bootfile-name [--name <name>]
| Options | |
|---|---|
| display usage information | |
the bootfile name for the client. This option should be used when the file field has been overloaded to carry options. |
broadcast-address
Broadcast address of the client's subnet.
Usage: ffx net dhcpd set option broadcast-address [--addr <addr>]
| Options | |
|---|---|
| display usage information | |
| the broadcast address of the client's subnet. Legal values are defined in RFC 1122. |
cookie-server
RFC 865 Cookie servers available to the client.
Usage: ffx net dhcpd set option cookie-server [--cookie-servers <cookie-servers...>]
| Options | |
|---|---|
| display usage information | |
| a list of RFC 865 Cookie servers available to the client, in order of preference. |
default-finger-server
Default Finger servers available to the client.
Usage: ffx net dhcpd set option default-finger-server [--finger-servers <finger-servers...>]
| Options | |
|---|---|
| display usage information | |
| a list of default Finger server addresses available to the client, listed in order of preference. |
default-ip-ttl
Default time-to-live to use on outgoing IP datagrams.
Usage: ffx net dhcpd set option default-ip-ttl [--ttl <ttl>]
| Options | |
|---|---|
| display usage information | |
| the default time-to-live to use on outgoing IP datagrams. The value must be between 1 and 255. |
default-irc-server
Default IRC servers available to the client.
Usage: ffx net dhcpd set option default-irc-server [--irc-servers <irc-servers...>]
| Options | |
|---|---|
| display usage information | |
| a list of Internet Relay Chat server addresses available to the client, listed in order of preference. |
default-www-server
Default WWW servers available to the client.
Usage: ffx net dhcpd set option default-www-server [--www-servers <www-servers...>]
| Options | |
|---|---|
| display usage information | |
| a list of default World Wide Web (WWW) server addresses available to the client, listed in order of preference. |
domain-name
Domain name of the client.
Usage: ffx net dhcpd set option domain-name [--name <name>]
| Options | |
|---|---|
| display usage information | |
| the client's domain name for use in resolving hostnames in the DNS. |
domain-name-server
Domain Name System servers available to the client.
Usage: ffx net dhcpd set option domain-name-server [--domain-name-servers <domain-name-servers...>]
| Options | |
|---|---|
| display usage information | |
| a list of DNS servers available to the client, in order of preference; |
ethernet-encapsulation
Flag specifying whether the client should use Ethernet v2 or IEEE 802.3 encapsulation.
Usage: ffx net dhcpd set option ethernet-encapsulation [--encapsulate]
| Options | |
|---|---|
| display usage information | |
| a flag specifying that the client should use Ethernet v2 encapsulation when false, and IEEE 802.3 encapsulation when true. |
extensions-path
Path name to a TFTP-retrievable file containing vendor-extension information.
Usage: ffx net dhcpd set option extensions-path [--path <path>]
| Options | |
|---|---|
| display usage information | |
| 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. |
host-name
Name of the client.
Usage: ffx net dhcpd set option host-name [--name <name>]
| Options | |
|---|---|
| display usage information | |
| the name of client, which may or may not be qualified with the local domain name. |
impress-server
Imagen Impress servers available to the client.
Usage: ffx net dhcpd set option impress-server [--impress-servers <impress-servers...>]
| Options | |
|---|---|
| display usage information | |
| a list of Imagen Impress servers available to the client, in order of preference. |
interface-mtu
MTU for the client's interface.
Usage: ffx net dhcpd set option interface-mtu [--mtu <mtu>]
| Options | |
|---|---|
| display usage information | |
| the MTU for the client's interface. Minimum value of 68. |
ip-forwarding
Flag enabling/disabling IP layer packet forwarding.
Usage: ffx net dhcpd set option ip-forwarding [--enabled]
| Options | |
|---|---|
| display usage information | |
| a flag which will enabled IP layer packet forwarding when true. |
log-server
MIT-LCS UDP Log servers available to the client.
Usage: ffx net dhcpd set option log-server [--log-servers <log-servers...>]
| Options | |
|---|---|
| display usage information | |
| a list of MIT-LCS UDP Log servers available to the client, in order of preference. |
lpr-server
RFC 1179 Line Printer servers available to the client.
Usage: ffx net dhcpd set option lpr-server [--lpr-servers <lpr-servers...>]
| Options | |
|---|---|
| display usage information | |
| a list of RFC 1179 Line Printer servers available to the client, in order of preference. |
mask-supplier
Flag indicating whether the client should respond to subnet mask discovery requests via ICMP.
Usage: ffx net dhcpd set option mask-supplier [--supplier]
| Options | |
|---|---|
| display usage information | |
| a flag indicating whether the client should respond to subnet mask discovery requests via ICMP. |
max-datagram-reassembly-size
Maximum sized datagram that the client should be able to reassemble.
Usage: ffx net dhcpd set option max-datagram-reassembly-size [--size <size>]
| Options | |
|---|---|
| display usage information | |
| the maximum sized datagram that the client should be able to reassemble, in octets. The minimum legal value is 576. |
max-message-size
Maximum length of a DHCP message that the participant is willing to accept.
Usage: ffx net dhcpd set option max-message-size [--length <length>]
| Options | |
|---|---|
| display usage information | |
| the maximum length in octets of a DHCP message that the participant is willing to accept. The minimum value is 576. |
merit-dump-file
Path name of a core dump file.
Usage: ffx net dhcpd set option merit-dump-file [--path <path>]
| Options | |
|---|---|
| display usage information | |
| the path name to the client's core dump in the event the client crashes. |
mobile-ip-home-agent
Mobile IP home agents available to the client.
Usage: ffx net dhcpd set option mobile-ip-home-agent [--home-agents <home-agents...>]
| Options | |
|---|---|
| display usage information | |
| a list of mobile IP home agent addresses available to the client, listed in order of preference. |
name-server
IEN 116 Name servers available to the client.
Usage: ffx net dhcpd set option name-server [--name-servers <name-servers...>]
| Options | |
|---|---|
| display usage information | |
| a list of IEN 116 Name servers available to the client, in order of preference. |
net-bios-over-tcpip-distribution-server
NetBIOS datagram distribution servers available to the client.
Usage: ffx net dhcpd set option net-bios-over-tcpip-distribution-server [--servers <servers...>]
| Options | |
|---|---|
| display usage information | |
| a list of NetBIOS datagram distribution servers available to the client, listed in order of preference. |
net-bios-over-tcpip-name-server
NetBIOS name servers available to the client.
Usage: ffx net dhcpd set option net-bios-over-tcpip-name-server [--servers <servers...>]
| Options | |
|---|---|
| display usage information | |
| a list of NetBIOS name server addresses available to the client, listed in order of preference. |
net-bios-over-tcpip-node-type
The NetBIOS node type which should be used by the client.
Usage: ffx net dhcpd set option net-bios-over-tcpip-node-type [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| b-node | A B node type. |
| h-node | A H node type. |
| m-node | A M node type. |
| p-node | A P node type. |
# b-node
A B node type.
Usage: ffx net dhcpd set option net-bios-over-tcpip-node-type b-node
| Options | |
|---|---|
| display usage information |
# h-node
A H node type.
Usage: ffx net dhcpd set option net-bios-over-tcpip-node-type h-node
| Options | |
|---|---|
| display usage information |
# m-node
A M node type.
Usage: ffx net dhcpd set option net-bios-over-tcpip-node-type m-node
| Options | |
|---|---|
| display usage information |
# p-node
A P node type.
Usage: ffx net dhcpd set option net-bios-over-tcpip-node-type p-node
| Options | |
|---|---|
| display usage information |
net-bios-over-tcpip-scope
NetBIOS scope parameter for the client.
Usage: ffx net dhcpd set option net-bios-over-tcpip-scope [--scope <scope>]
| Options | |
|---|---|
| display usage information | |
| the NetBIOS over TCP/IP scope parameter, as defined in RFC 1001, for the client. |
network-information-servers
Network Information Service servers available to the client.
Usage: ffx net dhcpd set option network-information-servers [--servers <servers...>]
| Options | |
|---|---|
| display usage information | |
| a list of Network Information Service server addresses available to the client, listed in order of preference. |
network-information-service-domain
Name of the client's Network Information Service domain.
Usage: ffx net dhcpd set option network-information-service-domain [--domain-name <domain-name>]
| Options | |
|---|---|
| display usage information | |
| the name of the client's Network Information Service domain. |
network-information-service-plus-domain
Network Information System+ domain name.
Usage: ffx net dhcpd set option network-information-service-plus-domain [--domain-name <domain-name>]
| Options | |
|---|---|
| display usage information | |
| the name of the client's Network Information System+ domain. |
network-information-service-plus-servers
Network Information System+ servers available to the client.
Usage: ffx net dhcpd set option network-information-service-plus-servers [--servers <servers...>]
| Options | |
|---|---|
| display usage information | |
| a list of Network Information System+ server addresses available to the client, listed in order of preference. |
network-time-protocol-servers
Network Time Protocol servers available to the client.
Usage: ffx net dhcpd set option network-time-protocol-servers [--servers <servers...>]
| Options | |
|---|---|
| display usage information | |
| a list of Network Time Protocol (NTP) server addresses available to the client, listed in order of preference. |
nntp-server
NNTP servers available to the client.
Usage: ffx net dhcpd set option nntp-server [--nntp-servers <nntp-servers...>]
| Options | |
|---|---|
| display usage information | |
| a list Network News Transport Protocol (NNTP) server addresses available to the client, listed in order of preference. |
non-local-source-routing
Flag enabling/disabling forwarding of IP packets with non-local source routes.
Usage: ffx net dhcpd set option non-local-source-routing [--enabled]
| Options | |
|---|---|
| display usage information | |
| a flag which will enable forwarding of IP packets with non-local source routes. |
path-mtu-aging-timeout
Timeout to use when aging Path MTU values.
Usage: ffx net dhcpd set option path-mtu-aging-timeout [--timeout <timeout>]
| Options | |
|---|---|
| display usage information | |
| the timeout, in seconds, to be used when again Path MTU values by the mechanism in RFC 1191. |
path-mtu-plateau-table
Table of MTU sizes for Path MTU Discovery.
Usage: ffx net dhcpd set option path-mtu-plateau-table [--mtu-sizes <mtu-sizes...>]
| Options | |
|---|---|
| display usage information | |
| A list of MTU sizes, ordered from smallest to largest. The smallest value cannot be smaller than 68. |
perform-mask-discovery
Flag indicating whether the client should perform subnet mask discovery via ICMP.
Usage: ffx net dhcpd set option perform-mask-discovery [--do-discovery]
| Options | |
|---|---|
| display usage information | |
| a flag indicating whether the client should perform subnet mask discovery via ICMP. |
perform-router-discovery
Flag indicating whether the client should solicit routers using Router Discovery.
Usage: ffx net dhcpd set option perform-router-discovery [--do-discovery]
| Options | |
|---|---|
| display usage information | |
| A flag indicating whether the client should solicit routers using Router Discovery as defined in RFC 1256. |
policy-filter
Policy filters for non-local source routing.
Usage: ffx net dhcpd set option policy-filter [--addresses <addresses...>]
| Options | |
|---|---|
| display usage information | |
| 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. |
pop3-server
POP3 servers available to the client.
Usage: ffx net dhcpd set option pop3-server [--pop3-servers <pop3-servers...>]
| Options | |
|---|---|
| display usage information | |
| a list of Post Office Protocol (POP3) server addresses available to the client, listed in order of preference. |
rebinding-time-value
Time interval from address assignment at which the client transitions to a Rebinding state.
Usage: ffx net dhcpd set option rebinding-time-value [--interval <interval>]
| Options | |
|---|---|
| display usage information | |
| the time interval, in seconds, after address assignment at which the client will transition to the Rebinding state. |
renewal-time-value
Time interval from address assignment at which the client transitions to a Renewing state.
Usage: ffx net dhcpd set option renewal-time-value [--interval <interval>]
| Options | |
|---|---|
| display usage information | |
| the time interval, in seconds, after address assignment at which the client will transition to the Renewing state. |
resource-location-server
RFC 887 Resource Location servers available to the client.
Usage: ffx net dhcpd set option resource-location-server [--resource-location-servers <resource-location-servers...>]
| Options | |
|---|---|
| display usage information | |
| a list of RFC 887 Resource Location servers available to the client, in order of preference. |
root-path
Path name to a TFTP-retrievable file containing vendor-extension information.
Usage: ffx net dhcpd set option root-path [--path <path>]
| Options | |
|---|---|
| display usage information | |
| 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. |
router
The routers within a client's subnet.
Usage: ffx net dhcpd set option router [--routers <routers...>]
| Options | |
|---|---|
| display usage information | |
| a list of the routers in a client's subnet, listed in order of preference. |
router-solicitation-address
Destination address for Router Solicitation requests.
Usage: ffx net dhcpd set option router-solicitation-address [--addr <addr>]
| Options | |
|---|---|
| display usage information | |
| the address to which the client should transmit Router Solicitation requests. |
smtp-server
SMTP servers available to the client.
Usage: ffx net dhcpd set option smtp-server [--smtp-servers <smtp-servers...>]
| Options | |
|---|---|
| display usage information | |
| a list of Simple Mail Transport Protocol (SMTP) server address available to the client, listed in order of preference. |
static-route
Static Routes which the client should put in its routing cache.
Usage: ffx net dhcpd set option static-route [--routes <routes...>]
| Options | |
|---|---|
| display usage information | |
| 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. |
stda-server
StreetTalk Directory Assistance servers available to the client.
Usage: ffx net dhcpd set option stda-server [--stda-servers <stda-servers...>]
| Options | |
|---|---|
| display usage information | |
| a list of StreetTalk Directory Assistance server addresses available to the client, listed in order of preference. |
street-talk-server
StreetTalk servers available to the client.
Usage: ffx net dhcpd set option street-talk-server [--streettalk-servers <streettalk-servers...>]
| Options | |
|---|---|
| display usage information | |
| a list of StreetTalk server addresses available to the client, listed in order of preference. |
subnet-mask
The client's subnet mask.
Usage: ffx net dhcpd set option subnet-mask [--mask <mask>]
| Options | |
|---|---|
| display usage information | |
| a 32-bit IPv4 subnet mask. |
swap-server
Address of the client's swap server.
Usage: ffx net dhcpd set option swap-server [--address <address>]
| Options | |
|---|---|
| display usage information | |
| the address of the client's swap server. |
tcp-default-ttl
Default time-to-live for outgoing TCP segments.
Usage: ffx net dhcpd set option tcp-default-ttl [--ttl <ttl>]
| Options | |
|---|---|
| display usage information | |
| the default time-to-live that the client should use for outgoing TCP segments. The minimum value is 1. |
tcp-keepalive-garbage
Flag specifying whether the client should send TCP keepalive messages with an octet of garbage.
Usage: ffx net dhcpd set option tcp-keepalive-garbage [--send-garbage]
| Options | |
|---|---|
| display usage information | |
| a flag specifying whether the client should send TCP keepalive messages with an octet of garbage for compatibility with older implementations. |
tcp-keepalive-interval
Interval the client should wait before sending a TCP keepalive message.
Usage: ffx net dhcpd set option tcp-keepalive-interval [--interval <interval>]
| Options | |
|---|---|
| display usage information | |
| 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. |
tftp-server-name
TFTP server available to the client.
Usage: ffx net dhcpd set option tftp-server-name [--name <name>]
| Options | |
|---|---|
| display usage information | |
the TFTP server name available to the client. This option should be used when the sname field has been overloaded to carry options. |
time-offset
The client's offset from UTC.
Usage: ffx net dhcpd set option time-offset [--offset <offset>]
| Options | |
|---|---|
| display usage information | |
| 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. |
time-server
Time Protocol servers available to the client.
Usage: ffx net dhcpd set option time-server [--time-servers <time-servers...>]
| Options | |
|---|---|
| display usage information | |
| a list of time servers available to the client, in order of preference. |
trailer-encapsulation
Flag specifying whether the client should negotiate the use of trailers in ARP.
Usage: ffx net dhcpd set option trailer-encapsulation [--trailers]
| Options | |
|---|---|
| display usage information | |
| a flag specifying whether the client negotiate the use of trailers when using ARP, per RFC 893. |
vendor-specific-information
Option for exchanging vendor-specific information between the DHCP client and DHCP server.
Usage: ffx net dhcpd set option vendor-specific-information [--data <data...>]
| Options | |
|---|---|
| display usage information | |
| an opaque object of octets for exchanging vendor-specific information. |
x-window-system-display-manager
X window System Display Manager systems available to the client.
Usage: ffx net dhcpd set option x-window-system-display-manager [--display-servers <display-servers...>]
| Options | |
|---|---|
| display usage information | |
| a list of X Window System Display Manager system addresses available to the client, listed in order of preference. |
x-window-system-font-server
X Window System Font servers available to the client.
Usage: ffx net dhcpd set option x-window-system-font-server [--servers <servers...>]
| Options | |
|---|---|
| display usage information | |
| a list of X Window System Font server addresses available to the client, listed in order of preference. |
parameter
A secondary command indicating a server parameter argument.
Usage: ffx net dhcpd set parameter [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| address-pool | The pool of addresses which the DHCP server manages. |
| 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. |
| ip-addrs | The IPv4 addresses to which the server is bound. |
| 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)). |
address-pool
The pool of addresses which the DHCP server manages.
Usage: ffx net dhcpd set parameter address-pool [--prefix-length <prefix-length>] [--range-start <range-start>] [--range-stop <range-stop>]
| Options | |
|---|---|
| display usage information | |
| the prefix length of the network's subnet mask | |
| the starting address, inclusive, of the range of addresses which the DHCP server will lease to clients | |
| the ending address, inclusive, of the range of addresses which the server will to clients |
arp-probe
Enables server behavior where the server ARPs an IP address prior to issuing it in a lease.
Usage: ffx net dhcpd set parameter arp-probe [--enabled]
| Options | |
|---|---|
| display usage information | |
| 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. |
bound-device-names
The names of the network devices on which the server will listen.
Usage: ffx net dhcpd set parameter bound-device-names [names...]
| Options | |
|---|---|
| display usage information |
ip-addrs
The IPv4 addresses to which the server is bound.
Usage: ffx net dhcpd set parameter ip-addrs [--addrs <addrs...>]
| Options | |
|---|---|
| display usage information | |
| A list of IPv4 Addresses to which the server is bound. |
lease-length
The duration of leases offered by the server.
Usage: ffx net dhcpd set parameter lease-length [--default <default>] [--max <max>]
| Options | |
|---|---|
| display usage information | |
| the default lease length, in seconds, to be issued to clients. | |
| 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. |
permitted-macs
The client MAC addresses which the server will issue leases to.
Usage: ffx net dhcpd set parameter permitted-macs [--macs <macs...>]
| Options | |
|---|---|
| display usage information | |
| 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. |
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)).
Usage: ffx net dhcpd set parameter statically-assigned-addrs [--hosts <hosts...>] [--assigned-addrs <assigned-addrs...>]
| Options | |
|---|---|
| display usage information | |
hosts which will be leased the addresses reserved by 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. |
start
A primary command to start the DHCP server.
Usage: ffx net dhcpd start
| Options | |
|---|---|
| display usage information |
stop
A primary command to stop the DHCP server.
Usage: ffx net dhcpd stop
| Options | |
|---|---|
| display usage information |
dns
commands to control the dns resolver
Usage: ffx net dns [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| lookup | performs dns resolution on the specified hostname |
lookup
performs dns resolution on the specified hostname
Usage: ffx net dns lookup [--ipv4 <ipv4>] [--ipv6 <ipv6>] [--sort <sort>] hostname
| Options | |
|---|---|
| display usage information | |
| include ipv4 results (defaults to true) | |
| include ipv6 results (defaults to true) | |
| sort addresses in order of preference (defaults to true) |
filter
commands for configuring packet filtering
Usage: ffx net filter [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| create | A command to create new filtering resources |
| list | A command to list filtering configuration. |
| remove | A command to remove existing filtering resources |
create
A command to create new filtering resources
Usage: ffx net filter create --controller <controller> [--idempotent] [subcommand...]
| Options | |
|---|---|
| display usage information | |
| the name of the controller to create (or connect to, if existing) | |
| whether the resource creation should be idempotent, i.e. succeed even if the resource already exists |
| Subcommands | |
|---|---|
| namespace | A command to specify a filtering namespace |
| routine | A command to specify a filtering routine |
| rule | A command to specify a filtering rule |
namespace
A command to specify a filtering namespace
Usage: ffx net filter create namespace --name <name> [--domain <domain>]
| Options | |
|---|---|
| display usage information | |
| the name of the namespace | |
| the IP domain of the namespace |
routine
A command to specify a filtering routine
Usage: ffx net filter create routine --namespace <namespace> --name <name> --type <type> [--hook <hook>] [--priority <priority>]
| Options | |
|---|---|
| display usage information | |
| the namespace that contains the routine | |
| the name of the routine | |
| the type of the routine (IP or NAT) | |
| the hook on which the routine is installed (optional) | |
| the priority of the routine on its hook (optional) |
rule
A command to specify a filtering rule
Usage: ffx net filter create rule --namespace <namespace> --routine <routine> --index <index> [--in-interface <in-interface>] [--out-interface <out-interface>] [--src-addr <src-addr>] [--dst-addr <dst-addr>] [--transport-protocol <transport-protocol>] [--src-port <src-port>] [--dst-port <dst-port>] [subcommand...]
| Options | |
|---|---|
| display usage information | |
| the namespace that contains the rule | |
| the routine that contains the rule | |
| the index of the rule | |
| a matcher for the ingress interface of the packet (optional) Accepted formats are any of "id: |
|
| a matcher for the egress interface of the packet (optional) Accepted formats are any of "id: |
|
| a matcher for the source address of the packet (optional) Accepted formats are any of "subnet: |
|
| a matcher for the destination address of the packet (optional) Accepted formats are any of "subnet: |
|
| a matcher for the transport protocol of the packet (optional) Accepted protocols are "tcp" | |
a matcher for the source port of the packet (optional) Must be accompanied by a transport protocol matcher for either TCP or UDP. Accepted format is "! for inverse match. |
|
a matcher for the destination port of the packet (optional) Must be accompanied by a transport protocol matcher for either TCP or UDP. Accepted format is "! for inverse match. |
| Subcommands | |
|---|---|
| accept | The fuchsia.net.filter/Action.Accept action. |
| drop | The fuchsia.net.filter/Action.Drop action. |
| jump | The fuchsia.net.filter/Action.Jump action. |
| masquerade | The fuchsia.net.filter/Action.Masquerade action. The source port range to use to rewrite the packet is optional, but --min-src-port and --max-src-port must either both be specified, or neither. |
| redirect | The fuchsia.net.filter/Action.Redirect action. The destination port range to which to redirect the packet is optional, but --min-dst-port and --max-dst-port must either both be specified, or neither. |
| return | The fuchsia.net.filter/Action.Return action. |
| tproxy | The fuchsia.net.filter/Action.TransparentProxy action. Both --addr and --port are optional, but at least one must be specified. |
accept
The fuchsia.net.filter/Action.Accept action.
Usage: ffx net filter create rule accept
| Options | |
|---|---|
| display usage information |
drop
The fuchsia.net.filter/Action.Drop action.
Usage: ffx net filter create rule drop
| Options | |
|---|---|
| display usage information |
jump
The fuchsia.net.filter/Action.Jump action.
Usage: ffx net filter create rule jump target
| Options | |
|---|---|
| display usage information |
masquerade
The fuchsia.net.filter/Action.Masquerade action. The source port range to use to rewrite the packet is optional, but --min-src-port and --max-src-port must either both be specified, or neither.
Usage: ffx net filter create rule masquerade [--src-port <src-port>]
| Options | |
|---|---|
| display usage information | |
| the source port range used to rewrite the packet (optional) |
redirect
The fuchsia.net.filter/Action.Redirect action. The destination port range to which to redirect the packet is optional, but --min-dst-port and --max-dst-port must either both be specified, or neither.
Usage: ffx net filter create rule redirect [--dst-port <dst-port>]
| Options | |
|---|---|
| display usage information | |
| the destination port range used to rewrite the packet (optional) |
return
The fuchsia.net.filter/Action.Return action.
Usage: ffx net filter create rule return
| Options | |
|---|---|
| display usage information |
tproxy
The fuchsia.net.filter/Action.TransparentProxy action. Both --addr and --port are optional, but at least one must be specified.
Usage: ffx net filter create rule tproxy [--addr <addr>] [--port <port>]
| Options | |
|---|---|
| display usage information | |
| the bound address of the local socket to redirect the packet to (optional) | |
| the bound port of the local socket to redirect the packet to (optional, must be nonzero) |
list
A command to list filtering configuration.
Usage: ffx net filter list
| Options | |
|---|---|
| display usage information |
remove
A command to remove existing filtering resources
Usage: ffx net filter remove --controller <controller> [--idempotent] [subcommand...]
| Options | |
|---|---|
| display usage information | |
| the name of the controller that owns the resource | |
| whether the resource removal should be idempotent, i.e. succeed even if the resource does not exist |
| Subcommands | |
|---|---|
| namespace | A command to identify a filtering namespace |
| routine | A command to identify a filtering routine |
| rule | A command to identify a filtering rule |
namespace
A command to identify a filtering namespace
Usage: ffx net filter remove namespace --name <name>
| Options | |
|---|---|
| display usage information | |
| the name of the namespace |
routine
A command to identify a filtering routine
Usage: ffx net filter remove routine --namespace <namespace> --name <name>
| Options | |
|---|---|
| display usage information | |
| the namespace that contains the routine | |
| the name of the routine |
rule
A command to identify a filtering rule
Usage: ffx net filter remove rule --namespace <namespace> --routine <routine> --index <index>
| Options | |
|---|---|
| display usage information | |
| the namespace that contains the rule | |
| the routine that contains the rule | |
| the index of the rule |
filter-deprecated
commands for configuring packet filtering with the deprecated API
Usage: ffx net filter-deprecated [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| 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
gets nat rules
Usage: ffx net filter-deprecated get-nat-rules
| Options | |
|---|---|
| display usage information |
get-rdr-rules
gets rdr rules
Usage: ffx net filter-deprecated get-rdr-rules
| Options | |
|---|---|
| display usage information |
get-rules
gets filter rules
Usage: ffx net filter-deprecated get-rules
| Options | |
|---|---|
| display usage information |
set-nat-rules
sets nat rules (see the netfilter::parser library for the NAT rules format)
Usage: ffx net filter-deprecated set-nat-rules rules
| Options | |
|---|---|
| display usage information |
set-rdr-rules
sets rdr rules (see the netfilter::parser library for the RDR rules format)
Usage: ffx net filter-deprecated set-rdr-rules rules
| Options | |
|---|---|
| display usage information |
set-rules
sets filter rules (see the netfilter::parser library for the rules format)
Usage: ffx net filter-deprecated set-rules rules
| Options | |
|---|---|
| display usage information |
if
commands for network interfaces
Usage: ffx net if [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| add | add interfaces |
| addr | commands for updating network interface addresses |
| bridge | creates a bridge between network interfaces |
| config | get or set interface configuration |
| disable | disables a network interface |
| enable | enables a network interface |
| get | queries a network interface |
| igmp | get or set IGMP configuration |
| ip-forward | get or set IP forwarding for an interface |
| list | lists network interfaces (supports ffx machine output) |
| mld | get or set MLD configuration |
| remove | remove interfaces |
add
add interfaces
Usage: ffx net if add [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| blackhole | add a blackhole interface |
blackhole
add a blackhole interface
Usage: ffx net if add blackhole name
| Options | |
|---|---|
| display usage information |
addr
commands for updating network interface addresses
Usage: ffx net if addr [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| add | adds an address to the network interface |
| del | deletes an address from the network interface |
| wait | waits for an address to be assigned on the network interface. by default waits for any address; if --ipv6 is specified, waits for an IPv6 address. |
add
adds an address to the network interface
Usage: ffx net if addr add [--no-subnet-route] nicid or name:ifname addr prefix
| Options | |
|---|---|
| display usage information | |
| skip adding a local subnet route for this interface and address |
del
deletes an address from the network interface
Usage: ffx net if addr del nicid or name:ifname addr [prefix]
| Options | |
|---|---|
| display usage information |
wait
waits for an address to be assigned on the network interface. by default waits for any address; if --ipv6 is specified, waits for an IPv6 address.
Usage: ffx net if addr wait [--ipv6] nicid or name:ifname
| Options | |
|---|---|
| display usage information | |
| wait for an IPv6 address |
bridge
creates a bridge between network interfaces
Usage: ffx net if bridge [nicid or name:ifname...]
| Options | |
|---|---|
| display usage information |
config
get or set interface configuration
Usage: ffx net if config [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| get | get interface configuration |
| set | set interface configuration |
get
get interface configuration
Usage: ffx net if config get
| Options | |
|---|---|
| display usage information |
set
set interface configuration
Configuration parameters and the values to be set to should be passed in pairs. The names of the configuration parameters are taken from the structure of fuchsia.net.interfaces.admin/Configuration.
The list of supported parameters are: ipv6.ndp.slaac.temporary_address_enabled bool Whether temporary addresses should be generated.
Usage: ffx net if config set [options...]
| Options | |
|---|---|
| display usage information |
disable
disables a network interface
Usage: ffx net if disable nicid or name:ifname
| Options | |
|---|---|
| display usage information |
enable
enables a network interface
Usage: ffx net if enable nicid or name:ifname
| Options | |
|---|---|
| display usage information |
get
queries a network interface
Usage: ffx net if get nicid or name:ifname
| Options | |
|---|---|
| display usage information |
igmp
get or set IGMP configuration
Usage: ffx net if igmp [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| get | get IGMP configuration for an interface |
| set | set IGMP configuration for an interface |
get
get IGMP configuration for an interface
Usage: ffx net if igmp get nicid or name:ifname
| Options | |
|---|---|
| display usage information |
set
set IGMP configuration for an interface
Usage: ffx net if igmp set [--version <version>] nicid or name:ifname
| Options | |
|---|---|
| display usage information | |
| the version of IGMP to perform. |
ip-forward
get or set IP forwarding for an interface
Usage: ffx net if ip-forward [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| get | get IP forwarding for an interface |
| set | set IP forwarding for an interface |
get
get IP forwarding for an interface
Usage: ffx net if ip-forward get nicid or name:ifname ip_version
| Options | |
|---|---|
| display usage information |
set
set IP forwarding for an interface
Usage: ffx net if ip-forward set nicid or name:ifname ip_version enable
| Options | |
|---|---|
| display usage information |
list
lists network interfaces (supports ffx machine output)
Usage: ffx net if list [name_pattern]
| Options | |
|---|---|
| display usage information |
mld
get or set MLD configuration
Usage: ffx net if mld [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| get | get MLD configuration for an interface |
| set | set MLD configuration for an interface |
get
get MLD configuration for an interface
Usage: ffx net if mld get nicid or name:ifname
| Options | |
|---|---|
| display usage information |
set
set MLD configuration for an interface
Usage: ffx net if mld set [--version <version>] nicid or name:ifname
| Options | |
|---|---|
| display usage information | |
| the version of MLD to perform. |
remove
remove interfaces
Usage: ffx net if remove nicid or name:ifname
| Options | |
|---|---|
| display usage information |
log
commands for logging
Usage: ffx net log [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| set-packets | log packets to stdout |
set-packets
log packets to stdout
Usage: ffx net log set-packets enabled
| Options | |
|---|---|
| display usage information |
migration
controls netstack selection for migration from netstack2 to netstack3
Usage: ffx net migration [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| clear | clears netstack version for migration configuration. |
| get | prints the currently configured netstack version for migration. |
| set | sets the netstack version at next boot to |
clear
clears netstack version for migration configuration.
Usage: ffx net migration clear
| Options | |
|---|---|
| display usage information |
get
prints the currently configured netstack version for migration.
Usage: ffx net migration get
| Options | |
|---|---|
| display usage information |
set
sets the netstack version at next boot to |ns2| or |ns3|.
Usage: ffx net migration set version
| Options | |
|---|---|
| display usage information |
neigh
commands for neighbor tables
Usage: ffx net neigh [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| add | adds an entry to the neighbor table |
| clear | removes all entries associated with a network interface from the neighbor table |
| config | commands for the Neighbor Unreachability Detection configuration |
| del | removes an entry from the neighbor table |
| list | lists neighbor table entries (supports ffx machine output) |
| watch | watches neighbor table entries for state changes (supports ffx machine output) |
add
adds an entry to the neighbor table
Usage: ffx net neigh add nicid or name:ifname ip mac
| Options | |
|---|---|
| display usage information |
clear
removes all entries associated with a network interface from the neighbor table
Usage: ffx net neigh clear nicid or name:ifname ip_version
| Options | |
|---|---|
| display usage information |
config
commands for the Neighbor Unreachability Detection configuration
Usage: ffx net neigh config [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| get | returns the current NUD configuration options for the provided interface |
| update | updates the current NUD configuration options for the provided interface |
get
returns the current NUD configuration options for the provided interface
Usage: ffx net neigh config get nicid or name:ifname ip_version
| Options | |
|---|---|
| display usage information |
update
updates the current NUD configuration options for the provided interface
Usage: ffx net neigh config update [--base-reachable-time <base-reachable-time>] nicid or name:ifname ip_version
| Options | |
|---|---|
| display usage information | |
| a base duration, in nanoseconds, for computing the random reachable time |
del
removes an entry from the neighbor table
Usage: ffx net neigh del nicid or name:ifname ip
| Options | |
|---|---|
| display usage information |
list
lists neighbor table entries (supports ffx machine output)
Usage: ffx net neigh list
| Options | |
|---|---|
| display usage information |
watch
watches neighbor table entries for state changes (supports ffx machine output)
Usage: ffx net neigh watch
| Options | |
|---|---|
| display usage information |
route
commands for routing tables
Usage: ffx net route [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| add | adds a route to the route table |
| del | deletes a route from the route table |
| list | lists routes (supports ffx machine output) |
add
adds a route to the route table
Usage: ffx net route add --destination <destination> --netmask <netmask or prefix length> [--gateway <gateway>] [--nicid <nicid or name:ifname>] [--metric <metric>]
| Options | |
|---|---|
| display usage information | |
| the network id of the destination network | |
| the netmask or prefix length corresponding to destination | |
| the ip address of the first hop router | |
| the outgoing network interface of the route | |
| the metric for the route |
del
deletes a route from the route table
Usage: ffx net route del --destination <destination> --netmask <netmask or prefix length> [--gateway <gateway>] [--nicid <nicid or name:ifname>] [--metric <metric>]
| Options | |
|---|---|
| display usage information | |
| the network id of the destination network | |
| the netmask or prefix length corresponding to destination | |
| the ip address of the first hop router | |
| the outgoing network interface of the route | |
| the metric for the route |
list
lists routes (supports ffx machine output)
Usage: ffx net route list
| Options | |
|---|---|
| display usage information |
rule
commands for policy-based-routing rules
Usage: ffx net rule [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| list | lists rules (supports ffx machine output) |
list
lists rules (supports ffx machine output)
Usage: ffx net rule list
| Options | |
|---|---|
| display usage information |
package
Create and publish Fuchsia packages
Usage: ffx package [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| archive | Archive Fuchsia packages |
| blob | Work with Fuchsia blob files. |
| build | Builds a package. |
| far | Work with Fuchsia Archive Format (FAR) files |
| file-hash | Compute the merkle tree root hash of one or more files. |
archive
Archive Fuchsia packages
Usage: ffx package archive [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| add | add a file ( |
| cat | write the contents of |
| create | create a package archive from a package_manifest.json |
| edit | edit the metadata of an existing package archive ( |
| extract | extract the contents of |
| list | List the contents of Fuchia package archive file |
| remove | remove a file ( |
add
add a file (
Usage: ffx package archive add -a <archive> -f <file-to-add> -p <path-of-file-in-archive> -o <output> [-w <overwrite>]
| Options | |
|---|---|
| display usage information | |
| package archive | |
| file to add to the package archive | |
| the destination path in the archive for |
|
| the name of the resulting archive. Can be the same as |
|
| if false, refuses to overwrite files in |
cat
write the contents of
Usage: ffx package archive cat archive far_path
| Options | |
|---|---|
| display usage information |
create
create a package archive from a package_manifest.json
Usage: ffx package archive create -o <out> [-r <root-dir>] [--depfile <depfile>] package_manifest
| Options | |
|---|---|
| display usage information | |
| output package archive | |
| root directory for paths in package_manifest.json | |
| produce a depfile file at the provided path |
edit
edit the metadata of an existing package archive (
Usage: ffx package archive edit -a <archive> [--package-name <package-name>] [--unsafe-override-abi-revision <unsafe-override-abi-revision>] -o <output>
| Options | |
|---|---|
| display usage information | |
| package archive | |
| if specified, change the name of the package (i.e., what appears in meta/package) to |
|
| if specified, replace the ABI revision in the package. Do not do this unless you're certain you know what you're doing! | |
| the name of the resulting archive. Can be the same as |
extract
extract the contents of
Usage: ffx package archive extract [-o <out>] [--repository <repository>] [--blobs-json] [--namespace] archive
| Options | |
|---|---|
| display usage information | |
| output directory for writing the extracted files. Defaults to the current directory. | |
| repository of the package | |
| produce a blobs.json file | |
| extract the package namespace into /pkg |
list
List the contents of Fuchia package archive file
Usage: ffx package archive list [-l] archive
| Options | |
|---|---|
| display usage information | |
| show long information for each entry |
remove
remove a file (
Usage: ffx package archive remove -a <archive> -f <file-to-remove> -o <output>
| Options | |
|---|---|
| display usage information | |
| package archive | |
| file to add to the package archive | |
| the name of the resulting archive. Can be the same as |
blob
Work with Fuchsia blob files.
Usage: ffx package blob [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| compress | Compress one or more blobs |
| decompress | Decompress one or more blobs |
| hash | Compute the merkle tree root hash of one or more delivery blobs or uncompressed blobs. |
compress
Compress one or more blobs
Usage: ffx package blob compress [-t <type>] -o <output> [--hash-as-name] [paths...]
| Options | |
|---|---|
| display usage information | |
| delivery blob type | |
| output compressed blobs into this directory | |
| use the merkle root of each file as its output name |
decompress
Decompress one or more blobs
Usage: ffx package blob decompress -o <output> [paths...]
| Options | |
|---|---|
| display usage information | |
| output decompressed blobs into this directory |
hash
Compute the merkle tree root hash of one or more delivery blobs or uncompressed blobs.
Usage: ffx package blob hash [-u] [paths...]
| Options | |
|---|---|
| display usage information | |
| blobs are uncompressed instead of delivery blobs |
build
Builds a package.
Usage: ffx package build [-o <out>] --api-level <api-level> [--published-name <published-name>] [--repository <repository>] [--depfile] [--blobs-json] [--blobs-manifest] [--subpackages-build-manifest-path <subpackages-build-manifest-path>] package_build_manifest_path
| Options | |
|---|---|
| display usage information | |
| directory to save package artifacts | |
| package API level | |
| name of the package | |
| repository of the package | |
| produce a depfile file | |
| produce a blobs.json file | |
| produce a blobs.manifest file | |
| path to the subpackages build manifest file |
far
Work with Fuchsia Archive Format (FAR) files
Usage: ffx package far [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| cat | Dump the contents of the |
| create | Create a FAR file from a directory. WARNING: this will overwrite |
| extract | Extract |
| list | List the entry paths contained in a FAR file |
cat
Dump the contents of the
Usage: ffx package far cat far_file path
| Options | |
|---|---|
| display usage information |
create
Create a FAR file from a directory. WARNING: this will overwrite
Usage: ffx package far create input_directory output_file
| Options | |
|---|---|
| display usage information |
extract
Extract
Usage: ffx package far extract [-v] [-o <output-dir>] far_file [paths...]
| Options | |
|---|---|
| display usage information | |
| verbose output: print file names that were extracted | |
| output directory (defaults to current directory, creates the directory if it doesn't exist) |
list
List the entry paths contained in a FAR file
Usage: ffx package far list [-l] far_file
| Options | |
|---|---|
| display usage information | |
| show detailed information for each entry (does nothing if --machine json is specified, which shows everything) |
file-hash
Compute the merkle tree root hash of one or more files.
Usage: ffx package file-hash [paths...]
| Options | |
|---|---|
| display usage information |
platform
Manage platform build prerequisites
Usage: ffx platform [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| preflight | Evaluate suitability for building and running Fuchsia |
preflight
Evaluate suitability for building and running Fuchsia
Usage: ffx platform preflight [--json]
| Options | |
|---|---|
| display usage information | |
| outputs json instead of human-readable text. |
power
Control system power features
Usage: ffx power [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| collaborative-reboot | Interact with collaborative reboot |
| debugcmd | Send a debug command to the Power Manager |
| system-activity | Manipulate SAG power elements |
collaborative-reboot
Interact with collaborative reboot
Usage: ffx power collaborative-reboot [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| perform-pending-reboot | Perform a pending Collaborative Reboot, if any. |
perform-pending-reboot
Perform a pending Collaborative Reboot, if any.
Usage: ffx power collaborative-reboot perform-pending-reboot
| Options | |
|---|---|
| display usage information |
debugcmd
Send a debug command to the Power Manager
Usage: ffx power debugcmd --node-name <node-name> --command <command> [--args <args...>]
| Options | |
|---|---|
| display usage information | |
| name of target node | |
| debug command to send | |
| arguments for the debug command |
system-activity
Manipulate SAG power elements
Usage: ffx power system-activity [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| application-activity | Takes and drops leases on activity governor elements. |
application-activity
Takes and drops leases on activity governor elements.
Usage: ffx power system-activity application-activity [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| restart | Stop application activity on the target and start it again. |
| start | Start application activity on the target |
| stop | Stop application activity on the target |
Examples
To change application_activity power level to 1:
$ ffx power system-activity application-activity start
To change application_activity power level to 0:
$ ffx power system-activity application-activity stopNotes
If the system-activity-governor-controller component is not available to the target, then this command will not work properly.
restart
Stop application activity on the target and start it again.
Usage: ffx power system-activity application-activity restart [--wait-time <wait-time>]
| Options | |
|---|---|
| display usage information | |
| the time the system waits before starting application activity again (in nanoseconds). The system is not guaranteed to start again after this time, but on the next wakeup this command will take a lease on application activity. Defaults to 100ms. |
start
Start application activity on the target
Usage: ffx power system-activity application-activity start
| Options | |
|---|---|
| display usage information |
stop
Stop application activity on the target
Usage: ffx power system-activity application-activity stop
| Options | |
|---|---|
| display usage information |
process
Processes related commands
Usage: ffx process [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| 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 |
| kill | Attempts to kill a process by it's KOID or process name. |
| list | outputs a list containing the name and koid of all processes |
| stack_trace | Attempts to get a strack trace a process by it's KOID or process name. |
| tree | outputs the tree of all tasks in the system |
filter
outputs information about the processes that correspond to the koids input
Usage: ffx process filter [process_koids...]
| Options | |
|---|---|
| display usage information |
generate-fuchsia-map
outputs the json required to generate a map of all processes and channels
Usage: ffx process generate-fuchsia-map
| Options | |
|---|---|
| display usage information |
kill
Attempts to kill a process by it's KOID or process name.
Usage: ffx process kill task_to_kill
| Options | |
|---|---|
| display usage information |
list
outputs a list containing the name and koid of all processes
Usage: ffx process list [--verbose]
| Options | |
|---|---|
| display usage information | |
| outputs all processes and the kernel objects owned by each of them |
stack_trace
Attempts to get a strack trace a process by it's KOID or process name.
Usage: ffx process stack_trace task
| Options | |
|---|---|
| display usage information |
tree
outputs the tree of all tasks in the system
Usage: ffx process tree [--threads]
| Options | |
|---|---|
| display usage information | |
| include threads |
product
Discover and access product bundle metadata and image data.
Usage: ffx product [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| create | Construct a product bundle using a platform, product, and board. |
| create-old | Create a Product Bundle using the outputs of Product Assembly. |
| download | Download Product Bundle from GCS. |
| get-artifacts | Get the paths of a group of artifacts inside a Product Bundle. |
| get-image-path | Get the path of an image inside a Product Bundle based on type and slot. |
| get-repository | Get the info of repository inside a Product Bundle. |
| get-version | Get the product version of a Product Bundle. |
| list | List all available products for a specific SDK version. |
| lookup | Retrieve image data. |
| show | Display a list of details from within a product bundle. |
create
Construct a product bundle using a platform, product, and board. The inputs can be local paths or CIPD references.
Artifact formats: path/to/artifacts: Use local artifact with specified path cipd://path/to/artifact@1.2.3.4: Use artifact from CIPD with specified url
Additional formats for the platform:
Usage: ffx product create [--platform <platform>] [--product <product>] [--board <board>] [--stage] [--out <out>] [product_board_combo]
| Options | |
|---|---|
| display usage information | |
| the platform artifacts to use. | |
| the product config to use. | |
| the board config to use. | |
| prepare the assembly inputs, but do not run assembly yet. | |
| the location to write the product bundle to. |
create-old
Create a Product Bundle using the outputs of Product Assembly.
Usage: ffx product create-old --product-name <product-name> --product-version <product-version> [--partitions <partitions>] [--system-a <system-a>] [--system-b <system-b>] [--system-r <system-r>] [--tuf-keys <tuf-keys>] [--update-package-version-file <update-package-version-file>] [--update-package-epoch <update-package-epoch>] [--virtual-device <virtual-device...>] [--recommended-device <recommended-device>] --out-dir <out-dir> [--delivery-blob-type <delivery-blob-type>] [--with-deprecated-flash-manifest] [--gerrit-size-report <gerrit-size-report>]
| Options | |
|---|---|
| display usage information | |
| product.board label. e.g. "workstation_eng.x64". | |
| unique version of this product.board. | |
| path to a partitions config, which lists the physical partitions of the target. | |
| path to an assembly manifest, which specifies images to put in slot A. | |
| path to an assembly manifest, which specifies images to put in slot B. | |
| path to an assembly manifest, which specifies images to put in slot R. | |
| path to the directory of TUF keys, which should include root.json, snapshot.json, targets.json, and timestamp.json. If provided, then a TUF repository will be created inside the product bundle and filled with the product blobs. | |
| file containing the version of the Product to put in the update package. | |
| backstop OTA version. Fuchsia will reject updates with a lower epoch. | |
| path to a Virtual Device Specification file to include in the product bundle. May be repeated to include multiple Virtual Devices. | |
| name of a Virtual Device Specification file to mark as the "recommended" device for emulation. | |
| directory to write the product bundle. | |
| the type of delivery blob the product needs. | |
| create a deprecated flash manifest for backward compatibility. | |
| an optional image size report to generate that indicates the sizes of the images when mapped to partitions. |
download
Download Product Bundle from GCS.
Usage: ffx product download [--force] [--auth <auth>] [--base-url <base-url>] [--version <version>] [--branch <branch>] manifest_url product_dir
| Options | |
|---|---|
| display usage information | |
| get the data again, even if it's already present locally. | |
| use specific auth flow for oauth2 (see examples; default: pkce). | |
| location to look for product bundles manifest inside GCS. | |
filter on products of a.b.c.d. e.g. 19.20240302.2.1. If this value is not passed in, the version will be defaulted to version of ffx tool itself. |
|
filter on products of LATEST. This option is exclusive with version option. |
Examples
Sample invocations:
// Download core.vim3 based on current ffx version. Note it will download
// the latest version of the date section.
ffx product download core.vim3 ~/local_pb
// Download core.vim3 with version 19.20240302.2.1
ffx product download core.vim3 ~/local_pb --version 19.20240302.2.1
// Download core.vim3 for latest version of f18
ffx product download core.vim3 ~/local_pb --branch f18 --force
Auth flow choices for --auth include:
`--auth no-auth` do not use auth.
`--auth pkce` to use PKCE auth flow (requires GUI browser).
`--auth device-experimental` to use device flow.
`--auth ` run tool at given path which will print an access
token to stdout and exit 0.
`--auth default` let the tool decide which auth flow to use.
get-artifacts
Get the paths of a group of artifacts inside a Product Bundle.
Usage: ffx product get-artifacts -g <artifacts-group> [-r] [product_bundle]
| Options | |
|---|---|
| display usage information | |
| select what group of artifacts to list. One of flash, emu, update, bootloader | |
| return relative path or not |
get-image-path
Get the path of an image inside a Product Bundle based on type and slot.
Usage: ffx product get-image-path [--slot <slot>] [--image-type <image-type>] [-b <bootloader>] [-r] [product_bundle]
| Options | |
|---|---|
| display usage information | |
| the slot where image will be located in. Valid slots are A,B,R. | |
| the type of image. Supported types are zbi, vbmeta, fvm, fxfs, fxfs.fastboot, qemu-kernel, or dtbo. | |
| the type of bootloader. | |
| return relative path or not |
get-repository
Get the info of repository inside a Product Bundle.
Usage: ffx product get-repository product_bundle
| Options | |
|---|---|
| display usage information |
get-version
Get the product version of a Product Bundle.
Usage: ffx product get-version product_bundle
| Options | |
|---|---|
| display usage information |
list
List all available products for a specific SDK version.
Usage: ffx product list [--auth <auth>] [--base-url <base-url>] [--version <version>] [--branch <branch>]
| Options | |
|---|---|
| display usage information | |
| use specific auth flow for oauth2 (see examples; default: pkce). | |
| location to look for product bundles manifest inside GCS. | |
filter on products of a.b.c.d. e.g. 19.20240302.2.1. If this value is not passed in, the version will be defaulted to version of ffx tool itself. |
|
filter on products of LATEST. This option is exclusive with version option. |
Examples
Sample invocations:
// List all product names based on current ffx version. Note it will list
// the latest version of the date section.
ffx product list
// List all product names with version 19.20240302.2.1
ffx product list --version 19.20240302.2.1
// List all product names for latest version of f18
ffx product list --branch f18
Auth flow choices for --auth include:
`--auth no-auth` do not use auth.
`--auth pkce` to use PKCE auth flow (requires GUI browser).
`--auth device-experimental` to use device flow.
`--auth ` run tool at given path which will print an access
token to stdout and exit 0.
`--auth default` let the tool decide which auth flow to use.
lookup
Retrieve image data.
Usage: ffx product lookup [--auth <auth>] [--base-url <base-url>] name version
| Options | |
|---|---|
| display usage information | |
| use specific auth flow for oauth2 (see examples; default: pkce). | |
| where to look for product bundles manifest. |
Examples
Auth flow choices for --auth include: `--auth oob` to use Out-of-Band auth (deprecated). `--auth pkce` to use PKCE auth flow (requires GUI browser). `--auth` run tool at given path which will print an access token to stdout and exit 0.
show
Display a list of details from within a product bundle.
Usage: ffx product show [--devices] [--device <device>] product_bundle_path
| Options | |
|---|---|
| display usage information | |
| list the virtual devices linked to this product bundle. | |
| print the details of a virtual device linked to this product bundle. |
profile
Profile run-time information from various subsystems
Usage: ffx profile [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| cpu | Query CPU-related information |
| gpu | Access GPU usage information |
| heapdump | Profile and dump heap memory usage |
| memory | Query memory related information |
| network | Access network activity information |
| power | Access power-related information |
| temperature | Access temperature-related information |
cpu
Query CPU-related information
Usage: ffx profile cpu [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| load | Collect and print CPU usage data for the specified time frame, or instruct the metrics-logger component to record the CPU usage data to Inspect, Trace, and/or syslog. |
load
Collect and print CPU usage data for the specified time frame, or instruct the metrics-logger component to record the CPU usage data to Inspect, Trace, and/or syslog.
Usage: ffx profile cpu load [-d <duration>] [subcommand...]
| Options | |
|---|---|
| display usage information | |
| duration over which to measure and print the CPU load |
| Subcommands | |
|---|---|
| start | Start logging on the target |
| stop | Stop logging on the target |
Examples
1) To measure the CPU load over a two second duration:
$ ffx profile cpu load --duration 2s
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]]%.
2) To log CPU load every 500 ms indefinitely:
$ ffx profile cpu load start --interval 500ms
Logged samples will be available via iquery under core/metrics-logger and via tracing in the `metrics_logger` category.
3) To log CPU load every 1 second for 30 seconds with output-to-syslog enabled:
$ ffx profile cpu load start --interval 1s -d 30s --output-to-syslog
Logged samples will be available in syslog, via iquery under core/metrics-logger and via tracing in the `metrics_logger` category.
Notes
Please specify a duration for immediate load display, or alternatively, utilize the start/stop subcommand to instruct the metrics-logger component to record the CPU usage data to Inspect, Trace,and/or syslog. If the metrics-logger component is not available to the target, add
--with //src/power/metrics-loggerto fx set.
start
Start logging on the target
Usage: ffx profile cpu load start -s <interval> [--output-to-syslog] [-d <duration>]
| Options | |
|---|---|
| display usage information | |
| interval for logging the CPU load | |
| toggle for logging CPU loads to syslog | |
| duration for which to log; if omitted, logging will continue indefinitely |
stop
Stop logging on the target
Usage: ffx profile cpu load stop
| Options | |
|---|---|
| display usage information |
gpu
Access GPU usage information
Usage: ffx profile gpu [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| 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 metrics_logger category. |
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 metrics_logger category.
Usage: ffx profile gpu usage [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| 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-syslogNotes
If the metrics-logger component is not available to the target, then this command will not work properly. Add --with //src/power/metrics-logger to fx set.
start
Start logging on the target
Usage: ffx profile gpu usage start -s <interval> [--output-to-syslog] [-d <duration>]
| Options | |
|---|---|
| display usage information | |
| interval for polling the GPU driver | |
| toggle for logging samples to syslog | |
| duration for which to log; if omitted, logging will continue indefinitely |
stop
Stop logging on the target
Usage: ffx profile gpu usage stop
| Options | |
|---|---|
| display usage information |
heapdump
Profile and dump heap memory usage
Usage: ffx profile heapdump [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| download | Download stored snapshot |
| list | List stored snapshots |
| snapshot | Snapshot current heap memory usage |
download
Download stored snapshot
Usage: ffx profile heapdump download [--collector <collector>] --snapshot-id <snapshot-id> [--with-tags] --output-file <output-file> [--symbolize]
| Options | |
|---|---|
| display usage information | |
| moniker of the collector to be queried (default: autodetect) | |
| snapshot ID to be downloaded | |
| write per-block metadata (as tags) in the protobuf file | |
| output protobuf file | |
| symbolize the generated profile |
list
List stored snapshots
Usage: ffx profile heapdump list [--collector <collector>] [--by-name <by-name>] [--by-koid <by-koid>]
| Options | |
|---|---|
| display usage information | |
| moniker of the collector to be queried (default: autodetect) | |
| select process by name | |
| select process by koid |
snapshot
Snapshot current heap memory usage
Usage: ffx profile heapdump snapshot [--collector <collector>] [--by-name <by-name>] [--by-koid <by-koid>] --output-file <output-file> [--with-tags] [--output-contents-dir <output-contents-dir>] [--symbolize]
| Options | |
|---|---|
| display usage information | |
| moniker of the collector to be queried (default: autodetect) | |
| select process by name | |
| select process by koid | |
| output protobuf file | |
| write per-block metadata (as tags) in the protobuf file | |
| optional directory to dump each blocks' contents into | |
| symbolize the generated profile |
memory
Query memory related information
Usage: ffx profile memory [--debug-json] [--process-koids <process-koids...>] [--process-names <process-names...>] [--interval <interval>] [--buckets] [--undigested] [--csv] [--exact-sizes] [--stdin-input] [--backend <backend>] [subcommand...]
| Options | |
|---|---|
| display usage information | |
| outputs the json returned by memory_monitor. For debug purposes only, no garantee is made on the stability of the output of this command. | |
| filters by process koids. Repeatable flag. | |
| filters by process names (exact match). Repeatable flag. | |
| repeats the command at the given interval (in seconds) until terminated. | |
| prints a bucketized digest of the memory usage. | |
| displays the detailed view of only the undigested memory (memory not part of any bucket) instead of the full memory. | |
| outputs csv that for every process shows the device uptime in 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. | |
| outputs the exact byte sizes, as opposed to a human-friendly format. Does not impact machine oriented outputs, such as CSV and JSON outputs. | |
| loads the unprocessed memory information as json from stdin. | |
| selects where to read the memory information from. 'default', 'memory_monitor_1', or 'memory_monitor_2' are supported. |
| Subcommands | |
|---|---|
| components | Components. |
| 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. |
components
Components.
Usage: ffx profile memory components [--stdin-input] [--debug-json] [--csv] [--buckets]
| Options | |
|---|---|
| display usage information | |
| loads the unprocessed memory information as json from stdin. | |
| outputs the unprocessed memory information from the device as json. | |
| outputs data in csv format. | |
| prints a bucketized digest of the memory usage. |
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.
Usage: ffx profile memory signal level
| Options | |
|---|---|
| display usage information |
network
Access network activity information
Usage: ffx profile network [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| activity | Controls the metrics-logger component to log network activity. Logged samples will be available in syslog, via iquery under core/metrics-logger and via tracing in the metrics_logger category. |
activity
Controls the metrics-logger component to log network activity. Logged samples will be available in syslog, via iquery under core/metrics-logger and via tracing in the metrics_logger category.
Usage: ffx profile network activity [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| start | Start logging on the target |
| stop | Stop logging on the target |
Examples
To poll network activity every 500 ms indefinitely:
$ ffx profile network activity start --interval 500ms
To poll network activity every 1 second for 30 seconds with output-to-syslog enabled:
$ ffx profile network activity start --interval 1s -d 30s --output-to-syslogNotes
If the metrics-logger component is not available to the target, then this command will not work properly. Add --with //src/power/metrics-logger to fx set.
start
Start logging on the target
Usage: ffx profile network activity start -s <interval> [--output-to-syslog] [-d <duration>]
| Options | |
|---|---|
| display usage information | |
| interval for polling the network activity | |
| toggle for logging samples to syslog | |
| duration for which to log; if omitted, logging will continue indefinitely |
stop
Stop logging on the target
Usage: ffx profile network activity stop
| Options | |
|---|---|
| display usage information |
power
Access power-related information
Usage: ffx profile power [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| 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 metrics_logger category. |
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 metrics_logger category.
Usage: ffx profile power logger [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| 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 30sNotes
If the metrics-logger component is not available to the target, then this command will not work properly. Add --with //src/power/metrics-logger to fx set.
start
Start logging on the target
Usage: ffx profile power logger start [-l <statistics-interval>] -s <sampling-interval> [--output-samples-to-syslog] [--output-stats-to-syslog] [-d <duration>]
| Options | |
|---|---|
| display usage information | |
| interval for summarizing statistics; if omitted, statistics is disabled | |
| interval for polling the sensor | |
| toggle for logging samples to syslog | |
| toggle for logging statistics to syslog | |
| duration for which to log; if omitted, logging will continue indefinitely |
stop
Stop logging on the target
Usage: ffx profile power logger stop
| Options | |
|---|---|
| display usage information |
temperature
Access temperature-related information
Usage: ffx profile temperature [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| logger | Controls the metrics-logger component to log temperature. Logged temperature samples will be available in syslog, via iquery under core/metrics-logger and via tracing in the metrics_logger category. |
logger
Controls the metrics-logger component to log temperature. Logged temperature samples will be available in syslog, via iquery under core/metrics-logger and via tracing in the metrics_logger category.
Usage: ffx profile temperature logger [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| start | Start logging on the target |
| stop | Stop logging on the target |
Examples
To poll temperature sensor every 500 ms indefinitely:
$ ffx profile temperature logger start --sampling-interval 500ms
To poll temperature 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 temperature logger start --sampling-interval 500ms --statistics-interval 1s --output-stats-to-syslog --output-samples-to-syslog -d 30sNotes
If the metrics-logger component is not available to the target, then this command will not work properly. Add --with //src/power/metrics-logger to fx set.
start
Start logging on the target
Usage: ffx profile temperature logger start [-l <statistics-interval>] -s <sampling-interval> [--output-samples-to-syslog] [--output-stats-to-syslog] [-d <duration>]
| Options | |
|---|---|
| display usage information | |
| interval for summarizing statistics; if omitted, statistics is disabled | |
| interval for polling the sensor | |
| toggle for logging samples to syslog | |
| toggle for logging statistics to syslog | |
| duration for which to log; if omitted, logging will continue indefinitely |
stop
Stop logging on the target
Usage: ffx profile temperature logger stop
| Options | |
|---|---|
| display usage information |
profiler
Interact with the profiling subsystem.
Usage: ffx profiler [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| attach | Profile a running task or component |
| launch | Record a profile. |
| symbolize | Symbolize a previously-recorded profile that was not symbolized. |
attach
Profile a running task or component
Usage: ffx profiler attach [--url <url>] [--buffer-size-mb <buffer-size-mb>] [--moniker <moniker>] [--pids <pids...>] [--tids <tids...>] [--job-ids <job-ids...>] [--system-wide] [--duration <duration>] [--output <output>] [--print-stats] [--symbolize <symbolize>] [--pprof-conversion <pprof-conversion>] [--sample-period-us <sample-period-us>] [--color-output <color-output>]
| Options | |
|---|---|
| display usage information | |
| url of a component to profile. If there is no matching component, wait for one to appear. | |
| buffer size in MiB to profile. Specifies the amount of memory allocated for storing profiling information. | |
| moniker of a component to profile. If there is no matching component, the profiler will | |
| pids to profile | |
| tids to profile | |
| jobs to profile | |
| profile everything running on the system. Equivalent to profiling the root job and everything running under it. | |
| how long to profiler for. If unspecified, will interactively wait until |
|
| name of output trace file. Defaults to profile.pb. | |
| print stats about how the profiling session went | |
| if false, output the raw sample file instead of attempting to symbolize it | |
| if false, output the raw symbolized sample file instead of attempting to convert to the pprof format. Ignored if --symbolize is false. | |
| how frequently to take a sample | |
| if true, include color codes in output. Defaults to true if terminal output is detected, else false |
launch
Record a profile.
Usage: ffx profiler launch --url <url> [--buffer-size-mb <buffer-size-mb>] [--moniker <moniker>] [--duration <duration>] [--output <output>] [--print-stats] [--symbolize <symbolize>] [--pprof-conversion <pprof-conversion>] [--sample-period-us <sample-period-us>] [--test] [--test-filters <test-filters...>] [--color-output <color-output>]
| Options | |
|---|---|
| display usage information | |
| url of a component to launch and profile | |
| buffer size in MiB to profile. Specifies the amount of memory allocated for storing profiling information. | |
moniker of a component to attach to and profile. If specified in combination with --url, will attempt to launch the component at the given moniker. |
|
| how long in seconds to profile for. If unspecified, will interactively wait until |
|
| name of output trace file. Defaults to profile.pb. | |
| print stats about how the profiling session went | |
| if false, output the raw sample file instead of attempting to symbolize it | |
| if false, output the raw symbolized sample file instead of attempting to convert to the pprof format. Ignored if --symbolize is false. | |
| how frequently to take a sample. This is the time interval between samples, in microseconds. The default is 10,000 microseconds (10 ms). | |
| the package being launched is a test to be launched via test_manager | |
| test case filters to apply to profiled tests | |
| if true, include color codes in output. Defaults to true if terminal output is detected, else false |
symbolize
Symbolize a previously-recorded profile that was not symbolized.
Usage: ffx profiler symbolize [--pprof-conversion <pprof-conversion>] input output
| Options | |
|---|---|
| display usage information | |
| if false, output the raw symbolized sample file instead of attempting to convert to the pprof format. |
repository
Inspect and manage package repositories
Usage: ffx repository [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| create | Create a repository. |
| default | Manage the default repository |
| package | List the packages inside a repository |
| publish | Publish packages. |
| server | Inspect and manage the repository server |
create
Create a repository.
Usage: ffx repository create [--time-versioning] [--keys <keys>] repo_path
| Options | |
|---|---|
| display usage information | |
| set repository version based on the current time rather than monotonically increasing version | |
| path to the repository keys directory. Default to generate keys at 'repo_path'/keys. |
default
Manage the default repository
Usage: ffx repository default [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| 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 --repository ...
Or use the `--config` option:
$ ffx --config repository.default= repository 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 therepository.defaultconfiguration key.
get
Get the default configured repository
Usage: ffx repository default get
| Options | |
|---|---|
| display usage information |
Notes
Returns the default configured repository from the 'User Configuration'. Returns an empty string if no default is configured.
set
Set the default repository
Usage: ffx repository default set [-l <level>] [-b <build-dir>] name
| Options | |
|---|---|
| display usage information | |
| config level, such as 'user', 'build', or 'global' | |
| optional directory to associate the provided build config |
Examples
To set the default repository: $ ffx repository default setTo set the 'repository.default` key at the global configuration: $ ffx repository default set -l global To specify a default repository for a specific build directory: $ ffx repository default set -l build -b ~/fuchsia/out
Notes
Sets the
repository.defaultconfiguration key. By default sets the key in the 'User Configuration'. Can be used in conjuction withffx repository listto 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
Clears the default configured repository
Usage: ffx repository default unset [-l <level>] [-b <build-dir>]
| Options | |
|---|---|
| display usage information | |
| config level, such as 'user', 'build', or 'global' | |
| optional directory to associate the provided build config |
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/outNotes
Clears the
repository.defaultconfiguration key. By default clears the 'User Configuration'. Returns a warning if the key is already empty.
package
List the packages inside a repository
Usage: ffx repository package [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| extract-archive | Extract a package archive from the repository |
| list | Inspect and manage package repositories |
| show | Inspect content of a package |
extract-archive
Extract a package archive from the repository
Usage: ffx repository package extract-archive -o <out> [-r <repository>] [-p <port>] [--repo-path <repo-path>] package
| Options | |
|---|---|
| display usage information | |
| output path for the extracted archive. | |
| extract package from this repository. | |
| repository server port number. Required disambiguate multiple repositories with the same name. | |
| list packages stored in the repository stored on disk. |
list
Inspect and manage package repositories
Usage: ffx repository package list [-r <repository>] [-p <port>] [--repo-path <repo-path>] [--full-hash] [--include-components <include-components>] [--include-size <include-size>]
| Options | |
|---|---|
| display usage information | |
| list packages from a running repository with this name. | |
| repository server port number. Required needed to disambiguate multiple repositories with the same name. | |
| list packages stored in the repository stored on disk. | |
| if true, package hashes will be displayed in full (i.e. not truncated). | |
| toggle whether components in each package will be fetched and shown in the output table | |
| toggle whether the sum of the uncompressed size of all blobs in each package will be calculated and shown in the output table |
show
Inspect content of a package
Usage: ffx repository package show [-r <repository>] [-p <port>] [--repo-path <repo-path>] [--full-hash] [--include-subpackages <include-subpackages>] package
| Options | |
|---|---|
| display usage information | |
| list package contents from this repository. | |
| repository server port number. Required to disambiguate multiple repositories with the same name. | |
| list packages stored in the repository stored on disk. | |
| if true, package hashes will be displayed in full (i.e. not truncated). | |
| if true, show contents of subpackages contained in the package. |
publish
Publish packages.
Usage: ffx repository publish [--signing-keys <signing-keys>] [--trusted-keys <trusted-keys>] [--trusted-root <trusted-root>] [--package <package...>] [--package-list <package-list...>] [--package-archive <package-archive...>] [--product-bundle <product-bundle...>] [--time-versioning] [--metadata-current-time <metadata-current-time>] [--refresh-root] [--clean] [--depfile <depfile>] [--copy-mode <copy-mode>] [--delivery-blob-type <delivery-blob-type>] [--watch] [--ignore-missing-packages] [--blob-manifest <blob-manifest>] [--blob-repo-dir <blob-repo-dir>] repo_path
| Options | |
|---|---|
| display usage information | |
| path to the keys used to sign metadata, but not trust for key rotation | |
path to the keys used to sign and trust metadata (default repository keys/ directory) |
|
| path to the initial trusted root metadata (default is to use 1.root.json from the repository) | |
| path to a package manifest | |
| path to a packages list manifest | |
| path to a package archive | |
| path to a product bundle | |
| set repository version based on time rather than monotonically increasing version | |
| the RFC 3339 time used to see if metadata has expired, and when new metadata should expire (default uses the current time) | |
| generate a new root metadata along side all the other metadata | |
| clean the repository so only new publications remain | |
| produce a depfile file | |
| mode used to copy blobs to repository. Either 'copy', 'copy-overwrite', or 'hard-link' (default 'copy'). | |
| the type of delivery blob to generate (default: type 1) | |
| republish packages on file change | |
| ignore if package paths do not exist | |
| path to write the blob manifest to | |
| path to the blobs directory (default '$repo_path/repository/blobs') |
server
Inspect and manage the repository server
Usage: ffx repository server [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| list | Retrieves the status of the repository server. If server is running will also return socket address. Note that all repositories under ffx repository list will be running as subpaths at the returned address. |
| start | Starts the package repository server. |
| stop | Stops the repository server |
list
Retrieves the status of the repository server. If server is running will also return socket address. Note that all repositories under ffx repository list will be running as subpaths at the returned address.
Usage: ffx repository server list [--full] [--name <name...>]
| Options | |
|---|---|
| display usage information | |
| long version of output. | |
| limit output to provided name. This option can appear multiple times |
start
Starts the package repository server.
Usage: ffx repository server start [--address <address>] [--background] [--foreground] [-r <repository>] [--trusted-root <trusted-root>] [--repo-path <repo-path>] [--product-bundle <product-bundle>] [--alias <alias...>] [--storage-type <storage-type>] [--alias-conflict-mode <alias-conflict-mode>] [--port-path <port-path>] [--tunnel-addr <tunnel-addr>] [--no-device] [--refresh-metadata] [--auto-publish <auto-publish>]
| Options | |
|---|---|
| display usage information | |
address on which to serve the repository. Note that this can be either IPV4 or IPV6. For example, [::]:8083 or 127.0.0.1:8083 Default is \[::]:8083. |
|
| run server as a background process. This is mutually exclusive with --daemon and --foreground. | |
| run server as a foreground process. This is the default mode. This is mutually exclusive with --daemon and --background. | |
register this repository. Default is devhost. |
|
| path to the root metadata that was used to sign the repository TUF metadata. This establishes the root of trust for this repository. If the TUF metadata was not signed by this root metadata, running this command will result in an error. Default is to use 1.root.json from the repository. | |
| location of the package repo. Default is given by the build directory obtained from the ffx context. | |
| location of product bundle. | |
set up a rewrite rule mapping each alias host to the repository identified by name. |
|
enable persisting this repository across reboots. Default is Ephemeral. |
|
resolution mechanism when alias registrations conflict. Must be either error-out or replace. Default is replace. |
|
| location to write server port information to, in case port dynamically instantiated. | |
| the address used to listen on target-side when tunneling is used. | |
if true, will not register repositories to device. Default is false. |
|
refresh repository metadata during startup. Note that this is not necessary if package-tool runs in the background taking care of it, e.g. as part of fx serve. Default is false. |
|
| auto publish packages listed in the given manifest. This uses time based versioning when publishing and ignores missing packages. The manifest is a json file a single member "content", which contains a list named "manifest". The list is a list of package manifests, relative paths are relative to the directory of the auto-publish manifest. |
stop
Stops the repository server
Usage: ffx repository server stop [--all] [--product-bundle <product-bundle>] [-p <port>] [name]
| Options | |
|---|---|
| display usage information | |
| stop all repository servers. | |
| stop servers serving the product bundle location. | |
| repository server port number. Required to disambiguate multiple repositories with the same name. |
scrutiny
Audit the security of Fuchsia
Usage: ffx scrutiny [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| extract | Extracts common Fuchsia file types |
| list | Lists properties about build artifacts |
| shell | Launch the scrutiny shell |
| verify | Verify the build |
extract
Extracts common Fuchsia file types
Usage: ffx scrutiny extract [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| 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
Extracts a Blobfs block file
Usage: ffx scrutiny extract blobfs input output
| Options | |
|---|---|
| display usage information |
Examples
To extract a Blobfs block file:
$ffx scrutiny extract blobfs blob.blk /tmp/blobsNotes
Extracts a blobfs block file to a specific directory.
fvm
Extracts a FVM file
Usage: ffx scrutiny extract fvm input output
| Options | |
|---|---|
| display usage information |
Examples
To extract a FVM file:
$ffx scrutiny extract fvm fvm.blk /tmp/fvmNotes
Extracts a FVM to a specific directory.
package
Extracts a Fuchsia package from a Url
Usage: ffx scrutiny extract package --product-bundle <product-bundle> --url <url> --output <output> [--recovery]
| Options | |
|---|---|
| display usage information | |
| a path to a product bundle that contains the package. | |
| the package url. | |
| the location to write the output artifacts. | |
| build scrutiny model based on recovery-mode build artifacts. |
Examples
To extract a Fuchsia package from a url:
$ ffx scrutiny extract package --product-bundle $(fx get-build-dir)/obj/build/images/fuchsia/product_bundle --url fuchsia-pkg://fuchsia.com/foo --output /tmp/fooNotes
Extracts a package to a specific directory.
structured-config
Extracts the structured configuration from Fuchsia build artifacts.
Usage: ffx scrutiny extract structured-config --product-bundle <product-bundle> --build-path <build-path> --depfile <depfile> --output <output> [--recovery]
| Options | |
|---|---|
| display usage information | |
| path to a product bundle. | |
| path to the build directory which is used to rebase the paths in the depfile. | |
| path to a depfile that should be written for build integration | |
| path to file to which to write the extracted configuration. | |
| build scrutiny model based on recovery-mode build artifacts. |
Notes
Extracts structured configuration
zbi
Extracts the Zircon Boot Image
Usage: ffx scrutiny extract zbi input output
| Options | |
|---|---|
| display usage information |
Examples
To extract a Zircon Boot Image:
$ffx scrutiny extract zbi foo.zbi /tmp/fooNotes
Extracts a ZBI to a specific directory.
list
Lists properties about build artifacts
Usage: ffx scrutiny list [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| 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
Lists all the components in the build
Usage: ffx scrutiny list components --product-bundle <product-bundle> [--recovery]
| Options | |
|---|---|
| display usage information | |
| path to a product bundle. | |
| build scrutiny model based on recovery-mode build artifacts. |
Examples
To list all the components in the build:
$ffx scrutiny list components --product-bundle $(fx get-build-dir)/obj/build/images/fuchsia/product_bundleNotes
Lists all the components in the build in a json format.
package
Lists all the files in a package
Usage: ffx scrutiny list package --product-bundle <product-bundle> --url <url> [--recovery]
| Options | |
|---|---|
| display usage information | |
| path to a product bundle. | |
| fuchsia url to the package. | |
| build scrutiny model based on recovery-mode build artifacts. |
Examples
To list all the files in a package:
$ ffx scrutiny list package --product-bundle $(fx get-build-dir)/obj/build/images/fuchsia/product_bundle --url fuchsia-pkg://fuchsia.com/fooNotes
Lists all the package contents in json format.
packages
Lists all the packages in the build
Usage: ffx scrutiny list packages --product-bundle <product-bundle> [--recovery]
| Options | |
|---|---|
| display usage information | |
| path to a product bundle. | |
| build scrutiny model based on recovery-mode build artifacts. |
Examples
To list all the packages in the build:
$ffx scrutiny list packages --product-bundle $(fx get-build-dir)/obj/build/images/fuchsia/product_bundleNotes
Lists all the packages in the build in a json format.
shell
Launch the scrutiny shell
Usage: ffx scrutiny shell command
| Options | |
|---|---|
| display usage information |
Examples
To run commands directly:
$ ffx scrutiny shell "tool.blobfs.extract --input --output "
Notes
Runs a command in scrutiny. Deprecated for the more specific scrutiny methods.
verify
Verify the build
Usage: ffx scrutiny verify [--depfile <depfile>] [--stamp <stamp>] [--tmp-dir <tmp-dir>] [--recovery] [subcommand...]
| Options | |
|---|---|
| display usage information | |
| path to depfile that gathers dependencies during execution. | |
| path to stamp file to write to if and only if verification succeeds. | |
| path to directory to use for temporary files. | |
| build scrutiny model based on recovery-mode build artifacts. |
| Subcommands | |
|---|---|
| bootfs | Verifies list of files in bootfs inside a product bundle 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. |
| pre-signing | Runs assorted checks to ensure a build is okay to sign |
| 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
Verifies list of files in bootfs inside a product bundle against a golden file
Usage: ffx scrutiny verify bootfs --product-bundle <product-bundle> [--golden <golden...>] [--golden-packages <golden-packages...>]
| Options | |
|---|---|
| display usage information | |
| absolute or working directory-relative path to a product bundle. | |
| absolute or working directory-relative path(s) to golden file(s) for verifying bootfs paths. | |
| absolute or working directory-relative path(s) to golden file(s) for verifying bootfs packages. |
Examples
To verify bootfs on your current build:
$ ffx scrutiny verify bootfs \
--product-bundle $(fx get-build-dir)/obj/build/images/fuchsia/product_bundle \
--golden /path/to/goldens/product.txt \
--golden /path/to/goldens/board.txtNotes
Verifies all file paths in bootfs.
component-resolvers
Verifies that component configured to use custom component resolvers are permitted by an allowlist.
Usage: ffx scrutiny verify component-resolvers --product-bundle <product-bundle> --allowlist <allowlist>
| Options | |
|---|---|
| display usage information | |
| absolute or working directory-relative path to a product bundle. | |
| absolute or working directory-relative path to allowlist file that specifies which components may use particular custom component resolvers. |
Examples
To verify component resolvers on your current eng build:
$ ffx scrutiny verify component-resolvers --product-bundle $(fx get-build-dir)/obj/build/images/fuchsia/product_bundle --allowlist ../../src/security/policy/component_resolvers_policy.json5Notes
Verifies all components that use a custom component resolver.
kernel-cmdline
Verifies that kernel cmdline arguments match golden files.
Usage: ffx scrutiny verify kernel-cmdline --product-bundle <product-bundle> [--golden <golden...>]
| Options | |
|---|---|
| display usage information | |
| absolute or working directory-relative path to a product bundle. | |
| absolute or working directory-relative path(s) to golden files to compare against during verification. |
Examples
To verify kernel cmdline arguments on your current build:
$ ffx scrutiny verify kernel-cmdline \
--product-bundle $(fx get-build-dir)/obj/build/images/fuchsia/product_bundle \
--golden path/to/goldenpre-signing
Runs assorted checks to ensure a build is okay to sign
Usage: ffx scrutiny verify pre-signing --policy <policy> --product-bundle <product-bundle> --golden-files-dir <golden-files-dir>
| Options | |
|---|---|
| display usage information | |
| path to a signing validation policy file | |
| path to the product bundle for the build to validate | |
| path to the directory containing golden files for pre_signing |
Examples
To run the pre signing checks against a build:
$ ffx scrutiny verify pre-signing \
--product-bundle $(fx get-build-dir)/obj/build/images/fuchsia/product_bundle \
--policy path/to/policy_file \
--golden_files_dir path/to/goldens/dirroute-sources
Verifies that routes to designated components are routed from designated sources.
Usage: ffx scrutiny verify route-sources --product-bundle <product-bundle> --config <config>
| Options | |
|---|---|
| display usage information | |
| absolute or working directory-relative path to a product bundle. | |
| absolute or working directory-relative path to configuration file that specifies components and their expected route sources. |
Examples
To verify route sources according to a configuration file on your current build:
$ ffx scrutiny verify route-sources
--product-bundle $(fx get-build-dir)/obj/build/images/fuchsia/product_bundle \
--config path/to/verify_route_sources/product.board.json5routes
Verifies capability routes in the component tree
Usage: ffx scrutiny verify routes [--capability-type <capability-type...>] [--response-level <response-level>] --product-bundle <product-bundle> [--component-tree-config <component-tree-config>]
| Options | |
|---|---|
| display usage information | |
| capability types to verify. | |
| response level to report from routes scrutiny plugin. | |
| absolute or working directory-relative path to a product bundle. | |
| absolute or working path-relative path to component tree configuration file that affects how component tree data is gathered. |
Examples
To verify routes on your current build:
$ ffx scrutiny verify routes \
--product-bundle $(fx get-build-dir)/obj/build/images/fuchsia/product_bundlestatic-pkgs
Check the static packages extracted from the ZBI against golden files
Usage: ffx scrutiny verify static-pkgs --product-bundle <product-bundle> [--golden <golden...>]
| Options | |
|---|---|
| display usage information | |
| path to a product bundle. | |
| path(s) to golden file(s) used to verify routes. |
Examples
To verify static packages on your current build:
$ ffx scrutiny verify static-pkgs --product-bundle $(fx get-build-dir)/obj/build/images/fuchsia/product_bundle --golden path/to/goldenstructured-config
Verifies component configuration according to configured assertions.
Usage: ffx scrutiny verify structured-config --policy <policy> --product-bundle <product-bundle>
| Options | |
|---|---|
| display usage information | |
| absolute or working directory-relative path to a policy file for structured configuration | |
| path to a product bundle. |
sdk
Modify or query the installed SDKs
Usage: ffx sdk [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| populate-path | Populates the given path with symlinks to the fuchsha-sdk-run tool to run project-specific sdk tools |
| run | Run a host tool from the active sdk |
| set | Set sdk-related configuration options |
| version | Retrieve the version of the current SDK |
populate-path
Populates the given path with symlinks to the fuchsha-sdk-run tool to run project-specific sdk tools
Usage: ffx sdk populate-path path
| Options | |
|---|---|
| display usage information |
run
Run a host tool from the active sdk
Usage: ffx sdk run name args
| Options | |
|---|---|
| display usage information |
set
Set sdk-related configuration options
Usage: ffx sdk set [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| root | Sets the path to the root of the preferred SDK |
root
Sets the path to the root of the preferred SDK
Usage: ffx sdk set root path
| Options | |
|---|---|
| display usage information |
version
Retrieve the version of the current SDK
Usage: ffx sdk version
| Options | |
|---|---|
| display usage information |
session
Control the session component.
Usage: ffx session [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| add | Add an element to the current session. |
| drop-power-lease | Drop the power lease reserved for the current session component. |
| launch | Launch a session component. |
| remove | Remove an element from the current session. |
| restart | Restart the current session component. |
| show | Show information about the current session |
| start | Start the default session component. |
| stop | Stop the session component. |
Notes
See https://fuchsia.dev/fuchsia-src/glossary#session-component.
add
Add an element to the current session.
If the --persist option is used, the package should be in the base or cache package set as otherwise it might fail to launch after a reboot.
Usage: ffx session add [--interactive] [--persist] [--name <name>] url
| Options | |
|---|---|
| display usage information | |
| pass to keep element alive until command exits | |
| pass to have the element persist over reboots | |
| name for the element which defaults to random if not specified |
Examples
To add the `bouncing_ball.cm` component as an element:
$ ffx session add fuchsia-pkg://fuchsia.com/bouncing_ball#meta/bouncing_ball.cmdrop-power-lease
Drop the power lease reserved for the current session component.
Usage: ffx session drop-power-lease
| Options | |
|---|---|
| display usage information |
Notes
This command is useful for testing system suspension. If the session component has not taken the lease, then the lease will be dropped. If no other components on the system hold a power lease on the execution state, this will suspend the system.
launch
Launch a session component.
Usage: ffx session launch [--config <config...>] url
| Options | |
|---|---|
| display usage information | |
provide additional configuration capabilities to the component being run. Specified in the format fully.qualified.Name=VALUE where fully.qualified.Name is the name of the configuration capability, and VALUE is a JSON string which can be resolved as the correct type of configuration value. |
Examples
To launch the `hello-world-session.cm` component as a session:
$ ffx session launch fuchsia-pkg://fuchsia.com/hello-world-session#meta/hello-world-session.cm
remove
Remove an element from the current session.
Persistent elements will be removed permanently. Any persistent storage used by elements will not be removed.
Usage: ffx session remove name
| Options | |
|---|---|
| display usage information |
restart
Restart the current session component.
Usage: ffx session restart
| Options | |
|---|---|
| display usage information |
Notes
Destroys the existing session component, if any, then creates and starts a new component with the same URL. Requires that a session componentwas previously launched.
show
Show information about the current session
Usage: ffx session show
| Options | |
|---|---|
| display usage information |
start
Start the default session component.
Usage: ffx session start
| Options | |
|---|---|
| display usage information |
Notes
The default session component is specified by the URL
session_urlinsession_manager's structured configuration.
stop
Stop the session component.
Usage: ffx session stop
| Options | |
|---|---|
| display usage information |
setui
Modify and query settings.
Usage: ffx setui [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| 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 |
accessibility
watch or set accessibility settings
Usage: ffx setui accessibility [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| 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
add caption options, the configuration for which sources get closed caption and how they look
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>]
| Options | |
|---|---|
| display usage information | |
| enable closed captions for media sources of audio | |
| enable closed captions for Text-To-Speech sources of audio | |
| border color used around the closed captions window. Valid options are red, green, and blue | |
| border color used around the closed captions window. Valid options are red, green, and blue | |
| 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 | |
| color of the closed caption text. Valid options are red, green, and blue | |
| 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) | |
| edge style for fonts as specified in 47 CFR §79.103(c)(7). Valid options are none, drop_shadow, raised, depressed, outline |
set
set other accessibility options
Usage: ffx setui accessibility set [-a <audio-description>] [-s <screen-reader>] [-i <color-inversion>] [-m <enable-magnification>] [-c <color-correction>]
| Options | |
|---|---|
| display usage information | |
| when set to 'true', will turn on an audio track for videos that includes a description of what is occurring in the video | |
| when set to 'true', will read aloud elements of the screen selected by the user | |
| when set to 'true', will invert the colors on the screen | |
| when set to 'true', will interpret triple-taps on the touchscreen as a command to zoom in | |
| configures the type of color-blindness to correct for. Valid options are none, protanomaly, deuteranomaly, and tritanomaly |
watch
watch current accessibility settings
Usage: ffx setui accessibility watch
| Options | |
|---|---|
| display usage information |
audio
get or set audio settings
Usage: ffx setui audio [-t <stream>] [-s <source>] [-l <level>] [-v <volume-muted>]
| Options | |
|---|---|
| display usage information | |
| which stream should be modified. Valid options are background, media, interruption, system_agent, communication and accessibility. | |
| which source is changing the stream. Valid options are user, system, and system_with_feedback | |
| the volume level specified as a float in the range [0, 1] | |
| whether or not the volume is muted |
display
get or set display settings
Usage: ffx setui display [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| get | Get the current display settings. |
| set | Sets display settings. |
| watch | Get the current display settings and watch for changes. |
get
Get the current display settings.
Usage: ffx setui display get [-f <field>]
| Options | |
|---|---|
| display usage information | |
| choose which display settings field value to return, valid options are auto and brightness |
set
Sets display settings.
Usage: ffx setui display set [-b <brightness>] [-o <auto-brightness-level>] [-a <auto-brightness>] [-m <low-light-mode>] [-t <theme>] [-s <screen-enabled>]
| Options | |
|---|---|
| display usage information | |
| the brightness value specified as a float in the range [0, 1] | |
| the brightness values used to control auto brightness as a float in the range [0, 1] | |
| when set to 'true', enables auto brightness | |
| which low light mode setting to enable. Valid options are enable, disable, and disable_immediately | |
| which theme to set for the device. Valid options are default, dark, light, darkauto, and lightauto | |
| when set to 'true' the screen is enabled |
watch
Get the current display settings and watch for changes.
Usage: ffx setui display watch
| Options | |
|---|---|
| display usage information |
do_not_disturb
get or set DnD settings
Usage: ffx setui do_not_disturb [-u <user-dnd>] [-n <night-mode-dnd>]
| Options | |
|---|---|
| display usage information | |
| when set to 'true', allows the device to enter do not disturb mode | |
| when set to 'true', forces the device into do not disturb mode |
factory_reset
get or set factory reset settings
Usage: ffx setui factory_reset [-l <is-local-reset-allowed>]
| Options | |
|---|---|
| display usage information | |
| when set to 'true', factory reset can be performed on the device |
input
get or set input settings
Usage: ffx setui input [-t <device-type>] [-n <name>] [-s <state>]
| Options | |
|---|---|
| display usage information | |
| the type of input device. Valid options are camera and microphone | |
| the name of the device. Must be unique within a device type | |
| the device state flags, pass a comma separated string of the values available, active, muted, disabled and error. E.g. "-s available,active" |
intl
get or set internationalization settings
Usage: ffx setui intl [-z <time-zone>] [-u <temperature-unit>] [-l <locales...>] [-h <hour-cycle>] [--clear-locales]
| Options | |
|---|---|
| display usage information | |
| a valid timezone matching the data available at https://www.iana.org/time-zones | |
| the unit to use for temperature. Valid options are celsius and fahrenheit | |
| list of locales, separated by spaces, formatted by Unicode BCP-47 Locale Identifier, e.g. en-us | |
| 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 | |
| if set, this flag will set locales as an empty list. Overrides the locales arguments |
keyboard
get or set keyboard settings
Usage: ffx setui keyboard [-k <keymap>] [-d <autorepeat-delay>] [-p <autorepeat-period>]
| Options | |
|---|---|
| display usage information | |
| keymap selection for the keyboard. Valid options are - UsQwerty - FrAzerty - UsDvorak - UsColemak | |
| 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. | |
| 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. |
light
get or set light settings
Usage: ffx setui light [-n <name>] [-s <simple...>] [-b <brightness...>] [-r <rgb...>]
| Options | |
|---|---|
| display usage information | |
| name of a light group to set values for. Required if setting the value of a light group | |
| repeated parameter for a list of simple on/off values to set for a light group. | |
| repeated parameter for a list of floating point brightness values in the range [0, 1] for a light group | |
| 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 |
night_mode
get or set night mode settings
Usage: ffx setui night_mode [-n <night-mode-enabled>]
| Options | |
|---|---|
| display usage information | |
| when 'true', enables night mode |
privacy
get or set privacy settings
Usage: ffx setui privacy [-u <user-data-sharing-consent>]
| Options | |
|---|---|
| display usage information | |
| 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 |
setup
get or set setup settings
Usage: ffx setui setup [-i <interfaces>]
| Options | |
|---|---|
| display usage information | |
| 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" |
speedtest
Developer tool for testing fffx latency and throughput to the target.
Usage: ffx speedtest [-r <repeat>] [-I <delay>] [subcommand...]
| Options | |
|---|---|
| display usage information | |
| how many times to repeat the test. Set zero to run until interrupted. | |
| time to delay between repetitions, in milliseconds. |
| Subcommands | |
|---|---|
| ping | Calculates latency to the target with simple channel messages. |
| socket | Calculates throughput to the target using zircon socket abstractions. |
ping
Calculates latency to the target with simple channel messages.
Usage: ffx speedtest ping [-c <count>]
| Options | |
|---|---|
| display usage information | |
| the number of probes to send to calculate average latency. |
socket
Calculates throughput to the target using zircon socket abstractions.
Usage: ffx speedtest socket [-L <transfer-mb>] [-b <buffer-kb>] [-R]
| Options | |
|---|---|
| display usage information | |
| transfer size in Mega Bytes (MB). | |
| buffer size in Kilo Bytes (KiB). | |
| perform target->host transfer. host->target transfer is performed by default. |
starnix
Control starnix containers
Usage: ffx starnix [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| adb | Bridge from host adb to adbd running inside starnix |
| console | Attach a console to a starnix container |
| vmo | Return all processes that have references to a file backed by a vmo with koid |
adb
Bridge from host adb to adbd running inside starnix
Usage: ffx starnix adb [--adb <adb>] [subcommand...]
| Options | |
|---|---|
| display usage information | |
| path to the adb client command |
| Subcommands | |
|---|---|
| connect | directly connect the local adb server to an adbd instance running on the target. |
| proxy | Bridge from host adb to adbd running inside starnix |
Examples
ffx starnix adb proxy
connect
directly connect the local adb server to an adbd instance running on the target.
Usage: ffx starnix adb connect
| Options | |
|---|---|
| display usage information |
proxy
Bridge from host adb to adbd running inside starnix
Usage: ffx starnix adb proxy [-m <moniker>] [-p <port>] [--no-autoconnect]
| Options | |
|---|---|
| display usage information | |
| the moniker of the container running adbd (defaults to looking for a container in the current session) | |
| which port to serve the adb server on | |
| disable automatically running "adb connect" |
console
Attach a console to a starnix container
Usage: ffx starnix console [-m <moniker>] [-e <env...>] argv
| Options | |
|---|---|
| display usage information | |
| the moniker of the container in which to create the console (defaults to looking for a container in the current session) | |
| environment variables to pass to the program. |
Examples
ffx starnix console \[-e ENV=VAL -e ...] program \[argument ...]
vmo
Return all processes that have references to a file backed by a vmo with koid
Usage: ffx starnix vmo -k <koid>
| Options | |
|---|---|
| display usage information | |
| koid of the vmo to search for references to. |
Examples
ffx starnix vmo -k 123456
storage
Manage Fuchsia Filesystems.
Usage: ffx storage [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| fxfs | Interact with fxfs instances. |
fxfs
Interact with fxfs instances.
Usage: ffx storage fxfs [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| compact | Forces a (blocking) compaction of all layer files. |
| delete_profile | Deletes a profile from a named unlocked volume. Fails during active profile record or replay. |
| stop_profile | Blocks while stopping all profile recording and replay activity. |
compact
Forces a (blocking) compaction of all layer files.
Usage: ffx storage fxfs compact
| Options | |
|---|---|
| display usage information |
Examples
ffx storage fxfs compact
delete_profile
Deletes a profile from a named unlocked volume. Fails during active profile record or replay.
Usage: ffx storage fxfs delete_profile volume profile
| Options | |
|---|---|
| display usage information |
Examples
ffx storage fxfs delete_profile
stop_profile
Blocks while stopping all profile recording and replay activity.
Usage: ffx storage fxfs stop_profile
| Options | |
|---|---|
| display usage information |
Examples
ffx storage fxfs stop_profile
target
Interact with a target device or emulator
Usage: ffx target [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| 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 |
| fastboot | Perform fastboot operations on a target device |
| flash | Flash an image to a target device |
| get-ssh-address | Get the target's ssh address |
| get-time | Returns the current time in the system monotonic clock. |
| list | List all targets |
| off | Powers off a target |
| package | Interact with target package management |
| reboot | Reboots a target |
| remove | Make the daemon forget a specific target |
| repository | Interact with target repository registration |
| screenshot | Takes a screenshot of the target |
| 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 |
| ssh | SSH to a target device |
| status | Run status checks step by step to determine a device's state |
| update | Update base system software on target |
| wait | Wait until able to establish a remote control connection to the target. |
Notes
The
targetsubcommand 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
Make the daemon aware of a specific target
Usage: ffx target add [-n] addr
| Options | |
|---|---|
| display usage information | |
| do not wait for a connection to be verified on the Fuchsia device. |
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:a00aNotes
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
Communicates with the bootloader
Usage: ffx target bootloader [-m <manifest>] [-p <product>] [-b <product-bundle>] [--skip-verify] [subcommand...]
| Options | |
|---|---|
| display usage information | |
| path to flashing manifest or zip file containing images and manifest | |
product entry in manifest - defaults to fuchsia |
|
| optional product bundle name | |
| skip hardware verification. This is dangerous, please be sure the images you are using match the device |
| Subcommands | |
|---|---|
| boot | RAM boots a fastboot target. |
| info | Prints fastboot variables for target. |
| lock | Locks a fastboot target. |
| unlock | Unlocks a fastboot target. |
boot
RAM boots a fastboot target.
Usage: ffx target bootloader boot [-z <zbi>] [-v <vbmeta>] [-s <slot>]
| Options | |
|---|---|
| display usage information | |
| optional zbi image file path to use | |
| optional vbmeta image file path to use | |
| slot corresponding to partitions in the flash manifest - |
only used if zbi and vbmeta files are not present
info
Prints fastboot variables for target.
Usage: ffx target bootloader info
| Options | |
|---|---|
| display usage information |
lock
Locks a fastboot target.
Usage: ffx target bootloader lock
| Options | |
|---|---|
| display usage information |
unlock
Unlocks a fastboot target.
Usage: ffx target bootloader unlock [-c <cred>] [--force]
| Options | |
|---|---|
| display usage information | |
| optional path to credential file to use to unlock the device | |
| skips the warning message that this command is dangerous |
clear-preferred-ssh-address
Clears a previously configured SSH address
Usage: ffx target clear-preferred-ssh-address
| Options | |
|---|---|
| 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
Manage the default target
Usage: ffx target default [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| get | Get the default configured target |
| set | Set the default target |
| unset | Clears the configured default target |
Examples
For one-off overrides for the default use `--target` option:
$ ffx --target Notes
Manages the default configured target for all operations. In
ffx target listthe default target is designated by a*next to the name.
get
Get the default configured target
Usage: ffx target default get
| Options | |
|---|---|
| display usage information |
Notes
Returns the effective default configured target from configuration, $FUCHSIA_NODENAME, and $FUCHSIA_DEVICE_ADDR. Returns an empty string if no default is configured.
set
Set the default target
Usage: ffx target default set nodename
| Options | |
|---|---|
| display usage information |
Examples
To set the default target: $ ffx target default set
Notes
Sets the default target in 'User Configuration' scope.
After setting the default target, ffx target list will mark the default
with a * in the output list.
unset
Clears the configured default target
Usage: ffx target default unset
| Options | |
|---|---|
| display usage information |
Examples
To clear the default target:
$ ffx target default unsetNotes
Unsets the default target on all configuration levels. Returns a warning if it's already unset. Returns an error if it's not possible to clear it.
echo
run echo test against the target
Usage: ffx target echo [--repeat] [text]
| Options | |
|---|---|
| display usage information | |
| run the echo test repeatedly until the command is killed |
fastboot
Perform fastboot operations on a target device
Usage: ffx target fastboot [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| continue | Continue subcommand |
| flash | Flash subcommand |
| getvar | Get Variable subcommand |
| oem | Oem subcommand |
| reboot | Reboot subcommand |
| sparse | Sparse subcommand. |
| stage | Stage subcommand |
Examples
To flash a specific image:
$ ffx target fastboot flash super foo.zbicontinue
Continue subcommand
Usage: ffx target fastboot continue
| Options | |
|---|---|
| display usage information |
flash
Flash subcommand
Usage: ffx target fastboot flash partition file
| Options | |
|---|---|
| display usage information |
getvar
Get Variable subcommand
Usage: ffx target fastboot getvar var_name
| Options | |
|---|---|
| display usage information |
oem
Oem subcommand
Usage: ffx target fastboot oem command
| Options | |
|---|---|
| display usage information |
reboot
Reboot subcommand
Usage: ffx target fastboot reboot [bootloader]
| Options | |
|---|---|
| display usage information |
sparse
Sparse subcommand.
Usage: ffx target fastboot sparse [--size <size>] file out_dir
| Options | |
|---|---|
| display usage information | |
| size to split the image into. If unset defaults to target's max download size |
Notes
Takes the provided file and out_dir and breaks the input file into a set of files named in format n-tmp.img, each of which is no larger than
size(defaulting to Target's max download size) and is in the Android Sparse Image Format.
stage
Stage subcommand
Usage: ffx target fastboot stage file
| Options | |
|---|---|
| display usage information |
flash
Flash an image to a target device
Usage: ffx target flash [-p <product>] [-b <product-bundle>] [-m <manifest>] [--oem-stage <oem-stage...>] [--authorized-keys <authorized-keys>] [--no-bootloader-reboot] [--skip-verify] [--timeout-rate <timeout-rate>] [--min-timeout-secs <min-timeout-secs>] [manifest_path]
| Options | |
|---|---|
| display usage information | |
product entry in manifest - defaults to fuchsia |
|
| optional product bundle name | |
| optional manifest path | |
| oem staged file - can be supplied multiple times | |
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. |
|
| the device should not reboot after bootloader images are flashed | |
| skip hardware verification. This is dangerous, please be sure the images you are flashing match the device | |
| flash timeout rate in mb/second. | |
| minimum timeout in seconds to wait while flashing per-partition |
Examples
To flash a specific image:
$ ffx target flash --manifest $(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 fuchsiaNotes
Flashes an image to a target device using the fastboot protocol. Requires a specific
file and 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
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:
'
get-ssh-address
Get the target's ssh address
Usage: ffx target get-ssh-address [-t <timeout>]
| Options | |
|---|---|
| display usage information | |
| the timeout in seconds [default = 1.0] |
Notes
Return the SSH address of the default target, which can be retrieved with
ffx target default get.
The command takes a 1.0
and overrides the value in the target.interaction.timeout key.
| Errors | |
|---|---|
| 1 | Timeout while getting ssh address |
| 2 | Unable to get ssh address from target |
get-time
Returns the current time in the system monotonic clock. This is the number of nanoseconds since the system was powered on. It does not always reset on reboot and does not adjust during sleep, and thus should not be used as a reliable source of uptime.
See https://fuchsia.dev/reference/syscalls/clock_get_monotonic
Usage: ffx target get-time [-b]
| Options | |
|---|---|
| display usage information | |
| if true, return boot time |
Examples
To get the target time:
$ ffx target get-time
list
List all targets
Usage: ffx target list [-f <format>] [--no-ipv4] [--no-ipv6] [--no-probe] [--no-mdns] [--no-usb] [nodename]
| Options | |
|---|---|
| display usage information | |
| determines the output format for the list operation | |
| do not return IPv4 addresses | |
| do not return IPv6 addresses | |
| do not connect to targets (local discovery only) | |
| do not do mDNS discovery (local discovery only) | |
| do not do USB discovery (local discovery only) |
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-f80ff974f283Notes
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 listto always get the latest list of targets. Targets are sorted by name.
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
| Errors | |
|---|---|
| 2 | If a nodename is supplied, an error code of 2 will be returned if the nodename cannot be resolved |
off
Powers off a target
Usage: ffx target off
| Options | |
|---|---|
| display usage information |
Notes
Power off a target. Uses the 'fuchsia.hardware.power.statecontrol.Admin' FIDL API to send the power off command.
'fuchsia.hardware.power.statecontrol.Admin' is exposed by the 'power_manager'
component. To verify that the target exposes this service, ffx component
select or ffx component knock can be used.
| Errors | |
|---|---|
| 1 | Timeout while powering off target. |
package
Interact with target package management
Usage: ffx target package [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| explore | Resolves a package and then spawns a shell with said package loaded into the namespace at /pkg. |
| resolve | Resolve packages from configured repositories on a target |
Notes
The `package` subcommand contains various commands for package management on-target. Most of the commands depend on the RCS (Remote Control Service) on the target.
explore
Resolves a package and then spawns a shell with said package loaded into the namespace at /pkg.
Usage: ffx target package explore [--subpackage <subpackage...>] [--tools <tools...>] [-c <command>] [--fuchsia-pkg-resolver <fuchsia-pkg-resolver>] url
| Options | |
|---|---|
| display usage information | |
the chain of subpackages, if any, of url to resolve, in resolution order. If subpackages is not empty, the package directory of the final subpackage will be loaded into the shell's namespace at /pkg. |
|
list of URLs of tools packages to include in the shell environment. the PATH variable will be updated to include binaries from these tools packages. repeat --tools url for each package to be included. The path preference is given by command line order. |
|
| execute a command instead of reading from stdin. the exit code of the command will be forwarded to the host. | |
| the resolver to use when resolving package URLs with scheme "fuchsia-pkg". Possible values are "base" and "full". Defaults to "full". |
Examples
To explore the update package interactively: > ffx target package explore 'fuchsia-pkg://fuchsia.com/update' $ ls svc pkg $ exit Connection to terminal closed To run a command directly from the command line: > ffx target package explore 'fuchsia-pkg://fuchsia.com/update' -c 'printenv' PATH=/.dash/tools/debug-dash-launcher PWD=/
Notes
The environment contains the following directories:
- /.dash User-added and built-in dash tools
- /pkg The package directory of the resolved package
- /svc Protocols required by the dash shell
If additional binaries are provided via --tools, they will be loaded into .dash/tools/
--tools URLs may be package or binary URLs. Note that collisions can occur if different URLs have
the same package and binary names. An error, NonUniqueBinaryName, is returned if a binary name
collision occurs.
resolve
Resolve packages from configured repositories on a target
Usage: ffx target package resolve [package]
| Options | |
|---|---|
| display usage information |
reboot
Reboots a target
Usage: ffx target reboot [-b] [-r]
| Options | |
|---|---|
| display usage information | |
| reboot to bootloader | |
| reboot to recovery |
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.
'fuchsia.hardware.power.statecontrol.Admin' is exposed by the 'power_manager'
component. To verify that the target exposes this service, ffx component
select or ffx component knock can be used.
| Errors | |
|---|---|
| 1 | Timeout while powering off target. |
remove
Make the daemon forget a specific target
Usage: ffx target remove [--all] [name_or_addr]
| Options | |
|---|---|
| display usage information | |
| remove all manually added targets |
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:a00aNotes
IP addresses are matched by their full string representation. for best results, copy the exact address from ffx target list.
repository
Interact with target repository registration
Usage: ffx target repository [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| 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
Make the target forget a specific repository
Usage: ffx target repository deregister [-r <repository>] [-p <port>]
| Options | |
|---|---|
| display usage information | |
remove the repository named name from the target, rather than the default. |
|
| repository server port number. Required to disambiguate multiple repositories with the same name. |
list
List all the repositories on a target
Usage: ffx target repository list
| Options | |
|---|---|
| display usage information |
register
Make the target aware of a specific repository
Usage: ffx target repository register [-r <repository>] [-p <port>] [--address-override <address-override>] [--storage-type <storage-type>] [--alias <alias...>] [--alias-conflict-mode <alias-conflict-mode>]
| Options | |
|---|---|
| display usage information | |
| register this repository, rather than the default. | |
| repository server port number. Required to disambiguate multiple repositories with the same name. | |
| repository server address override. When provided, overrides the server address registered on the target. Required when the server's listening address is not directly reachable by the target. | |
| enable persisting this repository across reboots. | |
set up a rewrite rule mapping each alias host to to the repository identified by name. |
|
resolution mechanism when alias registrations conflict. Must be either error-out or replace. Default is replace. |
screenshot
Takes a screenshot of the target
Usage: ffx target screenshot [-d <dir>] [--format <format>]
| Options | |
|---|---|
| display usage information | |
| override the default directory where the screenshot will be saved | |
| screenshot format. If no value is provided bgra will be used. |
Accepted values: bgra, rgba, png
Examples
Store the target's screenshot in a directory:
$ ffx target screenshot -d .
Exported ./screenshotNotes
This command connects to a running target to take its screenshot. The
--dircan be supplied to override the default screenshot saving location/tmp/screenshot/YYYYMMDD_HHMMSS/. The --format can be supplied to override the default format png. Accepted format values: bgra, rgba, png. The screenshot file name isscreenshot.<format>.
set-preferred-ssh-address
Sets the preferred SSH address
Usage: ffx target set-preferred-ssh-address addr
| Options | |
|---|---|
| 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
Display relevant information for the target
Usage: ffx target show [--desc] [--label]
| Options | |
|---|---|
| display usage information | |
| display descriptions of entries | |
| display label of entries |
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.
| Errors | |
|---|---|
| 1 | Timeout retrieving target information. |
snapshot
Takes a snapshot of the target's state
Usage: ffx target snapshot [-d <dir>] [--dump-annotations] [--upload]
| Options | |
|---|---|
| display usage information | |
| valid directory where the snapshot will be stored | |
print annotations without capturing the snapshot, ignores dir and upload flags |
|
| whether to upload the generated snapshot to a predefined GCS bucket |
Examples
Store the target's snapshot in the current directory:
$ ffx target snapshot -d .
Exported ./snapshot.zipNotes
This command connects to a running target to acquire its snapshot, which contains useful debugging information about the target. The
--dircan be supplied to override the default snapshot directory/tmp/snapshots/YYYYMMDD_HHMMSS/.
Snapshot contents: - Build information and annotations - Kernel and system logs - Inspect data
ssh
SSH to a target device
Usage: ffx target ssh [--sshconfig <sshconfig>] [command...]
| Options | |
|---|---|
| display usage information | |
| path to the custom ssh config file to use. |
Examples
To ssh to a specific device:
$ ffx -t fuchsia-EEEE-NNNN target ssh
To ssh and run a command:
$ ffx target ssh 'echo $USER'
status
Run status checks step by step to determine a device's state
Usage: ffx target status [proxy_connect_timeout]
| Options | |
|---|---|
| display usage information |
update
Update base system software on target
Usage: ffx target update [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| channel | View and manage update channels |
| check-now | Check and perform the system update operation |
| force-install | Trigger the system updater manually |
| wait-for-commit | Wait for the update to be committed. |
Notes
This command interfaces with system update services on the target.
channel
View and manage update channels
Usage: ffx target update channel [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| get-current | Return the currently configured update channel |
| get-next | Return the next or target update channel |
| list | List the known update channels |
| set | Sets the update channel |
Notes
Channel management commands and operations. Interfaces directly with the 'fuchsia.update.channelcontrol.ChannelControl' service on the target system.
get-current
Return the currently configured update channel
Usage: ffx target update channel get-current
| Options | |
|---|---|
| display usage information |
Notes
For developer product configurations, this is by default 'devhost'.
| Errors | |
|---|---|
| 1 | Timeout while getting update channel. |
get-next
Return the next or target update channel
Usage: ffx target update channel get-next
| Options | |
|---|---|
| display usage information |
Notes
Returns the next or target channel. This differs from
getwhen the next successful update changes the configured update channel on the system.
| Errors | |
|---|---|
| 1 | Timeout while getting update channel. |
list
List the known update channels
Usage: ffx target update channel list
| Options | |
|---|---|
| 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.
| Errors | |
|---|---|
| 1 | Timeout while getting list of update channel. |
set
Sets the update channel
Usage: ffx target update channel set channel
| Options | |
|---|---|
| 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 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.
| Errors | |
|---|---|
| 1 | Timeout while setting update channel. |
check-now
Check and perform the system update operation
Usage: ffx target update check-now [--service-initiated] [--monitor] [--product-bundle] [--product-bundle-port <product-bundle-port>] [product_bundle_path]
| Options | |
|---|---|
| display usage information | |
| the update check was initiated by a service, in the background. | |
| monitor for state update. | |
| use the product bundle to use as the source of the update. | |
port to start the OTA repo server on when using --product_bundle. This is configured by repository.ota_port and defaults to 0, which indicates a random unassigned port. |
Examples
To check for update and monitor progress:
$ ffx target update check-now --monitorNotes
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
Trigger the system updater manually
Usage: ffx target update force-install [--reboot <reboot>] [--product-bundle] [--product-bundle-port <product-bundle-port>] update_pkg_url [product_bundle_path]
| Options | |
|---|---|
| display usage information | |
| automatically trigger a reboot into the new system | |
| use the product bundle to use as the source of the update. | |
port to start the OTA repo server on when using --product_bundle. This is configured by repository.ota_port and defaults to 0, which indicates a random unassigned port. |
Examples
With a known update package URL, trigger an update and reboot:
$ ffx target update force-install fuchsia-pkg://fuchsia.com/update
Don't reboot after update:
$ ffx target update force-install
fuchsia-pkg://fuchsia.com/update
--reboot falseNotes
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
fuchsia-pkg://fuchsia.com/update
Takes an optional --reboot <true|false> to trigger a system reboot
after update has been successfully applied.
wait-for-commit
Wait for the update to be committed.
Usage: ffx target update wait-for-commit
| Options | |
|---|---|
| display usage information |
wait
Wait until able to establish a remote control connection to the target.
Usage: ffx target wait [-t <timeout>] [-d]
| Options | |
|---|---|
| display usage information | |
| the timeout in seconds [default = 120]. A value of 0 implies no timeout. | |
| wait for target to go down |
| Errors | |
|---|---|
| 1 | Timeout while getting ssh address |
test
Run test suite
Usage: ffx test [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| early-boot-profile | Manage early boot profiles |
| list-cases | List test suite cases |
| run | Execute test suites on a target device |
Notes
Run tests or inspect output from a previous test run.
early-boot-profile
Manage early boot profiles
Usage: ffx test early-boot-profile --output-directory <output-directory>
| Options | |
|---|---|
| display usage information | |
| output early boot profile to the specified directory. The produced output is in the format described in https://fuchsia.dev/fuchsia-src/reference/platform-spec/testing/test-output-format |
list-cases
List test suite cases
Usage: ffx test list-cases [--realm <realm>] test_url
| Options | |
|---|---|
| display usage information | |
| the realm to enumerate the test in. This field is optional and takes the form: /path/to/realm:test_collection. |
Notes
Lists the set of test cases available in a test suite
run
Execute test suites on a target device
Usage: ffx test run [--test-file <test-file>] [-t <timeout>] [--test-filter <test-filter...>] [--realm <realm>] [--run-disabled] [--parallel <parallel>] [--max-severity-logs <max-severity-logs>] [--continue-on-timeout] [--stop-after-failures <stop-after-failures>] [--count <count>] [--experimental-parallel-execution <experimental-parallel-execution>] [--break-on-failure] [--filter-ansi] [--min-severity-logs <min-severity-logs...>] [--show-full-moniker-in-logs] [--output-directory <output-directory>] [--disable-output-directory] [--no-exception-channel] [--no-cases-equals-success] [test_args...]
| Options | |
|---|---|
| display usage information | |
read test url and options from the specified file instead of from the command line. May not be used in conjunction with test_args, --count, --test-filter, --run-disabled, --parallel, --max-severity-logs This option is currently unstable and the format of the file is subject to change. Using this option requires setting the 'test.experimental_json_input' configuration to true. For current details, see test-list.json format at https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/src/lib/testing/test_list/ |
|
| test suite timeout in seconds. | |
| test case filter. This filter will match based on glob pattern. This option may be specified multiple times. Only test cases matching at least one pattern will be run. Negative filters may be specified by prepending '-' and will exclude matching test cases. | |
| the realm to run the test in. This field is optional and takes the form: /path/to/realm:test_collection. See https://fuchsia.dev/go/components/non-hermetic-tests | |
| also execute test cases that have been disabled by the test author. | |
| maximum number of test cases to run in parallel. Defaults to a value specified by the test runner. | |
| when set, fails tests that emit logs with a higher severity. For example, if --max-severity-logs WARN is specified, fails any test that produces an ERROR level log. | |
| continue running unfinished suites if a suite times out. This option is only relevant when multiple suites are run. | |
| stop running unfinished suites after the number of provided failures has occurred. This option is only relevant when multiple suites are run. | |
| number of times to run the test suite. By default run the suite 1 time. | |
| 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. | |
| enable break_on_failure for supported test runners. Any test case failure causes the test execution to stop and wait for zxdb to attach to debug the failure. When the debugger exits, the process will be released and the suite will be continued. Note: test runners may or may not have the ability to halt a test suite after it has started executing. If there isn't a way to raise an exception for a debugger to catch, the test will run and exit as normal, and will not wait for any debugger interaction. | |
| filter ANSI escape sequences from output. | |
| set the minimum log severity printed. This modifies the minimum log severity level emitted by components during the test execution. Specify using the format |
|
| show the full moniker in unstructured log output. | |
| output test results to the specified directory. The produced output is in the format described in https://fuchsia.dev/fuchsia-src/reference/platform-spec/testing/test-output-format | |
| disable structured output to a directory. Note structured output is disabled by default, unless --output-directory is specified. This option supported an experiment which has been removed. It is now a no-op and will soon be removed. | |
| when set, prevents test_manager from creating exception channels that may confilict with those created by the test. | |
| when set, the test_filter selecting an empty set of cases to run is treated as success rather than failure. |
Examples
Run a test suite:
$ ffx test run fuchsia-pkg://fuchsia.com/my_test#meta/my_test.cm
Run a test suite in system realm:
$ ffx test run --realm /core/testing/system-tests fuchsia-pkg://fuchsia.com/my_test#meta/my_test.cm
Run a test suite and pass arguments to the suite:
$ ffx test run fuchsia-pkg://fuchsia.com/my_test#meta/my_test.cm -- arg1 arg2
Run test suites specified in a JSON file (currently unstable):
$ ffx test run --test-file test-list.json
Given a suite that contains the test cases 'Foo.Test1', 'Foo.Test2',
'Bar.Test1', and 'Bar.Test2':
Run test cases that start with 'Foo.' ('Foo.Test1', 'Foo.Test2'):
$ ffx test run --test-filter 'Foo.*'
Run test cases that do not start with 'Foo.' ('Bar.Test1', 'Bar.Test2'):
$ ffx test run --test-filter '-Foo.*'
Run test cases that start with 'Foo.' and do not end with 'Test1' ('Foo.Test2'):
$ ffx test run --test-filter 'Foo.*' --test-filter '-*.Test1' Notes
Runs test suites implementing the
fuchsia.test.Suiteprotocol.
When multiple test suites are run, either through the --count option or through --test-file, the default behavior of ffx test is: If any test suite times out, halt execution and do not attempt to run any unstarted suites. If any test suite fails for any other reason, continue to run unstarted suites.
trace
Tracing is a tool that allows you to collect, aggregate, and visualize diagnostic tracing information from both userspace processes and the Zircon kernel on a Fuchsia device.
Usage: ffx trace [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| list-categories | List the target's known trace categories. |
| list-category-groups | List the builtin and custom category groups. |
| list-providers | List the target's trace providers. |
| start | Record a trace. |
| status | Gets status of all running traces. |
| stop | Stops an active running trace. |
| symbolize | Symbolizes the provided ordinal |
Examples
\[Quick Start]:
$ ffx trace start \[--duration ]
This will record a trace using the default categories, which are suitable for getting a high
level overview.
This will produce a file `trace.fxt` which can be uploaded to ui.perfetto.dev to be viewed. Notes
For a full tutorial, visit https://fuchsia.dev/fuchsia-src/development/sdk/ffx/record-traces
list-categories
List the target's known trace categories.
Usage: ffx trace list-categories
| Options | |
|---|---|
| display usage information |
list-category-groups
List the builtin and custom category groups.
Usage: ffx trace list-category-groups
| Options | |
|---|---|
| display usage information |
list-providers
List the target's trace providers.
Usage: ffx trace list-providers
| Options | |
|---|---|
| display usage information |
start
Record a trace.
Usage: ffx trace start [--buffering-mode <buffering-mode>] [--buffer-size <buffer-size>] [--categories <categories>] [--duration <duration>] [--output <output>] [--background] [-v] [--trigger <trigger...>] [--no-symbolize] [--no-verify-trace]
| Options | |
|---|---|
| display usage information | |
| the buffering scheme to trace with. Defaults to "oneshot" oneshot: Writes to the tracing buffer until it is full, then ignores all additional trace events. circular: Writes to the tracing buffer until its is full, then new events will replace old events. streaming: Forwards tracing events to the trace manager as they arrive. Provides additional buffer space with the trade off of some overhead due to occasional ipcs to send the events to the trace manager during the trace. | |
| size of per-provider trace buffer in MB. Defaults to 4. | |
comma-separated list of categories to enable. Defaults to "#default". Run ffx config get trace.category_groups.default to see what categories are included in #default. A trailing "" may be used to indicate a prefix match. For example, "kernel" includes any category that starts with kernel. A name prefixed with # indicates a category group that will be expanded from ffx config within the plugin before being sent to trace manager. A category group can either be added to global config by editing data/config.json in the ffx trace plugin, or by using ffx config set to add/edit a user configured category group. Available category groups can be discovered by running ffx config get -s all trace.category_groups A category may be limited to a specific trace provider using a '/'. For example --categories "scenic.cm/FrameDropped" will only enable the "FrameDropped" category for the scenic.cm trace provider and no other providers. Categories and category groups may be mixed, for example, ffx trace start --categories #default,my_category Enables all the default categories as well as "my_category". |
|
| duration of trace capture in seconds. | |
| name of output trace file. Defaults to trace.fxt. | |
| whether to run the trace in the background. Defaults to false, which means the trace will run in "interactive" mode. For a trace started in the background for a specified duration, symbolization is not done by default. | |
| increase verbosity of output on trace stop. Defaults to false. This is ignored if duration is not set. Enabling this prints stats from trace providers including the number of records dropped, wrapped buffers count, % of durable buffer used and non durable bytes written. | |
| 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 " |
|
| prevent symbolization of the trace file. Defaults to false. If the 'kernel:ipc' category is not included in tracing, this flag does nothing. Otherwise this flag will prevent the symbolization of the kernel IPC traces, leaving the ordinals as is in the trace. This flag is only used if tracing is manually stopped. | |
| prevent checking the trace data when stopping tracing. Defaults to false. If this flag is enabled, trace result analysis will not be triggered. |
Examples
\[Quick Start]:
$ ffx trace start \[--duration ]
This will record a trace using the default categories, which are suitable for getting a high
level overview.
This will produce a file `trace.fxt` which can be uploaded to ui.perfetto.dev to be viewed.
\[Trace Various Categories]:
$ ffx trace start --categories '#default,flatland:*,temp'
This will record a trace with all the default categories enabled, 'temp' events enabled, and any
event that starts with 'flatland:'
\[Capturing a Sporadic Occurrence]
$ ffx trace start --buffer-size 64 --buffering-mode circular
This will run the trace with the largest available buffer size, overwriting the old events with new
ones. When the event occurs press to stop the trace.
\[Automatically Capturing a Sporadic Occurrence with a Trigger]
This approach allows you to automatically stop the trace when the event happens, but the traced
code must already be set up to write a trigger event.
$ ffx trace start --buffer-size 64 --buffering-mode circular --trigger ':terminate'
Notes
For a full tutorial, visit https://fuchsia.dev/fuchsia-src/development/sdk/ffx/record-traces
status
Gets status of all running traces.
Usage: ffx trace status
| Options | |
|---|---|
| display usage information |
stop
Stops an active running trace.
Usage: ffx trace stop [--output <output>] [-v] [--no-symbolize] [--no-verify-trace]
| Options | |
|---|---|
| display usage information | |
| 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. | |
| increase verbosity of command output. Defaults to false. Enabling this prints stats from trace providers including the number of records dropped, wrapped buffers count, % of durable buffer used and non durable bytes written. | |
| prevent symbolization of the trace file. Defaults to false. If the 'kernel:ipc' category is not included in tracing, this flag does nothing. Otherwise this flag will prevent the symbolization of the kernel IPC traces, leaving only the ordinals in the trace. | |
| prevent checking the trace data when stopping tracing. Defaults to false. If this flag is enabled, trace result analysis will not be triggered. |
symbolize
Symbolizes the provided ordinal
Usage: ffx trace symbolize [--ordinal <ordinal>] [--fxt <fxt>] [--outfile <outfile>] [--ir-path <ir-path...>]
| Options | |
|---|---|
| display usage information | |
| FIDL ordinal to be symbolized. | |
| trace file to be symbolized. | |
| symbolized file path. Defaults to overwriting the input file. | |
| additional IR files to use for symbolization. Path provided must be absolute or relative to $FUCHSIA_BUILD_DIR. If not provided, only the files listed in $FUCHSIA_BUILD_DIR/all_fidl_json.txt will be checked. |
triage
Analyze Logs and Inspect in snapshots to find problems.
Usage: ffx triage [--config <config...>] [--data <data>] [--tag <tag...>] [--exclude-tag <exclude-tag...>]
| Options | |
|---|---|
| display usage information | |
| path to config file or dir | |
| path to snapshot.zip or uncompressed dir | |
| adds an action tags to include | |
| adds an action tags to exclude |
version
Print out ffx tool and daemon versions
Usage: ffx version [-v]
| Options | |
|---|---|
| display usage information | |
| if true, includes details about both ffx and the daemon |
wlan
Developer tool for manipulating WLAN state.
Usage: ffx wlan [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| ap | Controls WLAN AP policy API. |
| client | Controls WLAN client policy API. |
| deprecated | Controls to-be-deleted WLAN functionality. |
ap
Controls WLAN AP policy API.
Usage: ffx wlan ap [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| listen | Listens for policy AP updates |
| start | Start an access point interface |
| status | Provides the first available AP status update |
| stop | Stop an access point interface |
| stop-all | Stops all active APs |
listen
Listens for policy AP updates
Usage: ffx wlan ap listen
| Options | |
|---|---|
| display usage information |
Examples
To begin listening for AP events
$ ffx wlan ap listenstart
Start an access point interface
Usage: ffx wlan ap start [--ssid <ssid>] [--security-type <security-type>] [--credential-type <credential-type>] [--credential <credential>]
| Options | |
|---|---|
| display usage information | |
| WLAN network name | |
| one of None, WEP, WPA, WPA2, WPA3 | |
| one of None, PSK, Password | |
| WLAN Password or PSK |
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.
status
Provides the first available AP status update
Usage: ffx wlan ap status
| Options | |
|---|---|
| display usage information |
Examples
To query current AP status
$ ffx wlan ap statusstop
Stop an access point interface
Usage: ffx wlan ap stop [--ssid <ssid>] [--security-type <security-type>] [--credential-type <credential-type>] [--credential <credential>]
| Options | |
|---|---|
| display usage information | |
| WLAN network name | |
| one of None, WEP, WPA, WPA2, WPA3 | |
| one of None, PSK, Password | |
| WLAN Password or PSK |
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
Stops all active APs
Usage: ffx wlan ap stop-all
| Options | |
|---|---|
| display usage information |
Examples
To stop all APs
$ ffx wlan ap stop-allNotes
Only one application at a time can interact with the WLAN policy layer.
client
Controls WLAN client policy API.
Usage: ffx wlan client [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| batch-config | Allows WLAN credentials to be extracted and restored. |
| connect | Connect to the specified WLAN network |
| list-saved-networks | Lists all networks saved by the WLAN policy layer. |
| listen | Listens for policy client connections updates |
| 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 |
| status | Provides the first available client status update |
| stop | Stops automated WLAN policy control of client interfaces and |
batch-config
Allows WLAN credentials to be extracted and restored.
Usage: ffx wlan client batch-config [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| dump | Extracts a structured representation of the device's saved WLAN credentials. |
| restore | Injects a structure representation of WLAN credentials into a device. |
dump
Extracts a structured representation of the device's saved WLAN credentials.
Usage: ffx wlan client batch-config dump
| Options | |
|---|---|
| display usage information |
Examples
To dump WLAN client configs
$ ffx wlan client batch-config dumpNotes
Only one application at a time can interact with the WLAN policy layer.
restore
Injects a structure representation of WLAN credentials into a device.
Usage: ffx wlan client batch-config restore serialized_config
| Options | |
|---|---|
| display usage information |
Examples
To restore WLAN client configs
$ ffx wlan client batch-config restore Notes
Only one application at a time can interact with the WLAN policy layer.
connect
Connect to the specified WLAN network
Usage: ffx wlan client connect [--ssid <ssid>] [--security-type <security-type>]
| Options | |
|---|---|
| display usage information | |
| WLAN network name | |
| one of None, WEP, WPA, WPA2, WPA3 |
Examples
To remove a WLAN network
$ffx wlan client connect
--ssid TestNetwork
--security-type wpa2Notes
Only one application at a time can interact with the WLAN policy layer.
list-saved-networks
Lists all networks saved by the WLAN policy layer.
Usage: ffx wlan client list-saved-networks
| Options | |
|---|---|
| display usage information |
Examples
To list saved networks
$ ffx wlan client list-saved-networksNotes
Only one application at a time can interact with the WLAN policy layer.
listen
Listens for policy client connections updates
Usage: ffx wlan client listen
| Options | |
|---|---|
| display usage information |
Examples
To begin listening for client events
$ ffx wlan client listenremove-network
WLAN policy network storage container
Usage: ffx wlan client remove-network [--ssid <ssid>] [--security-type <security-type>] [--credential-type <credential-type>] [--credential <credential>]
| Options | |
|---|---|
| display usage information | |
| WLAN network name | |
| one of None, WEP, WPA, WPA2, WPA3 | |
| one of None, PSK, Password | |
| WLAN Password or PSK |
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
WLAN policy network storage container
Usage: ffx wlan client save-network [--ssid <ssid>] [--security-type <security-type>] [--credential-type <credential-type>] [--credential <credential>]
| Options | |
|---|---|
| display usage information | |
| WLAN network name | |
| one of None, WEP, WPA, WPA2, WPA3 | |
| one of None, PSK, Password | |
| WLAN Password or PSK |
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
Scan for nearby WLAN networks.
Usage: ffx wlan client scan
| Options | |
|---|---|
| display usage information |
Examples
To scan
$ ffx wlan client scanNotes
Only one application at a time can interact with the WLAN policy layer.
start
Allows wlancfg to automate WLAN client operation
Usage: ffx wlan client start
| Options | |
|---|---|
| display usage information |
Examples
To start client connections
$ ffx wlan client startNotes
Only one application at a time can interact with the WLAN policy layer.
status
Provides the first available client status update
Usage: ffx wlan client status
| Options | |
|---|---|
| display usage information |
Examples
To query client status
$ ffx wlan client statusstop
Stops automated WLAN policy control of client interfaces and destroys all client interfaces.
Usage: ffx wlan client stop
| Options | |
|---|---|
| display usage information |
Examples
To stop client connections
$ ffx wlan client stopNotes
Only one application at a time can interact with the WLAN policy layer.
deprecated
Controls to-be-deleted WLAN functionality.
Usage: ffx wlan deprecated [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| suggest-mac | Notifies WLAN policy of a MAC address that ought to be used when creating new AP interfaces |
suggest-mac
Notifies WLAN policy of a MAC address that ought to be used when creating new AP interfaces
Usage: ffx wlan deprecated suggest-mac mac
| Options | |
|---|---|
| display usage information |
Examples
To suggest an AP MAC address
$ ffx wlan deprecated suggest-mac 01:02:03:04:05:06wm
Control views presented by the window manager.
Usage: ffx wm [subcommand...]
| Options | |
|---|---|
| display usage information |
| Subcommands | |
|---|---|
| cycle | Shift all views forward by one position, view at position 0 is moved to the end. |
| focus | Focus the position and viewId of all windows currently presented in the session. |
| list | List the position and viewId of all windows currently presented in the session. |
| set-order | Re-order the window currently at old_position to be placed at new_position. |
Notes
The
wmsubcommand contains various commands that allow us to manipulate and inspect views being presented by the window manager component.
cycle
Shift all views forward by one position, view at position 0 is moved to the end.
Usage: ffx wm cycle
| Options | |
|---|---|
| display usage information |
focus
Focus the position and viewId of all windows currently presented in the session.
Usage: ffx wm focus position
| Options | |
|---|---|
| display usage information |
list
List the position and viewId of all windows currently presented in the session.
Usage: ffx wm list
| Options | |
|---|---|
| display usage information |
set-order
Re-order the window currently at old_position to be placed at new_position.
Usage: ffx wm set-order old-position new-position
| Options | |
|---|---|
| display usage information |