api

README

Protocol Documentation

Table of Contents

• v1/node.proto
  • MDataChannelNegotiation
  • MGetStatusRequest
  • MInterfaceMetrics
  • MPeerMetrics
  • MPublishRequest
  • MPublishResponse
  • MQueryRequest
  • MQueryResponse
  • MStatus
  • MSubscribeRequest
  • MSubscriptionEvent
  • EClusterStatus
  • EDataChannel
  • EFeature
  • EQueryRequest.QueryCommand
  • SNode
• v1/mesh.proto
  • MGetNodeRequest
  • MMeshEdge
  • MMeshEdge.AttributesEntry
  • MMeshEdges
  • MMeshGraph
  • MMeshNode
  • MNodeList
  • EEdgeAttributes
  • SMesh
• v1/rbac.proto
  • MGroup
  • MGroups
  • MRBACAction
  • MRole
  • MRoleBinding
  • MRoleBindings
  • MRoles
  • MRule
  • MSubject
  • ERuleResource
  • ERuleVerb
  • ESubjectType
• v1/network_acls.proto
  • MNetworkACL
  • MNetworkACLs
  • MNetworkAction
  • MRoute
  • MRoutes
  • EACLAction
• v1/admin.proto
  • SAdmin
• v1/app.proto
  • MConnectRequest
  • MConnectResponse
  • MDisconnectRequest
  • MDisconnectResponse
  • MMetricsRequest
  • MMetricsResponse
  • MMetricsResponse.InterfacesEntry
  • MStatusRequest
  • MStatusResponse
  • EStatusResponse.ConnectionStatus
  • SAppDaemon
• v1/raft.proto
  • MRaftApplyResponse
  • MRaftLogEntry
  • ERaftCommandType
• v1/members.proto
  • MJoinRequest
  • MJoinResponse
  • MLeaveRequest
  • MLeaveResponse
  • MRaftConfigurationRequest
  • MRaftConfigurationResponse
  • MRaftServer
  • MUpdateRequest
  • MUpdateResponse
  • MWireGuardPeer
  • SMembership
• v1/peer_discovery.proto
  • MListRaftPeersResponse
  • MRaftPeer
  • SPeerDiscovery
• v1/plugin.proto
  • MAllocateIPRequest
  • MAllocatedIP
  • MAuthenticationRequest
  • MAuthenticationRequest.HeadersEntry
  • MAuthenticationResponse
  • MDataSnapshot
  • MEvent
  • MPluginConfiguration
  • MPluginInfo
  • MPluginQuery
  • MPluginQueryResult
  • MReleaseIPRequest
  • MStoreLogRequest
  • EAllocateIPRequest.IPVersion
  • EPluginCapability
  • EPluginQuery.QueryCommand
  • EWatchEvent
  • SAuthPlugin
  • SIPAMPlugin
  • SPlugin
  • SStoragePlugin
  • SWatchPlugin
• v1/webrtc.proto
  • MDataChannelOffer
  • MStartDataChannelRequest
  • SWebRTC
• Scalar Value Types

v1/node.proto

Top

DataChannelNegotiation

DataChannelNegotiation is the message for communicating data channels to nodes.

Field	Type	Label	Description
proto	string		proto is the protocol of the traffic.
src	string		src is the address of the client that initiated the request.
dst	string		dst is the destination address of the traffic.
port	uint32		port is the destination port of the traffic.
offer	string		offer is the offer for the node to use as its local description.
answer	string		answer is the answer for the node to use as its remote description.
candidate	string		candidate is an ICE candidate.
stun_servers	string	repeated	stun_servers is the list of STUN servers to use.

GetStatusRequest

GetStatusRequest is a request to get the status of a node.

Field	Type	Label	Description
id	string		id is the ID of the node. If unset, the status of the local node is returned.

InterfaceMetrics

InterfaceMetrics is the metrics for the WireGuard interface on a node.

Field	Type	Label	Description
device_name	string		device_name is the name of the device.
public_key	string		public_key is the public key of the node.
address_v4	string		address_v4 is the IPv4 address of the node.
address_v6	string		address_v6 is the IPv6 address of the node.
type	string		type is the type of interface being used for wireguard.
listen_port	int32		listen_port is the port wireguard is listening on.
total_receive_bytes	uint64		total_receive_bytes is the total number of bytes received.
total_transmit_bytes	uint64		total_transmit_bytes is the total number of bytes transmitted.
num_peers	int32		num_peers is the number of peers connected to the node.
peers	PeerMetrics	repeated	peers are the per-peer statistics.

PeerMetrics

PeerMetrics are the metrics for a node's peer.

Field	Type	Label	Description
public_key	string		public_key is the public key of the peer.
endpoint	string		endpoint is the connected endpoint of the peer.
persistent_keep_alive	string		persistent_keep_alive is the persistent keep alive interval for the peer.
last_handshake_time	string		last_handshake_time is the last handshake time for the peer.
allowed_ips	string	repeated	allowed_ips is the list of allowed IPs for the peer.
protocol_version	int64		protocol_version is the version of the wireguard protocol negotiated with the peer.
receive_bytes	uint64		receive_bytes is the bytes received from the peer.
transmit_bytes	uint64		transmit_bytes is the bytes transmitted to the peer.

PublishRequest

PublishRequest is sent by the application to the node to publish events.

This currently only supports database events.

Field	Type	Label	Description
key	string		key is the key of the event.
value	string		value is the value of the event. This will be the raw value of the key.
ttl	google.protobuf.Duration		ttl is the time for the event to live in the database.

PublishResponse

PublishResponse is the response to a publish request. This is currently

empty.

QueryRequest

QueryRequest is sent by the application to the node to query the mesh for

information.

