<commit_before>.. only:: not (epub or latex or html)

    WARNING: You are looking at unreleased Cilium documentation.
    Please use the official rendered version released here:
    https://docs.cilium.io

.. _admin_system_reqs:

*******************
System Requirements
*******************

Before installing Cilium, please ensure that your system meets the minimum
requirements below. Most modern Linux distributions already do.

Summary
=======

When running Cilium using the container image ``cilium/cilium``, the host
system must meet these requirements:

- `Linux kernel`_ >= 4.9.17

When running Cilium as a native process on your host (i.e. **not** running the
``cilium/cilium`` container image) these additional requirements must be met:

- `clang+LLVM`_ >= 10.0
- iproute2_ with eBPF templating patches [#iproute2_foot]_

.. _`clang+LLVM`: https://llvm.org
.. _iproute2: https://www.kernel.org/pub/linux/utils/net/iproute2/

When running Cilium without Kubernetes these additional requirements
must be met:

- :ref:`req_kvstore` etcd >= 3.1.0 or consul >= 0.6.4

======================== ========================== ===================
Requirement              Minimum Version            In cilium container
======================== ========================== ===================
`Linux kernel`_          >= 4.9.17                  no
Key-Value store (etcd)   >= 3.1.0                   no
Key-Value store (consul) >= 0.6.4                   no
clang+LLVM               >= 10.0                    yes
iproute2                 >= 5.0.0 [#iproute2_foot]_ yes
======================== ========================== ===================

.. [#iproute2_foot] Requires support for eBPF templating as documented
   :ref:`below <iproute2_requirements>`.

.. hint:: 

    ``cilium kernel-check`` can be invoked as a Kubernetes Job  
    in order to check whether the machine provides the relevant eBPF capabilities: 

    .. parsed-literal::

       kubectl apply -f |SCM_WEB|/examples/kubernetes/kernel-check/kernel-check.yaml

Linux Distribution Compatibility Matrix
=======================================

The following table lists Linux distributions that are known to work
well with Cilium.

========================== ====================
Distribution               Minimum Version
========================== ====================
`Amazon Linux 2`_          all
`Container-Optimized OS`_  all
`CentOS`_                  >= 7.0 [#centos_foot]_
CoreOS_                    stable (>= 1298.5.0)
Debian_                    >= 9 Stretch
`Fedora Atomic/Core`_      >= 25
LinuxKit_                  all
`RedHat Enterprise Linux`_ >= 8.0
Ubuntu_                    >= 16.04.2, >= 16.10
Opensuse_                  Tumbleweed, >=Leap 15.0
RancherOS_                 >= 1.5.5
========================== ====================

.. _Amazon Linux 2: https://aws.amazon.com/amazon-linux-2/
.. _CentOS: https://centos.org
.. _Container-Optimized OS: https://cloud.google.com/container-optimized-os/docs
.. _CoreOS: https://coreos.com/releases/
.. _Debian: https://wiki.debian.org/DebianStretch
.. _Fedora Atomic/Core: http://www.projectatomic.io/blog/2017/03/fedora_atomic_2week_2/
.. _LinuxKit: https://github.com/linuxkit/linuxkit/tree/master/kernel
.. _RedHat Enterprise Linux: https://www.redhat.com/en/technologies/linux-platforms/enterprise-linux
.. _Ubuntu: https://wiki.ubuntu.com/YakketyYak/ReleaseNotes#Linux_kernel_4.8
.. _Opensuse: https://www.opensuse.org/
.. _RancherOS: https://rancher.com/rancher-os/

.. [#centos_foot] CentOS 7 requires a third-party kernel provided by `ElRepo <http://elrepo.org/tiki/tiki-index.php>`_
    whereas CentOS 8 ships with a supported kernel.

.. note:: The above list is based on feedback by users. If you find an unlisted
          Linux distribution that works well, please let us know by opening a
          GitHub issue or by creating a pull request that updates this guide.

.. note:: Systemd 245 and above (``systemctl --version``) overrides ``rp_filter`` setting
          of Cilium network interfaces. This introduces connectivity issues (see
          `GH-10645 <https://github.com/cilium/cilium/issues/10645>`_ for details). To
          avoid that, configure ``rp_filter`` in systemd using the following commands:

          .. code:: bash

              echo 'net.ipv4.conf.lxc*.rp_filter = 0' > /etc/sysctl.d/99-override_cilium_rp_filter.conf
              systemctl restart systemd-sysctl

.. _admin_kernel_version:

Linux Kernel
============

Cilium leverages and builds on the kernel eBPF functionality as well as various
subsystems which integrate with eBPF. Therefore, host systems are required to
run Linux kernel version 4.9.17 or later to run a Cilium agent. More recent
kernels may provide additional eBPF functionality that Cilium will automatically
detect and use on agent start.

In order for the eBPF feature to be enabled properly, the following kernel
configuration options must be enabled. This is typically the case  with
distribution kernels. When an option can be built as a module or statically
linked, either choice is valid.

.. code:: bash

        CONFIG_BPF=y
        CONFIG_BPF_SYSCALL=y
        CONFIG_NET_CLS_BPF=y
        CONFIG_BPF_JIT=y
        CONFIG_NET_CLS_ACT=y
        CONFIG_NET_SCH_INGRESS=y
        CONFIG_CRYPTO_SHA1=y
        CONFIG_CRYPTO_USER_API_HASH=y

.. note::

   Users running Linux 4.10 or earlier with Cilium CIDR policies may face
   :ref:`cidr_limitations`.

L7 proxy redirection currently uses ``TPROXY`` iptables actions as well
as ``socket`` matches. For L7 redirection to work as intended kernel
configuration must include the following modules:

.. code:: bash

        CONFIG_NETFILTER_XT_TARGET_TPROXY=m
        CONFIG_NETFILTER_XT_MATCH_MARK=m
        CONFIG_NETFILTER_XT_MATCH_SOCKET=m

When ``xt_socket`` kernel module is missing the forwarding of
redirected L7 traffic does not work in non-tunneled datapath
modes. Since some notable kernels (e.g., COS) are shipping without
``xt_socket`` module, Cilium implements a fallback compatibility mode
to allow L7 policies and visibility to be used with those
kernels. Currently this fallback disables ``ip_early_demux`` kernel
feature in non-tunneled datapath modes, which may decrease system
networking performance. This guarantees HTTP and Kafka redirection
works as intended.  However, if HTTP or Kafka enforcement policies or
visibility annotations are never used, this behavior can be turned off
by adding the following to the helm configuration command line:

.. parsed-literal::

   helm install cilium |CHART_RELEASE| \\
     ...
     --set enableXTSocketFallback=false

.. _features_kernel_matrix:

Required Kernel Versions for Advanced Features
==============================================

Cilium requires Linux kernel 4.9.17 or higher; however, development on
additional kernel features continues to progress in the Linux community. Some
of Cilium's features are dependent on newer kernel versions and are thus
enabled by upgrading to more recent kernel versions as detailed below.

======================================== ===============================
Cilium Feature                           Minimum Kernel Version
======================================== ===============================
:ref:`concepts_fragmentation`            >= 4.10
:ref:`cidr_limitations`                  >= 4.11
:ref:`host-services`                     >= 4.19.57, >= 5.1.16,  >= 5.2
:ref:`kubeproxy-free`                    >= 4.19.57, >= 5.1.16,  >= 5.2
:ref:`bandwidth-manager`                 >= 5.1
:ref:`local-redirect-policy`             >= 4.19.57, >= 5.1.16,  >= 5.2
Full support for :ref:`session-affinity` >= 5.7
BPF-based proxy redirection              >= 5.7
======================================== ===============================
<commit_msg>docs: Document kernel requirement for BPF host routing<commit_after>.. only:: not (epub or latex or html)

    WARNING: You are looking at unreleased Cilium documentation.
    Please use the official rendered version released here:
    https://docs.cilium.io

.. _admin_system_reqs:

*******************
System Requirements
*******************

Before installing Cilium, please ensure that your system meets the minimum
requirements below. Most modern Linux distributions already do.

Summary
=======

When running Cilium using the container image ``cilium/cilium``, the host
system must meet these requirements:

- `Linux kernel`_ >= 4.9.17

When running Cilium as a native process on your host (i.e. **not** running the
``cilium/cilium`` container image) these additional requirements must be met:

- `clang+LLVM`_ >= 10.0
- iproute2_ with eBPF templating patches [#iproute2_foot]_

.. _`clang+LLVM`: https://llvm.org
.. _iproute2: https://www.kernel.org/pub/linux/utils/net/iproute2/

When running Cilium without Kubernetes these additional requirements
must be met:

- :ref:`req_kvstore` etcd >= 3.1.0 or consul >= 0.6.4

======================== ========================== ===================
Requirement              Minimum Version            In cilium container
======================== ========================== ===================
`Linux kernel`_          >= 4.9.17                  no
Key-Value store (etcd)   >= 3.1.0                   no
Key-Value store (consul) >= 0.6.4                   no
clang+LLVM               >= 10.0                    yes
iproute2                 >= 5.0.0 [#iproute2_foot]_ yes
======================== ========================== ===================

.. [#iproute2_foot] Requires support for eBPF templating as documented
   :ref:`below <iproute2_requirements>`.

.. hint:: 

    ``cilium kernel-check`` can be invoked as a Kubernetes Job  
    in order to check whether the machine provides the relevant eBPF capabilities: 

    .. parsed-literal::

       kubectl apply -f |SCM_WEB|/examples/kubernetes/kernel-check/kernel-check.yaml

Linux Distribution Compatibility Matrix
=======================================

The following table lists Linux distributions that are known to work
well with Cilium.

========================== ====================
Distribution               Minimum Version
========================== ====================
`Amazon Linux 2`_          all
`Container-Optimized OS`_  all
`CentOS`_                  >= 7.0 [#centos_foot]_
CoreOS_                    stable (>= 1298.5.0)
Debian_                    >= 9 Stretch
`Fedora Atomic/Core`_      >= 25
LinuxKit_                  all
`RedHat Enterprise Linux`_ >= 8.0
Ubuntu_                    >= 16.04.2, >= 16.10
Opensuse_                  Tumbleweed, >=Leap 15.0
RancherOS_                 >= 1.5.5
========================== ====================

.. _Amazon Linux 2: https://aws.amazon.com/amazon-linux-2/
.. _CentOS: https://centos.org
.. _Container-Optimized OS: https://cloud.google.com/container-optimized-os/docs
.. _CoreOS: https://coreos.com/releases/
.. _Debian: https://wiki.debian.org/DebianStretch
.. _Fedora Atomic/Core: http://www.projectatomic.io/blog/2017/03/fedora_atomic_2week_2/
.. _LinuxKit: https://github.com/linuxkit/linuxkit/tree/master/kernel
.. _RedHat Enterprise Linux: https://www.redhat.com/en/technologies/linux-platforms/enterprise-linux
.. _Ubuntu: https://wiki.ubuntu.com/YakketyYak/ReleaseNotes#Linux_kernel_4.8
.. _Opensuse: https://www.opensuse.org/
.. _RancherOS: https://rancher.com/rancher-os/

.. [#centos_foot] CentOS 7 requires a third-party kernel provided by `ElRepo <http://elrepo.org/tiki/tiki-index.php>`_
    whereas CentOS 8 ships with a supported kernel.

.. note:: The above list is based on feedback by users. If you find an unlisted
          Linux distribution that works well, please let us know by opening a
          GitHub issue or by creating a pull request that updates this guide.

.. note:: Systemd 245 and above (``systemctl --version``) overrides ``rp_filter`` setting
          of Cilium network interfaces. This introduces connectivity issues (see
          `GH-10645 <https://github.com/cilium/cilium/issues/10645>`_ for details). To
          avoid that, configure ``rp_filter`` in systemd using the following commands:

          .. code:: bash

              echo 'net.ipv4.conf.lxc*.rp_filter = 0' > /etc/sysctl.d/99-override_cilium_rp_filter.conf
              systemctl restart systemd-sysctl

.. _admin_kernel_version:

Linux Kernel
============

Cilium leverages and builds on the kernel eBPF functionality as well as various
subsystems which integrate with eBPF. Therefore, host systems are required to
run Linux kernel version 4.9.17 or later to run a Cilium agent. More recent
kernels may provide additional eBPF functionality that Cilium will automatically
detect and use on agent start.

In order for the eBPF feature to be enabled properly, the following kernel
configuration options must be enabled. This is typically the case  with
distribution kernels. When an option can be built as a module or statically
linked, either choice is valid.

.. code:: bash

        CONFIG_BPF=y
        CONFIG_BPF_SYSCALL=y
        CONFIG_NET_CLS_BPF=y
        CONFIG_BPF_JIT=y
        CONFIG_NET_CLS_ACT=y
        CONFIG_NET_SCH_INGRESS=y
        CONFIG_CRYPTO_SHA1=y
        CONFIG_CRYPTO_USER_API_HASH=y

.. note::

   Users running Linux 4.10 or earlier with Cilium CIDR policies may face
   :ref:`cidr_limitations`.

L7 proxy redirection currently uses ``TPROXY`` iptables actions as well
as ``socket`` matches. For L7 redirection to work as intended kernel
configuration must include the following modules:

.. code:: bash

        CONFIG_NETFILTER_XT_TARGET_TPROXY=m
        CONFIG_NETFILTER_XT_MATCH_MARK=m
        CONFIG_NETFILTER_XT_MATCH_SOCKET=m

When ``xt_socket`` kernel module is missing the forwarding of
redirected L7 traffic does not work in non-tunneled datapath
modes. Since some notable kernels (e.g., COS) are shipping without
``xt_socket`` module, Cilium implements a fallback compatibility mode
to allow L7 policies and visibility to be used with those
kernels. Currently this fallback disables ``ip_early_demux`` kernel
feature in non-tunneled datapath modes, which may decrease system
networking performance. This guarantees HTTP and Kafka redirection
works as intended.  However, if HTTP or Kafka enforcement policies or
visibility annotations are never used, this behavior can be turned off
by adding the following to the helm configuration command line:

.. parsed-literal::

   helm install cilium |CHART_RELEASE| \\
     ...
     --set enableXTSocketFallback=false

.. _features_kernel_matrix:

Required Kernel Versions for Advanced Features
==============================================

Cilium requires Linux kernel 4.9.17 or higher; however, development on
additional kernel features continues to progress in the Linux community. Some
of Cilium's features are dependent on newer kernel versions and are thus
enabled by upgrading to more recent kernel versions as detailed below.

======================================== ===============================
Cilium Feature                           Minimum Kernel Version
======================================== ===============================
:ref:`concepts_fragmentation`            >= 4.10
:ref:`cidr_limitations`                  >= 4.11
:ref:`host-services`                     >= 4.19.57, >= 5.1.16,  >= 5.2
:ref:`kubeproxy-free`                    >= 4.19.57, >= 5.1.16,  >= 5.2
:ref:`bandwidth-manager`                 >= 5.1
:ref:`local-redirect-policy`             >= 4.19.57, >= 5.1.16,  >= 5.2
Full support for :ref:`session-affinity` >= 5.7
BPF-based proxy redirection              >= 5.7
BPF-based host routing                   >= 5.10
======================================== ===============================

{'fraction_non_alphanumeric': 0.16817486617384655, 'fraction_numerical': 0.020328829977058375, 'mean_word_length': 3.291222313371616, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 76, 'https://': 28, 'lorem ipsum': 0, 'www.': 8, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1362769', 'n_tokens_mistral': 4687, 'n_tokens_neox': 4222, 'n_words': 1439}