INSTALL.SELinux.rst

   1 ..
   2       Licensed under the Apache License, Version 2.0 (the "License"); you may
   3       not use this file except in compliance with the License. You may obtain
   4       a copy of the License at
   5
   6           http://www.apache.org/licenses/LICENSE-2.0
   7
   8       Unless required by applicable law or agreed to in writing, software
   9       distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  10       WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
  11       License for the specific language governing permissions and limitations
  12       under the License.
  13
  14       Convention for heading levels in Open vSwitch documentation:
  15
  16       =======  Heading 0 (reserved for the title in a document)
  17       -------  Heading 1
  18       ~~~~~~~  Heading 2
  19       +++++++  Heading 3
  20       '''''''  Heading 4
  21
  22       Avoid deeper levels because they do not render well.
  23
  24 =========================
  25 Open vSwitch with SELinux
  26 =========================
  27
  28 Security-Enhanced Linux (SELinux) is a Linux kernel security module that limits
  29 "the malicious things" that certain processes, including OVS, can do to the
  30 system in case they get compromised.  In our case SELinux basically serves as
  31 the "second line of defense" that limits the things that OVS processes are
  32 allowed to do.  The "first line of defense" is proper input validation that
  33 eliminates code paths that could be used by attacker to do any sort of "escape
  34 attacks", such as file name escape, shell escape, command line argument escape,
  35 buffer escape. Since developers don't always implement proper input validation,
  36 then SELinux Access Control's goal is to confine damage of such attacks, if
  37 they turned out to be possible.
  38
  39 Besides Type Enforcement there are other SELinux features, but they are out of
  40 scope for this document.
  41
  42 Currently there are two SELinux policies for Open vSwitch:
  43
  44 - the one that ships with your Linux distribution (i.e.
  45   selinux-policy-targeted package)
  46
  47 - the one that ships with OVS (i.e. openvswitch-selinux-policy package)
  48
  49 Limitations
  50 -----------
  51
  52 If Open vSwitch is directly started from command line, then it will run under
  53 ``unconfined_t`` SELinux domain that basically lets daemon to do whatever it
  54 likes.  This is very important for developers to understand, because they might
  55 introduced code in OVS that invokes new system calls that SELinux policy did
  56 not anticipate.  This means that their feature may have worked out just fine
  57 for them.  However, if someone else would try to run the same code when Open
  58 vSwitch is started through systemctl, then Open vSwitch would get Permission
  59 Denied errors.
  60
  61 Currently the only distributions that enforce SELinux on OVS by default are
  62 RHEL, CentOS and Fedora.  While Ubuntu and Debian also have some SELinux
  63 support, they run Open vSwitch under the unrestricted ``unconfined`` domain.
  64 Also, it seems that Ubuntu is leaning towards Apparmor that works slightly
  65 differently than SELinux.
  66
  67 SELinux and Open vSwitch are moving targets.  What this means is that, if you
  68 solely rely on your Linux distribution's SELinux policy, then this policy might
  69 not have correctly anticipated that a newer Open vSwitch version needs extra
  70 white list rules.  However, if you solely rely on SELinux policy that ships
  71 with Open vSwitch, then Open vSwitch developers might not have correctly
  72 anticipated the feature set that your SELinux implementation supports.
  73
  74 Installation
  75 ------------
  76
  77 Refer to the `Fedora installation guide <INSTALL.Fedora.rst>`__ for
  78 instructions on how to build all Open vSwitch rpm packages.
  79
  80 Once the package is built, install it on your Linux distribution::
  81
  82     $ dnf install openvswitch-selinux-policy-2.4.1-1.el7.centos.noarch.rpm
  83
  84 Restart Open vSwitch::
  85
  86     $ systemctl restart openvswitch
  87
  88 Troubleshooting
  89 ---------------
  90
  91 When SELinux was implemented some of the standard system utilities acquired
  92 ``-Z`` flag (e.g. ``ps -Z``, ``ls -Z``).  For example, to find out under which
  93 SELinux security domain process runs, use::
  94
  95     $ ps -AZ | grep ovs-vswitchd
  96     system_u:system_r:openvswitch_t:s0 854 ?    ovs-vswitchd
  97
  98 To find out the SELinux label of file or directory, use::
  99
 100     $ ls -Z /etc/openvswitch/conf.db
 101     system_u:object_r:openvswitch_rw_t:s0 /etc/openvswitch/conf.db
 102
 103 If, for example, SELinux policy for Open vSwitch is too strict, then you might
 104 see in Open vSwitch log files "Permission Denied" errors::
 105
 106     $ cat /var/log/openvswitch/ovs-vswitchd.log
 107     vlog|INFO|opened log file /var/log/openvswitch/ovs-vswitchd.log
 108     ovs_numa|INFO|Discovered 2 CPU cores on NUMA node 0
 109     ovs_numa|INFO|Discovered 1 NUMA nodes and 2 CPU cores
 110     reconnect|INFO|unix:/var/run/openvswitch/db.sock: connecting...
 111     reconnect|INFO|unix:/var/run/openvswitch/db.sock: connected
 112     netlink_socket|ERR|fcntl: Permission denied
 113     dpif_netlink|ERR|Generic Netlink family 'ovs_datapath' does not exist.
 114                      The Open vSwitch kernel module is probably not loaded.
 115     dpif|WARN|failed to enumerate system datapaths: Permission denied
 116     dpif|WARN|failed to create datapath ovs-system: Permission denied
 117
 118 However, not all "Permission denied" errors are caused by SELinux.  So, before
 119 blaming too strict SELinux policy, make sure that indeed SELinux was the one
 120 that denied OVS access to certain resources, for example, run:
 121
 122     $ grep "openvswitch_t" /var/log/audit/audit.log | tail
 123     type=AVC msg=audit(1453235431.640:114671): avc:  denied  { getopt } for  pid=4583 comm="ovs-vswitchd" scontext=system_u:system_r:openvswitch_t:s0 tcontext=system_u:system_r:openvswitch_t:s0 tclass=netlink_generic_socket permissive=0
 124
 125 If SELinux denied OVS access to certain resources, then make sure that you have
 126 installed our SELinux policy package that "loosens" up distribution's SELinux
 127 policy::
 128
 129     $ rpm -qa | grep openvswitch-selinux
 130     openvswitch-selinux-policy-2.4.1-1.el7.centos.noarch
 131
 132 Then verify that this module was indeed loaded::
 133
 134     # semodule -l | grep openvswitch
 135     openvswitch-custom    1.0
 136     openvswitch          1.1.1
 137
 138 If you still see Permission denied errors, then take a look into
 139 ``selinux/openvswitch.te`` file in the OVS source tree and try to add white
 140 list rules.  This is really simple, just run SELinux audit2allow tool::
 141
 142     $ grep "openvswitch_t" /var/log/audit/audit.log | audit2allow -M ovslocal
 143
 144 Contributing SELinux policy patches
 145 -----------------------------------
 146
 147 Here are few things to consider before proposing SELinux policy patches to Open
 148 vSwitch developer mailing list:
 149
 150 1. The SELinux policy that resides in Open vSwitch source tree amends SELinux
 151    policy that ships with your distributions.
 152
 153    Implications of this are that it is assumed that the distribution's Open
 154    vSwitch SELinux module must be already loaded to satisfy dependencies.
 155
 156 2. The SELinux policy that resides in Open vSwitch source tree must work on all
 157    currently relevant Linux distributions.
 158
 159    Implications of this are that you should use only those SELinux policy
 160    features that are supported by the lowest SELinux version out there.
 161    Typically this means that you should test your SELinux policy changes on the
 162    oldest RHEL or CentOS version that this OVS version supports.  Check
 163    INSTALL.Fedora.rst file to find out this.
 164
 165 3. The SELinux policy is enforced only when state transition to
 166    ``openvswitch_t`` domain happens.
 167
 168    Implications of this are that perhaps instead of loosening SELinux policy
 169    you can do certain things at the time rpm package is installed.
 170
 171 Reporting Bugs
 172 --------------
 173
 174 Report problems to bugs@openvswitch.org.