Linux TIPC 2.0 User's Guide

04 January 2011 [software version: TIPC 2.0.0, tipc-config 2.0.0]


Table of Contents

1. What's New
2. Release Status
3. System Requirements
4. Installation
5. Network Configuration
6. Network Monitoring
7. Command Reference
8. Interoperability
9. Known Issues

Introduction

This document is provided to assist software developers in setting up and operating a network using Linux TIPC 2.0.

For more information about the TIPC protocol, including information about writing applications that use TIPC, please consult the open source TIPC project website at http://tipc.sf.net . This site contains TIPC project software, documentation, news, and support instructions.

The TIPC development team welcomes input from the TIPC user community! Feel free to provide feedback on TIPC using the normal TIPC support procedures outlined at http://tipc.sf.net/support.html .

1. What's New

TIPC 2.0 contains significant differences from earlier TIPC releases:

  • TIPC 2.0 does not contain the experiment multi-cluster and multi-zone support present in TIPC 1.7.

  • TIPC 2.0 does not contain the experimental memory footprint reduction support present in TIPC 1.7.

  • TIPC 2.0 no longer supports the native API present in TIPC 1.3 through TIPC 1.7.

In addition, the entire TIPC 2.0 code base is being overhauled to update areas that have not been reviewed since the initial release of TIPC to open source. This will result in a leaner, faster, and more maintainable code base that provides a better foundation for the continued evolution of TIPC.

For information on the features of TIPC 2.0, please consult the TIPC documentation available at http://tipc.sf.net/docs_user.html .

2. Release Status

TIPC 2.0 is currently in development mode, which means that both new features and bug fixes are being integrated into it on an on-going basis.

Please report all issues and suggestions for improvements to the TIPC development team, using the normal TIPC support procedures outlined at http://tipc.sf.net/support.html .

3. System Requirements

TIPC 2.0 is present in Linux beginning with kernel version 2.6.35.

TIPC 2.0 requires tipc-config version 2.0.x for run-time configuration and operation.

4. Installation

These instructions assume that your system is running Linux kernel 2.6.35 (or later), and that you are already familiar with the steps involved in rebuilding a "vanilla" Linux kernel from source provided at www.kernel.org.

Caution: Some Linux distributions use a different procedure to build a kernel than the one described here, in which case you will need to adapt your actions accordingly.

If you aren't comfortable with the idea of updating your existing kernel, check to see if the kernel supports loadable modules; if so, you can build TIPC as a loadable module and install it dynamically.

  1. Configure the kernel to include TIPC, either statically or as a loadable module.

        eg. make menuconfig
                    

    The TIPC configuration menu is located at: Networking → Networking options → The TIPC Protocol

    Note: TIPC's default configuration settings should be sufficient for the needs of most users.

  2. Rebuild and install the kernel in the normal manner.

        eg. make
                    

    If you are building TIPC as a loadable module, build net/tipc/tipc.ko and install it in the standard manner.

    Note: The README file in the top level directory of a kernel source tree obtained from www.kernel.org provides a more complete description of how to build the Linux kernel and loadable modules.

  3. Boot up your system, then build the tipc-config tool and use it to configure and manage TIPC.

        eg. cd <tipc-config source directory>
            make
            ./tipc-config <commands>
                    

    Note: Be sure to use a version 2.0.x release of tipc-config, as earlier versions may not operate correctly with TIPC 2.0.

5. Network Configuration

Most TIPC users configure single-cluster networks in which each network node is connected to a common LAN using a single network interface per node. A smaller proportion of users utilize a second network interface per node to create an alternate, independent LAN, in order to provide redundancy in the event of a LAN failure.

To allow a new node running TIPC to join a single cluster TIPC network you simply use the tipc-config tool to tell the node the network ID and network address it should use, and to tell it which network interface(s) to use. For example, to assign TIPC the address <1.1.8> on network 1234 and have it use Ethernet interface eth0 you would enter:

    tipc-config -netid=1234 -a=1.1.8 -be=eth:eth0
        

You can confirm that the interface(s) have been successfully enabled by examining the Linux kernel log. (For example, use dmesg or look at /var/log/messages.) If there are other TIPC nodes with the same network ID present within your LAN you will also see printouts showing links being established.

Caution: If you want to use redundant LANs it is very important that they are not interconnected. The auto-configuration mechanism will become utterly confused if a network interface used by TIPC receives neighbour detection broadcasts from a single neighboring node using two or more different Ethernet addresses in a round-robin manner. (This is essentially the same confusion that results if multiple nodes are assigned the same <Z.C.N> address.)

