Understanding the IPOP Configuration

Understanding the IPOP Configuration

Quickstart

There are only two required modification to the IPOP configuration file that is necessary to get started. You must add your XMPP server host/IP address, username and password to the "Signal" section of the configuration JSON file. You will also want to set an appropriate IP4 address value in BridgeController. Example:

  "Signal": {
    "Enabled": true,
    "Overlays": {
      "101000F": {
        "HostAddress": "xmpp.host.addr",
        "Port": "5222",
        "Username": "xmpp-id@ejabberd",
        "Password": "a_secure-pswd",
        "AuthenticationMethod": "PASSWORD"
      }
    }
  },
  "BridgeController": {
    "Enabled": true,
    "Overlays": {
      "101000F": {
        "Type": "OVS",
        "BridgeName": "ipopbr",
        "IP4": "10.10.100.101",
        "PrefixLen": 24,
        "MTU": 1410,
        "AutoDelete": true
      }
    }
  }

A template can be found in the ipop installation directory /opt/ipop-vpn/sample-config.json, and should be completed and copied to /etc/opt/ipop-vpn/config.json.

Advanced Configuration

The IPOP configuration file uses the JSON format, and specifies the parameterized options for the various controller modules that make up the IPOP controller. A valid config.json file is required to run IPOP. The options that are of most interest and/or need to be changed are stored in this file. The controller/framework/fxlib.py contains the full set of default values in the CONFIG dictionary. This dictionary is loaded first and any values specified in config file will override them. Therefore, changes should always be made to the config.json file and not the fxlib.py file. The configurations tells the controller framework which modules to load and with what parameters. If a module is not specified in the configuration it is not loaded. Certain keys occur in multiple modules with the same meaning and effect. Each module has an Enabled key that when set to false will cause the framework to skip loading it. TimerInterval specifies how often a module’s timer event fires in seconds. Dependencies specify which modules are used a module and must be loaded before hand.

CFx - Used by the framework

• NodeId - hexadecimal UUID for the local node. One can specified here or left blank for the framework to generate its own.
• Model - A mnemonic to describe customized IPOP controllers. You can develop and add your own modules, or remove or replace existing modules.
• Overlays - List of overlays UUIDs that your controller creates and manages. By default there is only one but you can add more. Each overlay is a separate L2 network and must be configured separately throughout the config file1.
• NidFileName - Fully qualified filename for storing generated Node Id.

Logger - The controller logger module. Used by all other modules for logging. Supports disk file and console streams.

• LogLevel - The detail of information to log. Values: NONE/ERROR/WARNING/INFO/DEBUG.
• ConsoleLevel - Separate logging level used for the console when device is all
• Device - The output stream to be used. Values: File/Console/All.
• Directory - The filesystem directory path to store the log files.
• CtrlLogFileName - Controller log file name
• TincanLogFileName - Tincan (data plane) log file name
• MaxFileSize - Maximum individual log file size
• MaxArchives - no of log files to archive before overwriting

TincanInterface - Module to abstract interacting with Tincan process

• MaxReadSize - Max buffer size for Tincan Messages
• SocketReadWaitTime - Socket read wait time for Tincan Messages
• RcvServiceAddress - Controller server address
• SndServiceAddress - Tincan server address
• RcvServiceAddress6 - Controller server IPv6 address
• SndServiceAddress6 - Tincan server IPv6 address
• CtrlRecvPort - Controller Listening Port
• CtrlSendPort - Tincan Listening Port

Signal - Provides signalling services for bootstrapping tunnel connections.

