Android: External Storage

External Storage Technical Information

Android supports devices with external storage, which is defined to be a case-insensitive filesystem with immutable POSIX permission classes and modes. External storage can be provided by physical media (such as an SD card), or by exposing a portion of internal storage through an emulation layer. Devices may contain multiple instances of external storage.

Access to external storage is protected by various Android permissions. Starting in Android 1.0, write access is protected with the WRITE_EXTERNAL_STORAGE permission. Starting in Android 4.1, read access is protected with the READ_EXTERNAL_STORAGE permission.

Starting in Android 4.4, the owner, group and modes of files on external storage devices are now synthesized based on directory structure. This enables apps to manage their package-specific directories on external storage without requiring they hold the broad WRITE_EXTERNAL_STORAGE permission. For example, the app with package name com.example.foo can now freely access Android/data/com.example.foo/ on external storage devices with no permissions. These synthesized permissions are accomplished by wrapping raw storage devices in a FUSE daemon.

Since external storage offers minimal protection for stored data, system code should not store sensitive data on external storage. Specifically, configuration and log files should only be stored on internal storage where they can be effectively protected.

Multiple external storage devices

---

Starting in Android 4.4, multiple external storage devices are surfaced to developers throughContext.getExternalFilesDirs(), Context.getExternalCacheDirs(), and Context.getObbDirs().

External storage devices surfaced through these APIs must be a semi-permanent part of the device (such as an SD card slot in a battery compartment). Developers expect data stored in these locations to be available over long periods of time. For this reason, transient storage devices (such as USB mass storage drives) should not be surfaced through these APIs.

The WRITE_EXTERNAL_STORAGE permission must only grant write access to the primary external storage on a device. Apps must not be allowed to write to secondary external storage devices, except in their package-specific directories as allowed by synthesized permissions. Restricting writes in this way ensures the system can clean up files when applications are uninstalled.

Multi-user external storage

---

Starting in Android 4.2, devices can support multiple users, and external storage must meet the following constraints:

• Each user must have their own isolated primary external storage, and must not have access to the primary external storage of other users.
• The /sdcard path must resolve to the correct user-specific primary external storage based on the user a process is running as.
• Storage for large OBB files in the Android/obb directory may be shared between multiple users as an optimization.
• Secondary external storage must not be writable by apps, except in package-specific directories as allowed by synthesized permissions.

The default platform implementation of this feature leverages Linux kernel namespaces to create isolated mount tables for each Zygote-forked process, and then uses bind mounts to offer the correct user-specific primary external storage into that private namespace.

At boot, the system mounts a single emulated external storage FUSE daemon at EMULATED_STORAGE_SOURCE, which is hidden from apps. After the Zygote forks, it bind mounts the appropriate user-specific subdirectory from under the FUSE daemon to EMULATED_STORAGE_TARGET so that external storage paths resolve correctly for the app. Because an app lacks accessible mount points for other users' storage, they can only access storage for the user it was started as.

This implementation also uses the shared subtree kernel feature to propagate mount events from the default root namespace into app namespaces, which ensures that features like ASEC containers and OBB mounting continue working correctly. It does this by mounting the rootfs as shared, and then remounting it as slave after each Zygote namespace is created.

Device Specific Configuration

External storage is managed by a combination of the vold ( volume daemon) init service and MountService system servic. Mounting of physical external storage volumes is handled by vold, which performs staging operations to prepare the media before exposing it to apps.

For Android 4.2.2 and earlier, the device-specific vold.fstab configuration file defines mappings from sysfs devices to filesystem mount points, and each line follows this format:

dev_mount     [flags]

• label: Label for the volume.
• mount_point: Filesystem path where the volume should be mounted.
• partition: Partition number (1 based), or 'auto' for first usable partition.
• sysfs_path: One or more sysfs paths to devices that can provide this mount point. Separated by spaces, and each must start with /.
• flags: Optional comma separated list of flags, must not contain /. Possible values include nonremovableand encryptable.

For Android releases 4.3 and later, the various fstab files used by init, vold and recovery were unified in the/fstab. file. For external storage volumes that are managed by vold, the entries should have the following format:

• src: A path under sysfs (usually mounted at /sys) to the device that can provide the mount point. The path must start with /.
• mount_point: Filesystem path where the volume should be mounted.
• type: The type of the filesystem on the volume. For external cards, this is usually vfat.
• mnt_flags: Vold ignores this field and it should be set to defaults
• fs_mgr_flags: Vold ignores any lines in the unified fstab that do not include the voldmanaged= flag in this field. This flag must be followed by a label describing the card, and a partition number or the word auto. Here is an example: voldmanaged=sdcard:auto. Other possible flags are nonremovable,encryptable=sdcard, and noemulatedsd.

External storage interactions at and above the framework level are handled through MountService. The device-specific storage_list.xml configuration file, typically provided through a frameworks/base overlay, defines the attributes and constraints of storage devices. The  element contains one or more elements, exactly one of which should be marked primary.  attributes include:

• mountPoint: filesystem path of this mount.
• storageDescription: string resource that describes this mount.
• primary: true if this mount is the primary external storage.
• removable: true if this mount has removable media, such as a physical SD card.
• emulated: true if this mount is emulated and is backed by internal storage, possibly using a FUSE daemon.
• mtp-reserve: number of MB of storage that MTP should reserve for free storage. Only used when mount is marked as emulated.
• allowMassStorage: true if this mount can be shared via USB mass storage.
• maxFileSize: maximum file size in MB.

Devices may provide external storage by emulating a case-insensitive, permissionless filesystem backed by internal storage. One possible implementation is provided by the FUSE daemon in system/core/sdcard, which can be added as a device-specific init.rc service:

# virtual sdcard daemon running as media_rw (1023)
service sdcard /system/bin/sdcard   1023 1023
    class late_start

Where source_path is the backing internal storage and dest_path is the target mount point.

When configuring a device-specific init.rc script, the EXTERNAL_STORAGE environment variable must be defined as the path to the primary external storage. The /sdcard path must also resolve to the same location, possibly through a symlink. If a device adjusts the location of external storage between platform updates, symlinks should be created so that old paths continue working.

Typical Configuration Examples

Below are examples of external storage configurations as of Android 4.4 for various typical devices. Only the relevant portions of the configuration files are included.

Physical primary only (like Nexus One)

---

This is a typical configuration for a device with single external storage device which is a physical SD card.

The raw physical device must first be mounted under /mnt/media_rw where only the system and FUSE daemon can access it. vold will then manage the fuse_sdcard0 service when media is inserted/removed.

fstab.hardware

[physical device node]  auto  vfat  defaults  voldmanaged=sdcard0:auto,noemulatedsd

init.hardware.rc

on init
    mkdir /mnt/media_rw/sdcard0 0700 media_rw media_rw
    mkdir /storage/sdcard0 0700 root root

    export EXTERNAL_STORAGE /storage/sdcard0

service fuse_sdcard0 /system/bin/sdcard -u 1023 -g 1023 -d /mnt/media_rw/sdcard0 /storage/sdcard0
    class late_start
    disabled

storage_list.xml

    android:mountPoint="/storage/sdcard0"
    android:storageDescription="@string/storage_sd_card"
    android:removable="true"
    android:primary="true"
    android:maxFileSize="4096" />

Emulated primary only (like Nexus 4)

---

This is a typical configuration for a device with single external storage device which is backed by internal storage on the device.

init.hardware.rc

on init
    mkdir /mnt/shell/emulated 0700 shell shell
    mkdir /storage/emulated 0555 root root

    export EXTERNAL_STORAGE /storage/emulated/legacy
    export EMULATED_STORAGE_SOURCE /mnt/shell/emulated
    export EMULATED_STORAGE_TARGET /storage/emulated

on fs
    setprop ro.crypto.fuse_sdcard true

service sdcard /system/bin/sdcard -u 1023 -g 1023 -l /data/media /mnt/shell/emulated
    class late_start

storage_list.xml

    android:storageDescription="@string/storage_internal"
    android:emulated="true"
    android:mtpReserve="100" />

Emulated primary, physical secondary (like Xoom)

---

This is a typical configuration for a device with multiple external storage devices, where the primary device is backed by internal storage on the device, and where the secondary device is a physical SD card.

The raw physical device must first be mounted under /mnt/media_rw where only the system and FUSE daemon can access it. vold will then manage the fuse_sdcard1 service when media is inserted/removed.

fstab.hardware

[physical device node]  auto  vfat  defaults  voldmanaged=sdcard1:auto

init.hardware.rc

on init
    mkdir /mnt/shell/emulated 0700 shell shell
    mkdir /storage/emulated 0555 root root

    mkdir /mnt/media_rw/sdcard1 0700 media_rw media_rw
    mkdir /storage/sdcard1 0700 root root

    export EXTERNAL_STORAGE /storage/emulated/legacy
    export EMULATED_STORAGE_SOURCE /mnt/shell/emulated
    export EMULATED_STORAGE_TARGET /storage/emulated
    export SECONDARY_STORAGE /storage/sdcard1

on fs
    setprop ro.crypto.fuse_sdcard true

service sdcard /system/bin/sdcard -u 1023 -g 1023 -l /data/media /mnt/shell/emulated
    class late_start

service fuse_sdcard1 /system/bin/sdcard -u 1023 -g 1023 -w 1023 -d /mnt/media_rw/sdcard1 /storage/sdcard1
    class late_start
    disabled

storage_list.xml

    android:storageDescription="@string/storage_internal"
    android:emulated="true"
    android:mtpReserve="100" />

    android:mountPoint="/storage/sdcard1"
    android:storageDescription="@string/storage_sd_card"
    android:removable="true"
    android:maxFileSize="4096" />