[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-6547":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":16,"stars7d":17,"stars30d":18,"stars90d":15,"forks30d":15,"starsTrendScore":19,"compositeScore":20,"rankGlobal":9,"rankLanguage":9,"license":21,"archived":22,"fork":22,"defaultBranch":23,"hasWiki":22,"hasPages":22,"topics":24,"createdAt":9,"pushedAt":9,"updatedAt":25,"readmeContent":26,"aiSummary":27,"trendingCount":15,"starSnapshotCount":15,"syncStatus":14,"lastSyncTime":28,"discoverSource":29},6547,"katran","facebookincubator\u002Fkatran","facebookincubator","A high performance layer 4 load balancer",null,"C",5258,540,197,2,0,1,10,27,7,73.9,"GNU General Public License v2.0",false,"main",[],"2026-06-12 04:00:29","\u003Cp align=\"center\">\n  \u003Cimg src=\"logo.png\" alt=\"logo\" width=\"50%\"\u002F>\n\u003C\u002Fp>\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Ffacebookincubator\u002Fkatran\u002Factions?workflow=CI\">\n    \u003Cimg src=\"https:\u002F\u002Fgithub.com\u002Ffacebookincubator\u002Fkatran\u002Factions\u002Fworkflows\u002Fgetdeps_linux.yml\u002Fbadge.svg\" alt=\"CI Status\" \u002F>\n  \u003C\u002Fa>\n\u003C\u002Fp>\n\n\nKatran is a C++ library and [`BPF`](https:\u002F\u002Fen.wikipedia.org\u002Fwiki\u002FBerkeley_Packet_Filter) program to build high-performance\nlayer 4 load balancing forwarding plane. Katran leverages [`XDP infrastructure`](https:\u002F\u002Fwww.iovisor.org\u002Ftechnology\u002Fxdp)\nfrom the kernel to provide an in-kernel facility for fast packet's processing.\n\n## Katran's key features\n\n1. Blazing fast (especially w\u002F XDP in driver mode).\n2. Performance scaling linearly with a number of NIC's RX queues.\n3. RSS friendly encapsulation.\n\nSee the detailed features' description below :\n\n## Documentation's sections\n\n1. [`README`](README.md) (this file) - a generic overview of katran.\n2. [`USAGE`](USAGE.md) - the detailed description of how katran's library can be used, configured or changed.\n3. [`DEVELOPING`](DEVELOPING.md) - description of how developing process looks like: how to build and test katran.\n4. [`EXAMPLE`](EXAMPLE.md) - output of how to run provided examples (thrift and [`gRPC services`](https:\u002F\u002Fgrpc.io\u002Fdocs\u002F), which leverage katran library)\n\n## Examples of usage\n\nWe provide simple examples of katran library usage w\u002F thrift and gRPC endpoints.\nPlease refer to [`Examples`](EXAMPLE.md) for more detailed information.\n\n## Installation\n\nCurrent distribution tested: Ubuntu 20.04\n\nRequirements:\n  - Recent linux kernel (5.6+)\n  - Recent version of clang compiler (6.0+)\n      For ubuntu if unsure run `sudo apt install build-essential`\n\n### build_katran.sh\n\nTo build and install katran library and thrift\u002FgRPC examples - you need to run `build_katran.sh` script.\n\nIt should take care of all the required dependencies.\nIf you need to build it for other Linux distributions, you need to make sure that you have installed:\n    - [`folly`](https:\u002F\u002Fgithub.com\u002Ffacebook\u002Ffolly)\n    - recent version of clang compiler (6.0+)\n    - glog\u002Fgtest\u002Fgflags\u002Felf libraries\n\nAdditionally, if you want to build examples, [`fbthrift`](https:\u002F\u002Fgithub.com\u002Ffacebook\u002Ffbthrift) and [`gRPC`](https:\u002F\u002Fgithub.com\u002Fgrpc\u002Fgrpc) must be installed, as well!\n\nWhile we run Meta's CI on CentOS, we do our best to support OSS build on recent Ubuntu versions. If you have any issues with build or need older Ubuntu versions - open github issue or better send us PR :)\n\n## Motivation behind layer 4 load balancing\n\nLayer 4 load balancer (lb) enables to easily scale out Layer7 load balancers (the\nones which terminate TCP sessions). Benefits of L4 lb over other\ntechniques for scaling L7 lb is that it is :\n\n1. compared to DNS it doesn't need to wait for TTL to redirect traffic from failed\nL7 lb.\n\n2. compared to anycast-based solution, L4 lbs are more resilient to the networking\nrelated issues (which triggers mass ECMP reshuffle)\u002F enable better handling\nof adding\u002Fremoving of L7 lbs from the pool as well as provide better support for\nunequal load balancing.\n\n## Environment requirements for katran to run\n\nThere are special requirements for katran to work properly. However, we do\nbelieve that most of the potential users of the library can easily satisfy\nthem:\n\n1. katran works only in DSR (direct service response) mode.\n\n2. Network topology should be L3 based (everything above the top of the rack switch should be routed).\nThis is because we are 'offloading' routing decision for sending packets to the real server to first\nrouting device (by unconditionally sending all packets from katran there.)\n\n3. katran doesn't support fragmentation (it cannot forward the fragmented packet, nor it can fragment\nthem by itself if resulting packet size is bigger then MTU). This could be mitigated either by increasing MTU inside your\nnetwork or by changing advertising TCP MSS from L7 lbs (this is recommended even if you have\nincreased MTU, as it will prevent fragmentation related issues towards some of the client.\nFor example, if instead of default TCP MSS 1460 (for ipv4) you will advertise 1450 - it will help clients behind [`PPPoE`](https:\u002F\u002Fen.wikipedia.org\u002Fwiki\u002FPoint-to-Point_Protocol_over_Ethernet) connection).\n\n4. katran doesn't support packets w\u002F IP options set.\n\n5. Maximum packet size cannot be bigger than 3.5k (and 1.5k by default).\n\n6. katran is built with the assumption that it's going to be used in a\n\"load balancer on a stick\" scenario: where single interface would be used both for\ntraffic \"from user to L4 lb (ingress)\" and \"from L4 lb to L7 lb (egress).\"\n\n\u003Ch3 align=\"center\"> L4 load balancing network topology \u003C\u002Fh3>\n\n![alt text](imgs\u002Fkatran_pktflow.png \"Network Topology\")\n\n__Steps:__\n\n1. katran receives packet\n\n2. Checks if the destination of the packet is configured as a\nVIP (virtual IP address - IP address of the service).\n\n3. For an incoming packet toward a VIP - katran is checking if it saw packet from the same\nsession before, and if it has - it sends the packet to the same real (actual server\u002Fl7 lb\nwhich then processes\u002Fterminates the TCP session).\n\n4. If it's a new session - from 5 tuples in the packet, calculate a hash value.\n\n5. Using this hash value - pick a real server.\n\n6. Update session table with this lookup information so that katran can simply\nlookup this information for the next packet in the session and not calculate the hash again.\n\n7. Encapsulate packet in another IP packet and send to the real.\n\n\u003Ch3 align=\"center\"> L4 load balancing failure scenario \u003C\u002Fh3>\n\n![alt text](imgs\u002Fkatran_consistency.png \"Failure Scenario\")\n\nAs we use only the data from the packet's headers to calculate a hash value,\nwhich is then used to pick a real server, different L4 lbs are consistent in real server selection,\neven w\u002Fo explicit state sharing amongst each other. This feature allows us to restart\u002Fdrain single\nL4 lb w\u002Fo affecting TCP sessions, going to the L7 lbs.\n\n## katran's features description\n\n1. __Fast :__ katran uses XDP for packet forwarding, which allows\nto run packet handling routines right after packet has been received by\nnetwork interface card (NIC) and before kernel had any chance to run (when XDP\nis working in \"driver mode\", katran supports \"generic XDP\" mode of operation\nas well (with some performance degradation compare to \"driver mode\")).\n\n2. __Performance scales linearly with a number of NIC's RX queues :__ The way XDP\nworks is that it invokes BPF program on every received packet, and if your\nNIC has multiple queues, for each of them BPF program will be invoked\nindependently. As katran is completely lockless and uses per-cpu\nversions of BPF maps - it scales linearly.\n\n3. __RSS friendly encapsulation :__ katran is uses ipip encapsulation for packet\nforwarding from L4 lb to L7 lb. However, to be able to work in conjunction with\nRSS on L7 lb receive side, instead of using the same source for every ipip\npacket, katran crafts a special one, in such a way, that different flows will have\ndifferent outer (ipip) source IP, but packets in same flow will always have\nthe same.\n\n4. Fixed size (size is configurable on start) connection tracking table w\u002F LRU\nstrategy for eviction of old entries.\n\n5. __Modified Maglev hashing for connections :__ It provides us good resiliency in\ncase of failure and excellent load balancing features. The hashing was modified\nto be able to support unequal weights for backend (L7 lbs) servers\n\n6. __No need for busylooping on receive path :__ Your load balancer will barely\nconsume any CPU if there is no traffic to serve.\n\n7. katran (and XDP in general) allows you to run any application w\u002Fo any\nperformance penalties on the same server (compare to some of other\n\"kernel bypass\" technologies)\n\n## Trivia\n\nkatran is named (it's actually an alternative name) after __[spiny dogfish shark](https:\u002F\u002Fen.wikipedia.org\u002Fwiki\u002FSpiny_dogfish)__.\n\n## License\n\nkatran is GPL-2.0 licensed, as found in the LICENSE file.\n","Katran 是一个高性能的第四层负载均衡器。它基于C++库和BPF程序构建，利用XDP（eXpress Data Path）内核基础设施实现快速的数据包处理。Katran的主要特点包括极高的处理速度、性能随网络接口卡接收队列数量线性扩展以及支持RSS友好的封装方式。适用于需要高效数据包转发和负载均衡的场景，如大规模数据中心或云计算环境中的服务部署。通过Thrift和gRPC服务端点提供简单的使用示例，便于集成到现有系统中。","2026-06-11 03:07:32","top_language"]