The ffx component explore
command starts an interactive shell that lets you explore the internals of Fuchsia components running on a target device.
The ffx component explore
command launches a Dash{:.external} process scoped to the target component. Using this Dash process, you can:
ls
, cat
and grep
.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 $ {{ '<strong>' }}ls{{ '</strong>' }} exposed ns out runtime svc $
Note: The filesystem used in Dash is not POSIX-compliant. Capabilities are presented as files and directories to aid in navigation.
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.
To connect to a Fuchsia component and start an interactive shell, run the following command:
ffx component explore {{ '<var>' }}COMPONENT_IDENTIFIER{{ '</var>' }}
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.
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 $ {{ '<strong>' }}cd ns{{ '</strong>' }} $ {{ '<strong>' }}ls{{ '</strong>' }} 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 $ {{ '<strong>' }}ls{{ '</strong>' }} config events pkg svc
For more details on these directories, see What is the namespace root in ffx component explore?.
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 $ {{ '<strong>' }}cd exposed{{ '</strong>' }} $ {{ '<strong>' }}ls{{ '</strong>' }} diagnostics fuchsia.diagnostics.ArchiveAccessor fuchsia.diagnostics.FeedbackArchiveAccessor fuchsia.diagnostics.LegacyMetricsArchiveAccessor fuchsia.diagnostics.LoWPANArchiveAccessor fuchsia.diagnostics.LogSettings fuchsia.logger.Log fuchsia.logger.LogSink
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 $ {{ '<strong>' }}cd out{{ '</strong>' }} $ {{ '<strong>' }}ls{{ '</strong>' }} diagnostics svc $ {{ '<strong>' }}cd svc{{ '</strong>' }} $ {{ '<strong>' }}ls{{ '</strong>' }} fuchsia.diagnostics.ArchiveAccessor fuchsia.diagnostics.FeedbackArchiveAccessor fuchsia.diagnostics.LegacyMetricsArchiveAccessor fuchsia.diagnostics.LoWPANArchiveAccessor fuchsia.diagnostics.LogSettings fuchsia.logger.Log
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 $ {{ '<strong>' }}cd runtime/elf{{ '</strong>' }} $ {{ '<strong>' }}ls{{ '</strong>' }} job_id process_id process_start_time $ {{ '<strong>' }}cat process_id{{ '</strong>' }} 2542
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 $ {{ '<strong>' }}net help{{ '</strong>' }} 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
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
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:
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
.
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.
This is not supported directly from the command interpreter.
File all feature requests under the ComponentFramework > Tools
{:.external} Issue Tracker component.