Field	Type	Label	Description
command	QueryRequest.QueryCommand		command is the command of the query.
query	string		query is the key or prefix of the query.

QueryResponse

QueryResponse is the message containing a mesh query result.

Field	Type	Label	Description
key	string		key is the key of the query. For GET and ITER queries it will be the current key. For LIST queries it will be the prefix.
value	string	repeated	value is the value of the query. For GET and ITER queries it will be the value of the current key. For LIST queries it will be the list of keys that match the prefix.
error	string		error is an error that occurred during the query. At the end of an ITER query it will be set to "EOF" to indicate that the iteration is complete.

Status

Status represents the status of a node.

Field	Type	Label	Description
id	string		id is the ID of the node.
version	string		version is the version of the node.
commit	string		commit is the commit of the node.
build_date	string		build_date is the build date of the node.
uptime	string		uptime is the uptime of the node.
started_at	google.protobuf.Timestamp		started_at is the time the node started.
features	Feature	repeated	features is the list of features currently enabled.
cluster_status	ClusterStatus		cluster_status is the status of the node in the cluster.
current_leader	string		current_leader is the current leader of the cluster.
current_term	uint64		current_term is the current term of the cluster.
last_log_index	uint64		last_log_index is the last log index of the cluster.
last_applied	uint64		last_applied is the last applied index of the cluster.
interface_metrics	InterfaceMetrics		interface_metrics are the metrics for the node's interfaces.

SubscribeRequest

SubscribeRequest is sent by the application to the node to subscribe to

events. This currently only supports database events.

Field	Type	Label	Description
prefix	string		prefix is the prefix of the events to subscribe to.

SubscriptionEvent

SubscriptionEvent is a message containing a subscription event.

Field	Type	Label	Description
key	string		key is the key of the event.
value	string		value is the value of the event. This will be the raw value of the key.

ClusterStatus

ClusterStatus is the status of the node in the cluster.

Name	Number	Description
CLUSTER_STATUS_UNKNOWN	0	CLUSTER_STATUS_UNKNOWN is the default status.
CLUSTER_LEADER	1	CLUSTER_LEADER is the status for the leader node.
CLUSTER_VOTER	2	CLUSTER_VOTER is the status for a voter node.
CLUSTER_NON_VOTER	3	CLUSTER_NON_VOTER is the status for a non-voter node.
CLUSTER_NODE	4	CLUSTER_NODE is the status of a node that is not a part of the raft cluster.

DataChannel

DataChannel are the data channels used when communicating over ICE

with a node.

Name	Number	Description
CHANNELS	0	CHANNELS is the data channel used for negotiating new channels. This is the first channel that is opened. The ID of the channel should be 0.
CONNECTIONS	1	CONNECTIONS is the data channel used for negotiating new connections. This is a channel that is opened for each incoming connection from a client. The ID should start at 0 and be incremented for each new connection.

Feature

Feature is a list of features supported by a node.

Name	Number	Description
FEATURE_NONE	0	FEATURE_NONE is the default feature set.
NODES	1	NODES is the feature for nodes. This is always supported on raft members.
LEADER_PROXY	2	LEADER_PROXY is the feature for leader proxying.
MESH_API	3	MESH_API is the feature for the mesh API.
ADMIN_API	4	ADMIN_API is the feature for the admin API.
PEER_DISCOVERY	5	PEER_DISCOVERY is the feature for peer discovery.
METRICS	6	METRICS is the feature for exposing metrics.
ICE_NEGOTIATION	7	ICE_NEGOTIATION is the feature for ICE negotiation.
TURN_SERVER	8	TURN_SERVER is the feature for TURN server.
MESH_DNS	9	MESH_DNS is the feature for mesh DNS.
FORWARD_MESH_DNS	10	FORWARD_MESH_DNS is the feature for forwarding mesh DNS lookups to other meshes.

QueryRequest.QueryCommand

QueryCommand is the type of the query.

Name	Number	Description
UNKNOWN	0	UNKNOWN is the default command.
GET	1	GET is the command to get a value.
LIST	2	LIST is the command to list keys with an optional prefix.
ITER	3	ITER is the command to iterate over keys with an optional prefix.

Node

Node is the service exposed on every node in the mesh to communicate network

information amongst themselves and provide a mesh API to applications.

Method Name	Request Type	Response Type	Description
GetStatus	GetStatusRequest	Status	GetStatus gets the status of a node in the cluster.
Query	QueryRequest	QueryResponse stream	Query is used to query the mesh for information.
Publish	PublishRequest	PublishResponse	Publish is used to publish events to the mesh database. A restricted set of keys are allowed to be published to.
Subscribe	SubscribeRequest	SubscriptionEvent stream	Subscribe is used by non-raft nodes to receive updates to the mesh state. This is only available on nodes that are members of the raft cluster.
NegotiateDataChannel	DataChannelNegotiation stream	DataChannelNegotiation stream	NegotiateDataChannel is used to negotiate a WebRTC connection between a webmesh client and a node in the cluster. The handling server will send the target node the source address, the destination for traffic, and STUN/TURN servers to use for the negotiation. The node responds with an offer to be forwarded to the client. When the handler receives an answer from the client, it forwards it to the node. Once the node receives the answer, the stream can optionally be used to exchange ICE candidates.

v1/mesh.proto

Top

GetNodeRequest

GetNodeRequest is a request to get a node.

Field	Type	Label	Description
id	string		id is the ID of the node.

MeshEdge

MeshEdge is an edge between two nodes.

Field	Type	Label	Description
source	string		source is the source node.
target	string		target is the target node.
weight	int32		weight is the weight of the edge.
attributes	MeshEdge.AttributesEntry	repeated	attributes is a list of attributes for the edge.

MeshEdge.AttributesEntry

Field	Type	Label	Description
key	string
value	string

