blob: d13d9d53aab8d8cc2b7af1c17ea986d15526e82a [file] [log] [blame]
// Copyright 2019 The ChromiumOS Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
syntax = "proto3";
option optimize_for = LITE_RUNTIME;
// This file defines the messages used by the patchpanel D-Bus API. It is
// strongly recommended to not use the patchpanel D-Bus API directly and to
// instead use the thin client defined at platform2/patchpanel/client.h that
// provides additional functionalities and abstracts the details of the wire
// format. Access control for clients is defined in platform2/patchpanel/dbus.
package patchpanel;
option go_package = "chromiumos/system_api/patchpanel_proto";
// Notification that the ARC++ container is starting up.
// This is informational. The ARC boot and setup sequences do not require
// any information or permission from networking to continue.
message ArcStartupRequest {
// The PID of the ARC++ container.
// Required.
int32 pid = 1;
}
// This is an intentionally empty mesage. ARC++ startup does not require
// any information from networking to proceed.
message ArcStartupResponse {}
// Notification that the ARC++ container is shutting down.
message ArcShutdownRequest {
// The PID of the ARC++ container; must match the PID that was sent at
// startup.
// Required.
int32 pid = 1;
}
// This is an intentionally empty message. ARC++ startup does not require
// any information from networking to proceed.
message ArcShutdownResponse {}
// Notification that the ARC VM is starting up.
// Unlike in the container case, Concierge needs to know which TAP devices
// it can use.
message ArcVmStartupRequest {
// The content ID of the VM.
uint32 cid = 1;
}
// Represents an IPv4 subnet given a base address and prefix length.
message IPv4Subnet {
// The base address in network order.
uint32 base_addr = 1;
// The prefix length of the subnet.
uint32 prefix_len = 2;
}
// Represents a network device (physical or virtual) managed by the networking
// daemon.
message NetworkDevice {
// Identifies the guest for which the virtual device is used.
enum GuestType {
UNKNOWN = 0;
ARC = 1;
ARCVM = 2;
TERMINA_VM = 3;
PLUGIN_VM = 4;
};
// The name of the host device interface.
string ifname = 1;
// The name of the physical interface to which the virtual device is mapped.
// Only valid for virtual devices and will be empty for those tracking default
// logical or physical networks.
string phys_ifname = 5;
// The name of the interface inside the guest.
string guest_ifname = 7;
// The IPv4 address assigned to the guest, in network order.
uint32 ipv4_addr = 2;
// The IPv4 address assigned to the host device interface, in network order.
// This corresponds to the next hop IPv4 address for the guest and should be
// used for the default IPv4 route of the guest.
uint32 host_ipv4_addr = 6;
// The IPv4 subnet allocated for this device.
IPv4Subnet ipv4_subnet = 3;
// The guest to which the device is bound, if applicable.
GuestType guest_type = 4;
// The IPv4 and IPv6 addresses of the DNS proxy instance tied to the guest
// device, if applicable. The addresses are represented in network order as a
// byte array of size 4 and 16 respectively for IPv4 and IPv6.
bytes dns_proxy_ipv4_addr = 8;
bytes dns_proxy_ipv6_addr = 9;
}
// Request to obtain the list of virtual network devices that patchpanel
// manages for guest OSes. This does not include physical or virtual (e.g. VPN)
// devices managed by shill or virtual devices in connected namespaces.
message GetDevicesRequest {}
message GetDevicesResponse {
// The list of devices under patchpanel's management/control.
repeated NetworkDevice devices = 1;
}
// Information required by Concierge to continue the ARC VM startup process.
message ArcVmStartupResponse {
// The list of TAP devices to be used in the VM.
repeated NetworkDevice devices = 1;
}
// Notification that the ARC VM is shutting down.
// This message should also be sent if the startup process fails so any
// allocated resources are properly freed.
message ArcVmShutdownRequest {
// The CID of the ARC VM; must match the CID that was sent at
// startup.
// Required.
uint32 cid = 1;
}
// Intentionally empty response.
message ArcVmShutdownResponse {}
// Notification that a Termina VM is starting up.
message TerminaVmStartupRequest {
// The content ID of the VM.
uint32 cid = 1;
}
// Information required by Concierge to continue the Termina VM startup.
message TerminaVmStartupResponse {
// The TAP device to be used for the VM.
NetworkDevice device = 1;
// The container subnet to be used for the lxd bridge.
IPv4Subnet container_subnet = 2;
};
// Notification that the Termina VM is shutting down.
// This message must also be sent if the startup process fails so any
// allocated resources, including the subnets, are properly freed.
message TerminaVmShutdownRequest {
// The CID of the Termina VM; must match the PID that was sent at
// startup.
// Required.
uint32 cid = 1;
}
// Intentionally empty response.
message TerminaVmShutdownResponse {}
// Notification that a Plugin VM is starting up.
message PluginVmStartupRequest {
// The unique ID of the VM.
uint64 id = 1;
// The 1-based index of the desired subnet to allocate for use.
// Optional.
// TODO(b/236092161) Migrate to uint32.
int32 subnet_index = 2;
}
// Information required by Concierge to continue the Plugin VM startup.
message PluginVmStartupResponse {
// The TAP device to be used for the VM.
NetworkDevice device = 1;
};
// Notification that the Plugin VM is shutting down.
// This message must also be sent if the startup process fails so any
// allocated resources, including the subnets, are properly freed.
message PluginVmShutdownRequest {
// The unique ID of the Plugin VM; must match what was sent at startup.
// Required.
uint64 id = 1;
}
// Intentionally empty response.
message PluginVmShutdownResponse {}
// Request to set the VPN routing policy for a socket. The socket file
// descriptor must be immediately appended to the DBUS message after the
// serialized SetVpnIntentRequest message. The request must be sent before
// the socket is connected.
message SetVpnIntentRequest {
// Possible policies for VPN routing available to system processes.
// The enum values defined here are not meaningful with respect to the actual
// bits used inside the socket fwmark for encoding the VPN routing intent.
enum VpnRoutingPolicy {
// Let the routing layer apply the default policy for that process uid.
// This is the default policy for newly created sockets. It is in general
// incorrect to use this policy for the purpose of clearing any other VPN
// policy after the socket became connected. Instead a new socket should
// be made.
DEFAULT_ROUTING = 0;
// The socket traffic is always routed through the VPN if there is one.
ROUTE_ON_VPN = 1;
// The socket traffic is always routed through the physical network.
BYPASS_VPN = 2;
}
VpnRoutingPolicy policy = 1;
}
// Response to a SetVpnIntentRequest.
message SetVpnIntentResponse {
bool success = 1;
}
// Request for connecting and routing a network namespace. The client must
// append a valid file descriptor immediately after the serialized
// ConnectNamespaceRequest proto. This file descriptor must remain valid for as
// long as the client namespace needs to remain connected. Invalidating the file
// descriptor explicitly by closing it or implicitly when the client exits will
// trigger the teardown of the routing setup, the veth setup, and the release
// of the IPv4 subnet assigned to the namespace.
message ConnectNamespaceRequest {
// The pid of the client network namespace. If set to -1, a new network
// namespace which is not associated with any process will be created.
int32 pid = 1;
// If the client sets this field to the name of a physical network device
// managed by shill, the namespace egress traffic routed outside the device
// will be routed using the routing table specific to that physical device.
// If left empty, the namespace will be routed through the system highest
// priority interface (physical or virtual).
string outbound_physical_device = 2;
// If true, traffic originated from managed OSs (Crostini, ARC, PluginVMs) and
// from Chrome can be routed to this namespace, and traffic originated from
// this namespace can be routed to these other privilege domains.
bool allow_user_traffic = 3;
// This field specifies the routing behavior to use when (1)
// |outbound_physical_device| is empty and (2) the system's highest priority
// network interface is a VPN. If true, egress traffic will be routed to the
// VPN; if false, it will be left on the underlying physical interface.
bool route_on_vpn = 4;
// Specifies how the traffic flowing over the new virtual network should be
// accounted, if applicable.
// This field is required. The default behavior will be to treat unspecified
// and UNKNOWN sources as SYSTEM traffic for accounting purposes.
TrafficCounter.Source traffic_source = 5;
}
// Response to a ConnectNamespaceRequest. If the operation failed then all
// fields are left set to their default value (empty string or 0).
message ConnectNamespaceResponse {
// The subnet allocated to the client namespace.
IPv4Subnet ipv4_subnet = 1;
// Name of the veth interface created in the client namespace.
string peer_ifname = 2;
// The IPv4 address in network order assigned to the interface inside the
// client namespace.
uint32 peer_ipv4_address = 3;
// Name of the veth interface created in the host namespace.
string host_ifname = 4;
// The IPv4 address in network order assigned to the interface in the host
// namespace.
uint32 host_ipv4_address = 5;
// Name of the netns attached or created.
string netns_name = 6;
}
// Represents the traffic usage ({tx, rx} x {packets, bytes}) between a source
// and a shill device (interface), since the system (CrOS) is booted up. A
// counter will keep growing until the system (CrOS) shuts down.
// Used in TrafficCountersResponse.
message TrafficCounter {
// Possible traffic sources.
enum Source {
UNKNOWN = 0;
// Traffic associated with user chronos.
CHROME = 1;
// Traffic associated with user debugd, cups, and tlsdate, i.e., other user
// traffic except for that for user chronos.
USER = 2;
ARC = 3;
CROSVM = 4;
PLUGINVM = 5;
UPDATE_ENGINE = 6;
// As a source, VPN means traffic initiated by the VPN app/program and going
// to the underlying physical network (or from physical network to the VPN
// app/program).
VPN = 7;
// All other traffic.
SYSTEM = 8;
}
// Possible IP address family numbers.
enum IpFamily {
NONE = 0;
IPV4 = 1;
IPV6 = 2;
}
// Counter values need to be 64bits as 32bits is not enough to account for
// more than ~4GB of traffic.
uint64 rx_bytes = 1;
uint64 tx_bytes = 2;
uint64 rx_packets = 3;
uint64 tx_packets = 4;
// The source that originated the traffic.
Source source = 5;
// The shill device (interface) name (e.g., eth0) where the traffic leaves
// from or comes in.
string device = 6;
// The IP family of the traffic.
IpFamily ip_family = 7;
}
// Requests the traffic counters kept by patchpanel. |devices| is the set of
// interfaces for which counters should be returned, any unknown interfaces will
// be ignored. If |devices| is empty, counters for all known interfaces will be
// returned. Note that if an interface once appeared but does not exist now,
// counters for it will also be returned.
message TrafficCountersRequest {
repeated string devices = 1;
}
// Response to a TrafficCountersRequest.
message TrafficCountersResponse {
repeated TrafficCounter counters = 1;
}
// Request for opening and closing firewall port. If the request is valid,
// PatchPanel will run iptables commands following the request.
message ModifyPortRuleRequest {
enum Operation {
INVALID_OPERATION = 0;
CREATE = 1;
DELETE = 2;
}
enum RuleType {
INVALID_RULE_TYPE = 0;
ACCESS = 1; // Equivalent of iptables 'ACCEPT'
LOCKDOWN = 2; // Equivalent of iptables 'DROP'
FORWARDING = 3; // Equivalent of iptables 'DNAT'
}
enum Protocol {
INVALID_PROTOCOL = 0;
TCP = 1;
UDP = 2;
}
// Arguments specifying the type of operation, rule and protocol.
Operation op = 1;
RuleType type = 2;
Protocol proto = 3;
// A network interface name, or empty if unspecified. This is optional for
// ACCESS and FORWARDING, and is ignored for other rule types.
string input_ifname = 4;
// An IPv4 address, or empty if unspecified. This is optional for FORWARDING,
// and is ignored for other rule types.
string input_dst_ip = 5;
// A port value in-between 1 and 65535. This is required for all rule types.
// TODO(b/236092161) Migrate to uint16.
uint32 input_dst_port = 6;
// An IPv4 address, or empty if unspecified. This is required for FORWARDING,
// and is ignored for other rule types.
string dst_ip = 7;
// A port value between 1 and 65535. This is required for FORWARDING, and is
// ignored for other rule types.
// TODO(b/236092161) Migrate to uint16.
uint32 dst_port = 8;
}
// Response to a ModifyPortRuleRequest.
message ModifyPortRuleResponse {
bool success = 1;
}
// Request to start or stop VPN lockdown. When VPN lockdown is enabled and no
// VPN connection exists, any non-ARC traffic that would be routed to a VPN
// connection is instead rejected. ARC traffic is ignored because Android
// already implements VPN lockdown.
message SetVpnLockdownRequest {
// true: start VPN lockdown. false: stop VPN lockdown.
bool enable_vpn_lockdown = 1;
}
// Intentionally empty response to a SetVpnIntentRequest.
message SetVpnLockdownResponse {}
// Signal that is emitted when a device managed by patchpanel is added or
// removed.
message NetworkDeviceChangedSignal {
enum Event {
UNKNOWN_CHANGE = 0;
DEVICE_ADDED = 1;
DEVICE_REMOVED = 2;
};
NetworkDevice device = 1;
Event event = 2;
}
// Signal for notifying an event about the layer 2 reachability of a neighbor
// monitored by NeighborLinkMonitor.
message NeighborReachabilityEventSignal {
// Possible roles of a neighbor in the corresponding ipconfig.
enum Role {
INVALID_ROLE = 0;
GATEWAY = 1;
DNS_SERVER = 2;
GATEWAY_AND_DNS_SERVER = 3;
};
// Possible event types. Two consecutive events for the same neighbor should
// have different types. Also see the class comment of NeighborLinkMonitor
// for more details about how these events are generated.
enum EventType {
INVALID_EVENT_TYPE = 0;
// Indicates a failure is detected for this neighbor. Note that the neighbor
// may still be unreachable even if this signal is not sent out. For
// example, sometimes we may lose track of a neighbor from the kernel. We
// will not send out a FAILED signal when that happens, since that does not
// always mean a link failure.
FAILED = 1;
// Indicates the bidirectional reachability has just been confirmed.
REACHABLE = 2;
};
// The interface index of the device that connects to this neighbor.
int32 ifindex = 1;
// Neighbor properties.
string ip_addr = 2;
Role role = 3;
EventType type = 4;
}
// Request to start DNS traffic redirection when DNS proxy is running. The rules
// created depend on the type requested. The client must append a valid file
// descriptor immediately after the serialized SetDnsRedirectionRuleRequest
// proto. This file descriptor must remain valid for as long as the DNS traffic
// need to be redirected. Invalidating the file descriptor explicitly by closing
// it or implicitly when the client exits will trigger the teardown of the
// redirection rules.
message SetDnsRedirectionRuleRequest {
enum RuleType {
INVALID_RULE_TYPE = 0;
// Rules for traffic from guests that track the default network (e.g.
// Crostini, PluginVMs).
DEFAULT = 1;
// Rules for traffic from ARC interfaces (e.g. arc_eth0, arc_wlan0).
ARC = 2;
// Rule for traffic associated with user traffic (e.g. chronos, cups).
USER = 3;
// Rules to exclude traffic that is not using the underlying network's
// name server. This is only used for user traffic.
EXCLUDE_DESTINATION = 4;
}
RuleType type = 1;
// Identifies from which network interface the traffic originates.
// This field is required for ARC and DEFAULT type.
string input_ifname = 2;
// The IP address of the proxy. This field is required for ARC and
// USER type.
string proxy_address = 3;
// Nameservers are only necessary for Chrome redirect (USER type).
repeated string nameservers = 4;
// Name of the "local" veth interface visible in the host namespace.
string host_ifname = 5;
}
// Response to a SetDnsRedirectionRuleRequest.
message SetDnsRedirectionRuleResponse {
bool success = 1;
}
// Signal that is emitted when a network configuration change happens.
message NetworkConfigurationChangedSignal {}