Explore components

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, cat and grep.
  • 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 and dependent on hard-coded paths that 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 Issue Tracker component.