MeshEdges

MeshEdges is a list of edges.

Field	Type	Label	Description
items	MeshEdge	repeated	items is the list of edges.

MeshGraph

MeshGraph is a graph of nodes.

Field	Type	Label	Description
nodes	string	repeated	nodes is the list of nodes.
edges	MeshEdge	repeated	edges is the list of edges.
dot	string		dot is the DOT representation of the graph.

MeshNode

MeshNode is a node that has been registered with the controller.

Field	Type	Label	Description
id	string		id is the ID of the node.
primary_endpoint	string		primary_endpoint is the primary endpoint of the node.
wireguard_endpoints	string	repeated	wireguard_endpoints is a list of WireGuard endpoints for the node.
zone_awareness_id	string		zone_awareness_id is the zone awareness ID of the node.
raft_port	int32		raft_port is the Raft listen port of the node.
grpc_port	int32		grpc_port is the gRPC listen port of the node.
meshdns_port	int32		meshdns_port is the port the node advertises to offer DNS to other peers. a value of 0 means the node does not offer DNS. ports are currently assumed to be UDP.
public_key	string		public_key is the public key of the node.
private_ipv4	string		private_ipv4 is the private IPv4 address of the node.
private_ipv6	string		private_ipv6 is the private IPv6 address of the node.
features	Feature	repeated	features is a list of features supported by the node.
updated_at	google.protobuf.Timestamp		updated_at is the last time the node joined the cluster.
created_at	google.protobuf.Timestamp		created_at is the creation time for the node.
cluster_status	ClusterStatus		cluster_status is the status of the node in the cluster.

NodeList

NodeList is a list of nodes.

Field	Type	Label	Description
nodes	MeshNode	repeated	nodes is the list of nodes.

EdgeAttributes

EdgeAttributes are pre-defined edge attributes. They should

be used as their string values.

Name	Number	Description
EDGE_ATTRIBUTE_UNKNOWN	0	EDGE_ATTRIBUTE_UNKNOWN is an unknown edge attribute.
EDGE_ATTRIBUTE_ICE	1	EDGE_ATTRIBUTE_ICE is an ICE edge attribute.

Mesh

Mesh is a service that can optionally be exposed by a node. It provides methods for

interfacing with the webmesh from the outside.

Method Name	Request Type	Response Type	Description
GetNode	GetNodeRequest	MeshNode	GetNode gets a node by ID.
ListNodes	.google.protobuf.Empty	NodeList	ListNodes lists all nodes.
GetMeshGraph	.google.protobuf.Empty	MeshGraph	GetMeshGraph fetches the mesh graph. It returns a list of nodes, edges, and a rendering in the dot format.

v1/rbac.proto

Top

Group

Group is a group of subjects.

Field	Type	Label	Description
name	string		name is the name of the group.
subjects	Subject	repeated	subjects is the list of subjects in the group.

Groups

Groups is a list of groups.

Field	Type	Label	Description
items	Group	repeated	items is the list of groups.

RBACAction

RBACAction is an action that can be performed on a resource. It is used by implementations

to evaluate rules.

Field	Type	Label	Description
resource	RuleResource		resource is the resource on which the action is performed.
resource_name	string		resource_name is the name of the resource on which the action is performed.
verb	RuleVerb		verb is the verb that is performed on the resource.

Role

Role is a role that can be assigned to a subject.

Field	Type	Label	Description
name	string		name is the name of the role.
rules	Rule	repeated	rules is the list of rules that apply to the role.

RoleBinding

RoleBinding is a binding of a role to one or more subjects.

Field	Type	Label	Description
name	string		name is the name of the role binding.
role	string		role is the name of the role to which the binding applies.
subjects	Subject	repeated	subjects is the list of subjects to which the binding applies.

RoleBindings

RoleBindings is a list of role bindings.

Field	Type	Label	Description
items	RoleBinding	repeated	items is the list of role bindings.

Roles

Roles is a list of roles.

Field	Type	Label	Description
items	Role	repeated	items is the list of roles.

Rule

Rule is a rule that applies to a resource.

Field	Type	Label	Description
resources	RuleResource	repeated	resources is the resources to which the rule applies.
resource_names	string	repeated	resource_names is the list of resource names to which the rule applies.
verbs	RuleVerb	repeated	verbs is the list of verbs that apply to the resource.

Subject

Subject is a subject to which a role can be bound.

Field	Type	Label	Description
name	string		name is the name of the subject.
type	SubjectType		type is the type of the subject.

RuleResource

RuleResource is the resource type for a rule.

Name	Number	Description
RESOURCE_UNKNOWN	0	RESOURCE_UNKNOWN is an unknown resource.
RESOURCE_VOTES	1	RESOURCE_VOTES is the resource for voting in raft elections. The only verb evaluated for this resource is PUT.
RESOURCE_ROLES	2	RESOURCE_ROLES is the resource for managing roles.
RESOURCE_ROLE_BINDINGS	3	RESOURCE_ROLE_BINDINGS is the resource for managing role bindings.
RESOURCE_GROUPS	4	RESOURCE_GROUPS is the resource for managing groups.
RESOURCE_NETWORK_ACLS	5	RESOURCE_NETWORK_ACLS is the resource for managing network ACLs.
RESOURCE_ROUTES	6	RESOURCE_ROUTES is the resource for managing routes.
RESOURCE_DATA_CHANNELS	7	RESOURCE_DATA_CHANNELS is the resource for creating data channels.
RESOURCE_EDGES	8	RESOURCE_EDGES is the resource for managing edges between nodes.
RESOURCE_OBSERVERS	9	RESOURCE_OBSERVERS is the resource for managing observers. The only verb evaluated for this resource is PUT.
RESOURCE_PUBSUB	10	RESOURCE_PUBSUB is the resource for managing pubsub topics.
RESOURCE_ALL	999	RESOURCE_ALL is a wildcard resource that matches all resources.

