Init

Readme.md

@@ -0,0 +1,101 @@
+# QubesOS Port Forwarding GSoC 2021
+## Proposal text
+### Introduction
+Forwarding ports to Qubes VM is currently possible only though a multi step, error prone,manual process that also requires writing custom configuration in order to be persistentbetween reboots. Things as simple as starting a webserver or netcat for LAN file sharing canbe eventually a troublesome and time-wasting process[1][2]. Furthermore, applications thatrely on NAT traversal protocols such as those for audio and video communications do not workin direct P2P mode with STUN and always use TURN instead[3].
+
+### Project Goals
+Implement a GUI for automatic and persistent, eventually with a predefined timespan (ie: untilreboot), port forwarding. The idea is to split horizontally the "Firewall Rules" tab in the"Qubes Settings" window and add another area below it. It is aloready possible to forward TCPstreams, however there is no GUI nor a clear dashboard and furthermore its versatility islimited.Additionally, discuss and verify the possibility to implement a secure NAT traversal systemand GUI. A basic proposal could be a checkbox to enable NAT traversal requests. When thecheckbox is selected, the FirwallVM will redirect NAT traversal requests to a local pythondaemon or a dedicated VM that will negotiate the NAT traversal and configure the networkaccordingly. In this case, prompt the user in Dom0 about the NAT traversal request. Of coursethe qvm-* set of tools must e able to achieve the same tasks via CLI.
+
+### Implementation
+First develop and document the part related to manual port forwarding since it is both a morefrequent use case and is less complicated. Depending on the problems encountered, evaluate thefeasibility of secure NAT traversal.
+
+#### Notes
+[1] - https://github.com/QubesOS/qubes-issues/issues/3556
+[2] -https://www.reddit.com/r/Qubes/comments/8cb57i/how_to_achieve_qube_to_qube_communication_port/
+[3] - https://github.com/QubesOS/qubes-issues/issues/6225
+
+## Development
+### Background
+
+ * https://www.qubes-os.org/doc/admin-api/
+ * https://www.qubes-os.org/doc/vm-interface/#firewall-rules-in-4x
+ * https://www.qubes-os.org/doc/firewall/
+ * https://www.qubes-os.org/doc/config-files/
+
+### Main components involved
+ 1. [Firewall GUI in "Settings" (qubes-manager)](https://github.com/QubesOS/qubes-manager/blob/master/qubesmanager/firewall.py)
+ 2. [CLI interface available via `qvm-firewall` (core-admin-client)](https://github.com/QubesOS/qubes-core-admin-client/blob/master/qubesadmin/tools/qvm_firewall.py)
+ 3. [Actual client logic for the Admin API (core-admin-client)](https://github.com/QubesOS/qubes-core-admin-client/blob/master/qubesadmin/firewall.py)
+ 4. [Admin API interface - XML conf manager (core-admin)](https://github.com/QubesOS/qubes-core-admin/blob/master/qubes/firewall.py)
+ 5. [Agent running in firewall vm - executes `nft` or `iptables`](https://github.com/QubesOS/qubes-core-agent-linux/blob/master/qubesagent/firewall.py)
+
+### Current Status
+#### How does the GUI and `qvm-firewall` configuration work?
+The Qubes Manager GUI and the `qvm-firewall` both use the code imlemented in the Admi API Client library. The Client Library sends specific messages to the `qubesd` daemon.
+The currently supported operatins are:
+
+ * `admin.vm.firewall.Get`
+ * `admin.vm.firewall.Set`
+ * `admin.vm.firewall.Reload`
+These actions can be tested by using the `qvm-firewall` utility. It is important to note that both the client and the daemon are more flexibile compared to the settings available via the GUI.
+
+##### Configuration files
+If any non default configuration is set by the user, an AppVM will have a `firewall.xml` configuration file in the `var/lib/qubes/<appvm>/` path. Deleting the file will reset the firewall to the default state and any customization will be lost.
+
+The `firewall.xml` is clearly human readable and contains rules in the form:
+
+```
+<firewall version="2">
+	<rules>
+		<rule>
+			<properties>
+				<!-- accept outgoing to lsd.cat porto tcp port 443 -->
+				<property name="action">accept</property>
+				<property name="dsthost">lsd.cat</property>
+				<property name="proto">tcp</property>
+				<property name="dstports">443</property>
+			</properties>
+		</rule>
+		<rule>
+			<properties>
+				<!-- accept outgoing to 10.132.11.1/24 proto any -->
+				<property name="action">accept</property>
+				<property name="dsthost">10.132.11.1/24</property>
+			</properties>
+		</rule>
+		<rule>
+			<properties>
+				<!-- allow outgoing dns queries. needed for domain based rules -->
+				<property name="action">accept</property>
+				<property name="specialtarget">dns</property>
+			</properties>
+		</rule>
+		<rule>
+			<properties>
+				<!-- drop everything else -->
+				<property name="action">drop</property>
+			</properties>
+		</rule>
+	</rules>
+</firewall>
+```
+
+##### Commands
+The following command will return the firewall rules for `<vmnname>`.
+```
+qvm-firewall <vmname>
+```
+As can be seen, the output will show more colums that the GUI, specifically an `EXPIRE`, `COMMENT`, and `SPECIAL TARGET` columns will be displayed.
+
+
+The following command will reload the persistent rules stored in `firewall.xml` of `<vmname>` 
+```
+qvm-firewall <vmname> --reload
+``` 
+
+The following command can be used to add a rule. Not that if the GUI detects that the firewall has been edited from CLI, since it does not support all CLI settings, it will refuse to allow management again from the GUI.
+
+```
+qvm-firewall <vmname> add action=accept dsthost=1.1.1.1 proto=tcp command="cloudflare http test rule" expire=+5000
+```
+