INSTALL.SELinux.md

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