RuleVerb

RuleVerb is the verb type for a rule.

Name	Number	Description
VERB_UNKNOWN	0	VERB_UNKNOWN is an unknown verb.
VERB_PUT	1	VERB_PUT is the verb for creating or updating a resource.
VERB_GET	2	VERB_GET is the verb for getting a resource.
VERB_DELETE	3	VERB_DELETE is the verb for deleting a resource.
VERB_ALL	999	VERB_ALL is a wildcard verb that matches all verbs.

SubjectType

SubjectType is the type of a subject.

Name	Number	Description
SUBJECT_UNKNOWN	0	SUBJECT_UNKNOWN is an unknown subject type.
SUBJECT_NODE	1	SUBJECT_NODE is a subject type for a node.
SUBJECT_USER	2	SUBJECT_USER is a subject type for a user.
SUBJECT_GROUP	3	SUBJECT_GROUP is a subject type for a group.
SUBJECT_ALL	999	SUBJECT_ALL is a wildcard subject type that matches all subject types. It can be used with a subject named '*' to match all subjects.

v1/network_acls.proto

Top

NetworkACL

NetworkACL is a network ACL.

Field	Type	Label	Description
name	string		name is the name of the ACL.
priority	int32		priority is the priority of the ACL. ACLs with higher priority are evaluated first.
action	ACLAction		action is the action to take when a request matches the ACL.
source_nodes	string	repeated	source_nodes is a list of source nodes to match against. If empty, all nodes are matched. Groups can be specified with the prefix "group:".
destination_nodes	string	repeated	destination_nodes is a list of destination nodes to match against. If empty, all nodes are matched.
source_cidrs	string	repeated	source_cidrs is a list of source CIDRs to match against. If empty, all CIDRs are matched.
destination_cidrs	string	repeated	destination_cidrs is a list of destination CIDRs to match against. If empty, all CIDRs are matched.
protocols	string	repeated	protocols is a list of protocols to match against. If empty, all protocols are matched. Protocols can be specified by name or number.
ports	uint32	repeated	ports is a list of ports to match against. If empty, all ports are matched.

NetworkACLs

NetworkACLs is a list of network ACLs.

Field	Type	Label	Description
items	NetworkACL	repeated	items is the list of network ACLs.

NetworkAction

NetworkAction is an action that can be performed on a network resource. It is used

by implementations to evaluate network ACLs.

Field	Type	Label	Description
src_node	string		src_node is the source node of the action.
src_cidr	string		src_cidr is the source CIDR of the action.
dst_node	string		dst_node is the destination node of the action.
dst_cidr	string		dst_cidr is the destination CIDR of the action.
protocol	string		protocol is the protocol of the action.
port	uint32		port is the port of the action.

Route

Route is a route that is broadcasted by one or more nodes.

Field	Type	Label	Description
name	string		name is the name of the route.
node	string		node is the node that broadcasts the route. A group can be specified with the prefix "group:".
destination_cidrs	string	repeated	destination_cidrs are the destination CIDRs of the route.
next_hop_node	string		next_hop_node is an optional node that is used as the next hop for the route.

Routes

Routes is a list of routes.

Field	Type	Label	Description
items	Route	repeated	items is the list of routes.

ACLAction

ACLAction is the action to take when a request matches an ACL.

Name	Number	Description
ACTION_UNKNOWN	0	ACTION_UNKNOWN is the default action for ACLs. It is synonymous with ACTION_DENY.
ACTION_ACCEPT	1	ACTION_ACCEPT allows the request to proceed.
ACTION_DENY	2	ACTION_DENY denies the request.

v1/admin.proto

Top

Admin

Admin is the service that provides cluster admin operations. Most methods

require the leader to be contacted.

Method Name	Request Type	Response Type	Description
PutRole	Role	.google.protobuf.Empty	PutRole creates or updates a role.
DeleteRole	Role	.google.protobuf.Empty	DeleteRole deletes a role.
GetRole	Role	Role	GetRole gets a role.
ListRoles	.google.protobuf.Empty	Roles	ListRoles gets all roles.
PutRoleBinding	RoleBinding	.google.protobuf.Empty	PutRoleBinding creates or updates a role binding.
DeleteRoleBinding	RoleBinding	.google.protobuf.Empty	DeleteRoleBinding deletes a role binding.
GetRoleBinding	RoleBinding	RoleBinding	GetRoleBinding gets a role binding.
ListRoleBindings	.google.protobuf.Empty	RoleBindings	ListRoleBindings gets all role bindings.
PutGroup	Group	.google.protobuf.Empty	PutGroup creates or updates a group.
DeleteGroup	Group	.google.protobuf.Empty	DeleteGroup deletes a group.
GetGroup	Group	Group	GetGroup gets a group.
ListGroups	.google.protobuf.Empty	Groups	ListGroups gets all groups.
PutNetworkACL	NetworkACL	.google.protobuf.Empty	PutNetworkACL creates or updates a network ACL.
DeleteNetworkACL	NetworkACL	.google.protobuf.Empty	DeleteNetworkACL deletes a network ACL.
GetNetworkACL	NetworkACL	NetworkACL	GetNetworkACL gets a network ACL.
ListNetworkACLs	.google.protobuf.Empty	NetworkACLs	ListNetworkACLs gets all network ACLs.
PutRoute	Route	.google.protobuf.Empty	PutRoute creates or updates a route.
DeleteRoute	Route	.google.protobuf.Empty	DeleteRoute deletes a route.
GetRoute	Route	Route	GetRoute gets a route.
ListRoutes	.google.protobuf.Empty	Routes	ListRoutes gets all routes.
PutEdge	MeshEdge	.google.protobuf.Empty	PutEdge creates or updates an edge between two nodes.
DeleteEdge	MeshEdge	.google.protobuf.Empty	DeleteEdge deletes an edge between two nodes.
GetEdge	MeshEdge	MeshEdge	GetEdge gets an edge between two nodes.
ListEdges	.google.protobuf.Empty	MeshEdges	ListEdges gets all current edges.

