Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2025-05-06 08:45:04 -04:00
Code Issues Projects Releases Packages Wiki Activity

Fix a few typos

Browse source
This commit is contained in:
r00t 2016-01-10 18:41:30 -05:00
parent 5ae0d5dfb0
commit 0baa097f9b
39 changed files with 211 additions and 218 deletions
Download patch file Download diff file Expand all files Collapse all files

2
developers/building/building-archlinux-template.md
View file

@ -55,7 +55,7 @@ COMPONENTS:=$(filter-out desktop-linux-kde desktop-linux-xfce,$(COMPONENTS))
Just don't forget that you need to comment this line again if you want to build the whole Qubes-OS install CD.
Make all required qubes components
Make all required Qubes components
----------------------------------
The first use of the builder can take several hours depending on your bandwidth as it will install an archlinux chroot:

12
developers/building/building-non-fedora-template.md
View file

@ -65,9 +65,9 @@ The goal of this file is to prepare a development environment of your target OS
- the \$1 variable will contain the installation directory (INSTALLDIR should contain the same value than \$1 when you run 00\_prepare or 01\_install\_core)
- after your base system is installed, you should install development tools and libraries (gcc, make, ...)
- create a user called 'user' inside your chroot, and give him enought right to run the command sudo without any password
- create a user called 'user' inside your chroot, and give him enough rights to run the command sudo without any password
- register all the repository that could be necessary and synchronize the package database
- register a custom repository that will be used to store qubes packages
- register a custom repository that will be used to store Qubes packages
### Makefile.yourOSname
@ -84,7 +84,7 @@ These additional target need to exist once you created your first packages:
### Testing the development chroot
You will be able to test these script when making the first qubes packages. Don't forget that the first things that run when running 'make somcomponent-vm' will be these two scripts, and that you will need to debug it at this point.
You will be able to test these script when making the first Qubes packages. Don't forget that the first things that run when running 'make somcomponent-vm' will be these two scripts, and that you will need to debug it at this point.
Qubes packages
--------------
@ -118,7 +118,7 @@ The goal of this script is to install all the package that you want to use in yo
### 04\_install\_qubes.sh
The goal of this script is to install in your template all the packages you built previously. Also you need to edit the fstab file of your template to mount qubes virtual hard drives.
The goal of this script is to install in your template all the packages you built previously. Also you need to edit the fstab file of your template to mount Qubes virtual hard drives.
### 09\_cleanup.sh
@ -137,13 +137,13 @@ As soon as you manage to make qrexec and qubes-gui-agent working, it should be s
### Xen libraries
Several XEN libraries are required for Qubes to work correctly. In fact, you need to make xenstore commands working before anything else. For this, Qubes git can be used as several patches have been selected by Qubes developpers that could impact the activity inside a VM. Start be retrieving a recent git and identify how you can build a package from it: `git clone git://git.qubes-os.org/marmarek/xen`
Several XEN libraries are required for Qubes to work correctly. In fact, you need to make xenstore commands working before anything else. For this, Qubes git can be used as several patches have been selected by Qubes developers that could impact the activity inside a VM. Start be retrieving a recent git and identify how you can build a package from it: `git clone git://git.qubes-os.org/marmarek/xen`
Find the .spec file in the git repository (this is the file being used to build rpm packages), and try to adapt it to your OS in order to build a package similar to the target 'xen-vm'. For example, a PKGBUILD has been created for [ArchLinux](/doc/templates/archlinux/) and can be found on [http://aur.archlinux.org/packages/qu/qubes-vm-xen/PKGBUILD](http://aur.archlinux.org/packages/qu/qubes-vm-xen/PKGBUILD).
Don't be afraid with the complexity of the PKGBUILD, most of the code is almost a copy/paste of required sources and patches found in the .spec file provided in the git repository.
Note once the package has been successfully compiled and installed, you need to setup XEN filesystem. Add the folowing line to your fstab (you can create this line in your package install script): `xen /proc/xen xenfs defaults 0 0`
Note once the package has been successfully compiled and installed, you need to setup XEN filesystem. Add the following line to your fstab (you can create this line in your package install script): `xen /proc/xen xenfs defaults 0 0`
Now install the package you built and mount /proc/xen. Verify that xenstore-read works by running: `xenstore-read qubes_vm_type` That should give you the current VM type such as HVM or AppVM.

2
developers/building/development-workflow.md
View file

@ -149,7 +149,7 @@ RPMS will appear in qubes-src/linux-kernel/pkgs/fc20/x86\_64:
### Useful [QubesBuilder](/doc/qubes-builder/) commands
1. `make check` - will check if all the code was commited into repository and
1. `make check` - will check if all the code was committed into repository and
if all repository are tagged with signed tag.
2. `make show-vtags` - show version of each component (based on git tags) -
mostly useful just before building ISO. **Note:** this will not show version

3
developers/coding-style.md
View file

@ -39,7 +39,7 @@ General typographic conventions
- Class, functions, variables, and arguments naming convention for **Windows OS** -- exceptionally to preserve Windows conventions please use the following:
- `ClassName`, `FunctionName`
- `pszArgumentOne`, `hPipe` -- use hungerian notation for argument and variables
- `pszArgumentOne`, `hPipe` -- use Hungarian notation for argument and variables
- Horizontal spacing -- maintain at least decent amount of horizontal spacing, such as e.g. add obligatory space after `if` or before `{` in C, and similar in other languages. Whether to also use spaces within expressions, such as (x\*2+5) vs. (x \* 2 + 5) is left to the developer's judgment. Do not put spaces immediately after and before the brackets in expressions, so avoid constructs like this: `if ( condition )` and use `if (condition)` instead.
@ -169,4 +169,3 @@ Bash-specific guidelines
------------------------
- Avoid writing scripts in bash whenever possible. Use python instead. Bash-scripts are Unix-specific and will not work under Windows VMs, or in Windows admin domain, or Windows gui domain.

2
developers/debugging/profiling.md
View file

@ -70,7 +70,7 @@ cd ~/profiling
./Upload.sh
~~~
### Analyse
### Analyze
~~~
make

4
developers/debugging/test-bench.md
View file

@ -130,7 +130,7 @@ This step is optional, but very helpful. Put these scripts somewhere in your `${
pushd ${HOME}/builder >/dev/null
# the following are needed only if you have sources outside builder
#rm -rf qubes-src/core-admin
#rm -rf qubes-src/core-admin
#make COMPONENTS=core-admin get-sources
make core-admin
@ -139,7 +139,7 @@ This step is optional, but very helpful. Put these scripts somewhere in your `${
### Hooking git
I (woju) have those two git hooks. They ensure tests are passing (or are marked as expected failure) when commiting and pushing. For committing it is only possible to run tests that may be executed from git repo (even if the rest were available, I probably wouldn't want to do that). For pushing, I also install RPM and run tests on testbench.
I (woju) have those two git hooks. They ensure tests are passing (or are marked as expected failure) when committing and pushing. For committing it is only possible to run tests that may be executed from git repo (even if the rest were available, I probably wouldn't want to do that). For pushing, I also install RPM and run tests on testbench.
`core-admin/.git/hooks/pre-commit`: (you may retain also the default hook, here omitted for readability)

177
developers/fundamentals/gui.md
View file

@ -34,7 +34,7 @@ Main responsibilities of *qubes_guid* are:
- whenever AppVM signals damage event, tell local Xorg server to repaint a given window fragment
- receive information about window size/position change, apply them to the local window
Note that keyboard and mouse events are passed to AppVM only if a window belonging to this AppVM has focus. AppVM has no way to get information on keystrokes fed to other AppVMs (e.g. XTEST extension will report the status of local AppVM keyboard only), nor synthetize and pass events to other AppVMs.
Note that keyboard and mouse events are passed to AppVM only if a window belonging to this AppVM has focus. AppVM has no way to get information on keystrokes fed to other AppVMs (e.g. XTEST extension will report the status of local AppVM keyboard only), nor synthesize and pass events to other AppVMs.
Window content updates implementation
-------------------------------------
@ -123,62 +123,62 @@ The header is followed by message-specific data.
|Message name|Structure after header|Action|
|:-----------|:---------------------|:-----|
|MSG_CLIPBOARD_DATA|amorphic blob (length determined by the "window" field)|Store the received clipboard content (not parsing in any way)|
|MSG_CREATE|` struct msg_create { `
` uint32_t x; `
` uint32_t y; `
` uint32_t width; `
` uint32_t height; `
` uint32_t parent; `
` uint32_t override_redirect; `
|MSG_CREATE|` struct msg_create { `
` uint32_t x; `
` uint32_t y; `
` uint32_t width; `
` uint32_t height; `
` uint32_t parent; `
` uint32_t override_redirect; `
` }; `|Create a window with given parameters|
|MSG_DESTROY|None|Destroy a window|
|MSG_MAP|` struct msg_map_info { `
` uint32_t transient_for; `
` uint32_t override_redirect; `
|MSG_MAP|` struct msg_map_info { `
` uint32_t transient_for; `
` uint32_t override_redirect; `
` }; `|Map a window with given parameters|
|MSG_UNMAP|None|Unmap a window|
|MSG_CONFIGURE|` struct msg_configure { `
` uint32_t x; `
` uint32_t y; `
` uint32_t width; `
` uint32_t height; `
` uint32_t override_redirect; `
|MSG_CONFIGURE|` struct msg_configure { `
` uint32_t x; `
` uint32_t y; `
` uint32_t width; `
` uint32_t height; `
` uint32_t override_redirect; `
` }; `|Change window position/size/type|
|MSG_MFNDUMP|` struct shm_cmd { `
` uint32_t shmid; `
` uint32_t width; `
` uint32_t height; `
` uint32_t bpp; `
` uint32_t off; `
` uint32_t num_mfn; `
` uint32_t domid; `
` uint32_t mfns[0]; `
` }; `|Retrieve the array of mfns that constitute the composition buffer of a remote window.
|MSG_MFNDUMP|` struct shm_cmd { `
` uint32_t shmid; `
` uint32_t width; `
` uint32_t height; `
` uint32_t bpp; `
` uint32_t off; `
` uint32_t num_mfn; `
` uint32_t domid; `
` uint32_t mfns[0]; `
` }; `|Retrieve the array of mfns that constitute the composition buffer of a remote window.
The "num_mfn" 32bit integers follow the shm_cmd structure; "off" is the offset of the composite buffer start in the first frame; "shmid" and "domid" parameters are just placeholders (to be filled by *qubes_guid*), so that we can use the same structure when talking to *shmoverride.so*|
|MSG_SHMIMAGE|` struct msg_shmimage { `
` uint32_t x; `
` uint32_t y;`
` uint32_t width;`
` uint32_t height;`
|MSG_SHMIMAGE|` struct msg_shmimage { `
` uint32_t x; `
` uint32_t y;`
` uint32_t width;`
` uint32_t height;`
` }; `|Repaint the given window fragment|
|MSG_WMNAME|` struct msg_wmname { `
` char data[128]; `
|MSG_WMNAME|` struct msg_wmname { `
` char data[128]; `
` } ; `|Set the window name; only printable characters are allowed|
|MSG_DOCK|None|Dock the window in the tray|
|MSG_WINDOW_HINTS|` struct msg_window_hints { `
` uint32_t flags; `
` uint32_t min_width; `
` uint32_t min_height; `
` uint32_t max_width; `
` uint32_t max_height; `
` uint32_t width_inc; `
` uint32_t height_inc; `
` uint32_t base_width; `
` uint32_t base_height; `
|MSG_WINDOW_HINTS|` struct msg_window_hints { `
` uint32_t flags; `
` uint32_t min_width; `
` uint32_t min_height; `
` uint32_t max_width; `
` uint32_t max_height; `
` uint32_t width_inc; `
` uint32_t height_inc; `
` uint32_t base_width; `
` uint32_t base_height; `
` }; `|Size hints for window manager|
|MSG_WINDOW_FLAGS|` struct msg_window_flags { `
` uint32_t flags_set; `
` uint32_t flags_unset;`
|MSG_WINDOW_FLAGS|` struct msg_window_flags { `
` uint32_t flags_set; `
` uint32_t flags_unset;`
` }; `|Change window state request; fields contains bitmask which flags request to be set and which unset|
~~~
@ -202,59 +202,58 @@ The header is followed by message-specific data.
~~~
|Message name|Structure after header|Action|
|:-----------|:---------------------|:-----|
|MSG_KEYPRESS|` struct msg_keypress { `
` uint32_t type; `
` uint32_t x; `
` uint32_t y; `
` uint32_t state; `
` uint32_t keycode; `
|MSG_KEYPRESS|` struct msg_keypress { `
` uint32_t type; `
` uint32_t x; `
` uint32_t y; `
` uint32_t state; `
` uint32_t keycode; `
` }; `|Tell *qubes_drv* driver to generate a keypress|
|MSG_BUTTON|` struct msg_button { `
` uint32_t type; `
` uint32_t x; `
` uint32_t y; `
` uint32_t state; `
` uint32_t button; `
|MSG_BUTTON|` struct msg_button { `
` uint32_t type; `
` uint32_t x; `
` uint32_t y; `
` uint32_t state; `
` uint32_t button; `
` }; `|Tell *qubes_drv* driver to generate mouseclick|
|MSG_MOTION|` struct msg_motion { `
` uint32_t x; `
` uint32_t y; `
` uint32_t state; `
` uint32_t is_hint; `
|MSG_MOTION|` struct msg_motion { `
` uint32_t x; `
` uint32_t y; `
` uint32_t state; `
` uint32_t is_hint; `
` }; `|Tell *qubes_drv* driver to generate motion event|
|MSG_CONFIGURE|` struct msg_configure { `
` uint32_t x; `
` uint32_t y; `
` uint32_t width; `
` uint32_t height; `
` uint32_t override_redirect; `
|MSG_CONFIGURE|` struct msg_configure { `
` uint32_t x; `
` uint32_t y; `
` uint32_t width; `
` uint32_t height; `
` uint32_t override_redirect; `
` }; `|Change window position/size/type|
|MSG_MAP|` struct msg_map_info { `
` uint32_t transient_for; `
` uint32_t override_redirect; `
|MSG_MAP|` struct msg_map_info { `
` uint32_t transient_for; `
` uint32_t override_redirect; `
` }; `|Map a window with given parameters|
|MSG_CLOSE|None|send wmDeleteMessage to the window|
|MSG_CROSSING|` struct msg_crossing { `
` uint32_t type; `
` uint32_t x; `
` uint32_t y; `
` uint32_t state; `
` uint32_t mode; `
` uint32_t detail; `
` uint32_t focus; `
|MSG_CROSSING|` struct msg_crossing { `
` uint32_t type; `
` uint32_t x; `
` uint32_t y; `
` uint32_t state; `
` uint32_t mode; `
` uint32_t detail; `
` uint32_t focus; `
` }; `|Notify window about enter/leave event|
|MSG_FOCUS|` struct msg_focus { `
` uint32_t type; `
` uint32_t mode; `
` uint32_t detail; `
|MSG_FOCUS|` struct msg_focus { `
` uint32_t type; `
` uint32_t mode; `
` uint32_t detail; `
` }; `|Raise a window, XSetInputFocus|
|MSG_CLIPBOARD_REQ|None|Retrieve the local clipboard, pass contents to gui-daemon|
|MSG_CLIPBOARD_DATA|amorphic blob|Insert the received data into local clipboard|
|MSG_EXECUTE|Obsolete|Obsolete, unused|
|MSG_KEYMAP_NOTIFY|` unsigned char remote_keys[32]; `|Synchronize the keyboard state (key pressed/released) with dom0|
|MSG_WINDOW_FLAGS|` struct msg_window_flags { `
` uint32_t flags_set; `
` uint32_t flags_unset;`
|MSG_WINDOW_FLAGS|` struct msg_window_flags { `
` uint32_t flags_set; `
` uint32_t flags_unset;`
` }; `|Window state change confirmation|
~~~

2
developers/services/qfilecopy.md
View file

@ -23,7 +23,7 @@ This has the following disadvantages:
- performance - dom0 has to prepare and attach/detach block devices, which is slow because of hotplug scripts involvement.
- security - VM kernel parses partition table and filesystem metadata from the block device; they are controlled by (potentially untrusted) sender VM.
In Qubes Beta1, we have reimplemented interVM file copy using qrexec, which addresses the abovementioned disadvantages. In Qubes Beta2, even more generic solution (qubes rpc) is used. See the developer docs on qrexec and qubes rpc. In a nutshell, the file sender and the file receiver just read/write from stdin/stdout, and the qubes rpc layer passes data properly - so, no block devices are used.
In Qubes Beta1, we have reimplemented interVM file copy using qrexec, which addresses the above mentioned disadvantages. In Qubes Beta2, even more generic solution (qubes rpc) is used. See the developer docs on qrexec and qubes rpc. In a nutshell, the file sender and the file receiver just read/write from stdin/stdout, and the qubes rpc layer passes data properly - so, no block devices are used.
The rpc action for regular file copy is *qubes.Filecopy*, the rpc client is named *qfile-agent*, the rpc server is named *qfile-unpacker*. For DispVM copy, the rpc action is *qubes.OpenInVM*, the rpc client is named *qopen-in-vm*, rpc server is named *vm-file-editor*. Note that the qubes.OpenInVM action can be done on a normal AppVM, too.

5
developers/services/qrexec2.md
View file

@ -52,7 +52,7 @@ There can be almost arbitrary number of `qrexec-client` processes for a domain
(i.e., `qrexec-client` processes connected to the same `qrexec-daemon`);
their data is multiplexed independently.
There is a similar command line utility avilable inside Linux AppVMs (note
There is a similar command line utility available inside Linux AppVMs (note
the `-vm` suffix): `qrexec-client-vm` that will be described in subsequent
sections.
@ -265,7 +265,7 @@ Players:
users. `qrexec-client-vm` is designed to be wrapped up by Qubes apps.
## Windows VMs implemention ##
## Windows VMs implementation ##
`%QUBES_DIR%` is the installation path (`c:\Program Files\Invisible Things
Lab\Qubes OS Windows Tools` by default).
@ -327,4 +327,3 @@ steps are taken:
process to exit, and then destroys the DispVM.
*TODO: Protocol description ("wire-level" spec)*

8
developers/version-scheme.md
View file

@ -17,18 +17,18 @@ From now on, it will be as follows.
Qubes distributions and products
--------------------------------
We intend to make it easy to make a remix of qubes, targetting another
We intend to make it easy to make a remix of qubes, targeting another
hypervisor or isolation provider. We may also create commercial products
intended for specific circumstances. There is one distinguished distribution
called **Qubes OS**. All source code for it is available for download under GPL
licence and is openly developed on the mailing lists. The rest of this document
license and is openly developed on the mailing lists. The rest of this document
discusses Qubes OS. Another remix may have its own version series.
Release version
---------------
Qubes OS as a whole is released from time to time. Version scheme for all
releases is modelled after Linux kernel version numbers. When announcing new
releases is modeled after Linux kernel version numbers. When announcing new
release, we decide on the major.minor version (like `3.0`) and release
`3.0-rc1`. When we feel that enough progress has been made, we put `3.0-rc2`
and so on. All these versions are considered unstable and not ready for
@ -79,7 +79,7 @@ in `current` repository and the cycle starts over. There should be no less than
</table>
Starting with second cycle (that is, after `-rc1`) two weeks into the cycle
(after primary bug-reporting period) the Supreme Committee decides wether there
(after primary bug-reporting period) the Supreme Committee decides whether there
should be another RC. If, based on remaining issues, the Committee decides to
release final, then the Committee agrees upon the release date, which should be
no later than a week after.