Difference between revisions of "How to use overlayfs on Linux"

From FriendlyELEC WiKi
Jump to: navigation, search
(updated by API)
 
(16 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
[[How to use overlay fs on Linux/zh|查看中文]]
+
[[How to use overlayfs on Linux/zh|查看中文]]
  
 
==What Is OverlayFS==
 
==What Is OverlayFS==
−
Overlayfs是Linux下的一种堆叠文件系统，通俗地讲，根文件系统虽然在逻辑仍然是一个分区，但物理上被拆分成了两个分区来存储，其中，一个分区只读存放固化的系统数据(rootfs分区)，另一个分区存储写入的数据(data分区)，优点如下：<br />
+
OverlayFS is a union mount filesystem implementation for Linux. It allows a virtual merge of two partitions, while keeping their actual contents separate. One partition is the rootfs partition and the other is the data partition. It has the following advantages:<br />
−
1) 方便恢复出厂设置，格式化data分区即可；<br />
+
1) you can easily restore a system's factory settings by formatting the data partition;<br />
−
2) 避免重复掉电或异常掉电导致data分区挂载异常无法进入系统，由于rootfs是只读的，此时仍可以进入系统，方便维护升级；<br />
+
2) you can still boot your system since the rootfs is read-only even when the data partition cannot be correctly mounted due to unexpected shutdown.<br />
−
==哪些平台与系统支持OverlayFS==
+
 
−
===支持的硬件平台===
+
==FriendlyELEC's Systems That Support OverlayFS==
−
H3, H5, S5P4418, S5P6818, RK3399系列开发板
+
===Hardware Systems===
−
===支持的软件平台===
+
H3, H5, S5P4418, S5P6818, RK3399, RK3328, RK3568, RK3588 based boards
−
FriendlyCore, FriendlyDesktop, Lubuntu
+
===OS Systems===
−
==如何鉴别系统是否工作在OverlayFS==
+
All Linux-based systems
−
执行df命令，如果/分区挂载类型为 overlay，表示OverlayFS正在工作：
+
===Scope of Application===
 +
This document is only applicable to products using Rockchip platform. If you are using other platforms, please click on this link: [[How to use overlayfs on S5Pxxxx,H3,H5 platform]]
 +
==How to Check Whether OverlayFS Is Working==
 +
Run the df command. If the "/" partition is mounted as "overlay" it means OverlayFS is working;
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
−
pi@NanoPi-M1-Plus:~$ df
+
pi@NanoPi-R6C:/etc$ df -h
−
Filesystem     1K-blocks    Used Available Use% Mounted on
+
Filesystem     Size  Used Avail Use% Mounted on
−
udev              474848      0    474848  0% /dev
+
tmpfs           792M  2.2M  790M   1% /run
−
tmpfs             102304    3564    98740   4% /run
+
overlay         25G   13G  11G  53% /
−
overlay         28925547 1315493  26112465   5% /
+
tmpfs           3.9G    0 3.9G   0% /dev/shm
−
tmpfs             511512      0   511512   0% /dev/shm
+
tmpfs           5.0M  4.0K  5.0M   1% /run/lock
−
tmpfs               5120      4     5116   1% /run/lock
+
tmpfs           793M 116K  793M   1% /run/user/1000
−
tmpfs             511512      0    511512  0% /sys/fs/cgroup
+
−
/dev/mmcblk0p1    40862  11852    29010 30% /boot
+
−
tmpfs            102304      0    102304   0% /run/user/1000
+
 
</syntaxhighlight>
 
</syntaxhighlight>
−
==使用OverlayFS时的分区布局==
+
==Partition layout when using OverlayFS==
−
会有三个分区，分别为 rootfs分区、data分区与boot分区，对应映像文件rootfs.img, userdata.img 和 boot.img:
+
The user data will be composed of the rootfs partition and the userdata partition, corresponding to the image files rootfs.img and userdata.img. <br />
 +
