1 # SELinux - VPP Custom SELinux Policy {#selinux_doc}
5 Security-enhanced Linux (SELinux) is a security feature in the Linux kernel. At
6 a very high level, SELinux implements mandatory access controls (MAC), as
7 opposed to discretionary access control (DAC) implemented in standard Linux. MAC
8 defines how processes can interact with other system components (Files,
9 Directories, Other Processes, Pipes, Sockets, Network Ports). Each system
10 component is assigned a label, and then the SELinux Policy defines which labels
11 and which actions on each label a process is able to perform. The VPP Custom
12 SELinux Policy defines the actions VPP is allowed to perform on which labels.
14 The VPP Custom SELinux Policy is intended to be installed on RPM based platforms
15 (tested on CentOS 7 and RHEL 7). Though SELinux can run on Debian platforms, it
16 typically is not and therefore is not currently being built for Debian.
18 The VPP Custom SELinux Policy does not enable or disable SELinux, only allows
19 VPP to run when SELinux is enabled. A fresh install of either Fedora, CentOS or
20 RHEL will have SELinux enabled by default. To determine if SELinux is enabled on
21 a given system and enable it if needed, run:
33 To make the change persistent, modify the following file to set
37 $ sudo vi /etc/selinux/config
39 # This file controls the state of SELinux on the system.
40 # SELINUX= can take one of these three values:
41 # enforcing - SELinux security policy is enforced.
42 # permissive - SELinux prints warnings instead of enforcing.
43 # disabled - No SELinux policy is loaded.
50 To install VPP, see the installation instructions on the VPP Wiki
51 (https://wiki.fd.io/view/VPP/Installing_VPP_binaries_from_packages). The VPP
52 Custom SELinux Policy is packaged in its own RPM starting in 18.04,
53 `vpp-selinux-policy-<VERSION>-<RELEASE>.rpm`. It is packaged and installed along
54 with the other VPP RPMs.
56 ### Fresh Install of VPP
58 If VPP has never been installed on a system, then starting in 18.04, the VPP
59 Custom SELinux Policy will be installed with the other RPMs and all the system
60 components managed by VPP will be labeled properly.
62 ### Fix SELinux Labels for VPP
63 In the case where the VPP Custom Policy is being installed for the first time,
64 either because VPP has been upgraded or packages were removed and then
65 reinstalled, several directories and files will not not be properly labeled. The
66 labels on these files will need to be fixed for VPP to run properly with SELinux
67 enabled. After the VPP Custom SELinux Policy is installed, run the following
68 commands to fix the labels. If VPP is already running, make sure to restart
69 VPP after the labels are fixed. This change is persistent for the life of the
70 file. Once the VPP Custom Policy is installed on the system, subsequent files
71 created by VPP will be labeled properly. This is only to fix files created by
72 VPP prior to the VPP Custom Policy being installed.
75 $ sudo restorecon -Rv /etc/vpp/
76 $ sudo restorecon -Rv /usr/lib/vpp_api_test_plugins/
77 $ sudo restorecon -Rv /usr/lib/vpp_plugins/
78 $ sudo restorecon -Rv /usr/share/vpp/
79 $ sudo restorecon -Rv /var/run/vpp/
81 $ sudo chcon -t vpp_tmp_t /tmp/vpp_*
82 $ sudo chcon -t vpp_var_run_t /var/run/.vpp_*
85 **NOTE:** Because the VPP APIs allow custom filenames in certain scenarios, the
86 above commands may not handle all files. Inspect your system and correct any
87 files that are mislabeled. For example, to verify all VPP files in `/tmp/` are
88 labeled properly, run:
94 Any files not properly labeled with `vpp_tmp_t`, run:
97 $ sudo chcon -t vpp_tmp_t /tmp/<filename>
102 ### Recommended Default File Directories
104 Documentation in the VPP Wiki (https://wiki.fd.io/view/VPP/) and doxygen
105 generated documentation have examples with files located in certain directories.
106 Some of the recommend file locations have been moved to satisfy SELinux. Most of
107 the documentation has been updated, but links to older documentation still exist
108 and there may have been instances that were missed. Use the file locations
109 described below to allow SELinux to properly label the given files.
111 File locations that have changed:
112 * VPP Debug CLI Script Files
116 #### VPP Debug CLI Script Files
118 The VPP Debug CLI, `vppctl`, allows a sequence of CLI commands to be read from a
119 file and executed. To avoid from having to grant VPP access to all of `/tmp/` and
120 possibly `/home/` sub-directories, it is recommended that any VPP Debug CLI script
121 files be placed in a common directory such as `/usr/share/vpp/`.
125 $ cat /usr/share/vpp/scripts/gigup.txt
126 set interface state GigabitEthernet0/8/0 up
127 set interface state GigabitEthernet0/9/0 up
132 $ vppctl exec /usr/share/vpp/scripts/gigup.txt
137 _______ _ _ _____ ___
138 __/ __/ _ \ (_)__ | | / / _ \/ _ \
139 _/ _// // / / / _ \ | |/ / ___/ ___/
140 /_/ /____(_)_/\___/ |___/_/ /_/
142 vpp# exec /usr/share/vpp/scripts/gigup.txt
147 If the file is not labeled properly, you will see something similar to:
149 $ vppctl exec /home/<user>/dev/vpp/scripts/vppctl/gigup.txt
150 exec: failed to open `/home/<user>/dev/vpp/scripts/vppctl/gigup.txt': Permission denied
153 drwxrwxr-x. <user> <user> unconfined_u:object_r:user_home_t:s0 .
154 drwxrwxr-x. <user> <user> unconfined_u:object_r:user_home_t:s0 ..
155 -rw-r--r--. <user> <user> unconfined_u:object_r:user_home_t:s0 gigup.txt
158 ##### Original Documentation
160 Some of the original documentation showed script files being executed out of
161 `/tmp/`. Convenience also may lead to script files being placed in
162 `/home/<user>/` subdirectories. If a file is generated by the VPP process in
163 `/tmp/`, for example a trace file or pcap file, it will get properly labeled
164 with the SELinux label `vpp_tmp_t`. When a file is created, unless a rule is in
165 place for the process that created it, the file will inherit the SELinux label
166 of the parent directory. So if a user creates a file themselves in `/tmp/`, it
167 will get the SELinux label `tmp_t`, which VPP does not have permission to
168 access. Therefore it is recommended that script files are located as described
173 vHost sockets are created from VPP perspective in either Server or Client mode.
174 In Server mode, the socket name is provided to VPP and VPP creates the socket.
175 In Client mode, the socket name is provided to VPP and the hypervisor creates
176 the socket. In order for VPP and hypervisor to share the socket resource with
177 SELinux enabled, a rule in the VPP Custom SELinux Policy has been added. This
178 rules allows processes with the `svirt_t` label (the hypervisor) to access
179 sockets with the `vpp_var_run_t` label. As such, when SELinux is enabled,
180 vHost sockets should be created in the directory `/var/run/vpp/`.
182 ##### Original Documentation
184 Some of the original documentation showed vHost sockets being created in the
185 directory `/tmp/`. To work properly with SELinux enabled, vHost sockets should be
186 created as described above.
190 The VPP log file location is set by updating the `/etc/vpp/startup.conf` file:
193 vi /etc/vpp/startup.conf
196 log /var/log/vpp/vpp.log
202 By moving the log file to `/var/log/vpp/`, it will get the label `vpp_log_t`,
203 which indicates that the files are log files so they benefit from the
204 associated rules (for example granting rights to logrotate so that it can
207 ##### Original Documentation
209 The default `startup.conf` file creates the VPP log file in `/tmp/vpp.log`. By
210 leaving the log file in `/tmp/`, it will get the label `vpp_tmp_t`. Moving it
211 to `/var/log/vpp/`, it will get the label `vpp_log_t`.
213 ### Use of Non-default File Directories
215 VPP installs multiple files on the system.
216 Some files have fixed directory and file names:
217 - /etc/bash_completion.d/vppctl_completion
218 - /etc/sysctl.d/80-vpp.conf
219 - /usr/lib/systemd/system/vpp.service
221 Others files have default directory and file names but the default can be
223 - /etc/vpp/startup.conf
224 - Can be changed via the `/usr/lib/systemd/system/vpp.service` file by
225 changing the -c option on the VPP command line:
228 ExecStart=/usr/bin/vpp -c /etc/vpp/startup.conf
232 - Can be changed via the `/etc/vpp/startup.conf` file by changing the
238 cli-listen /run/vpp/cli.sock
244 - /var/log/vpp/vpp.log
245 - Can be changed via the `/etc/vpp/startup.conf` file by changing the log
251 log /var/log/vpp/vpp.log
257 If the directory of any VPP installed files is changed from the default, ensure
258 that the proper SELiunx label is applied. The SELinux label can be determined by
259 passing the -Z option to many common Linux commands:
263 drwxr-xr-x. root vpp system_u:object_r:vpp_var_run_t:s0 .
264 drwxr-xr-x. root root system_u:object_r:var_run_t:s0 ..
265 srwxrwxr-x. root vpp system_u:object_r:vpp_var_run_t:s0 cli.sock
268 ### VPP SELinux Types ###
270 The following SELinux types are created by the VPP Custom SELinux Policy:
271 - `vpp_t` - Applied to:
272 - VPP process and spawned threads.
274 - `vpp_config_rw_t` - Applied to:
277 - `vpp_tmp_t` - Applied to:
280 - `vpp_exec_t` - Applied to:
283 - `vpp_lib_t` - Applied to:
284 - `/usr/lib/vpp_api_test_plugins/*`
285 - `/usr/lib/vpp_plugins/*`
287 - `vpp_unit_file_t` - Applied to:
288 - `/usr/lib/systemd/system/vpp.*`
290 - `vpp_log_t` - Applied to:
293 - `vpp_var_run_t` - Applied to: