Network stack configuration tools

The Android operating system contains standard Linux networking utilities such as ifconfig, ip, and ip6tables. These utilities reside on the system image and enable configuration of the entire Linux networking stack. On devices running Android 7.x and lower, vendor code is allowed to call these binaries directly, which presents the following problems:

  • Because network utilities are updated in the system image, they don't provide a stable implementation.
  • The scope of the networking utilities is so broad it is difficult to evolve the system image while guaranteeing predictable behaviour.

On devices running Android 8.0 and higher, the vendor partition remains the same while the system partition receives an update. To achieve this, Android 8.0 provides the ability to define a stable, versioned interface while also using SELinux restrictions to keep the interdependency of vendor and system image to a known good set.

Vendors can use the platform-provided network configuration utilities to configure the Linux networking stack, but these utilities don't yet include a HIDL interface wrapper. To define such an interface, Android 8.0 includes the netutils-wrapper-1.0 tool.

Netutils wrapper

The netutils wrapper utility provides a subset of the Linux network stack configuration that isn't affected by system partition updates. Android 8.0 contains version 1.0 of the wrappers, which allows you to pass the same arguments as the wrapped utilities, installed in the system partition at /system/bin as follows:

u:object_r:system_file:s0           /system/bin/ip-wrapper-1.0 -> netutils-wrapper-1.0
u:object_r:system_file:s0           /system/bin/ip6tables-wrapper-1.0 -> netutils-wrapper-1.0
u:object_r:system_file:s0           /system/bin/iptables-wrapper-1.0 -> netutils-wrapper-1.0
u:object_r:system_file:s0           /system/bin/ndc-wrapper-1.0 -> netutils-wrapper-1.0
u:object_r:netutils_wrapper_exec:s0 /system/bin/netutils-wrapper-1.0
u:object_r:system_file:s0           /system/bin/tc-wrapper-1.0 -> netutils-wrapper-1.0

Symlinks show the networking utilities wrapped by the netutils wrapper, which include:

  • ip
  • iptables
  • ip6tables
  • ndc
  • tc

To use these utilities in Android 8.0 and higher, vendor implementations must adhere to the following rules:

  • Vendor processes must not execute /system/bin/netutils-wrapper-1.0 directly; attempts to do so results in error.
  • All utilities wrapped by netutils-wrapper-1.0 must be launched using their symlinks. For example, change the vendor code that did this before (/system/bin/ip <FOO> <BAR>) to /system/bin/ip-wrapper-1.0 <FOO> <BAR>.
  • Executing the wrappers without domain transition is prohibited in platform SELinux policy. This rule must not be changed and is tested against in the Android Compatibility Test Suite (CTS).
  • Executing the utilities directly (e.g., /system/bin/ip <FOO> <BAR>) from the vendor processes is also prohibited in the platform SELinux policies. This rule must not be changed and is tested against in CTS.
  • Any vendor domain (process) that needs to launch a wrapper must add the following domain transition rule in the SELinux policy: domain_auto_trans(VENDOR-DOMAIN-NAME, netutils_wrapper_exec, netutils_wrapper).

Netutils wrapper filters

Wrapped utilities can be used to configure almost any aspect of the Linux networking stack. However, to ensure it is possible to maintain a stable interface and allow updates to the system partition, only certain combinations of command line arguments are allowed; other commands are rejected.

Vendor interfaces and chains

The wrapper has a concept of vendor interfaces. These are interfaces typically managed by vendor code, such as cellular data interfaces. Typically, other types of interfaces (such as Wi-Fi) are managed by the HALs and the framework. The wrapper recognizes vendor interfaces by name (using a regular expression) and allows vendor code to perform many operations on them. Currently, vendor interfaces are:

  • Interfaces whose names end in "oem" followed by a number, such as oem0 or r_oem1234.
  • Interfaces used by current SOC and OEM implementations, such as rmnet_data[0-9].

Names of interfaces that are typically managed by the framework (such as wlan0) are never vendor interfaces.

The wrapper has a similar concept of vendor chains. These are used in iptables commands and are also recognized by name. Currently, vendor chains:

  • Start with oem_.
  • Are used by current SOC and OEM implementations, e.g., chains starting in nm_ or qcom_.

Allowed commands

Currently allowed commands are listed below. Restrictions are implemented via a set of regular expressions on the executed command lines. For details, refer to system/netd/netutils_wrappers/NetUtilsWrapper-1.0.cpp.

ip

The ip command is used to configure IP addresses, routing, IPsec encryption, and a number of other network parameters. The wrapper allows the following commands:

  • Add and remove IP addresses from vendor-managed interfaces.
  • Configure IPsec encryption.

iptables and ip6tables

The iptables and ip6tables commands are used to configure firewalling, packet mangling, NAT, and other per-packet processing. The wrapper allows the following commands:

  • Add and delete vendor chains.
  • Add and delete rules in any chain that refers to packets going into (-i) or out of (-o) a vendor interface.
  • Jump to a vendor chain from any point in any other chain.

ndc

ndc is used to communicate to the netd daemon that performs most network configuration on Android. The wrapper allows the following commands:

  • Create and destroy OEM networks (oemXX).
  • Add vendor-managed interfaces to OEM networks.
  • Add routes to OEM networks.
  • Enable or disable IP forwarding globally and on vendor interfaces.

tc

The tc command is used to configure traffic queueing and shaping on vendor interfaces.