v1/app.proto

Top

ConnectRequest

ConnectRequest is sent by the application to the node to establish a

connection to a mesh. This message will eventually contain unique

identifiers to allow creating connections to multiple meshes.

Field	Type	Label	Description
config	google.protobuf.Struct		Config is used to override any defaults configured on the node.
disable_bootstrap	bool		Disable bootstrap tells a node that is otherwise configured to bootstrap to not bootstrap for this connection.

ConnectResponse

ConnectResponse is returned by the Connect RPC.

Field	Type	Label	Description
node_id	string		node id is the unique identifier of the node.
mesh_domain	string		mesh domain is the domain of the mesh.
ipv4	string		ipv4 is the IPv4 address of the node.
ipv6	string		ipv6 is the IPv6 address of the node.

DisconnectRequest

DisconnectRequest is sent by the application to the node to disconnect

from a mesh. This message will eventually contain unique identifiers

for allowing the application to disconnect from a specific mesh.

DisconnectResponse

DisconnectResponse is returned by the Disconnect RPC.

MetricsRequest

MetricsRequest is sent by the application to the node to retrieve interface

metrics. It is intentionally empty for now, but can eventually be used to

query specific interfaces/metrics.

MetricsResponse

MetricsResponse is a message containing interface metrics.

Field	Type	Label	Description
interfaces	MetricsResponse.InterfacesEntry	repeated	interfaces is a map of interface names to metrics.

MetricsResponse.InterfacesEntry

Field	Type	Label	Description
key	string
value	InterfaceMetrics

StatusRequest

StatusRequest is sent by the application to the node to retrieve the status

of the node.

StatusResponse

StatusResponse is a message containing the status of the node.

Field	Type	Label	Description
connection_status	StatusResponse.ConnectionStatus		connection status is the status of the connection.
node	MeshNode		node is the node status. This is only populated if the node is connected.

StatusResponse.ConnectionStatus

Name	Number	Description
DISCONNECTED	0	DISCONNECTED indicates that the node is not connected to a mesh.
CONNECTING	1	CONNECTING indicates that the node is in the process of connecting to a mesh.
CONNECTED	2	CONNECTED indicates that the node is connected to a mesh.

AppDaemon

AppDaemon is exposed by nodes running in the app-daemon mode. This mode

allows the node to run in an idle state and be controlled by the

application. The application can send commands to the node to execute

tasks and receive responses.

Method Name	Request Type	Response Type	Description
Connect	ConnectRequest	ConnectResponse	Connect is used to establish a connection between the node and a mesh. The provided struct is used to override any defaults configured on the node.
Disconnect	DisconnectRequest	DisconnectResponse	Disconnect is used to disconnect the node from the mesh.
Query	QueryRequest	QueryResponse stream	Query is used to query the mesh for information.
Metrics	MetricsRequest	MetricsResponse	Metrics is used to retrieve interface metrics from the node.
Status	StatusRequest	StatusResponse	Status is used to retrieve the status of the node.
Subscribe	SubscribeRequest	SubscriptionEvent stream	Subscribe is used to subscribe to events in the mesh database.
Publish	PublishRequest	.google.protobuf.Empty	Publish is used to publish events to the mesh database. A restricted set of keys are allowed to be published to.

v1/raft.proto

Top

RaftApplyResponse

RaftApplyResponse is the response to an apply request. It

contains the result of applying the log entry.

Field	Type	Label	Description
time	string		time is the total time it took to apply the log entry.
error	string		error is an error that occurred during the apply.

RaftLogEntry

RaftLogEntry is the data of an entry in the Raft log.

Field	Type	Label	Description
type	RaftCommandType		type is the type of the log entry.
key	string		key is the key of the log entry.
value	string		value is the value of the log entry.
ttl	google.protobuf.Duration		ttl is the time to live of the log entry.

RaftCommandType

RaftCommandType is the type of command being sent to the

Raft log.

Name	Number	Description
UNKNOWN	0	UNKNOWN is the unknown command type.
PUT	1	PUT is the command for putting a key/value pair.
DELETE	2	DELETE is the command for deleting a key/value pair.

v1/members.proto

Top

JoinRequest

JoinRequest is a request to join the cluster.

Field	Type	Label	Description
id	string		id is the ID of the node.
public_key	string		public_key is the public wireguard key of the node to broadcast to peers.
raft_port	int32		raft_port is the Raft listen port of the node.
grpc_port	int32		grpc_port is the gRPC listen port of the node.
meshdns_port	int32		meshdns_port is the port the node wishes to advertise to offer DNS to other peers. a value of 0 indicates the node does not wish to offer DNS. ports are currently assumed to be UDP.
primary_endpoint	string		primary_endpoint is a routable address for the node. If left unset, the node is assumed to be behind a NAT and not directly accessible.
wireguard_endpoints	string	repeated	wireguard_endpoints is a list of WireGuard endpoints for the node.
zone_awareness_id	string		zone_awareness_id is the zone awareness ID of the node.
assign_ipv4	bool		assign_ipv4 is whether an IPv4 address should be assigned to the node.
prefer_raft_ipv6	bool		prefer_raft_ipv6 is whether IPv6 should be preferred over IPv4 for raft communication. This is only used if assign_ipv4 is true.
as_voter	bool		as_voter is whether the node should receive a vote in elections. The request will be denied if the node is not allowed to vote.
as_observer	bool		as_observer is whether the node should be added as an observer. They will receive updates to the raft log, but not be able to vote in elections.
routes	string	repeated	routes is a list of routes to advertise to peers. The request will be denied if the node is not allowed to put routes.
direct_peers	string	repeated	direct_peers is a list of extra peers that should be connected to directly over ICE. The request will be denied if the node is not allowed to put data channels or edges. The default joining behavior creates non-ICE links between the caller and the joiner. If the caller has a primary endpoint, the joiner will link the caller to all other nodes with a primary endpoint. If the caller has a zone awareness ID, the joiner will link the caller to all other nodes with the same zone awareness ID that also have a primary endpoint.
features	Feature	repeated	features is a list of features supported by the node that should be advertised to peers.

