1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 =========================================== 3 ===========================================
4 Mounting root file system via SMB (cifs.ko) 4 Mounting root file system via SMB (cifs.ko)
5 =========================================== 5 ===========================================
6 6
7 Written 2019 by Paulo Alcantara <palcantara@sus 7 Written 2019 by Paulo Alcantara <palcantara@suse.de>
8 8
9 Written 2019 by Aurelien Aptel <aaptel@suse.com 9 Written 2019 by Aurelien Aptel <aaptel@suse.com>
10 10
11 The CONFIG_CIFS_ROOT option enables experiment 11 The CONFIG_CIFS_ROOT option enables experimental root file system
12 support over the SMB protocol via cifs.ko. 12 support over the SMB protocol via cifs.ko.
13 13
14 It introduces a new kernel command-line option 14 It introduces a new kernel command-line option called 'cifsroot='
15 which will tell the kernel to mount the root f 15 which will tell the kernel to mount the root file system over the
16 network by utilizing SMB or CIFS protocol. 16 network by utilizing SMB or CIFS protocol.
17 17
18 In order to mount, the network stack will also 18 In order to mount, the network stack will also need to be set up by
19 using 'ip=' config option. For more details, s 19 using 'ip=' config option. For more details, see
20 Documentation/admin-guide/nfs/nfsroot.rst. 20 Documentation/admin-guide/nfs/nfsroot.rst.
21 21
22 A CIFS root mount currently requires the use o 22 A CIFS root mount currently requires the use of SMB1+UNIX Extensions
23 which is only supported by the Samba server. S 23 which is only supported by the Samba server. SMB1 is the older
24 deprecated version of the protocol but it has 24 deprecated version of the protocol but it has been extended to support
25 POSIX features (See [1]). The equivalent exten 25 POSIX features (See [1]). The equivalent extensions for the newer
26 recommended version of the protocol (SMB3) hav 26 recommended version of the protocol (SMB3) have not been fully
27 implemented yet which means SMB3 doesn't suppo 27 implemented yet which means SMB3 doesn't support some required POSIX
28 file system objects (e.g. block devices, pipes 28 file system objects (e.g. block devices, pipes, sockets).
29 29
30 As a result, a CIFS root will default to SMB1 30 As a result, a CIFS root will default to SMB1 for now but the version
31 to use can nonetheless be changed via the 'ver 31 to use can nonetheless be changed via the 'vers=' mount option. This
32 default will change once the SMB3 POSIX extens 32 default will change once the SMB3 POSIX extensions are fully
33 implemented. 33 implemented.
34 34
35 Server configuration 35 Server configuration
36 ==================== 36 ====================
37 37
38 To enable SMB1+UNIX extensions you will need t 38 To enable SMB1+UNIX extensions you will need to set these global
39 settings in Samba smb.conf:: 39 settings in Samba smb.conf::
40 40
41 [global] 41 [global]
42 server min protocol = NT1 42 server min protocol = NT1
43 unix extension = yes # default 43 unix extension = yes # default
44 44
45 Kernel command line 45 Kernel command line
46 =================== 46 ===================
47 47
48 :: 48 ::
49 49
50 root=/dev/cifs 50 root=/dev/cifs
51 51
52 This is just a virtual device that basically t 52 This is just a virtual device that basically tells the kernel to mount
53 the root file system via SMB protocol. 53 the root file system via SMB protocol.
54 54
55 :: 55 ::
56 56
57 cifsroot=//<server-ip>/<share>[,options] 57 cifsroot=//<server-ip>/<share>[,options]
58 58
59 Enables the kernel to mount the root file syst 59 Enables the kernel to mount the root file system via SMB that are
60 located in the <server-ip> and <share> specifi 60 located in the <server-ip> and <share> specified in this option.
61 61
62 The default mount options are set in fs/smb/cl 62 The default mount options are set in fs/smb/client/cifsroot.c.
63 63
64 server-ip 64 server-ip
65 IPv4 address of the server. 65 IPv4 address of the server.
66 66
67 share 67 share
68 Path to SMB share (rootfs). 68 Path to SMB share (rootfs).
69 69
70 options 70 options
71 Optional mount options. For more infor 71 Optional mount options. For more information, see mount.cifs(8).
72 72
73 Examples 73 Examples
74 ======== 74 ========
75 75
76 Export root file system as a Samba share in sm 76 Export root file system as a Samba share in smb.conf file::
77 77
78 ... 78 ...
79 [linux] 79 [linux]
80 path = /path/to/rootfs 80 path = /path/to/rootfs
81 read only = no 81 read only = no
82 guest ok = yes 82 guest ok = yes
83 force user = root 83 force user = root
84 force group = root 84 force group = root
85 browseable = yes 85 browseable = yes
86 writeable = yes 86 writeable = yes
87 admin users = root 87 admin users = root
88 public = yes 88 public = yes
89 create mask = 0777 89 create mask = 0777
90 directory mask = 0777 90 directory mask = 0777
91 ... 91 ...
92 92
93 Restart smb service:: 93 Restart smb service::
94 94
95 # systemctl restart smb 95 # systemctl restart smb
96 96
97 Test it under QEMU on a kernel built with CONF 97 Test it under QEMU on a kernel built with CONFIG_CIFS_ROOT and
98 CONFIG_IP_PNP options enabled:: 98 CONFIG_IP_PNP options enabled::
99 99
100 # qemu-system-x86_64 -enable-kvm -cpu host 100 # qemu-system-x86_64 -enable-kvm -cpu host -m 1024 \
101 -kernel /path/to/linux/arch/x86/boot/bzIma 101 -kernel /path/to/linux/arch/x86/boot/bzImage -nographic \
102 -append "root=/dev/cifs rw ip=dhcp cifsroo 102 -append "root=/dev/cifs rw ip=dhcp cifsroot=//10.0.2.2/linux,username=foo,password=bar console=ttyS0 3"
103 103
104 104
105 1: https://wiki.samba.org/index.php/UNIX_Exten 105 1: https://wiki.samba.org/index.php/UNIX_Extensions
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.