| // Copyright 2019 The Chromium OS Authors. All rights reserved. |
| // 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; |
| |
| // 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 assigned IPv4 address in network order. |
| uint32 ipv4_addr = 2; |
| |
| // The subnet allocated for this device |
| IPv4Subnet ipv4_subnet = 3; |
| |
| // The guest to which the device is bound, if applicable. |
| GuestType guest_type = 4; |
| } |
| |
| // 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. |
| 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. |
| 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; |
| } |
| |
| // 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; |
| } |
| |
| // 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; |
| |
| Source source = 5; |
| // The shill device (interface) name (e.g., eth0) where the traffic leaves |
| // from or comes in. |
| string device = 6; |
| } |
| |
| // 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. |
| 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. |
| uint32 dst_port = 8; |
| } |
| |
| // Response to a ModifyPortRuleRequest. |
| message ModifyPortRuleResponse { |
| bool success = 1; |
| } |
| |
| // 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. 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. After this event, no |
| // more FAILED events will be generated for this neighbor until a RECOVERED |
| // event happens. |
| FAILED = 1; |
| // Indicates this neighbor has recovered from the previous failure: the |
| // layer 2 bidirectional reachability has been confirmed for a while. Note |
| // that a new neighbor is considered as "reachable" so this event will not |
| // be generated when we start to monitor a new neighbor. |
| RECOVERED = 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; |
| } |