The ffx component explore command starts an interactive shell that lets you explore
the internals of Fuchsia components running on a target device.
Concepts
The ffx component explore command launches a Dash process scoped
to the target component. Using this Dash process, you can:
- Use familiar POSIX commands such as
ls,catandgrep. - Explore the component's incoming and outgoing capabilities.
Dash is the command interpreter previously used in other tools in the Fuchsia project,
such as fx shell, serial console, terminal windows, and virtcon. Dash provides
ffx component explore a familiar experience to developers, such as cd and ls, for
navigating spaces in a Fuchsia component, for example:
[host]$ ffx component explore /bootstrap/archivist
Moniker: /bootstrap/archivist
$ ls
exposed
ns
out
runtime
svc
$
However, unlike fx shell, the namespace only contains the component's incoming
and outgoing capabilities. This restriction means you can explore in an environment almost
identical to what the component sees.
Explore a component
To connect to a Fuchsia component and start an interactive shell, run the following command:
ffx component explore COMPONENT_IDENTIFIER
Replace COMPONENT_IDENTIFIER with the moniker, URL, or instance ID of your target component. The command also accepts a unique partial match on these identifiers.
The example command below starts an interactive shell ($) for exploring the
/bootstrap/archivst component:
[host]$ ffx component explore /bootstrap/archivist
Moniker: /bootstrap/archivist
$
In all examples in this guide, the shell prompt from the host machine's terminal is
represented as [host]$ while the prompt from the component's interactive shell is
represented as $ alone, without the [host] prefix. To put it differently,
[host]$ means that the command is run on the host machine's terminal while $
means the command is run on the interactive shell connected to the target component.
This guide also uses /bootstrap/archivist (which is a moniker) for the target component
in most examples. In practice, this argument should be replaced with the component identifier
of your target component.
Explore capabilities available to a component
To explore the capabilities of the target component, navigate to the /ns directory
in the component's interactive shell. The /ns directory contains the component's
namespace, exactly as the component would see it, for example:
[host]$ ffx component explore /bootstrap/archivist
Moniker: /bootstrap/archivist
$ cd ns
$ ls
config
events
pkg
svc
If you want the shell's namespace to match the component namespace,
use the -l (or --layout) flag, for example:
[host]$ ffx component explore /bootstrap/archivist -l namespace
Moniker: /bootstrap/archivist
$ ls
config
events
pkg
svc
For more details on these directories, see What is the namespace root in ffx component explore?.
Explore capabilities exposed by a component
The /exposed directory contains the capabilities exposed from your target
component to its parent, for example:
[host]$ ffx component explore /bootstrap/archivist
Moniker: /bootstrap/archivist
$ cd exposed
$ ls
diagnostics
fuchsia.diagnostics.ArchiveAccessor
fuchsia.diagnostics.FeedbackArchiveAccessor
fuchsia.diagnostics.LegacyMetricsArchiveAccessor
fuchsia.diagnostics.LoWPANArchiveAccessor
fuchsia.diagnostics.LogSettings
fuchsia.logger.Log
fuchsia.logger.LogSink
Explore capabilities served by a component
If the target component is running on the device, the /out directory
contains all the capabilities currently served by the component, for
example:
[host]$ ffx component explore /bootstrap/archivist
Moniker: /bootstrap/archivist
$ cd out
$ ls
diagnostics
svc
$ cd svc
$ ls
fuchsia.diagnostics.ArchiveAccessor
fuchsia.diagnostics.FeedbackArchiveAccessor
fuchsia.diagnostics.LegacyMetricsArchiveAccessor
fuchsia.diagnostics.LoWPANArchiveAccessor
fuchsia.diagnostics.LogSettings
fuchsia.logger.Log
Explore debug runtime data of a component
If the target component is running on the device, the /runtime directory
contains debug information provided by the component runner, for example:
[host]$ ffx component explore /bootstrap/archivist
Moniker: /bootstrap/archivist
$ cd runtime/elf
$ ls
job_id
process_id
process_start_time
$ cat process_id
2542
Use a custom command-line tool in the component's shell
To add custom command-line tools into the target component's shell environment, use
the --tools flag to provide the URLs of tools packages to the ffx component explore
command, for example:
[host]$ ffx component explore /core/network --tools fuchsia-pkg://fuchsia.com/net-cli
Moniker: /core/network
$ net help
Usage: net <command> [<args>]
commands for net-cli
Options:
--help display usage information
Commands:
filter commands for packet filter
if commands for network interfaces
log commands for logging
neigh commands for neighbor tables
route commands for routing tables
dhcp commands for an interfaces dhcp client
dhcpd commands to control a dhcp server
dns commands to control the dns resolver
Run a command on the component's shell non-interactively
To run a command in the component's on-device shell non-interactively and receive
stdout, stderr, and exit code, use the -c (or --command) flag, for example:
[host]$ ffx component explore /bootstrap/archivist -c "cat /runtime/elf/process_id"
Moniker: /bootstrap/archivist
2542
Appendices
Why can't I see child components from the parent?
Fuchsia does not allow accessing child components directly from the parent.
Previously, using knowledge of the component topology to access a child component's
capabilities made tools brittle in fx shell, and in other tools that used to keep
hard-coded paths to /hub-v2 which encoded knowledge about the system topology.
Instead, the following alternatives are recommended:
- Route capabilities explicitly from the child to the parent component.
- Explore the child component itself.
How is this different from ffx component run?
The ffx component run command creates and starts a component
in a specified collection within the component topology. However, ffx component run
offers no interactive capabilities. On the other hand, ffx component explore allows
exploring any existing component in the topology interactively. In summary, you can use
ffx component explore to learn about a component you just created using
ffx component run.
What is the namespace root in ffx component explore?
By default, the ffx component explore command creates a virtual file system at the
namespace root (/) that contains the following directories:
| Directory | Description |
|---|---|
/.dash |
Contains binaries needed by Dash. |
/exposed |
Contains all exposed capabilities. |
/ns
|
Contains the component's namespace, exactly as your component would see it. |
/svc |
Contains capabilities needed by Dash. |
If the target component is running on the device, the following directories are also present:
| Directory | Description |
|---|---|
/out |
Contains all capabilities currently being served by the component. |
/runtime |
Contains debug information served by the component’s runner. |
If the --layout namespace flag is set in ffx component explore, the shell's
namespace will match the component's namespace.
Can I access Zircon handles or make FIDL calls using the Dash shell?
This is not supported directly from the command interpreter.
How do I file a feature request for ffx component explore?
File all feature requests under the
ComponentFramework > Tools Monorail
component.