JoinResponse

JoinResponse is a response to a join request.

Field	Type	Label	Description
address_ipv4	string		address_ipv4 is the private IPv4 wireguard address of the node in CIDR format representing the network. This is only set if assign_ipv4 was set in the request or no network_ipv6 was provided. The bits are set to the network bits of the Mesh IPv4 network.
address_ipv6	string		address_ipv6 is the IPv6 network assigned to the node.
network_ipv4	string		network_ipv4 is the IPv4 network of the Mesh.
network_ipv6	string		network_ipv6 is the IPv6 network of the Mesh.
peers	WireGuardPeer	repeated	peers is a list of wireguard peers to connect to.
ice_servers	string	repeated	ice_servers is a list of public nodes that can be used to negotiate ICE connections if required. This may only be populated when one of the peers has the ICE flag set. This must be set if the requestor specifies direct_peers.
dns_servers	string	repeated	dns_servers is a list of peers offering DNS services.
mesh_domain	string		mesh_domain is the domain of the mesh.

LeaveRequest

LeaveRequest is a request to leave the cluster.

Field	Type	Label	Description
id	string		id is the ID of the node.

LeaveResponse

LeaveResponse is a response to a leave request. It is currently empty.

RaftConfigurationRequest

RaftConfigurationRequest is a request to get the current Raft configuration.

RaftConfigurationResponse

RaftConfigurationResponse is a response to a Raft configuration request.

Field	Type	Label	Description
servers	RaftServer	repeated	servers is the list of servers in the Raft configuration.

RaftServer

RaftServer is a server in the Raft configuration.

Field	Type	Label	Description
id	string		ID is the ID of the server.
suffrage	ClusterStatus		Suffrage is the suffrage of the server.
address	string		Address is the mesh address of the server.

UpdateRequest

UpdateRequest contains most of the same fields as JoinRequest, but is

used to update the state of a node in the cluster.

Field	Type	Label	Description
id	string		id is the ID of the node.
public_key	string		public_key is the public wireguard key of the node to broadcast to peers.
raft_port	int32		raft_port is the Raft listen port of the node.
grpc_port	int32		grpc_port is the gRPC listen port of the node.
meshdns_port	int32		meshdns_port is the port the node wishes to advertise to offer DNS to other peers. a value of 0 indicates the node does not wish to offer DNS. ports are currently assumed to be UDP.
primary_endpoint	string		primary_endpoint is a routable address for the node. If left unset, the node is assumed to be behind a NAT and not directly accessible.
wireguard_endpoints	string	repeated	wireguard_endpoints is a list of WireGuard endpoints for the node.
zone_awareness_id	string		zone_awareness_id is the zone awareness ID of the node.
as_voter	bool		as_voter is whether the node should receive a vote in elections. The request will be denied if the node is not allowed to vote.
routes	string	repeated	routes is a list of routes to advertise to peers. The request will be denied if the node is not allowed to put routes.
features	Feature	repeated	features is a list of features supported by the node that should be advertised to peers.

UpdateResponse

UpdateResponse is a response to an update request. It is currently empty.

WireGuardPeer

WireGuardPeer is a peer in the Wireguard network.

Field	Type	Label	Description
id	string		id is the ID of the peer.
public_key	string		public_key is the public key of the peer.
primary_endpoint	string		primary_endpoint is the primary endpoint of the peer.
wireguard_endpoints	string	repeated	wireguard_endpoints are the WireGuard endpoints for the peer, if applicable.
zone_awareness_id	string		zone_awareness_id is the zone awareness ID of the peer.
address_ipv4	string		address_ipv4 is the private IPv4 wireguard address of the peer.
address_ipv6	string		address_ipv6 is the private IPv6 wireguard address of the peer.
allowed_ips	string	repeated	allowed_ips is the list of allowed IPs for the peer.
allowed_routes	string	repeated	allowed_routes is the list of allowed routes for the peer.
ice	bool		ice indicates whether the connection to this peer should be established over ICE.
grpc_port	int32		grpc_port is the gRPC port of the peer.
raft_member	bool		raft_member indicates that this peer is able to serve raft requests.

Membership

The membership service is exposed on raft-nodes to allow nodes to join

and leave the cluster. This service is meant to be made available publicly

to allow people in from the outside.

Method Name	Request Type	Response Type	Description
Join	JoinRequest	JoinResponse	Join is used to join a node to the mesh.
Update	UpdateRequest	UpdateResponse	Update is used by a node to update its state in the mesh. The node will be updated in the mesh and will be able to query the mesh state or vote in elections. Only non-empty fields will be updated. It is almost semantically equivalent to a join request with the same ID, but redefined to avoid confusion and to allow for expansion.
Leave	LeaveRequest	LeaveResponse	Leave is used to remove a node from the mesh. The node will be removed from the mesh and will no longer be able to query the mesh state or vote in elections.
Apply	RaftLogEntry	RaftApplyResponse	Apply is used by voting nodes to request a log entry be applied to the state machine. This is only available on the leader, and can only be called by nodes that are allowed to vote.
GetRaftConfiguration	RaftConfigurationRequest	RaftConfigurationResponse	GetRaftConfiguration returns the current Raft configuration.

