Convert all the documentation to Sphinx / RST

.readthedocs.yaml

@@ -0,0 +1,25 @@
+version: 2
+
+build:
+  os: "ubuntu-22.04"
+  tools:
+    python: "3.10"
+
+submodules:
+  include: all
+  recursive: true
+
+sphinx:
+  builder: html
+  configuration: conf.py
+  fail_on_warning: false
+
+python:
+  install:
+   - requirements: requirements.txt
+
+formats:
+- pdf
+- epub
+
+

_dev/index.rst

@@ -1,9 +1,26 @@
+==============================================
 Welcome to Qubes OS developer's documentation!
 ==============================================
 
+
 This is documentation for the source code. Please choose specific repostitory:
 
-* `core-admin </projects/core-admin>`_
-* `core-admin-client </projects/core-admin-client>`_
+.. toctree::
+   :maxdepth: 1
+
+   core-admin <>
+.. _core-admin: /projects/core-admin
+
+
+
+   core-admin-client <>
+.. _core-admin-client: /projects/core-admin-client
+
+
+
+
+
+Or see the main Qubes OS documentation <https://www.qubes-os.org/doc/>
+.. _the main qubes os documentation: https://www.qubes-os.org/doc/
 
-Or see `the main Qubes OS documentation <https://www.qubes-os.org/doc/>`_.
+.

attachment/COPYRIGHT.md

