1.. SPDX-License-Identifier: GPL-2.0
2
3=================
4Linux Kernel TIPC
5=================
6
7Introduction
8============
9
10TIPC (Transparent Inter Process Communication) is a protocol that is specially
11designed for intra-cluster communication. It can be configured to transmit
12messages either on UDP or directly across Ethernet. Message delivery is
13sequence guaranteed, loss free and flow controlled. Latency times are shorter
14than with any other known protocol, while maximal throughput is comparable to
15that of TCP.
16
17TIPC Features
18-------------
19
20- Cluster wide IPC service
21
22  Have you ever wished you had the convenience of Unix Domain Sockets even when
23  transmitting data between cluster nodes? Where you yourself determine the
24  addresses you want to bind to and use? Where you don't have to perform DNS
25  lookups and worry about IP addresses? Where you don't have to start timers
26  to monitor the continuous existence of peer sockets? And yet without the
27  downsides of that socket type, such as the risk of lingering inodes?
28
29  Welcome to the Transparent Inter Process Communication service, TIPC in short,
30  which gives you all of this, and a lot more.
31
32- Service Addressing
33
34  A fundamental concept in TIPC is that of Service Addressing which makes it
35  possible for a programmer to chose his own address, bind it to a server
36  socket and let client programs use only that address for sending messages.
37
38- Service Tracking
39
40  A client wanting to wait for the availability of a server, uses the Service
41  Tracking mechanism to subscribe for binding and unbinding/close events for
42  sockets with the associated service address.
43
44  The service tracking mechanism can also be used for Cluster Topology Tracking,
45  i.e., subscribing for availability/non-availability of cluster nodes.
46
47  Likewise, the service tracking mechanism can be used for Cluster Connectivity
48  Tracking, i.e., subscribing for up/down events for individual links between
49  cluster nodes.
50
51- Transmission Modes
52
53  Using a service address, a client can send datagram messages to a server socket.
54
55  Using the same address type, it can establish a connection towards an accepting
56  server socket.
57
58  It can also use a service address to create and join a Communication Group,
59  which is the TIPC manifestation of a brokerless message bus.
60
61  Multicast with very good performance and scalability is available both in
62  datagram mode and in communication group mode.
63
64- Inter Node Links
65
66  Communication between any two nodes in a cluster is maintained by one or two
67  Inter Node Links, which both guarantee data traffic integrity and monitor
68  the peer node's availability.
69
70- Cluster Scalability
71
72  By applying the Overlapping Ring Monitoring algorithm on the inter node links
73  it is possible to scale TIPC clusters up to 1000 nodes with a maintained
74  neighbor failure discovery time of 1-2 seconds. For smaller clusters this
75  time can be made much shorter.
76
77- Neighbor Discovery
78
79  Neighbor Node Discovery in the cluster is done by Ethernet broadcast or UDP
80  multicast, when any of those services are available. If not, configured peer
81  IP addresses can be used.
82
83- Configuration
84
85  When running TIPC in single node mode no configuration whatsoever is needed.
86  When running in cluster mode TIPC must as a minimum be given a node address
87  (before Linux 4.17) and told which interface to attach to. The "tipc"
88  configuration tool makes is possible to add and maintain many more
89  configuration parameters.
90
91- Performance
92
93  TIPC message transfer latency times are better than in any other known protocol.
94  Maximal byte throughput for inter-node connections is still somewhat lower than
95  for TCP, while they are superior for intra-node and inter-container throughput
96  on the same host.
97
98- Language Support
99
100  The TIPC user API has support for C, Python, Perl, Ruby, D and Go.
101
102More Information
103----------------
104
105- How to set up TIPC:
106
107  http://tipc.io/getting_started.html
108
109- How to program with TIPC:
110
111  http://tipc.io/programming.html
112
113- How to contribute to TIPC:
114
115- http://tipc.io/contacts.html
116
117- More details about TIPC specification:
118
119  http://tipc.io/protocol.html
120
121
122Implementation
123==============
124
125TIPC is implemented as a kernel module in net/tipc/ directory.
126
127TIPC Base Types
128---------------
129
130.. kernel-doc:: net/tipc/subscr.h
131   :internal:
132
133.. kernel-doc:: net/tipc/bearer.h
134   :internal:
135
136.. kernel-doc:: net/tipc/name_table.h
137   :internal:
138
139.. kernel-doc:: net/tipc/name_distr.h
140   :internal:
141
142.. kernel-doc:: net/tipc/bcast.c
143   :internal:
144
145TIPC Bearer Interfaces
146----------------------
147
148.. kernel-doc:: net/tipc/bearer.c
149   :internal:
150
151.. kernel-doc:: net/tipc/udp_media.c
152   :internal:
153
154TIPC Crypto Interfaces
155----------------------
156
157.. kernel-doc:: net/tipc/crypto.c
158   :internal:
159
160TIPC Discoverer Interfaces
161--------------------------
162
163.. kernel-doc:: net/tipc/discover.c
164   :internal:
165
166TIPC Link Interfaces
167--------------------
168
169.. kernel-doc:: net/tipc/link.c
170   :internal:
171
172TIPC msg Interfaces
173-------------------
174
175.. kernel-doc:: net/tipc/msg.c
176   :internal:
177
178TIPC Name Interfaces
179--------------------
180
181.. kernel-doc:: net/tipc/name_table.c
182   :internal:
183
184.. kernel-doc:: net/tipc/name_distr.c
185   :internal:
186
187TIPC Node Management Interfaces
188-------------------------------
189
190.. kernel-doc:: net/tipc/node.c
191   :internal:
192
193TIPC Socket Interfaces
194----------------------
195
196.. kernel-doc:: net/tipc/socket.c
197   :internal:
198
199TIPC Network Topology Interfaces
200--------------------------------
201
202.. kernel-doc:: net/tipc/subscr.c
203   :internal:
204
205TIPC Server Interfaces
206----------------------
207
208.. kernel-doc:: net/tipc/topsrv.c
209   :internal:
210
211TIPC Trace Interfaces
212---------------------
213
214.. kernel-doc:: net/tipc/trace.c
215   :internal:
216