v1/peer_discovery.proto

Top

ListRaftPeersResponse

ListRaftPeersResponse is the response to ListPeers.

Field	Type	Label	Description
peers	RaftPeer	repeated	Peers is the list of peers.

RaftPeer

RaftPeer is a peer in the Raft cluster.

Field	Type	Label	Description
id	string		ID is the ID of the peer.
address	string		Address is the public gRPC address of the peer.
voter	bool		Voter is whether the peer is a voter.
leader	bool		Leader is whether the peer is the leader.

PeerDiscovery

PeerDiscovery is the service that provides peer discovery. This is a service

that can optionally be exposed by nodes in the mesh to provide peer discovery

to other nodes. Alternative methods of peer discovery can be used, such as

static files or DNS, but running one or more publicly accessible nodes with this

service registered is the simplest method.

It only makes sense to expose this service on a public address on a member of the

Raft cluster. It is not necessary to expose this service on every node in the mesh.

Method Name	Request Type	Response Type	Description
ListPeers	.google.protobuf.Empty	ListRaftPeersResponse	ListPeers returns a list of public peers currently known to the mesh.

v1/plugin.proto

Top

AllocateIPRequest

AllocateIPRequest is the message containing an IP allocation request.

Field	Type	Label	Description
node_id	string		node_id is the node that the IP should be allocated for.
subnet	string		subnet is the subnet that the IP should be allocated from.
version	AllocateIPRequest.IPVersion		version is the IP version that should be allocated.

AllocatedIP

AllocatedIP is the message containing an allocated IP.

Field	Type	Label	Description
ip	string		ip is the allocated IP. It should be returned in CIDR notation.

AuthenticationRequest

AuthenticationRequest is the message containing an authentication request.

Field	Type	Label	Description
headers	AuthenticationRequest.HeadersEntry	repeated	headers are the headers of the request.
certificates	bytes	repeated	certificates are the DER encoded certificates of the request.

AuthenticationRequest.HeadersEntry

Field	Type	Label	Description
key	string
value	string

AuthenticationResponse

AuthenticationResponse is the message containing an authentication response.

Field	Type	Label	Description
id	string		id is the id of the authenticated user.

DataSnapshot

DataSnapshot is the message containing a snapshot of the data.

Field	Type	Label	Description
term	uint64		term is the term of the log entry.
index	uint64		index is the index of the log entry.
data	bytes		data is the snapshot of the data.

Event

Event is the message containing a watch event.

Field	Type	Label	Description
type	WatchEvent		type is the type of the watch event.
node	MeshNode		node is the node that the event is about.

PluginConfiguration

PluginConfiguration is the message containing the configuration of a plugin.

Field	Type	Label	Description
config	google.protobuf.Struct		Config is the configuration of the plugin.

PluginInfo

PluginInfo is the information of a plugin.

Field	Type	Label	Description
name	string		Name is the name of the plugin.
version	string		Version is the version of the plugin.
description	string		Description is the description of the plugin.
capabilities	PluginCapability	repeated	Capabilities is the capabilities of the plugin.

PluginQuery

PluginQuery is the message containing a storage query. It contains

a request ID that is used to correlate the query with the result.

Field	Type	Label	Description
id	string		id is the ID of the query.
command	PluginQuery.QueryCommand		command is the command of the query.
query	string		query is the key or prefix of the query.

PluginQueryResult

PluginQueryResult is the message containing a storage query result. It contains

a request ID that is used to correlate the query with the result.

Field	Type	Label	Description
id	string		id is the ID of the query.
key	string		key is the key of the query. For GET and ITER queries it will be the current key. For LIST queries it will be the prefix.
value	string	repeated	value is the value of the query. For GET and ITER queries it will be the value of the current key. For LIST queries it will be the list of keys that match the prefix.
error	string		error is an error that occurred during the query. At the end of an ITER query it will be set to "EOF" to indicate that the iteration is complete.

ReleaseIPRequest

ReleaseIPRequest is the message containing an IP release request.

Field	Type	Label	Description
node_id	string		node_id is the node that the IP should be released for.
ip	string		ip is the IP that should be released.

StoreLogRequest

StoreLogRequest is the message containing a raft log entry.

Field	Type	Label	Description
term	uint64		term is the term of the log entry.
index	uint64		index is the index of the log entry.
log	RaftLogEntry		log is the log entry.

AllocateIPRequest.IPVersion

Name	Number	Description
IP_VERSION_UNKNOWN	0	IP_VERSION_UNKNOWN is the default value of IPVersion.
IP_VERSION_4	4	IP_VERSION_4 indicates that an IPv4 address should be allocated.
IP_VERSION_6	6	IP_VERSION_6 indicates that an IPv6 address should be allocated.

PluginCapability

PluginCapability is the capabilities of a plugin.

Name	Number	Description
PLUGIN_CAPABILITY_UNKNOWN	0	PLUGIN_CAPABILITY_UNKNOWN is the default value of PluginCapability.
PLUGIN_CAPABILITY_STORE	1	PLUGIN_CAPABILITY_STORE indicates that the plugin is a raft store plugin.
PLUGIN_CAPABILITY_AUTH	2	PLUGIN_CAPABILITY_AUTH indicates that the plugin is an auth plugin.
PLUGIN_CAPABILITY_WATCH	3	PLUGIN_CAPABILITY_WATCH indicates that the plugin wants to receive watch events.
PLUGIN_CAPABILITY_IPAMV4	4	PLUGIN_CAPABILITY_IPAMV4 indicates that the plugin is an IPv4 IPAM plugin.
PLUGIN_CAPABILITY_IPAMV6	5	PLUGIN_CAPABILITY_IPAMV6 indicates that the plugin is an IPv6 IPAM plugin.

