diff options
Diffstat (limited to 'en/devices/tech/config/filesystem.html')
-rw-r--r-- | en/devices/tech/config/filesystem.html | 174 |
1 files changed, 108 insertions, 66 deletions
diff --git a/en/devices/tech/config/filesystem.html b/en/devices/tech/config/filesystem.html index c1f13dc0..c2a3fd3f 100644 --- a/en/devices/tech/config/filesystem.html +++ b/en/devices/tech/config/filesystem.html @@ -1,6 +1,6 @@ <html devsite> <head> - <title>Configuring the File System</title> + <title>File DAC Configuration</title> <meta name="project_path" value="/_project.yaml" /> <meta name="book_path" value="/_book.yaml" /> </head> @@ -22,56 +22,122 @@ --> +<p>Earlier versions of Android used a system configuration file that was +not extensible, preventing device manufacturers from adding named binaries to +specify Discretionary Access Controls (DAC) of ownership, access mode, or +executable capabilities. This limitation occurred as a result of support for +Linux kernels 3.14 and higher in which wake lock is enabled via the +<code>CAP_SUSPEND_BLOCK</code> capability; partner-supplied GPS daemons were +required to hold this wake lock (and thus have this capability set in the file +system).</p> + +<p>As of Android 6.0, <code>fs_config</code> and associated structure definitions +(<code>system/core/include/private/android_filesystem_config.h</code>) are now +located in <code>system/core/libcutils/fs_config.c</code> where they can be +updated or overridden by binary files installed in +<code>/system/etc/fs_config_dirs</code> and +<code>/system/etc/fs_config_files</code>. For clarity, Android uses separate +matching and parsing rules for directories and files (which can use additional +glob expressions) and handles directories and files in two different tables. +Structure definitions in <code>system/core/libcutils/fs_config.c</code> not only +allow runtime reading of directories and files, but the host may use the same +files 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>.</p> + +<h2 id=gen-files>Generating override files</h2> + +<p>You can generate the aligned binary files +<code>/system/etc/fs_config_dirs</code> and +<code>/system/etc/fs_config_files</code> using the +<code>fs_config_generate</code> tool in <code>build/tools/fs_config</code>. The +tool uses a <code>libcutils</code> library function +(<code>fs_config_generate()</code>) to manage DAC requirements into a buffer +and defines rules for an include file to institutionalize the DAC rules.</p> + +<p>To use, create an include file in +<code>device/<em>vendor</em>/<em>device</em>/android_filesystem_config.h</code> +that acts as the override. The file must use the +<code>structure fs_path_config</code> format defined in +<code>system/core/include/private/android_filesystem_config.h</code> with the +following structure initializations for directory and file symbols:</p> +<ul> +<li>For directories, use <code>android<strong>_device</strong>_dirs[]</code>.</li> +<li>For files, use <code>android<strong>_device</strong>_files[]</code>.</li> +</ul> -<h2 id=abstract>Abstract</h2> - -<p>This document describes impending changes to the manner in which the Android -file system is configured.</p> - -<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 -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 <code>CAP_SUSPEND_BLOCK</code>; partner-supplied GPS daemons will need to hold this wake lock and thus have -this capability set in the file system.</p> - -<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> - -<h2 id=implementation>Implementation</h2> - -<p>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.</p> - -<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 -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 -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> - -<p><strong>Caution</strong>: This change is disruptive, as it removes some includes, structures and inline -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 -for adjustments for file system configuration has changed.</p> +<p>When not using <code>android_device_dirs[]</code> and +<code>android_device_files[]</code>, you can define +<code>NO_ANDROID_FILESYSTEM_CONFIG_DEVICE_DIRS</code> and <code>NO_ANDROID_FILESYSTEM_CONFIG_DEVICE_FILES</code> (see the +<a href="#example">example</a> below).</p> -<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> +<p>You can also specify the +override file using <code>TARGET_ANDROID_FILESYSTEM_CONFIG_H</code> in the board +configuration, with an enforced basename of +<code>android_filesystem_config.h</code>. -<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 -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 -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> +<h2 id=include-files>Including files</h2> -<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> +<p><code>PRODUCT_PACKAGES</code> must include <code>fs_config_dirs</code> +and/or <code>fs_config_files</code> to install them to +<code>/system/etc/fs_config_dirs</code> and +<code>/system/etc/fs_config_files</code>, respectively.</p> -<h3 id=instructions>Instructions</h3> +<p>The build system searches for custom <code>android_filesystem_config.h</code> +in <code>$(TARGET_DEVICE_DIR)</code>, where <code>BoardConfig.mk</code> exists. +If this file exists elsewhere, set board config variable +<code>TARGET_ANDROID_FILESYSTEM_CONFIG_H</code> to point to that location.</p> -<p>Follow these steps to configure the Android file system in the M release and -later.</p> +<h2 id=configuring>Configuring</h2> +<p>To configure the file system in Android 6.0 and higher:</p> <ol> - <li> Create the <code>$(TARGET_DEVICE_DIR)/android_filesystem_config.h</code> file - <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>) +<li>Create the <code>$(TARGET_DEVICE_DIR)/android_filesystem_config.h</code> +file.</li> +<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 (e.g., +<code>$(TARGET_DEVICE_DIR)/device.mk</code>).</li> </ol> -<h3 id=example>Example</h3> +<h2 id=migration-concerns>Migration concerns</h2> +<p>Migrating system configurations from Android 5.0 and earlier can be +disruptive. When planning such a migration, keep in mind that Android 6.0:</p> +<ul> +<li>Removes some includes, structures, and inline definitions.</li> +<li>Requires a reference to <code>libcutils</code> instead of running directly +from <code>system/core/include/private/android_filesystem_config.h</code>. +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> must add <code>libcutils</code> +library dependencies.</li> +<li>Requires device manufacturer private branch copies of the +<code>system/core/include/private/android_filesystem_config.h</code> with extra +content on existing targets to move to +<code>device/<em>vendor</em>/<em>device</em>/android_filesystem_config.h</code>. +</li> +<li>As Android reserves the right to apply SELinux Mandatory Access Controls (MAC) +to configuration files on the target system, implementations that include +custom target executables using <code>fs_config()</code> must ensure access.</li> +</ul> + +<h2 id=example>Example</h2> + +<p>This example shows a patch for overriding the <code>system/bin/glgps</code> +daemon to add wake lock support in the +<code>device/<em>vendor</em>/<em>device</em></code> directory. Keep the +following in mind:</p> -<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> +<ul> +<li>Each structure entry is the mode, uid, gid, capabilities, and the name. +<code>system/core/include/private/android_filesystem_config.h</code> is included +automatically to provide the manifest #defines (<code>AID_ROOT</code>, + <code>AID_SHELL</code>, <code>CAP_BLOCK_SUSPEND</code>).</li> +<li>The <code>android_device_files[]</code> section includes an action to +suppress access to <code>system/etc/fs_config_dirs</code> when unspecified, +which serves as an additional DAC protection for lack of content for directory +overrides. However, this is weak protection; if someone has control over +<code>/system</code>, they can typically do anything they want.</li> +</ul> <pre> diff --git a/android_filesystem_config.h b/android_filesystem_config.h @@ -130,36 +196,12 @@ index 0c71d21..235c1a7 100644 - wpa_supplicant.conf + wpa_supplicant.conf \ + fs_config_files - + ifeq ($(TARGET_PREBUILT_KERNEL),) ifeq ($(USE_SVELTE_KERNEL), true) </pre> -<h3 id=checklist>Checklist</h3> - -<ol> - <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 -android_device_files[] is not being filled out. - - <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). - - <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 -lack of any content for the directory overrides. It is considered pedantic weak -protection since if someone has control over<code> /system</code>, they can typically do anything they want. - <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. - - <li> 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. -</ol> - -<h3 id=architectural_concerns>Architectural Concerns</h3> - -<ul> - <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> - <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. - </body> +</body> </html> |