@@ -0,0 +1,10 @@
+doc/Thinkpad-t430-bios-main.jpg:
+[CC-BY-SA-4.0 Vitaly Zdanevich](https://commons.wikimedia.org/wiki/File:Thinkpad-t430-bios-main.jpg)
+doc/r4.0-snapshot\_40.png:  
+[Wikipedia](https://en.wikipedia.org/wiki/Main_page) is licensed under [CC-BY-SA 3.0](https://en.wikipedia.org/wiki/Wikipedia:Text_of_Creative_Commons_Attribution-ShareAlike_3.0_Unported_License)  
+* [Image showing Tom Brady](https://commons.wikimedia.org/wiki/File:Bucs_WFT_223_\(50833097576\).jpg) is licensed under [CC-BY-SA 2.0](https://creativecommons.org/licenses/by-sa/2.0/)
+* [Image showing Plate of the Sévres Efyption Service](https://commons.wikimedia.org/wiki/File:Plate_showing_statues_of_Amenhotep_III_at_Luxor,_Egypt._Commissioned_by_Napoleon_as_a_present_to_Josephine_but_she_rejected_it._From_France._The_Victoria_and_Albert_Museum,_London.jpg) is licensed under [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)  
+
+doc/r4.0-xfce-three-domains-at-work.png:  
+[xkcd](https://xkcd.com) is licensed under [CC-BY-NC 2.5](https://creativecommons.org/licenses/by-nc/2.5/)  
+["Day 116: 'Alexis'"](https://www.flickr.com/photos/66779558@N02/6968727080) is licensed under [CC-BY 2.0](https://creativecommons.org/licenses/by/2.0/)

attachment/README.md

@@ -0,0 +1,7 @@
+# qubes-attachment
+
+This repository contains binary files used for the Qubes OS Project's website,
+documentation, news posts, and more. For instructions about how to use this
+repo to add images to the documentation, please see:
+
+https://www.qubes-os.org/doc/doc-guidelines/#how-to-add-images

attachment/_diagrams/.gitignore

@@ -0,0 +1,3 @@
+*.jar
+*.dl
+*.png

attachment/_diagrams/Makefile

@@ -0,0 +1,23 @@
+PLANTUML_VER = 1.2020.0
+PLANTUML_URL = https://downloads.sourceforge.net/project/plantuml/$(PLANTUML_VER)/plantuml.$(PLANTUML_VER).jar
+PLANTUML_SHA256 = 7a9d2d56aeed9381066f98e3cf6450a06258ccfd4bfa7f306a62451e8af470c5
+
+DIAGRAMS = qrexec-vm-dom0.png qrexec-dom0-vm.png qrexec-vm-vm.png
+
+all: $(DIAGRAMS)
+
+install:
+	cp qrexec-vm-dom0.png ../doc/
+	cp qrexec-dom0-vm.png ../doc/
+	cp qrexec-vm-vm.png ../doc/
+
+./%.png: %.uml $(PLANTUML)
+	java -jar plantuml.jar $^
+
+plantuml.jar:
+	echo "PlantUML not found. Run 'make download'."
+
+download:
+	wget $(PLANTUML_URL) -O plantuml.$(PLANTUML_VER).jar.dl
+	echo "$(PLANTUML_SHA256)  plantuml.$(PLANTUML_VER).jar.dl" | sha256sum -c
+	mv plantuml.$(PLANTUML_VER).jar.dl plantuml.jar

attachment/_diagrams/README.md

@@ -0,0 +1,7 @@
+# Diagrams
+
+This is source for diagrams rendered with PlantUML.
+
+* `make download` - download PlantUML jar
+* `make` (or `make all`) - render diagrams
+* `make install` - copy the diagrams to destination directory

attachment/_diagrams/qrexec-dom0-vm.uml

@@ -0,0 +1,39 @@
+@startuml
+
+box dom0 #eee
+    participant "client" as c
+    participant "daemon domX" as d
+end box
+
+box domX #eee
+    participant "agent" as ax
+    participant "fork-server" as fx
+end box
+
+-> c: qrexec-client\n-d dom0\nuser:cmd
+activate c
+c -> d: MSG_EXEC_CMDLINE\ndom0,0,user:cmd
+activate d
+note right: negotiate port\nand run user:cmd
+rnote over d #fff: allocate port 513
+d -> c: MSG_EXEC_CMDLINE\ndomX,513
+rnote over c #fff: start vchan server\n on port 513
+d -> ax: MSG_EXEC_CMDLINE\ndom0,513,user:cmd
+deactivate d
+activate ax
+
+ax -> fx: MSG_EXEC_CMDLINE\ndom0,513,user:cmd
+deactivate ax
+activate fx
+rnote over fx #fff: start cmd (as user)
+fx --> c: connect over vchan port 513
+-> c: stdin
+c -> fx: MSG_DATA_STDIN ...
+fx -> c: MSG_DATA_STDOUT / MSG_DATA_STDERR ...
+<- c: stdout / stderr
+rnote over fx #fff: cmd exits
+fx -> c: MSG_DATA_EXIT_CODE 0
+deactivate fx
+<- c: exit with code 0
+deactivate c
+@end uml

attachment/_diagrams/qrexec-vm-dom0.uml

@@ -0,0 +1,55 @@
+@startuml
+
+box domX #eee
+    participant "client-vm" as cx
+    participant "agent" as ax
+end box
+
+box dom0 #eee
+    participant "daemon domX" as d
+    participant "client" as c
+    participant "policy" as p
+end box
+
+-> cx: qrexec-client-vm\ndom0 admin.Service
+
+activate cx
+cx -> ax: MSG_TRIGGER_SERVICE3\ndom0, SOCKET,\nadmin.Service
+activate ax
+note over ax: 11 is the FD of\nclient-vm connection
+ax -> d: MSG_TRIGGER_SERVICE3\ndom0, SOCKET11,\nadmin.Service
+deactivate ax
+activate d
+d -> p: qrexec-policy\nX domX dom0\nadmin.Service SOCKET11
+deactivate d
+activate p
+
+rnote over p #fff: evaluate policy,\ndecide to run command
+p -> c: qrexec-client\n-d dom0\n-c domX,X,SOCKET11\n"QUBESRPC admin.Service\ndomX name dom0"
+deactivate p
+activate c
+
+note over c: negotiating port
+c -> d: MSG_SERVICE_CONNECT\ndom0,0,SOCKET11
+activate d
+rnote over d #fff: allocate port 513
+d -> c: MSG_SERVICE_CONNECT\ndomX,513,SOCKET11
+d -> ax: MSG_SERVICE_CONNECT\ndom0,513,SOCKET11
+deactivate d
+activate ax
+ax -> cx: (no header)\ndom0,513
+deactivate ax
+rnote over cx #fff: start vchan server\n on port 513
+rnote over c #fff: start:\nqubes-rpc-multiplexer\nadmin.Service\ndomX name dom0
+c --> cx: connect over vchan port 513
+-> cx: stdin
+cx -> c: MSG_DATA_STDIN ...
+c -> cx: MSG_DATA_STDOUT ...
+<- cx: stdout
+rnote over c #fff: qubes-rpc-multiplexer exits
+c -> cx: MSG_DATA_EXIT_CODE 0
+deactivate c
+<- cx: exit with code 0
+deactivate cx
+
+@end uml

attachment/_diagrams/qrexec-vm-vm.uml

@@ -0,0 +1,74 @@
+@startuml
+
+box domX (source) #eee
+    participant "client-vm" as cx
+    participant "agent" as ax
+end box
+
+box dom0 #eee
+    participant "daemon domX" as dx
+    participant "client" as c
+    participant "policy" as p
+    participant "daemon domY" as dy
+end box
+
+box domY (target) #eee
+    participant "agent" as ay
+    participant "fork-server" as fy
+end box
+
+-> cx: qrexec-client-vm\n domY\nqubes.Service
+
+activate cx
+cx -> ax: MSG_TRIGGER_SERVICE3\ndomY, SOCKET,\nqubes.Service
+activate ax
+note over ax: 11 is the FD of\nclient-vm connection
+ax -> dx: MSG_TRIGGER_SERVICE3\ndomY, SOCKET11,\nqubes.Service
+deactivate ax
+activate dx
+dx -> p: qrexec-policy\nX domX domY\nqubes.Service SOCKET11
+deactivate dx
+
+activate p
+rnote over p #fff: evaluate policy,\ndecide to run command
+p -> c: qrexec-client\n-d domY\n-c domX,X,SOCKET11\n"DEFAULT:QUBESRPC\nqubes.Service domX"
+deactivate p
+activate c
+
+note over c: negotiating port
+c -> dy: MSG_EXEC_CMDLINE\ndomX,0,"DEFAULT:QUBESRPC\nqubes.Service domX"
+activate dy
+rnote over dy #fff: allocate port 513
+dy -> c: MSG_EXEC_CMDLINE\ndomY,513
+c -> dx: MSG_SERVICE_CONNECT\ndomY,513,SOCKET11
+deactivate c
+
+activate dx
+dx -> ax: MSG_SERVICE_CONNECT\ndomY,513,SOCKET11
+deactivate dx
+activate ax
+ax -> cx: (no header)\ndomY, 513
+deactivate ax
+note over cx #fff: start vchan server\non port 513
+
+note over dy: "DEFAULT"\ngets translated to\nVM's default user
+dy -> ay: MSG_EXEC_CMDLINE\ndomX,513,\n"user:QUBESRPC\nqubes.Service domX"
+deactivate dy
+activate ay
+ay -> fy: MSG_EXEC_CMDLINE\ndomX,513,\n"user:QUBESRPC\nqubes.Service domX"
+deactivate ay
+activate fy
+rnote over fy #fff: start:\nqubes-rpc-multiplexer\nqubes.Service domX\n(as user)
+
+fy --> cx: connect over vchan port 513
+-> cx: stdin
+cx -> fy: MSG_DATA_STDIN ...
+fy -> cx: MSG_DATA_STDOUT / MSG_DATA_STDERR ...
+<- cx: stdout / stderr
+rnote over fy #fff: qubes-rpc-multiplexer\nexits
+fy -> cx: MSG_DATA_EXIT_CODE 0
+deactivate fy
+<- cx: exit with code 0
+deactivate cx
+
+@end uml