diff options
Diffstat (limited to 'extras/selinux')
| -rw-r--r-- | extras/selinux/selinux_doc.md | 506 | ||||
| -rw-r--r-- | extras/selinux/selinux_doc.rst | 554 |
2 files changed, 554 insertions, 506 deletions
diff --git a/extras/selinux/selinux_doc.md b/extras/selinux/selinux_doc.md deleted file mode 100644 index 2320dd538d2..00000000000 --- a/extras/selinux/selinux_doc.md +++ /dev/null @@ -1,506 +0,0 @@ -# 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/*` - -## Debug SELinux Issues - -If SELinux issues are suspected, there are a few steps that can be taken to -debug the issue. This section provides a few pointers on on those steps. Any -SELinux JIRAs will need this information to properly address the issue. - -### Additional SELinux Packages and Setup - -First, install the SELinux troubleshooting packages: - -``` -$ sudo yum -y install setroubleshoot setroubleshoot-server setools-console --- OR -- -$ sudo dnf -y install setroubleshoot setroubleshoot-server setools-console -``` - -To enable proper logging, restart auditd: - -``` -$ sudo service auditd restart -``` - -While debugging issues, it is best to set SELinux to `Permissive` mode. In -`Permissive` mode, SELinux will still detect and flag errors, but will allow -processes to continue normal operation. This allows multiple errors to be -collected at once as opposed to breaking on each individual error. To set -SELinux to `Permissive` mode (until next reboot or it is set back), use: - -``` -$ sudo setenforce 0 - -$ getenforce -Permissive -``` - -After debugging, to set SELinux back to `Enforcing` mode, use: - -``` -$ sudo setenforce 1 - -$ getenforce -Enforcing -``` - -### Debugging - -Once the SELinux troubleshooting packages are installed, perform the actions -that are suspected to be blocked by SELinux. Either `tail` the log during -these actions or `grep` the log for additional SELinux logs: - -``` -sudo tail -f /var/log/messages --- OR -- -sudo journalctl -f -``` - -Below are some examples of SELinux logs that are generated: - -``` -May 14 11:28:34 svr-22 setroubleshoot: SELinux is preventing /usr/bin/vpp from read access on the file hostCreate.txt. For complete SELinux messages run: sealert -l a418f869-f470-4c8a-b8e9-bdd41f2dd60b -May 14 11:28:34 svr-22 python: SELinux is preventing /usr/bin/vpp from read access on the file hostCreate.txt.#012#012***** Plugin catchall (100. confidence) suggests **************************#012#012If you believe that vpp should be allowed read access on the hostCreate.txt file by default.#012Then you should report this as a bug.#012You can generate a local policy module to allow this access.#012Do#012allow this access for now by executing:#012# ausearch -c 'vpp_main' --raw | audit2allow -M my-vppmain#012# semodule -i my-vppmain.pp#012 -May 14 11:28:34 svr-22 setroubleshoot: SELinux is preventing /usr/bin/vpp from read access on the file hostCreate.txt. For complete SELinux messages run: sealert -l a418f869-f470-4c8a-b8e9-bdd41f2dd60b -May 14 11:28:34 svr-22 python: SELinux is preventing /usr/bin/vpp from read access on the file hostCreate.txt.#012#012***** Plugin catchall (100. confidence) suggests **************************#012#012If you believe that vpp should be allowed read access on the hostCreate.txt file by default.#012Then you should report this as a bug.#012You can generate a local policy module to allow this access.#012Do#012allow this access for now by executing:#012# ausearch -c 'vpp_main' --raw | audit2allow -M my-vppmain#012# semodule -i my-vppmain.pp#012 -May 14 11:28:37 svr-22 setroubleshoot: SELinux is preventing vpp_main from map access on the packet_socket packet_socket. For complete SELinux messages run: sealert -l ab6667d9-3f14-4dbd-96a0-7a655f7b4eb1 -May 14 11:28:37 svr-22 python: SELinux is preventing vpp_main from map access on the packet_socket packet_socket.#012#012***** Plugin catchall (100. confidence) suggests **************************#012#012If you believe that vpp_main should be allowed map access on the packet_socket packet_socket by default.#012Then you should report this as a bug.#012You can generate a local policy module to allow this access.#012Do#012allow this access for now by executing:#012# ausearch -c 'vpp_main' --raw | audit2allow -M my-vppmain#012# semodule -i my-vppmain.pp#012 -May 14 11:28:51 svr-22 setroubleshoot: SELinux is preventing vpp_main from map access on the packet_socket packet_socket. For complete SELinux messages run: sealert -l ab6667d9-3f14-4dbd-96a0-7a655f7b4eb1 -May 14 11:28:51 svr-22 python: SELinux is preventing vpp_main from map access on the packet_socket packet_socket.#012#012***** Plugin catchall (100. confidence) suggests **************************#012#012If you believe that vpp_main should be allowed map access on the packet_socket packet_socket by default.#012Then you should report this as a bug.#012You can generate a local policy module to allow this access.#012Do#012allow this access for now by executing:#012# ausearch -c 'vpp_main' --raw | audit2allow -M my-vppmain#012# semodule -i my-vppmain.pp#012 -``` - -From the logs above, there are two sets of commands that are recommended to be -run. The first is to run the `sealert` command. The second is to run the -`ausearch | audit2allow` commands and the `semodule` command. - -#### sealert Command - -This `sealert` command provides a more detailed output for the given issue -detected. - -``` -$ sealert -l a418f869-f470-4c8a-b8e9-bdd41f2dd60b -SELinux is preventing /usr/bin/vpp from 'read, write' accesses on the chr_file noiommu-0. - -***** Plugin device (91.4 confidence) suggests **************************** - -If you want to allow vpp to have read write access on the noiommu-0 chr_file -Then you need to change the label on noiommu-0 to a type of a similar device. -Do -# semanage fcontext -a -t SIMILAR_TYPE 'noiommu-0' -# restorecon -v 'noiommu-0' - -***** Plugin catchall (9.59 confidence) suggests ************************** - -If you believe that vpp should be allowed read write access on the noiommu-0 chr_file by default. -Then you should report this as a bug. -You can generate a local policy module to allow this access. -Do -allow this access for now by executing: -# ausearch -c 'vpp' --raw | audit2allow -M my-vpp -# semodule -i my-vpp.pp - - -Additional Information: -Source Context system_u:system_r:vpp_t:s0 -Target Context system_u:object_r:device_t:s0 -Target Objects noiommu-0 [ chr_file ] -Source vpp -Source Path /usr/bin/vpp -Port <Unknown> -Host vpp_centos7_selinux -Source RPM Packages vpp-19.01.2-rc0~17_gcfd3086.x86_64 -Target RPM Packages -Policy RPM selinux-policy-3.13.1-229.el7_6.12.noarch -Selinux Enabled True -Policy Type targeted -Enforcing Mode Permissive -Host Name vpp_centos7_selinux -Platform Linux vpp_centos7_selinux - 3.10.0-957.12.1.el7.x86_64 #1 SMP Mon Apr 29 - 14:59:59 UTC 2019 x86_64 x86_64 -Alert Count 1 -First Seen 2019-05-13 18:10:50 EDT -Last Seen 2019-05-13 18:10:50 EDT -Local ID a418f869-f470-4c8a-b8e9-bdd41f2dd60b - -Raw Audit Messages -type=AVC msg=audit(1557785450.964:257): avc: denied { read write } for pid=5273 comm="vpp" name="noiommu-0" dev="devtmpfs" ino=36022 scontext=system_u:system_r:vpp_t:s0 tcontext=system_u:object_r:device_t:s0 tclass=chr_file permissive=1 - - -type=AVC msg=audit(1557785450.964:257): avc: denied { open } for pid=5273 comm="vpp" path="/dev/vfio/noiommu-0" dev="devtmpfs" ino=36022 scontext=system_u:system_r:vpp_t:s0 tcontext=system_u:object_r:device_t:s0 tclass=chr_file permissive=1 - - -type=SYSCALL msg=audit(1557785450.964:257): arch=x86_64 syscall=open success=yes exit=ENOTBLK a0=7fb395ffd7f0 a1=2 a2=7fb395ffd803 a3=7fb395ffe2a0 items=0 ppid=1 pid=5273 auid=4294967295 uid=0 gid=0 euid=0 suid=0 fsuid=0 egid=993 sgid=0 fsgid=993 tty=(none) ses=4294967295 comm=vpp exe=/usr/bin/vpp subj=system_u:system_r:vpp_t:s0 key=(null) - -Hash: vpp,vpp_t,device_t,chr_file,read,write -``` - -In general, this command pumps out too much info and is only needed for -additional debugging for tougher issues. Also note that once the process being -tested is restarted, this command loses it's context and will not provide any -information: - -``` -$ sealert -l a418f869-f470-4c8a-b8e9-bdd41f2dd60b -Error -query_alerts error (1003): id (a418f869-f470-4c8a-b8e9-bdd41f2dd60b) not found -``` - -#### ausearch | audit2allow and semodule Commands - -These set of commands are more useful for basic debugging. The -`ausearch | audit2allow` commands generate a set files. It may be worthwhile to -run the commands in a temporary subdirectory: - -``` -$ mkdir test-01/; cd test-01/ - -$ sudo ausearch -c 'vpp_main' --raw | audit2allow -M my-vppmain - -$ ls -my-vpp.pp my-vpp.te - -$ cat my-vpp.te -module my-vpp 1.0; - -require { - type user_home_t; - type vpp_t; - class packet_socket map; - class file { open read }; -} - -#============= vpp_t ============== -allow vpp_t self:packet_socket map; -allow vpp_t user_home_t:file { open read }; -``` - -As shown above, the file `my-vpp.te` has been generated. This file shows -possible changes to the SELinux policy that may fix the issue. If an SELinux -policy was being created from scratch, this policy could be applied using the -`semodule -i my-vpp.pp` command. HOWEVER, VPP already has a policy in place. So -these changes need to be incorporated into the existing policy. The VPP SELinux -policy is located in the following files: - -``` -$ ls extras/selinux/ -selinux_doc.md vpp-custom.fc vpp-custom.if vpp-custom.te -``` - -In this example, `map` needs to be added to the `packet_socket` class. If the -`vpp-custom.te` is examined (prior to this fix), then one would see that the -`packet_socket` class is already defined and just needs to be updated: - -``` -$ vi extras/selinux/vpp-custom.te -: -allow vpp_t self:process { execmem execstack setsched signal }; # too benevolent -allow vpp_t self:packet_socket { bind create setopt ioctl }; <--- -allow vpp_t self:tun_socket { create relabelto relabelfrom }; -: -``` - -Before blindly applying the changes proposed by the `ausearch | audit2allow` -commands, try to determine what is being allowed by the policy and determine if -this is desired, or if the code can be reworked to no longer require the -suggested permission. In the `my-vpp.te` file from above, it is suggested to -allow `vpp_t` (i.e. the VPP process) access to all files in the home directory -(`allow vpp_t user_home_t:file { open read };`). This was because a -`vppctl exec` command was executed calling a script located in the -`/home/<user>/` directory. Once this script was run from the `/usr/share/vpp/` -directory as described in a section above, these permissions were no longer -needed. diff --git a/extras/selinux/selinux_doc.rst b/extras/selinux/selinux_doc.rst new file mode 100644 index 00000000000..a902ec675ce --- /dev/null +++ b/extras/selinux/selinux_doc.rst @@ -0,0 +1,554 @@ +.. _selinux_doc: + +SELinux - VPP Custom SELinux Policy +=================================== + +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-1: + +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-2: + +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/*`` + +Debug SELinux Issues +-------------------- + +If SELinux issues are suspected, there are a few steps that can be taken +to debug the issue. This section provides a few pointers on on those +steps. Any SELinux JIRAs will need this information to properly address +the issue. + +Additional SELinux Packages and Setup +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +First, install the SELinux troubleshooting packages: + +:: + + $ sudo yum -y install setroubleshoot setroubleshoot-server setools-console + -- OR -- + $ sudo dnf -y install setroubleshoot setroubleshoot-server setools-console + +To enable proper logging, restart auditd: + +:: + + $ sudo service auditd restart + +While debugging issues, it is best to set SELinux to ``Permissive`` +mode. In ``Permissive`` mode, SELinux will still detect and flag errors, +but will allow processes to continue normal operation. This allows +multiple errors to be collected at once as opposed to breaking on each +individual error. To set SELinux to ``Permissive`` mode (until next +reboot or it is set back), use: + +:: + + $ sudo setenforce 0 + + $ getenforce + Permissive + +After debugging, to set SELinux back to ``Enforcing`` mode, use: + +:: + + $ sudo setenforce 1 + + $ getenforce + Enforcing + +Debugging +~~~~~~~~~ + +Once the SELinux troubleshooting packages are installed, perform the +actions that are suspected to be blocked by SELinux. Either ``tail`` the +log during these actions or ``grep`` the log for additional SELinux +logs: + +:: + + sudo tail -f /var/log/messages + -- OR -- + sudo journalctl -f + +Below are some examples of SELinux logs that are generated: + +:: + + May 14 11:28:34 svr-22 setroubleshoot: SELinux is preventing /usr/bin/vpp from read access on the file hostCreate.txt. For complete SELinux messages run: sealert -l a418f869-f470-4c8a-b8e9-bdd41f2dd60b + May 14 11:28:34 svr-22 python: SELinux is preventing /usr/bin/vpp from read access on the file hostCreate.txt.#012#012***** Plugin catchall (100. confidence) suggests **************************#012#012If you believe that vpp should be allowed read access on the hostCreate.txt file by default.#012Then you should report this as a bug.#012You can generate a local policy module to allow this access.#012Do#012allow this access for now by executing:#012# ausearch -c 'vpp_main' --raw | audit2allow -M my-vppmain#012# semodule -i my-vppmain.pp#012 + May 14 11:28:34 svr-22 setroubleshoot: SELinux is preventing /usr/bin/vpp from read access on the file hostCreate.txt. For complete SELinux messages run: sealert -l a418f869-f470-4c8a-b8e9-bdd41f2dd60b + May 14 11:28:34 svr-22 python: SELinux is preventing /usr/bin/vpp from read access on the file hostCreate.txt.#012#012***** Plugin catchall (100. confidence) suggests **************************#012#012If you believe that vpp should be allowed read access on the hostCreate.txt file by default.#012Then you should report this as a bug.#012You can generate a local policy module to allow this access.#012Do#012allow this access for now by executing:#012# ausearch -c 'vpp_main' --raw | audit2allow -M my-vppmain#012# semodule -i my-vppmain.pp#012 + May 14 11:28:37 svr-22 setroubleshoot: SELinux is preventing vpp_main from map access on the packet_socket packet_socket. For complete SELinux messages run: sealert -l ab6667d9-3f14-4dbd-96a0-7a655f7b4eb1 + May 14 11:28:37 svr-22 python: SELinux is preventing vpp_main from map access on the packet_socket packet_socket.#012#012***** Plugin catchall (100. confidence) suggests **************************#012#012If you believe that vpp_main should be allowed map access on the packet_socket packet_socket by default.#012Then you should report this as a bug.#012You can generate a local policy module to allow this access.#012Do#012allow this access for now by executing:#012# ausearch -c 'vpp_main' --raw | audit2allow -M my-vppmain#012# semodule -i my-vppmain.pp#012 + May 14 11:28:51 svr-22 setroubleshoot: SELinux is preventing vpp_main from map access on the packet_socket packet_socket. For complete SELinux messages run: sealert -l ab6667d9-3f14-4dbd-96a0-7a655f7b4eb1 + May 14 11:28:51 svr-22 python: SELinux is preventing vpp_main from map access on the packet_socket packet_socket.#012#012***** Plugin catchall (100. confidence) suggests **************************#012#012If you believe that vpp_main should be allowed map access on the packet_socket packet_socket by default.#012Then you should report this as a bug.#012You can generate a local policy module to allow this access.#012Do#012allow this access for now by executing:#012# ausearch -c 'vpp_main' --raw | audit2allow -M my-vppmain#012# semodule -i my-vppmain.pp#012 + +From the logs above, there are two sets of commands that are recommended +to be run. The first is to run the ``sealert`` command. The second is to +run the ``ausearch | audit2allow`` commands and the ``semodule`` +command. + +sealert Command +^^^^^^^^^^^^^^^ + +This ``sealert`` command provides a more detailed output for the given +issue detected. + +:: + + $ sealert -l a418f869-f470-4c8a-b8e9-bdd41f2dd60b + SELinux is preventing /usr/bin/vpp from 'read, write' accesses on the chr_file noiommu-0. + + ***** Plugin device (91.4 confidence) suggests **************************** + + If you want to allow vpp to have read write access on the noiommu-0 chr_file + Then you need to change the label on noiommu-0 to a type of a similar device. + Do + # semanage fcontext -a -t SIMILAR_TYPE 'noiommu-0' + # restorecon -v 'noiommu-0' + + ***** Plugin catchall (9.59 confidence) suggests ************************** + + If you believe that vpp should be allowed read write access on the noiommu-0 chr_file by default. + Then you should report this as a bug. + You can generate a local policy module to allow this access. + Do + allow this access for now by executing: + # ausearch -c 'vpp' --raw | audit2allow -M my-vpp + # semodule -i my-vpp.pp + + + Additional Information: + Source Context system_u:system_r:vpp_t:s0 + Target Context system_u:object_r:device_t:s0 + Target Objects noiommu-0 [ chr_file ] + Source vpp + Source Path /usr/bin/vpp + Port <Unknown> + Host vpp_centos7_selinux + Source RPM Packages vpp-19.01.2-rc0~17_gcfd3086.x86_64 + Target RPM Packages + Policy RPM selinux-policy-3.13.1-229.el7_6.12.noarch + Selinux Enabled True + Policy Type targeted + Enforcing Mode Permissive + Host Name vpp_centos7_selinux + Platform Linux vpp_centos7_selinux + 3.10.0-957.12.1.el7.x86_64 #1 SMP Mon Apr 29 + 14:59:59 UTC 2019 x86_64 x86_64 + Alert Count 1 + First Seen 2019-05-13 18:10:50 EDT + Last Seen 2019-05-13 18:10:50 EDT + Local ID a418f869-f470-4c8a-b8e9-bdd41f2dd60b + + Raw Audit Messages + type=AVC msg=audit(1557785450.964:257): avc: denied { read write } for pid=5273 comm="vpp" name="noiommu-0" dev="devtmpfs" ino=36022 scontext=system_u:system_r:vpp_t:s0 tcontext=system_u:object_r:device_t:s0 tclass=chr_file permissive=1 + + + type=AVC msg=audit(1557785450.964:257): avc: denied { open } for pid=5273 comm="vpp" path="/dev/vfio/noiommu-0" dev="devtmpfs" ino=36022 scontext=system_u:system_r:vpp_t:s0 tcontext=system_u:object_r:device_t:s0 tclass=chr_file permissive=1 + + + type=SYSCALL msg=audit(1557785450.964:257): arch=x86_64 syscall=open success=yes exit=ENOTBLK a0=7fb395ffd7f0 a1=2 a2=7fb395ffd803 a3=7fb395ffe2a0 items=0 ppid=1 pid=5273 auid=4294967295 uid=0 gid=0 euid=0 suid=0 fsuid=0 egid=993 sgid=0 fsgid=993 tty=(none) ses=4294967295 comm=vpp exe=/usr/bin/vpp subj=system_u:system_r:vpp_t:s0 key=(null) + + Hash: vpp,vpp_t,device_t,chr_file,read,write + +In general, this command pumps out too much info and is only needed for +additional debugging for tougher issues. Also note that once the process +being tested is restarted, this command loses it’s context and will not +provide any information: + +:: + + $ sealert -l a418f869-f470-4c8a-b8e9-bdd41f2dd60b + Error + query_alerts error (1003): id (a418f869-f470-4c8a-b8e9-bdd41f2dd60b) not found + +ausearch \| audit2allow and semodule Commands +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +These set of commands are more useful for basic debugging. The +``ausearch | audit2allow`` commands generate a set files. It may be +worthwhile to run the commands in a temporary subdirectory: + +:: + + $ mkdir test-01/; cd test-01/ + + $ sudo ausearch -c 'vpp_main' --raw | audit2allow -M my-vppmain + + $ ls + my-vpp.pp my-vpp.te + + $ cat my-vpp.te + module my-vpp 1.0; + + require { + type user_home_t; + type vpp_t; + class packet_socket map; + class file { open read }; + } + + #============= vpp_t ============== + allow vpp_t self:packet_socket map; + allow vpp_t user_home_t:file { open read }; + +As shown above, the file ``my-vpp.te`` has been generated. This file +shows possible changes to the SELinux policy that may fix the issue. If +an SELinux policy was being created from scratch, this policy could be +applied using the ``semodule -i my-vpp.pp`` command. HOWEVER, VPP +already has a policy in place. So these changes need to be incorporated +into the existing policy. The VPP SELinux policy is located in the +following files: + +:: + + $ ls extras/selinux/ + selinux_doc.md vpp-custom.fc vpp-custom.if vpp-custom.te + +In this example, ``map`` needs to be added to the ``packet_socket`` +class. If the ``vpp-custom.te`` is examined (prior to this fix), then +one would see that the ``packet_socket`` class is already defined and +just needs to be updated: + +:: + + $ vi extras/selinux/vpp-custom.te + : + allow vpp_t self:process { execmem execstack setsched signal }; # too benevolent + allow vpp_t self:packet_socket { bind create setopt ioctl }; <--- + allow vpp_t self:tun_socket { create relabelto relabelfrom }; + : + +Before blindly applying the changes proposed by the +``ausearch | audit2allow`` commands, try to determine what is being +allowed by the policy and determine if this is desired, or if the code +can be reworked to no longer require the suggested permission. In the +``my-vpp.te`` file from above, it is suggested to allow ``vpp_t`` +(i.e. the VPP process) access to all files in the home directory +(``allow vpp_t user_home_t:file { open read };``). This was because a +``vppctl exec`` command was executed calling a script located in the +``/home/<user>/`` directory. Once this script was run from the +``/usr/share/vpp/`` directory as described in a section above, these +permissions were no longer needed. |