PluginQuery.QueryCommand

QueryCommand is the type of the query.

Name	Number	Description
UNKNOWN	0	UNKNOWN is the default value of QueryCommand.
GET	1	GET is the command to get a value.
LIST	2	LIST is the command to list keys with an optional prefix.
ITER	3	ITER is the command to iterate over keys with an optional prefix.

WatchEvent

WatchEvent is the type of a watch event.

Name	Number	Description
WATCH_EVENT_UNKNOWN	0	WATCH_EVENT_UNKNOWN is the default value of WatchEvent.
WATCH_EVENT_NODE_JOIN	1	WATCH_EVENT_NODE_JOIN indicates that a node has joined the cluster.
WATCH_EVENT_NODE_LEAVE	2	WATCH_EVENT_NODE_LEAVE indicates that a node has left the cluster.
WATCH_EVENT_LEADER_CHANGE	3	WATCH_EVENT_LEADER_CHANGE indicates that the leader of the cluster has changed.

AuthPlugin

AuthPlugin is the service definition for a Webmesh auth plugin.

Method Name	Request Type	Response Type	Description
Authenticate	AuthenticationRequest	AuthenticationResponse	Authenticate authenticates a request.

IPAMPlugin

IPAMPlugin is the service definition for a Webmesh IPAM plugin.

Method Name	Request Type	Response Type	Description
Allocate	AllocateIPRequest	AllocatedIP	Allocate allocates an IP for a node.
Release	ReleaseIPRequest	.google.protobuf.Empty	Release releases an IP for a node.

Plugin

Plugin is the general service definition for a Webmesh plugin.

It must be implemented by all plugins.

Method Name	Request Type	Response Type	Description
GetInfo	.google.protobuf.Empty	PluginInfo	GetInfo returns the information for the plugin.
Configure	PluginConfiguration	.google.protobuf.Empty	Configure configures the plugin.
InjectQuerier	PluginQueryResult stream	PluginQuery stream	InjectQuerier is a stream opened by the node to faciliate read-only queries against the mesh state. The signature is misleading, but it is required to be able to stream the query results back to the node. The node will open a stream to the plugin and send a PluginSQLQueryResult message for every query that is received. The plugin can return an Unimplemented error or simply close the stream with no error it it does not wish to keep the stream open.
Close	.google.protobuf.Empty	.google.protobuf.Empty	Close closes the plugin. It is called when the node is shutting down.

StoragePlugin

StoragePlugin is the service definition for a Webmesh storage plugin.

Method Name	Request Type	Response Type	Description
Store	StoreLogRequest	RaftApplyResponse	Store dispatches a Raft log entry for storage.
RestoreSnapshot	DataSnapshot	.google.protobuf.Empty	RestoreSnapshot should drop any existing state and restore from the snapshot.

WatchPlugin

WatchPlugin is the service definition for a Webmesh watch plugin.

Method Name	Request Type	Response Type	Description
Emit	Event	.google.protobuf.Empty	Emit handles a watch event.

v1/webrtc.proto

Top

DataChannelOffer

DataChannelOffer is an offer for a data channel. Candidates

are sent after the offer is sent.

Field	Type	Label	Description
offer	string		offer is the offer.
stun_servers	string	repeated	stun_servers is the list of STUN servers to use.
candidate	string		candidate is an ICE candidate.

StartDataChannelRequest

StartDataChannelRequest is a request to start a data channel.

The answer and candidate fields are populated after the offer

is received.

Field	Type	Label	Description
node_id	string		node_id is the ID of the node to send the data to.
proto	string		proto is the protocol of the traffic.
dst	string		dst is the destination address of the traffic.
port	uint32		port is the destination port of the traffic. A port of 0 coupled with the udp protocol indicates forwarding to the WireGuard interface.
answer	string		answer is the answer to the offer.
candidate	string		candidate is an ICE candidate.

WebRTC

WebRTC is a service for negotiating WebRTC connections to nodes in the mesh.

It is typically run alongside a TURN server, however the server can be configured

to use public STUN servers instead.

Method Name	Request Type	Response Type	Description
StartDataChannel	StartDataChannelRequest stream	DataChannelOffer stream	StartDataChannel requests a new WebRTC connection to a node. The client speaks first with the request containing the node ID and where forwarded packets should be sent. The server responds with an offer and STUN servers to be used to establish a WebRTC connection. The client should then respond with an answer to the offer that matches the spec of the DataChannel.CHANNELS enum value. After the offer is accepted, the stream can be used to exchange ICE candidates to speed up the connection process.

Scalar Value Types

.proto Type	Notes	C++	Java	Python	Go	C#	PHP	Ruby
double		double	double	float	float64	double	float	Float
float		float	float	float	float32	float	float	Float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long	int64	long	integer/string	Bignum
uint32	Uses variable-length encoding.	uint32	int	int/long	uint32	uint	integer	Bignum or Fixnum (as required)
uint64	Uses variable-length encoding.	uint64	long	int/long	uint64	ulong	integer/string	Bignum or Fixnum (as required)
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long	int64	long	integer/string	Bignum
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int	uint32	uint	integer	Bignum or Fixnum (as required)
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long	uint64	ulong	integer/string	Bignum
sfixed32	Always four bytes.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sfixed64	Always eight bytes.	int64	long	int/long	int64	long	integer/string	Bignum
bool		bool	boolean	boolean	bool	bool	boolean	TrueClass/FalseClass
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode	string	string	string	String (UTF-8)
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str	[]byte	ByteString	string	String (ASCII-8BIT)