RollSite: Configuring Route Table

1. Design Considerations

Let's rethink how your home router works. When you try to visit an intranet site, say 192.168.0.1, your router probably knows where it is and directs the traffic there; but now you try to visit github, your router has no idea where it is and it forwards those traffic to the default gateway. The story continues and loops until some wise router knows where github is, and finally it transmits those traffic to github.

RollSite is a layer-7 router-alike application and its routing mechanism works just the same as your home router.

Considering RollSite works like a router, the RollSite network topology is highly flexible. You can config a star / mesh / ring / bus topology as whichever suits your scenario.

2. Configurations

2.1. Example

Here is an example route table:

{
  "route_table":
  {
    "default":
    {
      "default":[
        {
          "port": 9370,
          "ip": "www.example.com"
        }
      ]
    },
    "10001":
    {
      "default":[
        {
          "port": 9370,
          "ip": "www.example.com"
        }
      ]
    },
    "10002":
    {
      "default": [
        {
          "port": 9370,
          "ip": "192.168.0.10"
        }
      ],
      "service1": [
        {
          "port": 9470,
          "ip": "192.168.0.20"
        }
      ],
      "service2": [
        {
          "port": 9570,
          "ip": "192.168.0.30",
          "is_secure": true
        }
      ]
    }
  },
  "permission":
  {
    "default_allow": true
  }
}

There are 2 nodes on top level: route_table and permission. permission defines if communications are allowed between 2 sites and it is temporarily deprecated. Discussion below focuses on the route_table section.

2.2. Routing Explained

All routing decisions are based on dst of Metadata in the proxy protocol. dst is a Topic message. For the routing scenario we are discussing, we can focus on partyId and role fields.

Let's revisit the route table example above (section 2.1). The direct sub-node of route_table section are default, 10001 and 10002. These are partyIds in the protocol and they are the 1st priority for routing. Amongst these partyIds, RollSite first search for an exact match (192.168.0.1 in your home router), and if there is none, RollSite will use default (default gateway in your home router). What if there is neither exact match nor default? RollSite reports an error.

Now that we have found the partyId, say 10002, the next step is to see which service (or role in the federated learning context) should the packet be forwarded to. role in the protocol is used for this routing decision (well, a legacy name though ..), i.e. the 2nd priority. The matching principle here is exactly the same as partyId matching (first exact match -> not found then default -> no default then error raised).

Let's see some examples.

#	partyId	partyId match? (1st priority)	role (service name)	role (service name) match? (2nd priority)	final route
1	10002	exact match	service1	exact match	192.168.0.20:9470
2	10002	exact match	random_service	not found, using default	192.168.0.10:9370
3	9999	not match, using default	service2	not found, using default	www.example.com:9370

2.3. Configurations Details

Use partyId=default, role=default as an example. Details of this partyId-role pair is an JsonArray, and inside this JsonArray are JsonObjects. This JsonArray is reserved for future features. For now you can use only 1 JsonObject in this JsonArray.

Followings are possible keys in site configurations:

#	key name	value type	meaning	default value
1	ip	string	ip / hostname	<N/A>
2	port	int	port	<N/A>
3	is_secure	boolean	Whether to use a secure (TLS) client when connecting to this site	false
4	is_polling	boolean	Whether this is a polling client	false

2.4. Packet to "Myself" - Command to RollSite

Let's assume RollSite is working for partyId=${thisPartyId} and port=${thisPort}. One can send a unary call packet with partyId=${thisPartyId} and port=${thisPort}. In this case, the RollSite will process this command if authentication passes. Followings are possible commands:

#	command	meaning
1	get_route_table	get route table
2	set_route_table	set route table
3	ping	ping

3. Q&A

3.1. Can I use multiple roles (service names) in partyId=default?

Yes.

3.2. Json configuration file is old / tedious / error-prone, can Eggroll support other configuration file type?

Yes. Actually yaml is also supported. We will update this document soon.

3.3. Can you explain in more detail about the polling configuration?

Yes. Please refer to RollSite: Configuring Polling Mode

3.4. How to test if a route table is ok?

There is a ping operation to test connectivity status. We will make it a convenient tool and release. Stay tuned :)

3.5. How to know "My Party Id" and "My Port"?

Please check ${EGGROLL_HOME}/conf/eggroll.properties. "My Party Id"=eggroll.rollsite.party.id, "My Port"=eggroll.rollsite.port.

3.6. Should I always config a default for partyId / role?

It depends on your usage. For correctness, the defaults are not mandatory. So if you are working with only a handful of parties, you can use any topology, e.g. mesh / star, with or without defaults. But when you are working with many or unknown number of parties, it is recommended that you configure a star network and taking the advantage of RollSite's default mechanism to reduce overall network complexities.