Linux Kernel TIPC¶
Introduction¶
TIPC (Transparent Inter Process Communication) is a protocol that is specially designed for intra-cluster communication. It can be configured to transmit messages either on UDP or directly across Ethernet. Message delivery is sequence guaranteed, loss free and flow controlled. Latency times are shorter than with any other known protocol, while maximal throughput is comparable to that of TCP.
TIPC Features¶
Cluster wide IPC service
Have you ever wished you had the convenience of Unix Domain Sockets even when transmitting data between cluster nodes? Where you yourself determine the addresses you want to bind to and use? Where you don’t have to perform DNS lookups and worry about IP addresses? Where you don’t have to start timers to monitor the continuous existence of peer sockets? And yet without the downsides of that socket type, such as the risk of lingering inodes?
Welcome to the Transparent Inter Process Communication service, TIPC in short, which gives you all of this, and a lot more.
Service Addressing
A fundamental concept in TIPC is that of Service Addressing which makes it possible for a programmer to chose his own address, bind it to a server socket and let client programs use only that address for sending messages.
Service Tracking
A client wanting to wait for the availability of a server, uses the Service Tracking mechanism to subscribe for binding and unbinding/close events for sockets with the associated service address.
The service tracking mechanism can also be used for Cluster Topology Tracking, i.e., subscribing for availability/non-availability of cluster nodes.
Likewise, the service tracking mechanism can be used for Cluster Connectivity Tracking, i.e., subscribing for up/down events for individual links between cluster nodes.
Transmission Modes
Using a service address, a client can send datagram messages to a server socket.
Using the same address type, it can establish a connection towards an accepting server socket.
It can also use a service address to create and join a Communication Group, which is the TIPC manifestation of a brokerless message bus.
Multicast with very good performance and scalability is available both in datagram mode and in communication group mode.
Inter Node Links
Communication between any two nodes in a cluster is maintained by one or two Inter Node Links, which both guarantee data traffic integrity and monitor the peer node’s availability.
Cluster Scalability
By applying the Overlapping Ring Monitoring algorithm on the inter node links it is possible to scale TIPC clusters up to 1000 nodes with a maintained neighbor failure discovery time of 1-2 seconds. For smaller clusters this time can be made much shorter.
Neighbor Discovery
Neighbor Node Discovery in the cluster is done by Ethernet broadcast or UDP multicast, when any of those services are available. If not, configured peer IP addresses can be used.
Configuration
When running TIPC in single node mode no configuration whatsoever is needed. When running in cluster mode TIPC must as a minimum be given a node address (before Linux 4.17) and told which interface to attach to. The “tipc” configuration tool makes is possible to add and maintain many more configuration parameters.
Performance
TIPC message transfer latency times are better than in any other known protocol. Maximal byte throughput for inter-node connections is still somewhat lower than for TCP, while they are superior for intra-node and inter-container throughput on the same host.
Language Support
The TIPC user API has support for C, Python, Perl, Ruby, D and Go.
More Information¶
How to set up TIPC:
How to program with TIPC:
How to contribute to TIPC:
More details about TIPC specification:
Implementation¶
TIPC is implemented as a kernel module in net/tipc/ directory.
TIPC Base Types¶
-
struct
tipc_subscription
¶ TIPC network topology subscription object
Definition
struct tipc_subscription {
struct tipc_subscr s;
struct tipc_event evt;
struct kref kref;
struct net *net;
struct timer_list timer;
struct list_head service_list;
struct list_head sub_list;
int conid;
bool inactive;
spinlock_t lock;
};
Members
s
host-endian copy of the user subscription
evt
template for events generated by subscription
kref
reference count for this subscription
net
network namespace associated with subscription
timer
timer governing subscription duration (optional)
service_list
adjacent subscriptions in name sequence’s subscription list
sub_list
adjacent subscriptions in subscriber’s subscription list
conid
connection identifier of topology server
inactive
true if this subscription is inactive
lock
serialize up/down and timer events
-
struct
tipc_media_addr
¶ destination address used by TIPC bearers
Definition
struct tipc_media_addr {
u8 value[TIPC_MEDIA_INFO_SIZE];
u8 media_id;
u8 broadcast;
};
Members
value
address info (format defined by media)
media_id
TIPC media type identifier
broadcast
non-zero if address is a broadcast address
-
struct
tipc_media
¶ Media specific info exposed to generic bearer layer
Definition
struct tipc_media {
int (*send_msg)(struct net *net, struct sk_buff *buf,struct tipc_bearer *b, struct tipc_media_addr *dest);
int (*enable_media)(struct net *net, struct tipc_bearer *b, struct nlattr *attr[]);
void (*disable_media)(struct tipc_bearer *b);
int (*addr2str)(struct tipc_media_addr *addr,char *strbuf, int bufsz);
int (*addr2msg)(char *msg, struct tipc_media_addr *addr);
int (*msg2addr)(struct tipc_bearer *b,struct tipc_media_addr *addr, char *msg);
int (*raw2addr)(struct tipc_bearer *b,struct tipc_media_addr *addr, char *raw);
u32 priority;
u32 tolerance;
u32 min_win;
u32 max_win;
u32 mtu;
u32 type_id;
u32 hwaddr_len;
char name[TIPC_MAX_MEDIA_NAME];
};
Members
send_msg
routine which handles buffer transmission
enable_media
routine which enables a media
disable_media
routine which disables a media
addr2str
convert media address format to string
addr2msg
convert from media addr format to discovery msg addr format
msg2addr
convert from discovery msg addr format to media addr format
raw2addr
convert from raw addr format to media addr format
priority
default link (and bearer) priority
tolerance
default time (in ms) before declaring link failure
min_win
minimum window (in packets) before declaring link congestion
max_win
maximum window (in packets) before declaring link congestion
mtu
max packet size bearer can support for media type not dependent on underlying device MTU
type_id
TIPC media identifier
hwaddr_len
TIPC media address len
name
media name
-
struct
tipc_bearer
¶ Generic TIPC bearer structure
Definition
struct tipc_bearer {
void __rcu *media_ptr;
u32 mtu;
struct tipc_media_addr addr;
char name[TIPC_MAX_BEARER_NAME];
struct tipc_media *media;
struct tipc_media_addr bcast_addr;
struct packet_type pt;
struct rcu_head rcu;
u32 priority;
u32 min_win;
u32 max_win;
u32 tolerance;
u32 domain;
u32 identity;
struct tipc_discoverer *disc;
char net_plane;
unsigned long up;
refcount_t refcnt;
};
Members
media_ptr
pointer to additional media-specific information about bearer
mtu
max packet size bearer can support
addr
media-specific address associated with bearer
name
bearer name (format = media:interface)
media
ptr to media structure associated with bearer
bcast_addr
media address used in broadcasting
pt
packet type for bearer
rcu
rcu struct for tipc_bearer
priority
default link priority for bearer
min_win
minimum window (in packets) before declaring link congestion
max_win
maximum window (in packets) before declaring link congestion
tolerance
default link tolerance for bearer
domain
network domain to which links can be established
identity
array index of this bearer within TIPC bearer array
disc
ptr to link setup request
net_plane
network plane (‘A’ through ‘H’) currently associated with bearer
up
bearer up flag (bit 0)
refcnt
tipc_bearer reference counter
Note
media-specific code is responsible for initialization of the fields indicated below when a bearer is enabled; TIPC’s generic bearer code takes care of initializing all other fields.
-
struct
publication
¶ info about a published service address or range
Definition
struct publication {
struct tipc_service_range sr;
struct tipc_socket_addr sk;
u16 scope;
u32 key;
u32 id;
struct list_head binding_node;
struct list_head binding_sock;
struct list_head local_publ;
struct list_head all_publ;
struct list_head list;
struct rcu_head rcu;
};
Members
sr
service range represented by this publication
sk
address of socket bound to this publication
scope
scope of publication, TIPC_NODE_SCOPE or TIPC_CLUSTER_SCOPE
key
publication key, unique across the cluster
id
publication id
binding_node
all publications from the same node which bound this one - Remote publications: in node->publ_list; Used by node/name distr to withdraw publications when node is lost - Local/node scope publications: in name_table->node_scope list - Local/cluster scope publications: in name_table->cluster_scope list
binding_sock
all publications from the same socket which bound this one Used by socket to withdraw publications when socket is unbound/released
local_publ
list of identical publications made from this node Used by closest_first and multicast receive lookup algorithms
all_publ
all publications identical to this one, whatever node and scope Used by round-robin lookup algorithm
list
to form a list of publications in temporal order
rcu
RCU callback head used for deferred freeing
-
struct
name_table
¶ table containing all existing port name publications
Definition
struct name_table {
struct hlist_head services[TIPC_NAMETBL_SIZE];
struct list_head node_scope;
struct list_head cluster_scope;
rwlock_t cluster_scope_lock;
u32 local_publ_count;
u32 rc_dests;
u32 snd_nxt;
};
Members
services
name sequence hash lists
node_scope
all local publications with node scope - used by name_distr during re-init of name table
cluster_scope
all local publications with cluster scope - used by name_distr to send bulk updates to new nodes - used by name_distr during re-init of name table
cluster_scope_lock
lock for accessing cluster_scope
local_publ_count
number of publications issued by this node
rc_dests
destination node counter
snd_nxt
next sequence number to be used
-
struct
distr_item
¶ publication info distributed to other nodes
Definition
struct distr_item {
__be32 type;
__be32 lower;
__be32 upper;
__be32 port;
__be32 key;
};
Members
type
name sequence type
lower
name sequence lower bound
upper
name sequence upper bound
port
publishing port reference
key
publication key
Description
===> All fields are stored in network byte order. <===
First 3 fields identify (name or) name sequence being published. Reference field uniquely identifies port that published name sequence. Key field uniquely identifies publication, in the event a port has multiple publications of the same name sequence.
Note
There is no field that identifies the publishing node because it is the same for all items contained within a publication message.
-
struct
tipc_bc_base
¶ base structure for keeping broadcast send state
Definition
struct tipc_bc_base {
struct tipc_link *link;
struct sk_buff_head inputq;
int dests[MAX_BEARERS];
int primary_bearer;
bool bcast_support;
bool force_bcast;
bool rcast_support;
bool force_rcast;
int rc_ratio;
int bc_threshold;
};
Members
link
broadcast send link structure
inputq
data input queue; will only carry SOCK_WAKEUP messages
dests
array keeping number of reachable destinations per bearer
primary_bearer
a bearer having links to all broadcast destinations, if any
bcast_support
indicates if primary bearer, if any, supports broadcast
force_bcast
forces broadcast for multicast traffic
rcast_support
indicates if all peer nodes support replicast
force_rcast
forces replicast for multicast traffic
rc_ratio
dest count as percentage of cluster size where send method changes
bc_threshold
calculated from rc_ratio; if dests > threshold use broadcast
TIPC Bearer Interfaces¶
-
struct tipc_media *
tipc_media_find
(const char *name)¶ locates specified media object by name
Parameters
const char *name
name to locate
-
struct tipc_media *
media_find_id
(u8 type)¶ locates specified media object by type identifier
Parameters
u8 type
type identifier to locate
-
int
tipc_media_addr_printf
(char *buf, int len, struct tipc_media_addr *a)¶ record media address in print buffer
Parameters
char *buf
output buffer
int len
output buffer size remaining
struct tipc_media_addr *a
input media address
-
int
bearer_name_validate
(const char *name, struct tipc_bearer_names *name_parts)¶ validate & (optionally) deconstruct bearer name
Parameters
const char *name
ptr to bearer name string
struct tipc_bearer_names *name_parts
ptr to area for bearer name components (or NULL if not needed)
Return
1 if bearer name is valid, otherwise 0.
-
struct tipc_bearer *
tipc_bearer_find
(struct net *net, const char *name)¶ locates bearer object with matching bearer name
Parameters
struct net *net
the applicable net namespace
const char *name
bearer name to locate
-
int
tipc_enable_bearer
(struct net *net, const char *name, u32 disc_domain, u32 prio, struct nlattr *attr[], struct netlink_ext_ack *extack)¶ enable bearer with the given name
Parameters
struct net *net
the applicable net namespace
const char *name
bearer name to enable
u32 disc_domain
bearer domain
u32 prio
bearer priority
struct nlattr *attr[]
nlattr array
struct netlink_ext_ack *extack
netlink extended ack
-
int
tipc_reset_bearer
(struct net *net, struct tipc_bearer *b)¶ Reset all links established over this bearer
Parameters
struct net *net
the applicable net namespace
struct tipc_bearer *b
the target bearer
-
void
bearer_disable
(struct net *net, struct tipc_bearer *b)¶ disable this bearer
Parameters
struct net *net
the applicable net namespace
struct tipc_bearer *b
the bearer to disable
Note
This routine assumes caller holds RTNL lock.
-
int
tipc_l2_send_msg
(struct net *net, struct sk_buff *skb, struct tipc_bearer *b, struct tipc_media_addr *dest)¶ send a TIPC packet out over an L2 interface
Parameters
struct net *net
the associated network namespace
struct sk_buff *skb
the packet to be sent
struct tipc_bearer *b
the bearer through which the packet is to be sent
struct tipc_media_addr *dest
peer destination address
-
int
tipc_l2_rcv_msg
(struct sk_buff *skb, struct net_device *dev, struct packet_type *pt, struct net_device *orig_dev)¶ handle incoming TIPC message from an interface
Parameters
struct sk_buff *skb
the received message
struct net_device *dev
the net device that the packet was received on
struct packet_type *pt
the packet_type structure which was used to register this handler
struct net_device *orig_dev
the original receive net device in case the device is a bond
Description
Accept only packets explicitly sent to this node, or broadcast packets; ignores packets sent using interface multicast, and traffic sent to other nodes (which can happen if interface is running in promiscuous mode).
-
int
tipc_l2_device_event
(struct notifier_block *nb, unsigned long evt, void *ptr)¶ handle device events from network device
Parameters
struct notifier_block *nb
the context of the notification
unsigned long evt
the type of event
void *ptr
the net device that the event was on
Description
This function is called by the Ethernet driver in case of link change event.
-
struct
udp_media_addr
¶ IP/UDP addressing information
Definition
struct udp_media_addr {
__be16 proto;
__be16 port;
union {
struct in_addr ipv4;
struct in6_addr ipv6;
};
};
Members
proto
Ethernet protocol in use
port
port being used
{unnamed_union}
anonymous
ipv4
IPv4 address of neighbor
ipv6
IPv6 address of neighbor
Description
This is the bearer level originating address used in neighbor discovery messages, and all fields should be in network byte order
-
struct
udp_bearer
¶ ip/udp bearer data structure
Definition
struct udp_bearer {
struct tipc_bearer __rcu *bearer;
struct socket *ubsock;
u32 ifindex;
struct work_struct work;
struct udp_replicast rcast;
};
Members
bearer
associated generic tipc bearer
ubsock
bearer associated socket
ifindex
local address scope
work
used to schedule deferred work on a bearer
rcast
associated udp_replicast container
-
int
tipc_parse_udp_addr
(struct nlattr *nla, struct udp_media_addr *addr, u32 *scope_id)¶ build udp media address from netlink data
Parameters
struct nlattr *nla
netlink attribute containing sockaddr storage aligned address
struct udp_media_addr *addr
tipc media address to fill with address, port and protocol type
u32 *scope_id
IPv6 scope id pointer, not NULL indicates it’s required
-
int
tipc_udp_enable
(struct net *net, struct tipc_bearer *b, struct nlattr *attrs[])¶ callback to create a new udp bearer instance
Parameters
struct net *net
network namespace
struct tipc_bearer *b
pointer to generic tipc_bearer
struct nlattr *attrs[]
netlink bearer configuration
Description
validate the bearer parameters and initialize the udp bearer rtnl_lock should be held
TIPC Crypto Interfaces¶
-
struct
tipc_tfm
¶ TIPC TFM structure to form a list of TFMs
Definition
struct tipc_tfm {
struct crypto_aead *tfm;
struct list_head list;
};
Members
tfm
cipher handle/key
list
linked list of TFMs
-
struct
tipc_aead
¶ TIPC AEAD key structure
Definition
struct tipc_aead {
#define TIPC_AEAD_HINT_LEN (5);
struct tipc_tfm * __percpu *tfm_entry;
struct tipc_crypto *crypto;
struct tipc_aead *cloned;
atomic_t users;
u32 salt;
u8 authsize;
u8 mode;
char hint[2 * TIPC_AEAD_HINT_LEN + 1];
struct rcu_head rcu;
struct tipc_aead_key *key;
u16 gen;
atomic64_t seqno ;
refcount_t refcnt ;
};
Members
tfm_entry
per-cpu pointer to one entry in TFM list
crypto
TIPC crypto owns this key
cloned
reference to the source key in case cloning
users
the number of the key users (TX/RX)
salt
the key’s SALT value
authsize
authentication tag size (max = 16)
mode
crypto mode is applied to the key
hint
a hint for user key
rcu
struct rcu_head
key
the aead key
gen
the key’s generation
seqno
the key seqno (cluster scope)
refcnt
the key reference counter
-
struct
tipc_crypto_stats
¶ TIPC Crypto statistics
Definition
struct tipc_crypto_stats {
unsigned int stat[MAX_STATS];
};
Members
stat
array of crypto statistics
-
struct
tipc_crypto
¶ TIPC TX/RX crypto structure
Definition
struct tipc_crypto {
struct net *net;
struct tipc_node *node;
struct tipc_aead __rcu *aead[KEY_MAX + 1];
atomic_t peer_rx_active;
u16 key_gen;
struct tipc_key key;
u8 skey_mode;
struct tipc_aead_key *skey;
struct workqueue_struct *wq;
struct delayed_work work;
#define KEY_DISTR_SCHED 1;
#define KEY_DISTR_COMPL 2;
atomic_t key_distr;
u32 rekeying_intv;
struct tipc_crypto_stats __percpu *stats;
char name[48];
atomic64_t sndnxt ;
unsigned long timer1;
unsigned long timer2;
union {
struct {
u8 working:1;
u8 key_master:1;
u8 legacy_user:1;
u8 nokey: 1;
};
u8 flags;
};
spinlock_t lock;
};
Members
net
struct net
node
TIPC node (RX)
aead
array of pointers to AEAD keys for encryption/decryption
peer_rx_active
replicated peer RX active key index
key_gen
TX/RX key generation
key
the key states
skey_mode
session key’s mode
skey
received session key
wq
common workqueue on TX crypto
work
delayed work sched for TX/RX
key_distr
key distributing state
rekeying_intv
rekeying interval (in minutes)
stats
the crypto statistics
name
the crypto name
sndnxt
the per-peer sndnxt (TX)
timer1
general timer 1 (jiffies)
timer2
general timer 2 (jiffies)
{unnamed_union}
anonymous
{unnamed_struct}
anonymous
working
the crypto is working or not
key_master
flag indicates if master key exists
legacy_user
flag indicates if a peer joins w/o master key (for bwd comp.)
nokey
no key indication
flags
combined flags field
lock
tipc_key lock
-
int
tipc_aead_key_validate
(struct tipc_aead_key *ukey, struct genl_info *info)¶ Validate a AEAD user key
Parameters
struct tipc_aead_key *ukey
pointer to user key data
struct genl_info *info
netlink info pointer
-
int
tipc_aead_key_generate
(struct tipc_aead_key *skey)¶ Generate new session key
Parameters
struct tipc_aead_key *skey
input/output key with new content
Return
0 in case of success, otherwise < 0
-
void
tipc_aead_free
(struct rcu_head *rp)¶ Release AEAD key incl. all the TFMs in the list
Parameters
struct rcu_head *rp
rcu head pointer
-
struct crypto_aead *
tipc_aead_tfm_next
(struct tipc_aead *aead)¶ Move TFM entry to the next one in list and return it
Parameters
struct tipc_aead *aead
the AEAD key pointer
-
int
tipc_aead_init
(struct tipc_aead **aead, struct tipc_aead_key *ukey, u8 mode)¶ Initiate TIPC AEAD
Parameters
struct tipc_aead **aead
returned new TIPC AEAD key handle pointer
struct tipc_aead_key *ukey
pointer to user key data
u8 mode
the key mode
Description
Allocate a (list of) new cipher transformation (TFM) with the specific user key data if valid. The number of the allocated TFMs can be set via the sysfs “net/tipc/max_tfms” first. Also, all the other AEAD data are also initialized.
Return
0 if the initiation is successful, otherwise: < 0
Parameters
struct tipc_aead **dst
dest key for the cloning
struct tipc_aead *src
source key to clone from
Description
Make a “copy” of the source AEAD key data to the dest, the TFMs list is common for the keys. A reference to the source is hold in the “cloned” pointer for the later freeing purposes.
Note
this must be done in cluster-key mode only!
Return
0 in case of success, otherwise < 0
-
void *
tipc_aead_mem_alloc
(struct crypto_aead *tfm, unsigned int crypto_ctx_size, u8 **iv, struct aead_request **req, struct scatterlist **sg, int nsg)¶ Allocate memory for AEAD request operations
Parameters
struct crypto_aead *tfm
cipher handle to be registered with the request
unsigned int crypto_ctx_size
size of crypto context for callback
u8 **iv
returned pointer to IV data
struct aead_request **req
returned pointer to AEAD request data
struct scatterlist **sg
returned pointer to SG lists
int nsg
number of SG lists to be allocated
Description
Allocate memory to store the crypto context data, AEAD request, IV and SG lists, the memory layout is as follows: crypto_ctx || iv || aead_req || sg[]
Return
the pointer to the memory areas in case of success, otherwise NULL
-
int
tipc_aead_encrypt
(struct tipc_aead *aead, struct sk_buff *skb, struct tipc_bearer *b, struct tipc_media_addr *dst, struct tipc_node *__dnode)¶ Encrypt a message
Parameters
struct tipc_aead *aead
TIPC AEAD key for the message encryption
struct sk_buff *skb
the input/output skb
struct tipc_bearer *b
TIPC bearer where the message will be delivered after the encryption
struct tipc_media_addr *dst
the destination media address
struct tipc_node *__dnode
TIPC dest node if “known”
Return
0 : if the encryption has completed
-EINPROGRESS/-EBUSY : if a callback will be performed
< 0 : the encryption has failed
-
int
tipc_aead_decrypt
(struct net *net, struct tipc_aead *aead, struct sk_buff *skb, struct tipc_bearer *b)¶ Decrypt an encrypted message
Parameters
struct net *net
struct net
struct tipc_aead *aead
TIPC AEAD for the message decryption
struct sk_buff *skb
the input/output skb
struct tipc_bearer *b
TIPC bearer where the message has been received
Return
0 : if the decryption has completed
-EINPROGRESS/-EBUSY : if a callback will be performed
< 0 : the decryption has failed
-
bool
tipc_ehdr_validate
(struct sk_buff *skb)¶ Validate an encryption message
Parameters
struct sk_buff *skb
the message buffer
Return
“true” if this is a valid encryption message, otherwise “false”
-
int
tipc_ehdr_build
(struct net *net, struct tipc_aead *aead, u8 tx_key, struct sk_buff *skb, struct tipc_crypto *__rx)¶ Build TIPC encryption message header
Parameters
struct net *net
struct net
struct tipc_aead *aead
TX AEAD key to be used for the message encryption
u8 tx_key
key id used for the message encryption
struct sk_buff *skb
input/output message skb
struct tipc_crypto *__rx
RX crypto handle if dest is “known”
Return
the header size if the building is successful, otherwise < 0
-
int
tipc_crypto_key_init
(struct tipc_crypto *c, struct tipc_aead_key *ukey, u8 mode, bool master_key)¶ Initiate a new user / AEAD key
Parameters
struct tipc_crypto *c
TIPC crypto to which new key is attached
struct tipc_aead_key *ukey
the user key
u8 mode
the key mode (CLUSTER_KEY or PER_NODE_KEY)
bool master_key
specify this is a cluster master key
Description
A new TIPC AEAD key will be allocated and initiated with the specified user key, then attached to the TIPC crypto.
Return
new key id in case of success, otherwise: < 0
-
int
tipc_crypto_key_attach
(struct tipc_crypto *c, struct tipc_aead *aead, u8 pos, bool master_key)¶ Attach a new AEAD key to TIPC crypto
Parameters
struct tipc_crypto *c
TIPC crypto to which the new AEAD key is attached
struct tipc_aead *aead
the new AEAD key pointer
u8 pos
desired slot in the crypto key array, = 0 if any!
bool master_key
specify this is a cluster master key
Return
new key id in case of success, otherwise: -EBUSY
-
bool
tipc_crypto_key_try_align
(struct tipc_crypto *rx, u8 new_pending)¶ Align RX keys if possible
Parameters
struct tipc_crypto *rx
RX crypto handle
u8 new_pending
new pending slot if aligned (= TX key from peer)
Description
Peer has used an unknown key slot, this only happens when peer has left and rejoned, or we are newcomer. That means, there must be no active key but a pending key at unaligned slot. If so, we try to move the pending key to the new slot.
Note
A potential passive key can exist, it will be shifted correspondingly!
Return
“true” if key is successfully aligned, otherwise “false”
-
struct tipc_aead *
tipc_crypto_key_pick_tx
(struct tipc_crypto *tx, struct tipc_crypto *rx, struct sk_buff *skb, u8 tx_key)¶ Pick one TX key for message decryption
Parameters
struct tipc_crypto *tx
TX crypto handle
struct tipc_crypto *rx
RX crypto handle (can be NULL)
struct sk_buff *skb
the message skb which will be decrypted later
u8 tx_key
peer TX key id
Description
This function looks up the existing TX keys and pick one which is suitable for the message decryption, that must be a cluster key and not used before on the same message (i.e. recursive).
Return
the TX AEAD key handle in case of success, otherwise NULL
-
void
tipc_crypto_key_synch
(struct tipc_crypto *rx, struct sk_buff *skb)¶ Synch own key data according to peer key status
Parameters
struct tipc_crypto *rx
RX crypto handle
struct sk_buff *skb
TIPCv2 message buffer (incl. the ehdr from peer)
Description
This function updates the peer node related data as the peer RX active key has changed, so the number of TX keys’ users on this node are increased and decreased correspondingly.
It also considers if peer has no key, then we need to make own master key (if any) taking over i.e. starting grace period and also trigger key distributing process.
The “per-peer” sndnxt is also reset when the peer key has switched.
-
int
tipc_crypto_xmit
(struct net *net, struct sk_buff **skb, struct tipc_bearer *b, struct tipc_media_addr *dst, struct tipc_node *__dnode)¶ Build & encrypt TIPC message for xmit
Parameters
struct net *net
struct net
struct sk_buff **skb
input/output message skb pointer
struct tipc_bearer *b
bearer used for xmit later
struct tipc_media_addr *dst
destination media address
struct tipc_node *__dnode
destination node for reference if any
Description
First, build an encryption message header on the top of the message, then encrypt the original TIPC message by using the pending, master or active key with this preference order. If the encryption is successful, the encrypted skb is returned directly or via the callback. Otherwise, the skb is freed!
Return
0 : the encryption has succeeded (or no encryption)
-EINPROGRESS/-EBUSY : the encryption is ongoing, a callback will be made
- -ENOKEK
: the encryption has failed due to no key
- -EKEYREVOKED
: the encryption has failed due to key revoked
- -ENOMEM
: the encryption has failed due to no memory
< 0 : the encryption has failed due to other reasons
-
int
tipc_crypto_rcv
(struct net *net, struct tipc_crypto *rx, struct sk_buff **skb, struct tipc_bearer *b)¶ Decrypt an encrypted TIPC message from peer
Parameters
struct net *net
struct net
struct tipc_crypto *rx
RX crypto handle
struct sk_buff **skb
input/output message skb pointer
struct tipc_bearer *b
bearer where the message has been received
Description
If the decryption is successful, the decrypted skb is returned directly or as the callback, the encryption header and auth tag will be trimed out before forwarding to tipc_rcv() via the tipc_crypto_rcv_complete(). Otherwise, the skb will be freed!
Note
RX key(s) can be re-aligned, or in case of no key suitable, TX cluster key(s) can be taken for decryption (- recursive).
Return
0 : the decryption has successfully completed
-EINPROGRESS/-EBUSY : the decryption is ongoing, a callback will be made
- -ENOKEY
: the decryption has failed due to no key
- -EBADMSG
: the decryption has failed due to bad message
- -ENOMEM
: the decryption has failed due to no memory
< 0 : the decryption has failed due to other reasons
-
void
tipc_crypto_msg_rcv
(struct net *net, struct sk_buff *skb)¶ Common ‘MSG_CRYPTO’ processing point
Parameters
struct net *net
the struct net
struct sk_buff *skb
the receiving message buffer
-
int
tipc_crypto_key_distr
(struct tipc_crypto *tx, u8 key, struct tipc_node *dest)¶ Distribute a TX key
Parameters
struct tipc_crypto *tx
the TX crypto
u8 key
the key’s index
struct tipc_node *dest
the destination tipc node, = NULL if distributing to all nodes
Return
0 in case of success, otherwise < 0
-
int
tipc_crypto_key_xmit
(struct net *net, struct tipc_aead_key *skey, u16 gen, u8 mode, u32 dnode)¶ Send a session key
Parameters
struct net *net
the struct net
struct tipc_aead_key *skey
the session key to be sent
u16 gen
the key’s generation
u8 mode
the key’s mode
u32 dnode
the destination node address, = 0 if broadcasting to all nodes
Description
The session key ‘skey’ is packed in a TIPC v2 ‘MSG_CRYPTO/KEY_DISTR_MSG’ as its data section, then xmit-ed through the uc/bc link.
Return
0 in case of success, otherwise < 0
-
bool
tipc_crypto_key_rcv
(struct tipc_crypto *rx, struct tipc_msg *hdr)¶ Receive a session key
Parameters
struct tipc_crypto *rx
the RX crypto
struct tipc_msg *hdr
the TIPC v2 message incl. the receiving session key in its data
Description
This function retrieves the session key in the message from peer, then schedules a RX work to attach the key to the corresponding RX crypto.
Return
“true” if the key has been scheduled for attaching, otherwise “false”.
-
void
tipc_crypto_work_rx
(struct work_struct *work)¶ Scheduled RX works handler
Parameters
struct work_struct *work
the struct RX work
Description
The function processes the previous scheduled works i.e. distributing TX key or attaching a received session key on RX crypto.
-
void
tipc_crypto_rekeying_sched
(struct tipc_crypto *tx, bool changed, u32 new_intv)¶ (Re)schedule rekeying w/o new interval
Parameters
struct tipc_crypto *tx
TX crypto
bool changed
if the rekeying needs to be rescheduled with new interval
u32 new_intv
new rekeying interval (when “changed” = true)
-
void
tipc_crypto_work_tx
(struct work_struct *work)¶ Scheduled TX works handler
Parameters
struct work_struct *work
the struct TX work
Description
The function processes the previous scheduled work, i.e. key rekeying, by generating a new session key based on current one, then attaching it to the TX crypto and finally distributing it to peers. It also re-schedules the rekeying if needed.
TIPC Discoverer Interfaces¶
-
struct
tipc_discoverer
¶ information about an ongoing link setup request
Definition
struct tipc_discoverer {
u32 bearer_id;
struct tipc_media_addr dest;
struct net *net;
u32 domain;
int num_nodes;
spinlock_t lock;
struct sk_buff *skb;
struct timer_list timer;
unsigned long timer_intv;
};
Members
bearer_id
identity of bearer issuing requests
dest
destination address for request messages
net
network namespace instance
domain
network domain to which links can be established
num_nodes
number of nodes currently discovered (i.e. with an active link)
lock
spinlock for controlling access to requests
skb
request message to be (repeatedly) sent
timer
timer governing period between requests
timer_intv
current interval between requests (in ms)
-
void
tipc_disc_init_msg
(struct net *net, struct sk_buff *skb, u32 mtyp, struct tipc_bearer *b)¶ initialize a link setup message
Parameters
struct net *net
the applicable net namespace
struct sk_buff *skb
buffer containing message
u32 mtyp
message type (request or response)
struct tipc_bearer *b
ptr to bearer issuing message
-
void
disc_dupl_alert
(struct tipc_bearer *b, u32 node_addr, struct tipc_media_addr *media_addr)¶ issue node address duplication alert
Parameters
struct tipc_bearer *b
pointer to bearer detecting duplication
u32 node_addr
duplicated node address
struct tipc_media_addr *media_addr
media address advertised by duplicated node
-
void
tipc_disc_rcv
(struct net *net, struct sk_buff *skb, struct tipc_bearer *b)¶ handle incoming discovery message (request or response)
Parameters
struct net *net
applicable net namespace
struct sk_buff *skb
buffer containing message
struct tipc_bearer *b
bearer that message arrived on
-
int
tipc_disc_create
(struct net *net, struct tipc_bearer *b, struct tipc_media_addr *dest, struct sk_buff **skb)¶ create object to send periodic link setup requests
Parameters
struct net *net
the applicable net namespace
struct tipc_bearer *b
ptr to bearer issuing requests
struct tipc_media_addr *dest
destination address for request messages
struct sk_buff **skb
pointer to created frame
Return
0 if successful, otherwise -errno.
-
void
tipc_disc_delete
(struct tipc_discoverer *d)¶ destroy object sending periodic link setup requests
Parameters
struct tipc_discoverer *d
ptr to link dest structure
-
void
tipc_disc_reset
(struct net *net, struct tipc_bearer *b)¶ reset object to send periodic link setup requests
Parameters
struct net *net
the applicable net namespace
struct tipc_bearer *b
ptr to bearer issuing requests
TIPC Link Interfaces¶
Error
kernel-doc missing
TIPC msg Interfaces¶
Parameters
u32 size
message size (including TIPC header)
gfp_t gfp
memory allocation flags
Return
a new buffer with data pointers set to the specified size.
NOTE
Headroom is reserved to allow prepending of a data link header. There may also be unrequested tailroom present at the buffer’s end.
-
int
tipc_msg_append
(struct tipc_msg *_hdr, struct msghdr *m, int dlen, int mss, struct sk_buff_head *txq)¶ Append data to tail of an existing buffer queue
Parameters
struct tipc_msg *_hdr
header to be used
struct msghdr *m
the data to be appended
int dlen
size of data to be appended
int mss
max allowable size of buffer
struct sk_buff_head *txq
queue to append to
Return
the number of 1k blocks appended or errno value
-
int
tipc_msg_fragment
(struct sk_buff *skb, const struct tipc_msg *hdr, int pktmax, struct sk_buff_head *frags)¶ build a fragment skb list for TIPC message
Parameters
struct sk_buff *skb
TIPC message skb
const struct tipc_msg *hdr
internal msg header to be put on the top of the fragments
int pktmax
max size of a fragment incl. the header
struct sk_buff_head *frags
returned fragment skb list
Return
0 if the fragmentation is successful, otherwise: -EINVAL or -ENOMEM
-
int
tipc_msg_build
(struct tipc_msg *mhdr, struct msghdr *m, int offset, int dsz, int pktmax, struct sk_buff_head *list)¶ create buffer chain containing specified header and data
Parameters
struct tipc_msg *mhdr
Message header, to be prepended to data
struct msghdr *m
User message
int offset
buffer offset for fragmented messages (FIXME)
int dsz
Total length of user data
int pktmax
Max packet size that can be used
struct sk_buff_head *list
Buffer or chain of buffers to be returned to caller
Description
Note that the recursive call we are making here is safe, since it can logically go only one further level down.
Return
message data size or errno: -ENOMEM, -EFAULT
-
bool
tipc_msg_bundle
(struct sk_buff *bskb, struct tipc_msg *msg, u32 max)¶ Append contents of a buffer to tail of an existing one
Parameters
struct sk_buff *bskb
the bundle buffer to append to
struct tipc_msg *msg
message to be appended
u32 max
max allowable size for the bundle buffer
Return
“true” if bundling has been performed, otherwise “false”
-
bool
tipc_msg_try_bundle
(struct sk_buff *tskb, struct sk_buff **skb, u32 mss, u32 dnode, bool *new_bundle)¶ Try to bundle a new message to the last one
Parameters
struct sk_buff *tskb
the last/target message to which the new one will be appended
struct sk_buff **skb
the new message skb pointer
u32 mss
max message size (header inclusive)
u32 dnode
destination node for the message
bool *new_bundle
if this call made a new bundle or not
Return
“true” if the new message skb is potential for bundling this time or later, in the case a bundling has been done this time, the skb is consumed (the skb pointer = NULL). Otherwise, “false” if the skb cannot be bundled at all.
-
bool
tipc_msg_extract
(struct sk_buff *skb, struct sk_buff **iskb, int *pos)¶ extract bundled inner packet from buffer
Parameters
struct sk_buff *skb
buffer to be extracted from.
struct sk_buff **iskb
extracted inner buffer, to be returned
int *pos
position in outer message of msg to be extracted. Returns position of next msg. Consumes outer buffer when last packet extracted
Return
true when there is an extracted buffer, otherwise false
-
bool
tipc_msg_reverse
(u32 own_node, struct sk_buff **skb, int err)¶ swap source and destination addresses and add error code
Parameters
u32 own_node
originating node id for reversed message
struct sk_buff **skb
buffer containing message to be reversed; will be consumed
int err
error code to be set in message, if any Replaces consumed buffer with new one when successful
Return
true if success, otherwise false
-
bool
tipc_msg_lookup_dest
(struct net *net, struct sk_buff *skb, int *err)¶ try to find new destination for named message
Parameters
struct net *net
pointer to associated network namespace
struct sk_buff *skb
the buffer containing the message.
int *err
error code to be used by caller if lookup fails Does not consume buffer
Return
true if a destination is found, false otherwise
TIPC Name Interfaces¶
-
struct
service_range
¶ container for all bindings of a service range
Definition
struct service_range {
u32 lower;
u32 upper;
struct rb_node tree_node;
u32 max;
struct list_head local_publ;
struct list_head all_publ;
};
Members
lower
service range lower bound
upper
service range upper bound
tree_node
member of service range RB tree
max
largest ‘upper’ in this node subtree
local_publ
list of identical publications made from this node Used by closest_first lookup and multicast lookup algorithm
all_publ
all publications identical to this one, whatever node and scope Used by round-robin lookup algorithm
-
struct
tipc_service
¶ container for all published instances of a service type
Definition
struct tipc_service {
u32 type;
u32 publ_cnt;
struct rb_root ranges;
struct hlist_node service_list;
struct list_head subscriptions;
spinlock_t lock;
struct rcu_head rcu;
};
Members
type
32 bit ‘type’ value for service
publ_cnt
increasing counter for publications in this service
ranges
rb tree containing all service ranges for this service
service_list
links to adjacent name ranges in hash chain
subscriptions
list of subscriptions for this service type
lock
spinlock controlling access to pertaining service ranges/publications
rcu
RCU callback head used for deferred freeing
-
service_range_foreach_match
(sr, sc, start, end)¶ iterate over tipc service rbtree for each range match
Parameters
sr
the service range pointer as a loop cursor
sc
the pointer to tipc service which holds the service range rbtree
start
beginning of the search range (end >= start) for matching
end
end of the search range (end >= start) for matching
-
struct service_range *
service_range_match_first
(struct rb_node *n, u32 start, u32 end)¶ find first service range matching a range
Parameters
struct rb_node *n
the root node of service range rbtree for searching
u32 start
beginning of the search range (end >= start) for matching
u32 end
end of the search range (end >= start) for matching
Return
the leftmost service range node in the rbtree that overlaps the specific range if any. Otherwise, returns NULL.
-
struct service_range *
service_range_match_next
(struct rb_node *n, u32 start, u32 end)¶ find next service range matching a range
Parameters
struct rb_node *n
a node in service range rbtree from which the searching starts
u32 start
beginning of the search range (end >= start) for matching
u32 end
end of the search range (end >= start) for matching
Return
the next service range node to the given node in the rbtree that overlaps the specific range if any. Otherwise, returns NULL.
-
struct publication *
tipc_publ_create
(struct tipc_uaddr *ua, struct tipc_socket_addr *sk, u32 key)¶ create a publication structure
Parameters
struct tipc_uaddr *ua
the service range the user is binding to
struct tipc_socket_addr *sk
the address of the socket that is bound
u32 key
publication key
-
struct tipc_service *
tipc_service_create
(struct net *net, struct tipc_uaddr *ua)¶ create a service structure for the specified ‘type’
Parameters
struct net *net
network namespace
struct tipc_uaddr *ua
address representing the service to be bound
Description
Allocates a single range structure and sets it to all 0’s.
-
struct publication *
tipc_service_remove_publ
(struct service_range *r, struct tipc_socket_addr *sk, u32 key)¶ remove a publication from a service
Parameters
struct service_range *r
service_range to remove publication from
struct tipc_socket_addr *sk
address publishing socket
u32 key
target publication key
-
void
tipc_service_subscribe
(struct tipc_service *service, struct tipc_subscription *sub)¶ attach a subscription, and optionally issue the prescribed number of events if there is any service range overlapping with the requested range
Parameters
struct tipc_service *service
the tipc_service to attach the sub to
struct tipc_subscription *sub
the subscription to attach
-
bool
tipc_nametbl_lookup_anycast
(struct net *net, struct tipc_uaddr *ua, struct tipc_socket_addr *sk)¶ perform service instance to socket translation
Parameters
struct net *net
network namespace
struct tipc_uaddr *ua
service address to look up
struct tipc_socket_addr *sk
address to socket we want to find
Description
On entry, a non-zero ‘sk->node’ indicates the node where we want lookup to be performed, which may not be this one.
On exit:
If lookup is deferred to another node, leave ‘sk->node’ unchanged and return ‘true’.
If lookup is successful, set the ‘sk->node’ and ‘sk->ref’ (== portid) which represent the bound socket and return ‘true’.
If lookup fails, return ‘false’
Note that for legacy users (node configured with Z.C.N address format) the ‘closest-first’ lookup algorithm must be maintained, i.e., if sk.node is 0 we must look in the local binding list first
-
void
tipc_nametbl_withdraw
(struct net *net, struct tipc_uaddr *ua, struct tipc_socket_addr *sk, u32 key)¶ withdraw a service binding
Parameters
struct net *net
network namespace
struct tipc_uaddr *ua
service address/range being unbound
struct tipc_socket_addr *sk
address of the socket being unbound from
u32 key
target publication key
-
bool
tipc_nametbl_subscribe
(struct tipc_subscription *sub)¶ add a subscription object to the name table
Parameters
struct tipc_subscription *sub
subscription to add
-
void
tipc_nametbl_unsubscribe
(struct tipc_subscription *sub)¶ remove a subscription object from name table
Parameters
struct tipc_subscription *sub
subscription to remove
-
void
tipc_service_delete
(struct net *net, struct tipc_service *sc)¶ purge all publications for a service and delete it
Parameters
struct net *net
the associated network namespace
struct tipc_service *sc
tipc_service to delete
-
void
publ_to_item
(struct distr_item *i, struct publication *p)¶ add publication info to a publication message
Parameters
struct distr_item *i
location of item in the message
struct publication *p
publication info
-
struct sk_buff *
named_prepare_buf
(struct net *net, u32 type, u32 size, u32 dest)¶ allocate & initialize a publication message
Parameters
struct net *net
the associated network namespace
u32 type
message type
u32 size
payload size
u32 dest
destination node
Description
The buffer returned is of size INT_H_SIZE + payload size
-
struct sk_buff *
tipc_named_publish
(struct net *net, struct publication *p)¶ tell other nodes about a new publication by this node
Parameters
struct net *net
the associated network namespace
struct publication *p
the new publication
-
struct sk_buff *
tipc_named_withdraw
(struct net *net, struct publication *p)¶ tell other nodes about a withdrawn publication by this node
Parameters
struct net *net
the associated network namespace
struct publication *p
the withdrawn publication
-
void
named_distribute
(struct net *net, struct sk_buff_head *list, u32 dnode, struct list_head *pls, u16 seqno)¶ prepare name info for bulk distribution to another node
Parameters
struct net *net
the associated network namespace
struct sk_buff_head *list
list of messages (buffers) to be returned from this function
u32 dnode
node to be updated
struct list_head *pls
linked list of publication items to be packed into buffer chain
u16 seqno
sequence number for this message
-
void
tipc_named_node_up
(struct net *net, u32 dnode, u16 capabilities)¶ tell specified node about all publications by this node
Parameters
struct net *net
the associated network namespace
u32 dnode
destination node
u16 capabilities
peer node’s capabilities
-
void
tipc_publ_purge
(struct net *net, struct publication *p, u32 addr)¶ remove publication associated with a failed node
Parameters
struct net *net
the associated network namespace
struct publication *p
the publication to remove
u32 addr
failed node’s address
Description
Invoked for each publication issued by a newly failed node. Removes publication structure from name table & deletes it.
-
bool
tipc_update_nametbl
(struct net *net, struct distr_item *i, u32 node, u32 dtype)¶ try to process a nametable update and notify subscribers
Parameters
struct net *net
the associated network namespace
struct distr_item *i
location of item in the message
u32 node
node address
u32 dtype
name distributor message type
Description
tipc_nametbl_lock must be held.
Return
the publication item if successful, otherwise NULL.
-
void
tipc_named_rcv
(struct net *net, struct sk_buff_head *namedq, u16 *rcv_nxt, bool *open)¶ process name table update messages sent by another node
Parameters
struct net *net
the associated network namespace
struct sk_buff_head *namedq
queue to receive from
u16 *rcv_nxt
store last received seqno here
bool *open
last bulk msg was received (FIXME)
-
void
tipc_named_reinit
(struct net *net)¶ re-initialize local publications
Parameters
struct net *net
the associated network namespace
Description
This routine is called whenever TIPC networking is enabled. All name table entries published by this node are updated to reflect the node’s new network address.
TIPC Node Management Interfaces¶
Error
kernel-doc missing
TIPC Socket Interfaces¶
Error
kernel-doc missing
TIPC Network Topology Interfaces¶
-
bool
tipc_sub_check_overlap
(struct tipc_service_range *subscribed, struct tipc_service_range *found)¶ test for subscription overlap with the given values
Parameters
struct tipc_service_range *subscribed
the service range subscribed for
struct tipc_service_range *found
the service range we are checking for match
Description
Returns true if there is overlap, otherwise false.
TIPC Server Interfaces¶
-
struct
tipc_topsrv
¶ TIPC server structure
Definition
struct tipc_topsrv {
struct idr conn_idr;
spinlock_t idr_lock;
int idr_in_use;
struct net *net;
struct work_struct awork;
struct workqueue_struct *rcv_wq;
struct workqueue_struct *send_wq;
struct socket *listener;
char name[TIPC_SERVER_NAME_LEN];
};
Members
conn_idr
identifier set of connection
idr_lock
protect the connection identifier set
idr_in_use
amount of allocated identifier entry
net
network namspace instance
awork
accept work item
rcv_wq
receive workqueue
send_wq
send workqueue
listener
topsrv listener socket
name
server name
-
struct
tipc_conn
¶ TIPC connection structure
Definition
struct tipc_conn {
struct kref kref;
int conid;
struct socket *sock;
unsigned long flags;
struct tipc_topsrv *server;
struct list_head sub_list;
spinlock_t sub_lock;
struct work_struct rwork;
struct list_head outqueue;
spinlock_t outqueue_lock;
struct work_struct swork;
};
Members
kref
reference counter to connection object
conid
connection identifier
sock
socket handler associated with connection
flags
indicates connection state
server
pointer to connected server
sub_list
lsit to all pertaing subscriptions
sub_lock
lock protecting the subscription list
rwork
receive work item
outqueue
pointer to first outbound message in queue
outqueue_lock
control access to the outqueue
swork
send work item
TIPC Trace Interfaces¶
-
int
tipc_skb_dump
(struct sk_buff *skb, bool more, char *buf)¶ dump TIPC skb data
Parameters
struct sk_buff *skb
skb to be dumped
bool more
dump more? - false: dump only tipc msg data - true: dump kernel-related skb data and tipc cb[] array as well
char *buf
returned buffer of dump data in format
-
int
tipc_list_dump
(struct sk_buff_head *list, bool more, char *buf)¶ dump TIPC skb list/queue
Parameters
struct sk_buff_head *list
list of skbs to be dumped
bool more
dump more? - false: dump only the head & tail skbs - true: dump the first & last 5 skbs
char *buf
returned buffer of dump data in format