1 page.title=Configuring the File System 2 @jd:body 3 4 <!-- 5 Copyright 2015 The Android Open Source Project 6 7 Licensed under the Apache License, Version 2.0 (the "License"); 8 you may not use this file except in compliance with the License. 9 You may obtain a copy of the License at 10 11 http://www.apache.org/licenses/LICENSE-2.0 12 13 Unless required by applicable law or agreed to in writing, software 14 distributed under the License is distributed on an "AS IS" BASIS, 15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 16 See the License for the specific language governing permissions and 17 limitations under the License. 18 --> 19 20 <div id="qv-wrapper"> 21 <div id="qv"> 22 <h2>In this document</h2> 23 <ol id="auto-toc"> 24 </ol> 25 </div> 26 </div> 27 28 <h2 id=abstract>Abstract</h2> 29 30 <p>This document describes impending changes to the manner in which the Android 31 file system is configured.</p> 32 33 <p>The Android file system configuration file (<code>system/core/include/private/android_filesystem_config.h</code>) is not extensible in that device manufacturers have no means to add their own 34 named binaries to the list to specify Discretionary Access Controls (DAC) of 35 ownership, access mode, or executable capabilities. This limitation is shown 36 with the introduction of support for Linux kernels 3.14 and higher where the 37 wake lock is enabled via a capability <code>CAP_SUSPEND_BLOCK</code>; partner-supplied GPS daemons will need to hold this wake lock and thus have 38 this capability set in the file system.</p> 39 40 <p>Therefore, the Android M release is planned to move both the <code>fs_config</code> inline and the structure definitions in <code>system/core/include/private/android_filesystem_config.h</code> that it feeds on into <code>system/core/libcutils/fs_config.c</code> to be updated or overridden by binary files installed in <code>/system/etc/fs_config_dirs </code>and<code> /system/etc/fs_config_files</code>.</p> 41 42 <h2 id=implementation>Implementation</h2> 43 44 <p>Separate matching and parsing rules exist for directories and files. Files get 45 the advantage of utilizing additional glob expressions. Files and Directories 46 are handled separately by two different tables.</p> 47 48 <p>The Android M release will remove the <code>fs_config</code> inline and the structure definitions that it feeds on, and place the code and 49 default definitions into <code>system/core/libcutils/fs_config.c</code>. The <code>fs_config.c</code> file is modified beyond the basic definition to allow runtime reading of <code>/system/etc/fs_config_dirs</code> and <code>/system/etc/fs_config_files</code> to garner override that the device manufacturer would wish to extend. The same 50 files accessed during build time to construct filesystem images as <code>${OUT}/system/etc/fs_config_dirs</code> and <code>${OUT}/system/etc/fs_config_files</code> may be used on the host.</p> 51 52 <p><strong>Caution</strong>: This change is disruptive, as it removes some includes, structures and inline 53 definitions; it also adds a need to refer to <code>libcutils</code> instead of running directly from <code>system/core/include/private/android_filesystem_config.h</code>. It also requires all device manufacturers to be informed that the location 54 for adjustments for file system configuration has changed.</p> 55 56 <p>There is also a tool to generate the aligned binary files <code>/system/etc/fs_config_dirs</code> and <code>/system/etc/fs_config_files</code> content that is delivered on the target.</p> 57 58 <p>A new function in <code>libcutils</code> - <code>fs_config_generate()</code> - is used to manage the DAC requirements into a buffer. <code>build/tools/fs_config</code> in turn houses the new tool <code>fs_config_generate</code> that uses this library function and defines rules for an include file to 59 institutionalize the DAC rules. It expects an include file in <code>device/<vendor>/<device>/android_filesystem_config.h</code> to act as the override in <code>structure fs_path_config</code> format as defined in <code>system/core/include/private/android_filesystem_config.h</code>, except defining the structure initialization for the symbols struct 60 fs_path_config android<strong>_device</strong>_dirs[] and struct fs_path_config android<strong>_device</strong>_files[] for directories and files, respectively. See the example below.</p> 61 62 <p>The override file may also be specified using <code>TARGET_ANDROID_FILESYSTEM_CONFIG_H </code>in the board configuration, with an enforced basename of <code>android_filesystem_config.h</code>. Finally, <code>PRODUCT_PACKAGES</code> must include <code>fs_config_dirs</code> and/or <code>fs_config_files</code> in order to install them to <code>/system/etc/fs_config_dirs</code> and <code>/system/etc/fs_config_files</code>, respectively.</p> 63 64 <h3 id=instructions>Instructions</h3> 65 66 <p>Follow these steps to configure the Android file system in the M release and 67 later.</p> 68 69 <ol> 70 <li> Create the <code>$(TARGET_DEVICE_DIR)/android_filesystem_config.h</code> file 71 <li> Add the <code>fs_config_dirs</code> and/or <code>fs_config_files</code> to <code>PRODUCT_PACKAGES </code>in the board configuration file (eg: <code>$(TARGET_DEVICE_DIR)/device.mk</code>) 72 </ol> 73 74 <h3 id=example>Example</h3> 75 76 <p>In order to activate an override for the<code> system/bin/glgps</code> daemon to add wake lock support, one would do something like this within the <code>device/<vendor>/<device></code> directory (in patch format, relevant actions are highlighted for clarity):</p> 77 78 <pre> 79 diff --git a/android_filesystem_config.h b/android_filesystem_config.h 80 new file mode 100644 81 index 0000000..874195f 82 --- /dev/null 83 +++ b/android_filesystem_config.h 84 @@ -0,0 +1,36 @@ 85 +/* 86 + * Copyright (C) 2015 The Android Open Source Project 87 + * 88 + * Licensed under the Apache License, Version 2.0 (the "License"); 89 + * you may not use this file except in compliance with the License. 90 + * You may obtain a copy of the License at 91 + * 92 + * http://www.apache.org/licenses/LICENSE-2.0 93 + * 94 + * Unless required by applicable law or agreed to in writing, software 95 + * distributed under the License is distributed on an "AS IS" BASIS, 96 + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 97 + * implied. See the License for the specific language governing 98 + * permissions and limitations under the License. 99 + */ 100 + 101 +/* This file is used to define the properties of the filesystem 102 +** images generated by build tools (eg: mkbootfs) and 103 +** by the device side of adb. 104 +*/ 105 + 106 +#define NO_ANDROID_FILESYSTEM_CONFIG_DEVICE_DIRS 107 +/* static const struct fs_path_config android_device_dirs[] = { }; */ 108 + 109 +/* Rules for files. 110 +** These rules are applied based on "first match", so they 111 +** should start with the most specific path and work their 112 +** way up to the root. Prefixes ending in * denotes wildcard 113 +** and will allow partial matches. 114 +*/ 115 +static const struct fs_path_config android_device_files[] = { 116 + { 00755, AID_ROOT, AID_SHELL, (1ULL << CAP_BLOCK_SUSPEND), 117 "system/bin/glgps" }, 118 +#ifdef NO_ANDROID_FILESYSTEM_CONFIG_DEVICE_DIRS 119 + { 00000, AID_ROOT, AID_ROOT, 0, "system/etc/fs_config_dirs" }, 120 +#endif 121 +}; 122 123 124 diff --git a/device.mk b/device.mk 125 index 0c71d21..235c1a7 100644 126 --- a/device.mk 127 +++ b/device.mk 128 @@ -18,7 +18,8 @@ PRODUCT_PACKAGES := \ 129 libwpa_client \ 130 hostapd \ 131 wpa_supplicant \ 132 - wpa_supplicant.conf 133 + wpa_supplicant.conf \ 134 + fs_config_files 135 136 ifeq ($(TARGET_PREBUILT_KERNEL),) 137 ifeq ($(USE_SVELTE_KERNEL), true) 138 </pre> 139 140 <h3 id=checklist>Checklist</h3> 141 142 <ol> 143 <li> <code>NO_ANDROID_FILESYSTEM_CONFIG_DEVICE_DIRS</code> and <code>NO_ANDROID_FILESYSTEM_CONFIG_DEVICE_FILES</code> are available to be defined when android_device_dirs[] and 144 android_device_files[] is not being filled out. 145 146 <li> Each structure entry is the mode, uid, gid, capabilities and the name. <code>system/core/include/private/android_filesystem_config.h</code> has been included already automatically to provide the manifest defines (<code>AID_ROOT</code>, <code>AID_SHELL</code>, <code>CAP_BLOCK_SUSPEND</code> in the above). 147 148 <li> The action above in the example android_device_files[] to suppress access to <code>system/etc/fs_config_dirs</code> when we have not specified it will act as an additional DAC protection for our 149 lack of any content for the directory overrides. It is considered pedantic weak 150 protection since if someone has control over<code> /system</code>, they can typically do anything they want. 151 152 <li> The build system searches for the custom <code>android_filesystem_config.h</code> in <code>$(TARGET_DEVICE_DIR)</code>, in which the BoardConfig.mk exists. You can also set board config variable <code>TARGET_ANDROID_FILESYSTEM_CONFIG_H</code> to point to the file, if it exists elsewhere. 153 154 <li> On the target system, we reserve the right to apply SELinux Mandatory Access 155 Controls (MAC) to these configuration files. Please check if you have custom 156 target executables that utilize fs_config() to make sure you permit access if 157 not provided otherwise. 158 </ol> 159 160 <h3 id=architectural_concerns>Architectural Concerns</h3> 161 162 <ul> 163 <li> Device manufacturer private branch copies of the <code>system/core/include/private/android_filesystem_config.h</code> with extra content on existing targets will have to move over to: <code>device/<vendor>/<device>/android_filesystem_config.h</code> 164 <li> Device manufacturer private executables that depend on <code>system/code/include/private_filesystem_config.h</code> for the file or directory structures or <code>fs_config</code> will have to add <code>libcutils</code> library dependencies. 165
