Configuring the File System

Configuring the File System

Abstract

---

This document describes impending changes to the manner in which the Android file system is configured.

The Android file system configuration file (system/core/include/private/android_filesystem_config.h) is not extensible in that device manufacturers have no means to add their own named binaries to the list to specify Discretionary Access Controls (DAC) of ownership, access mode, or executable capabilities. This limitation is shown with the introduction of support for Linux kernels 3.14 and higher where the wake lock is enabled via a capability CAP_SUSPEND_BLOCK; partner-supplied GPS daemons will need to hold this wake lock and thus have this capability set in the file system.

Therefore, the Android M release is planned to move both the fs_config inline and the structure definitions in system/core/include/private/android_filesystem_config.h that it feeds on into system/core/libcutils/fs_config.c to be updated or overridden by binary files installed in /system/etc/fs_config_dirs and /system/etc/fs_config_files.

Implementation

---

Separate matching and parsing rules exist for directories and files. Files get the advantage of utilizing additional glob expressions. Files and Directories are handled separately by two different tables.

The Android M release will remove the fs_config inline and the structure definitions that it feeds on, and place the code and default definitions into system/core/libcutils/fs_config.c. The fs_config.c file is modified beyond the basic definition to allow runtime reading of /system/etc/fs_config_dirs and /system/etc/fs_config_files to garner override that the device manufacturer would wish to extend. The same files accessed during build time to construct filesystem images as ${OUT}/system/etc/fs_config_dirs and ${OUT}/system/etc/fs_config_files may be used on the host.

Caution: This change is disruptive, as it removes some includes, structures and inline definitions; it also adds a need to refer to libcutils instead of running directly from system/core/include/private/android_filesystem_config.h. It also requires all device manufacturers to be informed that the location for adjustments for file system configuration has changed.

There is also a tool to generate the aligned binary files /system/etc/fs_config_dirs and /system/etc/fs_config_files content that is delivered on the target.

A new function in libcutils - fs_config_generate() - is used to manage the DAC requirements into a buffer. build/tools/fs_config in turn houses the new tool fs_config_generate that uses this library function and defines rules for an include file to institutionalize the DAC rules. It expects an include file in device///android_filesystem_config.h to act as the override in structure fs_path_config format as defined in system/core/include/private/android_filesystem_config.h, except defining the structure initialization for the symbols struct fs_path_config android_device_dirs[] and struct fs_path_config android_device_files[] for directories and files, respectively. See the example below.

The override file may also be specified using TARGET_ANDROID_FILESYSTEM_CONFIG_H in the board configuration, with an enforced basename of android_filesystem_config.h. Finally, PRODUCT_PACKAGES must include fs_config_dirs and/or fs_config_files in order to install them to /system/etc/fs_config_dirs and /system/etc/fs_config_files, respectively.

Instructions

Follow these steps to configure the Android file system in the M release and later.

1. Create the $(TARGET_DEVICE_DIR)/android_filesystem_config.h file
2. Add the fs_config_dirs and/or fs_config_files to PRODUCT_PACKAGES in the board configuration file (eg: $(TARGET_DEVICE_DIR)/device.mk)

Example

In order to activate an override for the system/bin/glgps daemon to add wake lock support, one would do something like this within the device// directory (in patch format, relevant actions are highlighted for clarity):

diff --git a/android_filesystem_config.h b/android_filesystem_config.h
new file mode 100644
index 0000000..874195f
--- /dev/null
+++ b/android_filesystem_config.h
@@ -0,0 +1,36 @@
+/*
+ * Copyright (C) 2015 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ * implied. See the License for the specific language governing
+ * permissions and limitations under the License.
+ */
+
+/* This file is used to define the properties of the filesystem
+** images generated by build tools (eg: mkbootfs) and
+** by the device side of adb.
+*/
+
+#define NO_ANDROID_FILESYSTEM_CONFIG_DEVICE_DIRS
+/* static const struct fs_path_config android_device_dirs[] = { }; */
+
+/* Rules for files.
+** These rules are applied based on "first match", so they
+** should start with the most specific path and work their
+** way up to the root. Prefixes ending in * denotes wildcard
+** and will allow partial matches.
+*/
+static const struct fs_path_config android_device_files[] = {
+  { 00755, AID_ROOT, AID_SHELL, (1ULL << CAP_BLOCK_SUSPEND),
"system/bin/glgps" },
+#ifdef NO_ANDROID_FILESYSTEM_CONFIG_DEVICE_DIRS
+  { 00000, AID_ROOT, AID_ROOT, 0, "system/etc/fs_config_dirs" },
+#endif
+};


diff --git a/device.mk b/device.mk
index 0c71d21..235c1a7 100644
--- a/device.mk
+++ b/device.mk
@@ -18,7 +18,8 @@ PRODUCT_PACKAGES := \
     libwpa_client \
     hostapd \
     wpa_supplicant \
-    wpa_supplicant.conf
+    wpa_supplicant.conf \
+    fs_config_files
 
 ifeq ($(TARGET_PREBUILT_KERNEL),)
 ifeq ($(USE_SVELTE_KERNEL), true)

Checklist

1. NO_ANDROID_FILESYSTEM_CONFIG_DEVICE_DIRS and NO_ANDROID_FILESYSTEM_CONFIG_DEVICE_FILES are available to be defined when android_device_dirs[] and android_device_files[] is not being filled out.
2. Each structure entry is the mode, uid, gid, capabilities and the name. system/core/include/private/android_filesystem_config.h has been included already automatically to provide the manifest defines (AID_ROOT, AID_SHELL, CAP_BLOCK_SUSPEND in the above).
3. The action above in the example android_device_files[] to suppress access to system/etc/fs_config_dirs when we have not specified it will act as an additional DAC protection for our lack of any content for the directory overrides. It is considered pedantic weak protection since if someone has control over /system, they can typically do anything they want.
4. The build system searches for the custom android_filesystem_config.h in $(TARGET_DEVICE_DIR), in which the BoardConfig.mk exists. You can also set board config variable TARGET_ANDROID_FILESYSTEM_CONFIG_H to point to the file, if it exists elsewhere.
5. On the target system, we reserve the right to apply SELinux Mandatory Access Controls (MAC) to these configuration files. Please check if you have custom target executables that utilize fs_config() to make sure you permit access if not provided otherwise.

Architectural Concerns

• Device manufacturer private branch copies of the system/core/include/private/android_filesystem_config.h with extra content on existing targets will have to move over to: device///android_filesystem_config.h
• Device manufacturer private executables that depend on system/code/include/private_filesystem_config.h for the file or directory structures or fs_config will have to add libcutils library dependencies.