Many users will have no need to do any additional configuration of TIPC, since the system defaults will be sufficient for their purposes. Some users with special needs may need to take additional steps.

  • Users who wish to change the default limits used by TIPC (eg. maximum # of publications permitted) can do so using the Linux kernel configuration tool and then rebuilding TIPC. (Most of these limits can also be changed without rebuilding TIPC using tipc-config commands, although there are limitations that restrict when such commands may be issued.)

A more detailed description of all network configuration commands provided by tipc-config can be found in Section 7, “Command Reference”.

6. Network Monitoring

The tipc-config tool allows users to monitor the behavior of a TIPC network. Commonly used commands include the following:

    -l     - display status of all links created by TIPC
    -n     - display status of all neighboring nodes discovered by TIPC
    -nt    - display all name table information used by TIPC
    -p     - display all ports created by TIPC
        

A more detailed description of all network monitoring commands provided by tipc-config can be found in Section 7, “Command Reference”.

7. Command Reference

The tipc-config tool provides numerous commands for configuring and monitoring a TIPC network. Certain commands are only available to users having network administrator privileges (eg. root) to prevent unauthorized users from reconfiguring the network.

Users can pass multiple commands to tipc-config in a single invocation. Commands are normally processed serially, from left to right; exceptions are the "-v", "-i", and "-dest" commands, which have an immediate effect on all commands in a command set. If tipc-config detects a failure while executing a set of commands, it exits without attempting any unprocessed commands.

Command names and arguments are case-sensitive. Commands can be abbreviated by truncating the command name, as long as the abbreviation is unambiguous. For example, "-addr" may be abbreviated to "-a" or "-ad", but "-max_publ" cannot be abbreviated to "-max".

Note: A full command name is never ambiguous, even if it is a substring of another command. For example, "-m" is non-ambiguous, even though there are other commands that begin with the same sequence of characters (eg. "-mng").

This command reference utilizes the following syntax conventions:

    <addr>       - a network node (eg. 1.1.12)
    <domain>     - a network region (eg. 2.3.12, 2.3.0, 2.0.0, or 0.0.0)
    <linkname>   - a link name (eg. 1.1.10:eth3-1.1.17:eth2)
    <linkpat>    - a link name pattern (eg. <linkname> or ?1.1.17 or ?eth3)
    <bearer>     - a bearer name (eg. eth:eth0)
    <bearerpat>  - a bearer name pattern (eg. <bearer> or ?eth)
    <media>      - a media type (eg. eth)
        

A pattern argument can be either a full name or a partial name (denoted by an initial '?' character). A partial name matches all names containing the string that follows the '?'.

Any command argument that is not described by the conventions above denotes an unsigned integer value.

The following commands are supported:

-addr[=<addr>]

Set the network address of the node. If <addr> is omitted, the node's current network address is displayed.

Note: Once the node's network address has been set, it is no longer possible to alter certain TIPC configuration settings, such as the network ID and certain "-max_XXX" limits.

-b[=<bearerpat>]

List all bearers having a name that matches the specified pattern. If no pattern is specified, all bearers are listed.

-bd=<bearerpat>

Disable the bearers having a name that matches the specified pattern.

-be=<bearer>[/<domain>[/<priority>]]

Enable a TIPC bearer on the interface <bearer>. The bearer name has the form <media>:<ifname>, indicating the media type used by the interface and the interface's name (eg. eth:eth0). More than one interface may be enabled at a time by specifying multiple bearers in a comma separated list (e.g. -be=eth:eth0,eth:eth1).

Once enabled, TIPC starts broadcasting over the bearer to detect other nodes in its network. The optional <domain> value specifes a "neighbour detection domain" which limits the nodes that TIPC can set up links to. For example, <0.0.0> (the default) tells TIPC to set up links to all nodes it finds, while <1.1.0> tells TIPC to communicate only with nodes that are part of cluster <1.1>.

The optional <priority> value specifies the priority for any TIPC links created by the bearer. Priorities can range from 0 (lowest) to 31 (highest); a priority of 32 (the default) tells TIPC to use the standard priority associated with the bearer's media type.

-dest=<addr>

Perform management commands on node <addr>. Other commands issued as part of the same command set are directed to the specified node for processing. (Note: Some commands that alter the configuration of TIPC cannot be performed remotely.)

-help

Display a summary of the options supported by tipc-config.

-i

Enable "interactive" mode. Other commands issued as part of the same command set will prompt for confirmation before attempting to change the configuration of TIPC.

-l[=<domain>|<linkpat>]

List all links to neighboring nodes in the specified network domain, or whose name matches the specified pattern.

If no argument is supplied, <domain> defaults to <0.0.0>, which causes the links to all neighboring nodes to be listed.

-log[=<size>]

Set the size of TIPC's system log to the specified number of bytes. To disable logging of system messages specify a <size> of zero.

If <size> is omitted the contents of the system log are displayed, and the log is reset to empty.

-lp=<linkpat>|<bearer>|<media>/<value>

Set the priority for links having a name that matches <linkpat> to <value>. Priorities can range from 0 (lowest) to 31 (highest).

This command can also be used to change the default priority assigned to new links created by the specified bearer (eg. -lp=eth:eth1/<value>), or to links created by new bearers of the specified media type (eg. -lp=eth/<value>). Note that such use will have no effect on the priority of existing links or the default priority of existing bearers.

If TIPC has more than one link to the same neighboring node, it will send traffic over the links with the highest priority, and only utilize lower priority links if all higher priority links have failed. If there are two links having highest priority, TIPC sends traffic over both links (although not necessarily in equal amounts).

-ls[=<linkpat>]

Display status and statistics information for links having a name that matches the specified pattern. If no pattern is specified, information for all links is displayed.

-lsr=<linkpat>

Reset the statistics counters for links having a name that matches the specified pattern.

-lt=<linkpat>|<bearer>|<media>/<value>

Set the tolerance for links having a name that matches <linkpat> to <value> milliseconds.

This command can also be used to change the default tolerance assigned to new links created by the specified bearer (eg. -lt=eth:eth1/<value>), or to links created by new bearers of the specified media type (eg. -lt=eth/<value>). Note that such use will have no effect on the tolerance of existing links or the default tolerance of existing bearers.

Link tolerance specifies the maximum time that TIPC will allow a communication problem to exist before taking the link down.

-lw=<linkpat>|<bearer>|<media>/<value>

Set the window for links having a name that matches <linkpat> to <value> messages.

This command can also be used to change the default window assigned to new links created by the specified bearer (eg. -lw=eth:eth1/<value>), or to links created by new bearers of the specified media type (eg. -lw=eth/<value>). Note that such use will have no effect on the window of existing links or the default window of existing bearers.

The link window controls how many unacknowledged messages a link endpoint can have in its transmit queue before TIPC's congestion control mechanisms become active.

-m

List all media types supported by TIPC.

-max_nodes[=<value>]

Set the maximum number of nodes supported by the node's cluster to <value>. If <value> is omitted the current setting is displayed.

Note: Once the node's network address has been set it is no longer possible to alter this setting.

-max_ports[=<value>]

Set the maximum number of ports supported by the node to <value>. If <value> is omitted the current setting is displayed.

Note: TIPC does not yet allow this setting to be changed once TIPC has been activated. Users wishing to change the default setting must reconfigure the Linux kernel and rebuild TIPC.

-max_publ[=<value>]

Set the maximum number of name publications (eg. socket bind() operations) supported by the node to <value>. If <value> is omitted the current setting is displayed.

-max_subscr[=<value>]

Set the maximum number of name subscriptions supported by the node to <value>. If <value> is omitted the current setting is displayed.

-mng[=enable|disable]

Permit or disallow processing of configuration commands issued by other nodes.

-n[=<domain>]

List all neighboring nodes within the specified network domain. If <domain> is omitted it defaults to <0.0.0>, which causes all neighboring nodes to be listed.

-netid[=<value>]

Set the network ID of the node to <value>. If <value> is omitted the current network ID is displayed.

This command makes it possible to configure multiple independent networks on a LAN whose nodes will not interact with each other. If you are the only TIPC user on the LAN, you can use the default network ID.

Note: Once the node's network address has been set it is no longer possible to alter the network ID.

-nt[=[<depth>,]<type>[,<low>[,<up>]]]

Display information from TIPC's name table.

Use <depth> to control how much detail is displayed for each entry listed:

  types = displays type info only
  names = displays type and instance info (i.e. name info)
  ports = displays type, instance, and port info
  all   = displays type, instance, port, and publication info
            

If <depth> is omitted, it defaults to "all".

Use <type>,<low>,<up> to control how many name table entries are displayed:

  <type>            displays all entries for the specified type
  <type>,<low>      displays all entries overlapping the specified name
  <type>,<low>,<up> displays all entries overlapping the specified name sequence
            

If <type> is omitted, all name table entries are displayed.

-p

List all ports created by TIPC on the node.

-s

Display TIPC status information. Currently, the only information provided is the version of TIPC being used (eg. TIPC version 1.7.x).

-v

Enable "verbose" mode. Other commands issued as part of the same command set may produce more detailed output describing what they are doing.

-V

Display the version of tipc-config being used.

8. Interoperability

TIPC 2.0 is designed to interoperate with nodes running TIPC 1.5/1.6/1.7, as long as all nodes belong to the same cluster. This interoperability allows an existing TIPC 1.5/1.6/1.7 cluster to be expanded to include new nodes running TIPC 2.0.

It is recommended that the tipc-config tool only be used to remotely manage nodes running a compatible version of TIPC. (That is, tipc-config version 2.0.x should only be used to manage nodes running TIPC 2.0; likewise, tipc-config 1.1.x should only be used to manage TIPC 1.7 nodes.)

The TIPC development team makes no claims regarding the interoperability of a TIPC 2.0 node with a node running TIPC 1.3/1.4.

9. Known Issues

This release has been sanitized using the TIPC test suite, and runs the TIPC demos. Please report all issues and suggestions for improvements to the TIPC development team using the normal TIPC support procedures outlined at http://tipc.sf.net/support.html .

[END OF DOCUMENT]