• CacheExpiry - Minimum duration in seconds that an entry remains in the Node ID -> JID cache
• Overlays - A configuration for each overlay being managed by this controller
  • Overlay UUID - A hexadecimal value matching one in the CFx Overlays list (see above 1)
  • HostAddress - A compliant XMPP server (eg ejabberd) host/IP address
  • Port: XMPP server listening network port
  • Username - XMPP user name in user@host format
  • Password - corresponding XMPP password, can be blank if password is stored in keyring.
  • AuthenticationMethod - Use password or asymmetric key for authentication. Values: Password/x509
  • TrustStore - Directory to the local root trust store
  • CertDirectory - Directory where the client certificates
  • CertFile - Client certificate filename
  • KeyFile - Client key filename

Topology - Module that defines and enforces the overlay topology.

• Overlays - A configuration for each overlay being managed by this controller
  • Overlay UUID - A hexadecimal value matching one in the CFx Overlays list (see above 1)
  • Name - Descriptive mnemonic .
  • Description - Descriptive mnemonic .
  • EnforcedEdges - Peer Ids that a tunnel should be created to, eg., [ "12345", 12346", 12347" ].
  • ManualTopology - Should the topology only create enforced edges. Values true/false (default)
  • PeerDiscoveryCoalesce - The number of new peer notifications to wait on before attempting to update the overlay edges. If this threshold is not reached the overlay will be refreshed on its periodic TimerInterval.
  • MaxSuccessors - Maximum number of successors links to create. These are outgoing links to the next peer in the overlay's ring.
  • MaxLongDistEdges - Maximum number of outgoing long distance edges to initiate.
  • MaxConcurrentEdgeSetup - Maximum number of edges to be created concurrently. Prevents the stampede effect when joining an existing large overlay.
  • Role - Switch (if this node will perform switching operations and accept incoming connection requests), or Leaf (if it is a client/edge device that will connect to switch node, and reject any incoming requests for an edge).

LinkManager - Creates and manages the WebRTC based links between peers.

• Stun - List of STUN server addresses in format address:port
• Turn - List of dictionaries which specify the TURN server and corresponding credentials.
  • Address - TURN server host/IP address and port in format address:port
  • User - TURN user name
  • Password - Corresponding TURN password.
• Overlays - A configuration for each overlay being managed by this controller
  • Overlay UUID - A hexadecimal value matching one in the CFx Overlays list (see above 1)
  • Type - Should only be TUNNEL
  • TapName - The prefix used for creating the IPOP TAP devices. The first 7 chars of the link ID are appended.
  • IgnoredNetInterfaces - List of TAP device names that should not be used for tunneling. No CAS endpoints points bound to these network interfaces will be generated.

BridgeController - Module that manages the network bridge interaction with the IPOP TAP devices.

• Overlays - A configuration for each overlay being managed by this controller
  • Overlay UUID - A hexadecimal value matching one in the CFx Overlays list (see above 1)
  • Type - The type of network bridge to instantiate, the Linux bridge and Openvswitch are supported. Values: LXBR/OVS/VNIC. Set this value to VNIC if Topology's Role is set to Leaf.
  • BridgeName - Mnemonic used for naming the bridge instance.
  • IP4 - The IPv4 address to assign to the bridge. This is an optional parameter, if your deployment does not require assigning an IP configuration to the bridge it can be omitted.
  • PrefixLen - The network prefix length to apply to the bridge. (Optional parameter)
  • MTU - The maximum transmission unit size to be applied to the bridge. Optional parameter, IPOP sets an MTU of 1410.
  • AutoDelete - Remove the bridge device that was specified when the controller shuts down. Values: True/False (default)
  • STP - Enable or disable Spanning Tree Protocol on the IPOP bridge device.

OverlayVisualizer - Module which collects overlay network status and metrics and transmits it to the collector web service.

• WebServiceAddress - The host/IP address of the collector and visualization web service, in the format address:port.
• NodeName - A user provided descriptive mnemonic that is used for labeling the node in the visualization browser UI.

UsageReport - Module that collects and transmits anonymized usage data necessary for reporting to NSF per funding agreement. If you do not wish to participate, set the module’s Enabled key to false. There is no other parameter to configure.

Sample Configuration File

A sample configuration file is available here.