aboutsummaryrefslogtreecommitdiffstats
path: root/extras/selinux/selinux_doc.md
diff options
context:
space:
mode:
Diffstat (limited to 'extras/selinux/selinux_doc.md')
-rw-r--r--extras/selinux/selinux_doc.md294
1 files changed, 294 insertions, 0 deletions
diff --git a/extras/selinux/selinux_doc.md b/extras/selinux/selinux_doc.md
new file mode 100644
index 00000000000..e71bd658286
--- /dev/null
+++ b/extras/selinux/selinux_doc.md
@@ -0,0 +1,294 @@
+# SELinux - VPP Custom SELinux Policy {#selinux_doc}
+
+## Overview
+
+Security-enhanced Linux (SELinux) is a security feature in the Linux kernel. At
+a very high level, SELinux implements mandatory access controls (MAC), as
+opposed to discretionary access control (DAC) implemented in standard Linux. MAC
+defines how processes can interact with other system components (Files,
+Directories, Other Processes, Pipes, Sockets, Network Ports). Each system
+component is assigned a label, and then the SELinux Policy defines which labels
+and which actions on each label a process is able to perform. The VPP Custom
+SELinux Policy defines the actions VPP is allowed to perform on which labels.
+
+The VPP Custom SELinux Policy is intended to be installed on RPM based platforms
+(tested on CentOS 7 and RHEL 7). Though SELinux can run on Debian platforms, it
+typically is not and therefore is not currently being built for Debian.
+
+The VPP Custom SELinux Policy does not enable or disable SELinux, only allows
+VPP to run when SELinux is enabled. A fresh install of either Fedora, CentOS or
+RHEL will have SELinux enabled by default. To determine if SELinux is enabled on
+a given system and enable it if needed, run:
+
+```
+ $ getenforce
+ Permissive
+
+ $ sudo setenforce 1
+
+ $ getenforce
+ Enforcing
+```
+
+To make the change persistent, modify the following file to set
+`SELINUX=enforcing`:
+
+```
+ $ sudo vi /etc/selinux/config
+ :
+ # This file controls the state of SELinux on the system.
+ # SELINUX= can take one of these three values:
+ # enforcing - SELinux security policy is enforced.
+ # permissive - SELinux prints warnings instead of enforcing.
+ # disabled - No SELinux policy is loaded.
+ SELINUX=enforcing
+ :
+```
+
+## Installation
+
+To install VPP, see the installation instructions on the VPP Wiki
+(https://wiki.fd.io/view/VPP/Installing_VPP_binaries_from_packages). The VPP
+Custom SELinux Policy is packaged in its own RPM starting in 18.04,
+`vpp-selinux-policy-<VERSION>-<RELEASE>.rpm`. It is packaged and installed along
+with the other VPP RPMs.
+
+### Fresh Install of VPP
+
+If VPP has never been installed on a system, then starting in 18.04, the VPP
+Custom SELinux Policy will be installed with the other RPMs and all the system
+components managed by VPP will be labeled properly.
+
+### Fix SELinux Labels for VPP
+In the case where the VPP Custom Policy is being installed for the first time,
+either because VPP has been upgraded or packages were removed and then
+reinstalled, several directories and files will not not be properly labeled. The
+labels on these files will need to be fixed for VPP to run properly with SELinux
+enabled. After the VPP Custom SELinux Policy is installed, run the following
+commands to fix the labels. If VPP is already running, make sure to restart
+VPP after the labels are fixed. This change is persistent for the life of the
+file. Once the VPP Custom Policy is installed on the system, subsequent files
+created by VPP will be labeled properly. This is only to fix files created by
+VPP prior to the VPP Custom Policy being installed.
+
+```
+ $ sudo restorecon -Rv /etc/vpp/
+ $ sudo restorecon -Rv /usr/lib/vpp_api_test_plugins/
+ $ sudo restorecon -Rv /usr/lib/vpp_plugins/
+ $ sudo restorecon -Rv /usr/share/vpp/
+ $ sudo restorecon -Rv /var/run/vpp/
+
+ $ sudo chcon -t vpp_tmp_t /tmp/vpp_*
+ $ sudo chcon -t vpp_var_run_t /var/run/.vpp_*
+```
+
+**NOTE:** Because the VPP APIs allow custom filenames in certain scenarios, the
+above commands may not handle all files. Inspect your system and correct any
+files that are mislabeled. For example, to verify all VPP files in `/tmp/` are
+labeled properly, run:
+
+```
+ $ sudo ls -alZ /tmp/
+```
+
+Any files not properly labeled with `vpp_tmp_t`, run:
+
+```
+ $ sudo chcon -t vpp_tmp_t /tmp/<filename>
+```
+
+## VPP Files
+
+### Recommended Default File Directories
+
+Documentation in the VPP Wiki (https://wiki.fd.io/view/VPP/) and doxygen
+generated documentation have examples with files located in certain directories.
+Some of the recommend file locations have been moved to satisfy SELinux. Most of
+the documentation has been updated, but links to older documentation still exist
+and there may have been instances that were missed. Use the file locations
+described below to allow SELinux to properly label the given files.
+
+File locations that have changed:
+* VPP Debug CLI Script Files
+* vHost Sockets
+* VPP Log Files
+
+#### VPP Debug CLI Script Files
+
+The VPP Debug CLI, `vppctl`, allows a sequence of CLI commands to be read from a
+file and executed. To avoid from having to grant VPP access to all of `/tmp/` and
+possibly `/home/` sub-directories, it is recommended that any VPP Debug CLI script
+files be placed in a common directory such as `/usr/share/vpp/`.
+
+For example:
+```
+$ cat /usr/share/vpp/scripts/gigup.txt
+set interface state GigabitEthernet0/8/0 up
+set interface state GigabitEthernet0/9/0 up
+```
+
+To execute:
+```
+$ vppctl exec /usr/share/vpp/scripts/gigup.txt
+```
+Or
+```
+$ vppctl
+ _______ _ _ _____ ___
+ __/ __/ _ \ (_)__ | | / / _ \/ _ \
+ _/ _// // / / / _ \ | |/ / ___/ ___/
+ /_/ /____(_)_/\___/ |___/_/ /_/
+
+vpp# exec /usr/share/vpp/scripts/gigup.txt
+vpp# quit
+
+```
+
+If the file is not labeled properly, you will see something similar to:
+```
+$ vppctl exec /home/<user>/dev/vpp/scripts/vppctl/gigup.txt
+exec: failed to open `/home/<user>/dev/vpp/scripts/vppctl/gigup.txt': Permission denied
+
+$ ls -alZ
+drwxrwxr-x. <user> <user> unconfined_u:object_r:user_home_t:s0 .
+drwxrwxr-x. <user> <user> unconfined_u:object_r:user_home_t:s0 ..
+-rw-r--r--. <user> <user> unconfined_u:object_r:user_home_t:s0 gigup.txt
+```
+
+##### Original Documentation
+
+Some of the original documentation showed script files being executed out of
+`/tmp/`. Convenience also may lead to script files being placed in
+`/home/<user>/` subdirectories. If a file is generated by the VPP process in
+`/tmp/`, for example a trace file or pcap file, it will get properly labeled
+with the SELinux label `vpp_tmp_t`. When a file is created, unless a rule is in
+place for the process that created it, the file will inherit the SELinux label
+of the parent directory. So if a user creates a file themselves in `/tmp/`, it
+will get the SELinux label `tmp_t`, which VPP does not have permission to
+access. Therefore it is recommended that script files are located as described
+above.
+
+#### vHost Sockets
+
+vHost sockets are created from VPP perspective in either Server or Client mode.
+In Server mode, the socket name is provided to VPP and VPP creates the socket.
+In Client mode, the socket name is provided to VPP and the hypervisor creates
+the socket. In order for VPP and hypervisor to share the socket resource with
+SELinux enabled, a rule in the VPP Custom SELinux Policy has been added. This
+rules allows processes with the `svirt_t` label (the hypervisor) to access
+sockets with the `vpp_var_run_t` label. As such, when SELinux is enabled,
+vHost sockets should be created in the directory `/var/run/vpp/`.
+
+##### Original Documentation
+
+Some of the original documentation showed vHost sockets being created in the
+directory `/tmp/`. To work properly with SELinux enabled, vHost sockets should be
+created as described above.
+
+#### VPP Log Files
+
+The VPP log file location is set by updating the `/etc/vpp/startup.conf` file:
+
+```
+vi /etc/vpp/startup.conf
+unix {
+:
+ log /var/log/vpp/vpp.log
+:
+}
+
+```
+
+By moving the log file to `/var/log/vpp/`, it will get the label `vpp_log_t`,
+which indicates that the files are log files so they benefit from the
+associated rules (for example granting rights to logrotate so that it can
+manipulate them).
+
+##### Original Documentation
+
+The default `startup.conf` file creates the VPP log file in `/tmp/vpp.log`. By
+leaving the log file in `/tmp/`, it will get the label `vpp_tmp_t`. Moving it
+to `/var/log/vpp/`, it will get the label `vpp_log_t`.
+
+### Use of Non-default File Directories
+
+VPP installs multiple files on the system.
+Some files have fixed directory and file names:
+- /etc/bash_completion.d/vppctl_completion
+- /etc/sysctl.d/80-vpp.conf
+- /usr/lib/systemd/system/vpp.service
+
+Others files have default directory and file names but the default can be
+overwritten:
+- /etc/vpp/startup.conf
+ - Can be changed via the `/usr/lib/systemd/system/vpp.service` file by
+ changing the -c option on the VPP command line:
+
+```
+ExecStart=/usr/bin/vpp -c /etc/vpp/startup.conf
+```
+
+- /run/vpp/cli.sock
+ - Can be changed via the `/etc/vpp/startup.conf` file by changing the
+ cli-listen setting:
+
+```
+unix {
+:
+ cli-listen /run/vpp/cli.sock
+:
+}
+```
+
+
+- /var/log/vpp/vpp.log
+ - Can be changed via the `/etc/vpp/startup.conf` file by changing the log
+ setting:
+
+```
+unix {
+ :
+ log /var/log/vpp/vpp.log
+ :
+}
+
+```
+
+If the directory of any VPP installed files is changed from the default, ensure
+that the proper SELiunx label is applied. The SELinux label can be determined by
+passing the -Z option to many common Linux commands:
+
+```
+ls -alZ /run/vpp/
+drwxr-xr-x. root vpp system_u:object_r:vpp_var_run_t:s0 .
+drwxr-xr-x. root root system_u:object_r:var_run_t:s0 ..
+srwxrwxr-x. root vpp system_u:object_r:vpp_var_run_t:s0 cli.sock
+```
+
+### VPP SELinux Types ###
+
+The following SELinux types are created by the VPP Custom SELinux Policy:
+- `vpp_t` - Applied to:
+ - VPP process and spawned threads.
+
+- `vpp_config_rw_t` - Applied to:
+ - `/etc/vpp/*`
+
+- `vpp_tmp_t` - Applied to:
+ - `/tmp/*`
+
+- `vpp_exec_t` - Applied to:
+ - `/usr/bin/*`
+
+- `vpp_lib_t` - Applied to:
+ - `/usr/lib/vpp_api_test_plugins/*`
+ - `/usr/lib/vpp_plugins/*`
+
+- `vpp_unit_file_t` - Applied to:
+ - `/usr/lib/systemd/system/vpp.*`
+
+- `vpp_log_t` - Applied to:
+ - `/var/log/vpp/*`
+
+- `vpp_var_run_t` - Applied to:
+ - `/var/run/vpp/*`