Enter the following command to view the partition layout:
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
−
root@NanoPi-M1-Plus:~# lsblk /dev/mmcblk0
+
View eMMC partition layout: sudo parted -s /dev/mmcblk2 unit MiB print
−
NAME        MAJ:MIN RM  SIZE RO TYPE MOUNTPOINT
+
View SD card partition layout: sudo parted -s /dev/mmcblk0 unit MiB print
−
mmcblk0    179:0    0 29.7G  0 disk
+
−
|-mmcblk0p2 179:2    0  1.2G  0 part
+
−
|-mmcblk0p3 179:3    0 28.5G  0 part
+
−
`-mmcblk0p1 179:1    0  40M  0 part /boot
+
 
</syntaxhighlight>
 
</syntaxhighlight>
−
其中，rootfs分区存放固化的系统数据，所有对根目录的数据写入，都会写入到 data分区。
+
The output is shown as follows：
−
==使用OverlayFS实现恢复出厂设置功能==
+
−
===方法1：操作userdata分区===
+
−
factory reset:
+
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
−
mount /dev/mmcblk0p3 /media/ && cd /media/
+
pi@NanoPi-R6C:/etc$ sudo apt install parted
−
mv root/ deleteme.root
+
pi@NanoPi-R6C:/etc$ sudo parted /dev/mmcblk0 print
−
mv work/ deleteme.work
+
Model: SD SR32G (sd/mmc)
−
reboot
+
Disk /dev/mmcblk0: 31.9GB
 +
Sector size (logical/physical): 512B/512B
 +
Partition Table: gpt
 +
Disk Flags:
 +
 
 +
Number  Start  End    Size    File system  Name      Flags
 +
1      8389kB  12.6MB  4194kB              uboot
 +
2      12.6MB  16.8MB  4194kB              misc
 +
3      16.8MB  21.0MB  4194kB              dtbo
 +
4      21.0MB  37.7MB  16.8MB              resource
 +
5      37.7MB  79.7MB  41.9MB              kernel
 +
6      79.7MB  113MB  33.6MB              boot
 +
7      113MB  147MB  33.6MB              recovery
 +
8      147MB  4173MB  4027MB  ext4        rootfs
 +
9      4173MB  31.9GB  27.7GB  ext4        userdata
 
</syntaxhighlight>
 
</syntaxhighlight>
−
cleanup after reboot:
+
the rootfs partition is mounted as read-only, while userdata is mounted as read-write. The rootfs partition stores fixed system data, and any subsequent writes to the root directory will be written to the userdata partition. Therefore, formatting userdata is equivalent to restoring factory settings.<br />
 +
== Common Operations ==
 +
'''Notes:'''<br/>
 +
* These operations will erase user data, so be sure to backup your data in advance.<br>
 +
* The OS image needs to be updated to version 2023/03/14 or later, or only the boot.img needs to be updated.<br>
 +
* The device nodes /dev/mmcblkX that appear in the commands are fictitious nodes, and need to be changed to the real devices. The device node for eMMC is /dev/mmcblk2, and the device node for TF card is /dev/mmcblk0.<br>
 +
===View the current partition layout===
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
−
mount /dev/mmcblk0p3 /media/ && rm -rf /media/deleteme.*
+
sudo apt update
 +
sudo apt install parted
 +
export DEV=/dev/mmcblkX # Need to change to real device
 +
sudo parted -s ${DEV} unit MiB print
 
</syntaxhighlight>
 
</syntaxhighlight>
−
===方法2：命令行参数===
+
===Disable OverlayFS feature===
−
在内核命令行参数中加入 wipedata=yes，S5P4418与S5P6818平台可以在系统运行时进行修改：
+
Create a file named ".init_wipedata" in the root directory with the content "overlayfs=disable" and then reboot：
−
====设置下次开机时抹掉data分区的数据(即恢复出厂设置)====
+
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
−
sudo fw_setenv bootargs "`cat /proc/cmdline` wipedata=yes"
+
sudo passwd root  # Create a password for the root user, if not done before
 +
su - root -c 'echo "overlayfs=disable" > /.init_wipedata'
 
sudo reboot
 
sudo reboot
 
</syntaxhighlight>
 
</syntaxhighlight>
−
====开机时不再抹掉data分区====
+
=== Resize the userdata partition and create an additional partition===
 +
* View current partition layout
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
−
sudo fw_setenv bootargs "`cat /proc/cmdline` wipedata=no"
+
sudo apt update
 +
sudo apt install parted fdisk
 +
export DEV=/dev/mmcblkX # Need to change to real device
 +
sudo parted -s ${DEV} unit MiB print
 +
</syntaxhighlight>
 +
* Resize the userdata partition
 +
Here is an example of resizing to 8G, create a file named ".init_wipedata" in the root directory, with the content "overlayfs=enable userdata=8096", and then Reboot, where userdata= is followed by the new userdata partition size in MB, the command is as follows：
 +
<syntaxhighlight lang="bash">
 +
su - root -c 'echo "overlayfs=enable userdata=8096" > /.init_wipedata'
 
sudo reboot
 
sudo reboot
 
</syntaxhighlight>
 
</syntaxhighlight>
−
其他平台需要根据BSP提供的方法进行kernel command line修改，也可以开机进入uboot命令行进行设置。
+
After reboot, you can see that the userdata partition has been resized to 8GB：
−
 
+
<syntaxhighlight lang="bash">
−
==临时禁用OverlayFS==
+
export DEV=/dev/mmcblkX  # Need to change to real device
−
可以做完TF启动卡之后，用 fdisk 操作TF卡，删除 data 分区。
+
sudo parted -s ${DEV} unit MiB print
 +
</syntaxhighlight>
 +
* Create new partition and format it
 +
<syntaxhighlight lang="bash">
 +
(echo n; echo ""; echo ""; echo ""; echo w) | sudo fdisk ${DEV}
 +
NUM=$(sudo parted ${DEV} print | awk 'NF > 1 {p = $1} END {print p}')  # Get the last partition index
 +
sudo mkfs.ext4 ${DEV}p${NUM}
 +
</syntaxhighlight>
 +
* Mount the new partition to the specified directory
 +
<syntaxhighlight lang="bash">
 +
sudo mkdir -p /oem
 +
sudo blkid ${DEV}p${NUM}
 +
# Note down the UUID
 +
# Configure automatic mounting
 +
sudo vi /etc/fstab
 +
# Add the following to the end of the file (where the UUID needs to be replaced with the real one)
 +
UUID=bbb06fe1-df52-4c7c-b2eb-926b14605fe4 /oem ext4 suid,dev,exec,auto,nouser,async,noatime,nofail 0 0
 +
# Enter the following command to mount the partition
 +
sudo mount /oem
 +
</syntaxhighlight>
 +
===Restore factory settings===
 +
<syntaxhighlight lang="bash">
 +
su - root -c 'echo "overlayfs=enable" > /.init_wipedata'
 +
sudo reboot
 +
</syntaxhighlight>
 +
The next time boot into the ramdisk stage, the userdata partition is formatted and the /var/.init_wipedata file is cleared.
 +
===Debug===
 +
If you find that the partition has not changed, there may be an error, check if an error message is printed with the following command：
 +
<syntaxhighlight lang="bash">
 +
dmesg | grep initfs
 +
</syntaxhighlight>

Latest revision as of 09:33, 20 March 2023

查看中文

1 What Is OverlayFS

OverlayFS is a union mount filesystem implementation for Linux. It allows a virtual merge of two partitions, while keeping their actual contents separate. One partition is the rootfs partition and the other is the data partition. It has the following advantages:
1) you can easily restore a system's factory settings by formatting the data partition;
2) you can still boot your system since the rootfs is read-only even when the data partition cannot be correctly mounted due to unexpected shutdown.

2 FriendlyELEC's Systems That Support OverlayFS

2.1 Hardware Systems

H3, H5, S5P4418, S5P6818, RK3399, RK3328, RK3568, RK3588 based boards

2.2 OS Systems

All Linux-based systems

2.3 Scope of Application

This document is only applicable to products using Rockchip platform. If you are using other platforms, please click on this link: How to use overlayfs on S5Pxxxx,H3,H5 platform

3 How to Check Whether OverlayFS Is Working

Run the df command. If the "/" partition is mounted as "overlay" it means OverlayFS is working; 

pi@NanoPi-R6C:/etc$ df -h
Filesystem      Size  Used Avail Use% Mounted on
tmpfs           792M  2.2M  790M   1% /run
overlay          25G   13G   11G  53% /
tmpfs           3.9G     0  3.9G   0% /dev/shm
tmpfs           5.0M  4.0K  5.0M   1% /run/lock
tmpfs           793M  116K  793M   1% /run/user/1000

4 Partition layout when using OverlayFS

The user data will be composed of the rootfs partition and the userdata partition, corresponding to the image files rootfs.img and userdata.img.
Enter the following command to view the partition layout: 

View eMMC partition layout: sudo parted -s /dev/mmcblk2 unit MiB print
View SD card partition layout: sudo parted -s /dev/mmcblk0 unit MiB print

The output is shown as follows： 

pi@NanoPi-R6C:/etc$ sudo apt install parted
pi@NanoPi-R6C:/etc$ sudo parted /dev/mmcblk0 print
Model: SD SR32G (sd/mmc)
Disk /dev/mmcblk0: 31.9GB
Sector size (logical/physical): 512B/512B
Partition Table: gpt
Disk Flags:
 
Number  Start   End     Size    File system  Name      Flags
 1      8389kB  12.6MB  4194kB               uboot
 2      12.6MB  16.8MB  4194kB               misc
 3      16.8MB  21.0MB  4194kB               dtbo
 4      21.0MB  37.7MB  16.8MB               resource
 5      37.7MB  79.7MB  41.9MB               kernel
 6      79.7MB  113MB   33.6MB               boot
 7      113MB   147MB   33.6MB               recovery
 8      147MB   4173MB  4027MB  ext4         rootfs
 9      4173MB  31.9GB  27.7GB  ext4         userdata

the rootfs partition is mounted as read-only, while userdata is mounted as read-write. The rootfs partition stores fixed system data, and any subsequent writes to the root directory will be written to the userdata partition. Therefore, formatting userdata is equivalent to restoring factory settings.

5 Common Operations

Notes:

  • These operations will erase user data, so be sure to backup your data in advance.
  • The OS image needs to be updated to version 2023/03/14 or later, or only the boot.img needs to be updated.
  • The device nodes /dev/mmcblkX that appear in the commands are fictitious nodes, and need to be changed to the real devices. The device node for eMMC is /dev/mmcblk2, and the device node for TF card is /dev/mmcblk0.

5.1 View the current partition layout

sudo apt update
sudo apt install parted
export DEV=/dev/mmcblkX # Need to change to real device
sudo parted -s ${DEV} unit MiB print

5.2 Disable OverlayFS feature

Create a file named ".init_wipedata" in the root directory with the content "overlayfs=disable" and then reboot： 

sudo passwd root  # Create a password for the root user, if not done before
su - root -c 'echo "overlayfs=disable" > /.init_wipedata'
sudo reboot

5.3 Resize the userdata partition and create an additional partition

  • View current partition layout
sudo apt update
sudo apt install parted fdisk
export DEV=/dev/mmcblkX # Need to change to real device
sudo parted -s ${DEV} unit MiB print
  • Resize the userdata partition

Here is an example of resizing to 8G, create a file named ".init_wipedata" in the root directory, with the content "overlayfs=enable userdata=8096", and then Reboot, where userdata= is followed by the new userdata partition size in MB, the command is as follows： 

su - root -c 'echo "overlayfs=enable userdata=8096" > /.init_wipedata'
sudo reboot

After reboot, you can see that the userdata partition has been resized to 8GB： 

export DEV=/dev/mmcblkX  # Need to change to real device
sudo parted -s ${DEV} unit MiB print
  • Create new partition and format it
(echo n; echo ""; echo ""; echo ""; echo w) | sudo fdisk ${DEV}
NUM=$(sudo parted ${DEV} print | awk 'NF > 1 {p = $1} END {print p}')  # Get the last partition index
sudo mkfs.ext4 ${DEV}p${NUM}
  • Mount the new partition to the specified directory
sudo mkdir -p /oem
sudo blkid ${DEV}p${NUM}
# Note down the UUID
# Configure automatic mounting
sudo vi /etc/fstab
# Add the following to the end of the file (where the UUID needs to be replaced with the real one)
UUID=bbb06fe1-df52-4c7c-b2eb-926b14605fe4 /oem ext4 suid,dev,exec,auto,nouser,async,noatime,nofail 0 0
# Enter the following command to mount the partition
sudo mount /oem

5.4 Restore factory settings

su - root -c 'echo "overlayfs=enable" > /.init_wipedata'
sudo reboot

The next time boot into the ramdisk stage, the userdata partition is formatted and the /var/.init_wipedata file is cleared.

5.5 Debug

If you find that the partition has not changed, there may be an error, check if an error message is printed with the following command： 

dmesg | grep initfs
Retrieved from "https://wiki.friendlyelec.com/wiki/index.php?title=How_to_use_overlayfs_on_Linux&oldid=24128"