1 <html devsite> 2 <head> 3 <title>File DAC Configuration</title> 4 <meta name="project_path" value="/_project.yaml" /> 5 <meta name="book_path" value="/_book.yaml" /> 6 </head> 7 <body> 8 <!-- 9 Copyright 2017 The Android Open Source Project 10 11 Licensed under the Apache License, Version 2.0 (the "License"); 12 you may not use this file except in compliance with the License. 13 You may obtain a copy of the License at 14 15 http://www.apache.org/licenses/LICENSE-2.0 16 17 Unless required by applicable law or agreed to in writing, software 18 distributed under the License is distributed on an "AS IS" BASIS, 19 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 20 See the License for the specific language governing permissions and 21 limitations under the License. 22 --> 23 24 25 <p>Earlier versions of Android used a system configuration file that was 26 not extensible, preventing device manufacturers from adding named binaries to 27 specify Discretionary Access Controls (DAC) of ownership, access mode, or 28 executable capabilities. This limitation occurred as a result of support for 29 Linux kernels 3.14 and higher in which wake lock is enabled via the 30 <code>CAP_SUSPEND_BLOCK</code> capability; partner-supplied GPS daemons were 31 required to hold this wake lock (and thus have this capability set in the file 32 system).</p> 33 34 <p>As of Android 6.0, <code>fs_config</code> and associated structure definitions 35 (<code>system/core/include/private/android_filesystem_config.h</code>) are now 36 located in <code>system/core/libcutils/fs_config.c</code> where they can be 37 updated or overridden by binary files installed in 38 <code>/system/etc/fs_config_dirs</code> and 39 <code>/system/etc/fs_config_files</code>. For clarity, Android uses separate 40 matching and parsing rules for directories and files (which can use additional 41 glob expressions) and handles directories and files in two different tables. 42 Structure definitions in <code>system/core/libcutils/fs_config.c</code> not only 43 allow runtime reading of directories and files, but the host may use the same 44 files during build time to construct filesystem images as 45 <code>${OUT}/system/etc/fs_config_dirs</code> and 46 <code>${OUT}/system/etc/fs_config_files</code>.</p> 47 48 <h2 id=gen-files>Generating override files</h2> 49 50 <p>You can generate the aligned binary files 51 <code>/system/etc/fs_config_dirs</code> and 52 <code>/system/etc/fs_config_files</code> using the 53 <code>fs_config_generate</code> tool in <code>build/tools/fs_config</code>. The 54 tool uses a <code>libcutils</code> library function 55 (<code>fs_config_generate()</code>) to manage DAC requirements into a buffer 56 and defines rules for an include file to institutionalize the DAC rules.</p> 57 58 <p>To use, create an include file in 59 <code>device/<em>vendor</em>/<em>device</em>/android_filesystem_config.h</code> 60 that acts as the override. The file must use the 61 <code>structure fs_path_config</code> format defined in 62 <code>system/core/include/private/android_filesystem_config.h</code> with the 63 following structure initializations for directory and file symbols:</p> 64 <ul> 65 <li>For directories, use <code>android<strong>_device</strong>_dirs[]</code>.</li> 66 <li>For files, use <code>android<strong>_device</strong>_files[]</code>.</li> 67 </ul> 68 69 <p>When not using <code>android_device_dirs[]</code> and 70 <code>android_device_files[]</code>, you can define 71 <code>NO_ANDROID_FILESYSTEM_CONFIG_DEVICE_DIRS</code> and <code>NO_ANDROID_FILESYSTEM_CONFIG_DEVICE_FILES</code> (see the 72 <a href="#example">example</a> below).</p> 73 74 <p>You can also specify the 75 override file using <code>TARGET_ANDROID_FILESYSTEM_CONFIG_H</code> in the board 76 configuration, with an enforced basename of 77 <code>android_filesystem_config.h</code>. 78 79 <h2 id=include-files>Including files</h2> 80 81 <p><code>PRODUCT_PACKAGES</code> must include <code>fs_config_dirs</code> 82 and/or <code>fs_config_files</code> to install them to 83 <code>/system/etc/fs_config_dirs</code> and 84 <code>/system/etc/fs_config_files</code>, respectively.</p> 85 86 <p>The build system searches for custom <code>android_filesystem_config.h</code> 87 in <code>$(TARGET_DEVICE_DIR)</code>, where <code>BoardConfig.mk</code> exists. 88 If this file exists elsewhere, set board config variable 89 <code>TARGET_ANDROID_FILESYSTEM_CONFIG_H</code> to point to that location.</p> 90 91 <h2 id=configuring>Configuring</h2> 92 <p>To configure the file system in Android 6.0 and higher:</p> 93 94 <ol> 95 <li>Create the <code>$(TARGET_DEVICE_DIR)/android_filesystem_config.h</code> 96 file.</li> 97 <li>Add the <code>fs_config_dirs</code> and/or <code>fs_config_files</code> to 98 <code>PRODUCT_PACKAGES </code>in the board configuration file (e.g., 99 <code>$(TARGET_DEVICE_DIR)/device.mk</code>).</li> 100 </ol> 101 102 <h2 id=migration-concerns>Migration concerns</h2> 103 <p>Migrating system configurations from Android 5.0 and earlier can be 104 disruptive. When planning such a migration, keep in mind that Android 6.0:</p> 105 <ul> 106 <li>Removes some includes, structures, and inline definitions.</li> 107 <li>Requires a reference to <code>libcutils</code> instead of running directly 108 from <code>system/core/include/private/android_filesystem_config.h</code>. 109 Device manufacturer private executables that depend on 110 <code>system/code/include/private_filesystem_config.h</code> for the file or 111 directory structures or <code>fs_config</code> must add <code>libcutils</code> 112 library dependencies.</li> 113 <li>Requires device manufacturer private branch copies of the 114 <code>system/core/include/private/android_filesystem_config.h</code> with extra 115 content on existing targets to move to 116 <code>device/<em>vendor</em>/<em>device</em>/android_filesystem_config.h</code>. 117 </li> 118 <li>As Android reserves the right to apply SELinux Mandatory Access Controls (MAC) 119 to configuration files on the target system, implementations that include 120 custom target executables using <code>fs_config()</code> must ensure access.</li> 121 </ul> 122 123 <h2 id=example>Example</h2> 124 125 <p>This example shows a patch for overriding the <code>system/bin/glgps</code> 126 daemon to add wake lock support in the 127 <code>device/<em>vendor</em>/<em>device</em></code> directory. Keep the 128 following in mind:</p> 129 130 <ul> 131 <li>Each structure entry is the mode, uid, gid, capabilities, and the name. 132 <code>system/core/include/private/android_filesystem_config.h</code> is included 133 automatically to provide the manifest #defines (<code>AID_ROOT</code>, 134 <code>AID_SHELL</code>, <code>CAP_BLOCK_SUSPEND</code>).</li> 135 <li>The <code>android_device_files[]</code> section includes an action to 136 suppress access to <code>system/etc/fs_config_dirs</code> when unspecified, 137 which serves as an additional DAC protection for lack of content for directory 138 overrides. However, this is weak protection; if someone has control over 139 <code>/system</code>, they can typically do anything they want.</li> 140 </ul> 141 142 <pre class="devsite-click-to-copy"> 143 diff --git a/android_filesystem_config.h b/android_filesystem_config.h 144 new file mode 100644 145 index 0000000..874195f 146 --- /dev/null 147 +++ b/android_filesystem_config.h 148 @@ -0,0 +1,36 @@ 149 +/* 150 + * Copyright (C) 2015 The Android Open Source Project 151 + * 152 + * Licensed under the Apache License, Version 2.0 (the "License"); 153 + * you may not use this file except in compliance with the License. 154 + * You may obtain a copy of the License at 155 + * 156 + * http://www.apache.org/licenses/LICENSE-2.0 157 + * 158 + * Unless required by applicable law or agreed to in writing, software 159 + * distributed under the License is distributed on an "AS IS" BASIS, 160 + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 161 + * implied. See the License for the specific language governing 162 + * permissions and limitations under the License. 163 + */ 164 + 165 +/* This file is used to define the properties of the filesystem 166 +** images generated by build tools (eg: mkbootfs) and 167 +** by the device side of adb. 168 +*/ 169 + 170 +#define NO_ANDROID_FILESYSTEM_CONFIG_DEVICE_DIRS 171 +/* static const struct fs_path_config android_device_dirs[] = { }; */ 172 + 173 +/* Rules for files. 174 +** These rules are applied based on "first match", so they 175 +** should start with the most specific path and work their 176 +** way up to the root. Prefixes ending in * denotes wildcard 177 +** and will allow partial matches. 178 +*/ 179 +static const struct fs_path_config android_device_files[] = { 180 + { 00755, AID_ROOT, AID_SHELL, (1ULL << CAP_BLOCK_SUSPEND), 181 "system/bin/glgps" }, 182 +#ifdef NO_ANDROID_FILESYSTEM_CONFIG_DEVICE_DIRS 183 + { 00000, AID_ROOT, AID_ROOT, 0, "system/etc/fs_config_dirs" }, 184 +#endif 185 +}; 186 187 188 diff --git a/device.mk b/device.mk 189 index 0c71d21..235c1a7 100644 190 --- a/device.mk 191 +++ b/device.mk 192 @@ -18,7 +18,8 @@ PRODUCT_PACKAGES := \ 193 libwpa_client \ 194 hostapd \ 195 wpa_supplicant \ 196 - wpa_supplicant.conf 197 + wpa_supplicant.conf \ 198 + fs_config_files 199 200 ifeq ($(TARGET_PREBUILT_KERNEL),) 201 ifeq ($(USE_SVELTE_KERNEL), true) 202 </pre> 203 204 205 206 </body> 207 </html> 208
