From 38e50a5b4f700524979dca8c21a6a395b6b56485 Mon Sep 17 00:00:00 2001 From: Martin Stein Date: Wed, 4 Apr 2018 12:30:09 +0200 Subject: [PATCH] nic_router/README: adapt to new ICMP features --- repos/os/src/server/nic_router/README | 153 +++++++++++++++++++------- 1 file changed, 115 insertions(+), 38 deletions(-) diff --git a/repos/os/src/server/nic_router/README b/repos/os/src/server/nic_router/README index 4f937fc42..8d0c874cc 100644 --- a/repos/os/src/server/nic_router/README +++ b/repos/os/src/server/nic_router/README @@ -7,11 +7,22 @@ Brief ##### -The 'nic_router' component can be used to individually route IPv4 packets -between multiple NIC sessions. Thereby, it can translate between different -subnets. The component supports IP routing, TCP and UDP routing, the -partitioning of the TCP and UDP port spaces, port forwarding, NAT, and can -also act as DHCP server and as DHCP client. +The 'nic_router' component can be used to achieve a controlled mediation +between multiple NIC sessions on network or transport level. NIC sessions are +assigned to domains. The rules configured by the user then mediate between +these domains. This is a brief overview of the features thereby provided: + +* Acting as hub between NIC session with the same domain, +* routing of UDP and TCP according to destination IP address and port, +* routing of ICMP and IPv4 according to destination IP address, +* port forwarding for UDP and TCP, +* NAPT for UDP, TCP and ICMP "Echo", +* forwarding of ICMP "Destination Unreachable" according to the UDP, TCP or + ICMP "Echo" connection it refers to, +* acting as DHCP server or client per domain, +* provide per-domain network statistics via a report session, +* print out header information for each packet received or sent, +* and be fully re-configurable at runtime. Basics @@ -24,7 +35,7 @@ server. Inside the component, uplink and downlinks are treated the same. Its routing algorithm is ultimately controlled through the configuration. NIC sessions are assigned to domains. Each domain represents one subnet and a corresponding routing configuration. Currently, each domain can contain -only one NIC session at a time. The assigment of sessions to domains is +only one NIC session at a time. The assignment of sessions to domains is controlled through the the common Genode session-policy tag: ! @@ -87,6 +98,9 @@ meaning: --------------------------------------------------------------- | Routing IP packets that target | IP range X +--------------------------------------------------------------- + | Routing ICMP packets that target + | IP range X A detailed explanation of the different routing rules is given in the following sections of this document. For all rules marked with a star, the @@ -98,15 +112,36 @@ additional back-routing rule for that. Now having this variety of ways of routing a packet, it is absolutely legal that for one packet the domain may contain multiple rules that are applicable. And additionally, there may even be a link state that fits. The router's -choice, however, is always deterministic. It follows a simple priority scheme: +choice, however, is always deterministic. It follows this priority scheme: -1) Link states -2) Port forwarding rules -3) Longest prefix match amongst TCP respectively UDP rules - 3.1) Subrule that permits any port - 3.2) Subrules that permit specific ports +:For TCP and UDP: + +1) Domain-local IP traffic +2) Link states +3) Port forwarding rules +4) Longest prefix match amongst TCP respectively UDP rules + 4.1) Subrule that permits any port + 4.2) Subrules that permit specific ports +5) Longest prefix match amongst IP rules + +:For ICMP "Echo": + +1) Domain-local IP traffic +2) Link states +3) Longest prefix match amongst ICMP rules 4) Longest prefix match amongst IP rules +:For ICMP "Destination Unreachable" with embedded UDP, TCP or ICMP "Echo": + +1) Domain-local IP traffic +2) Link states +3) Longest prefix match amongst IP rules + +:For IP with unsupported transport-layer protocol: + +1) Domain-local IP traffic +2) Longest prefix match amongst IP rules + IP rules ######## @@ -132,6 +167,35 @@ to unexpected leakage of local IP addresses and ports, you should use the combination of IP rules and NAT only with great care. +ICMP rules +########## + +These are examples for ICMP rules: + +! +! +! + +ICMP rules only apply to ICMP "Echo" packets from sessions of the surrounding +domain. The 'dst' attribute is compared with the IP destination of the packet. +The rule with the longest prefix match is taken. The packet is then routed to +the domain given in the rule. + +For bidirectional traffic, you'll need only one ICMP rule describing the +client-to-server direction. The server-sided domain doesn't need a rule as the +router correlates replies to the client-sided rule (and only those) via a link +state (Section [Link states]) that was created at the clients initial request. + +ICMP rules consider whether the router shall apply NAT (Section [Configuring +NAT]) for the client side. If this is the case, source IP and ICMP query ID +are replaced by the router's IP identity and a free ICMP query ID at the +server-sided domain. Also the corresponding link state takes this in account +to change back the destination of the replies. + +The router also forwards ICMP errors. This is described in section +[Link states]. + + TCP and UDP rules ################# @@ -199,16 +263,16 @@ and port are translated. Link states ########### -Each time a packet gets routed by using a TCP, UDP, or port-forwarding rule, -the router creates a link state. From then on, all packets that belong +Each time a packet gets routed by using a TCP, UDP, ICMP or port-forwarding +rule, the router creates a link state. From then on, all packets that belong to the exchange this first packet initiated and come from one of the two -involved domains are routed by the link state and not by a rule. The costs -for the link state are paid by the session that sent the first packet. +involved domains are routed by the link state and not by a rule. The costs for +the link state are paid by the session that sent the first packet. -If a link state exists for a packet, it is unambiguously correlated through -the source IP and port as well as the destination IP and port. This is also -the case if the transfer includes NAT no matter of what kind or for which -side. +If a link state exists for a packet, it is unambiguously correlated either +through source IP and port plus destination IP and port or, for ICMP, through +source and destination IP plus ICMP query ID. This is also the case if the +transfer includes NAT no matter of what kind or for which side. It is desirable to discard a link state as soon as it is not needed anymore. The more precise this is done, the more efficient can NIC sessions use their @@ -220,19 +284,20 @@ the NIC router shall discard a link state can be configured in the tag of the router for each link type separately: ! +! tcp_idle_timeout_sec="50" +! icmp_idle_timeout_sec="5"> -This would set the maximum UDP idle time to 30 and the maximum TCP idle time -to 50 seconds. You should choose these values with care. If they are too low, -replies that normally need no routing rule may get lost. If it is too high, -link states are held longer than necessary. +This would set the maximum ICMP idle time to 5, the maximum UDP idle time to +30 and the maximum TCP idle time to 50 seconds. You should choose these values +with care. If they are too low, replies that normally need no routing rule may +get lost. If it is too high, link states are held longer than necessary. -For UDP link states, this timeout is the only condition that leads to a -discard. This is better known as hole punching. It allows peers to keep alive -a UDP pseudo-connection through the router by frequently sending empty packets. -The need for such a pseudo-connection arises from the router's demand to -support NAT for UDP transfers and the consequence of keeping the corresponding -mapping information. +For UDP and ICMP link states, this timeout is the only condition that leads to +a discard. This is better known as hole punching. It allows peers to keep +alive a UDP or ICMP pseudo-connection through the router by frequently sending +empty packets. The need for such a pseudo-connection arises from the router's +demand to support NAT for UDP and ICMP transfers and the consequence of +keeping the corresponding mapping information. The lifetime management of TCP link states, in contrast, is more complex. In addition to the common timeout, they may be discarded also after the router @@ -242,6 +307,12 @@ in the tag too: ! +As long as there is a link state for a connection, the router also forwards +ICMP "Destination Unreachable" packets that contain a packet of this +connection embedded in their payload. The embedded packet is adapted according +to the NAT configuration of the link state as well as the outer IPv4 packet +that contains the ICMP. + Configuring NAT ############### @@ -274,11 +345,16 @@ And even combined: ! -If one of the two attributes is not set, this means that no port shall be used -for this protocol which effectively disables it. Thus, at least one of the two -attributes must be set for the NAT rule to be sensible. Restricting the port -usage is necessary to avoid that a client can run Denial-of-Service attacks -against the destination domain by occupying all of its ports. +The same goes for ICMP query IDs: + +! + +If one of the port or ID attributes is not set, this means that no port or ID +shall be used for this protocol which effectively disables it. Thus, at least +one of these attributes must be set for the NAT rule to be sensible. +Restricting the port usage is necessary to avoid that a client can run +Denial-of-Service attacks against the destination domain by occupying all of +its ports or IDs. Configuring DHCP server functionality @@ -378,7 +454,7 @@ Log router decisions and optional hints. ! Log most important protocol header fields of each packet that is received or -sent by the router (ETH, IPv4, ARP, UDP, TCP, DHCP). +sent by the router (ETH, IPv4, ARP, UDP, TCP, DHCP, ICMP). ! @@ -390,7 +466,8 @@ connected, current IPv4 config). ! Log most important protocol header fields of each packet that is received or -sent at a specific domain (ETH, IPv4, ARP, UDP, TCP, DHCP). +sent at a specific domain (ETH, IPv4, ARP, UDP, TCP, DHCP, ICMP). + Examples ########