Go back to topic: How to use the Qubes Admin Policies/API despite the lack of documentation - WIP
| First, choose a template to make the sys-gui | First, choose a template to make the management dvms from that will be used in the construction of sys-gui. We will use fedora-38, because as of 2024-11-09: * fedora-38 works for setting up sys-gui * The debian templates do *not* work for setting up sys-gui * fedora-40-xfce often does not work with a error like: “no such module” salt.{something}.six} |
| * `qvm-template install fedora-38`
| * `qvm-template install fedora-38` |
| Then actually create the sys-gui qube: | |
| now create a file in dom0 called / | now create a file in dom0 called /user/local/bin/fix-guivm-password.sh, that contains: |
| chmod a+x / | chmod a+x /usr/local/bin/fix-guivm-password.sh |
| / | /usr/local/bin/fix-guivm-password.sh $1 |
| First, choose a template to make the sys-gui | First, choose a template to make the management dvms from that will be used in the construction of sys-gui. We will use fedora-38, because as of 2024-11-09: * fedora-38 works for setting up sys-gui * The debian templates do *not* work for setting up sys-gui * fedora-40-xfce often does not work with a error like: “no such module” salt.{something}.six} |
| / | /usr/local/bin/fix-guivm-password.sh sys-gui-vnc |
| ##### sys-gui-vnc (with no networking) | ##### sys-gui-vnc for debugging (I.E. with no networking) By default, sys-gui-vnc does *not* allow remote control from over the network. Thats something you have to specifically set up. We will not be setting that up. We are just creating a sys-gui-vnc for debugging purposes. The procedure is as follows: |
| You can set up a [sys-gui](https://www.qubes-os.org/doc/gui-domain/) qube by | You can set up a [sys-gui](https://www.qubes-os.org/doc/gui-domain/) qube by doing the following: First, choose a template to make the sys-gui-vnc from. We will use fedora-38, because as of 2024-11-09: * fedora-38 works * The debian templates do *not* work * fedora-40-xfce often does not work with a error like: “no such module” salt.{something}.six} If you do not have the fedora-38 template installed, you can install it with either: * `qvm-template-gui` * `qvm-template install fedora-38` * Then set the template to match whatever you chose: |
| ``` The actually create the sys-gui qube: | |
| (Note: fedora-40-xfce is another option, but sometimes gives a "no such module" salt.{something}.six} error### (also, dont use debian) ``` | |
| First, make | First, choose a template to make the sys-gui-vnc from. We will use fedora-38, because as of 2024-11-09: * fedora-38 works * The debian templates do *not* work * fedora-40-xfce often does not work with a error like: “no such module” salt.{something}.six} If you do not have the fedora-38 template installed, you can install it with either: * `qvm-template-gui` * `qvm-template install fedora-38` Then set the template to match whatever you chose: |
| ```
| ``` |
| ``` if everything worked, you can then: ``` |
| First, make sure you have the fedora-38 template installed (via qubes-template-manager) Then: | |
| qvm-prefs default-mgmt-dvm template fedora-38 ``` (Note: fedora-40-xfce is another option, but sometimes gives a “no such module” salt.{something}.six} error### (also, dont use debian) Now, create the sys-gui-vnc qube: ``` |
| sudo qubesctl top.disable qvm.sys-gui | sudo qubesctl top.disable qvm.sys-gui-vnc |
| It is probably asking about devault-dvm | It is probably asking about devault-dvm becauot work, so you’lse default-dvm is set as the default disposable template. This would be a opportunity to explore that policy. |
| All qubes policies names are actually the name of a call to qrexec, so the method of trying qrexec calls should be comprehensive for all calls that get data (the effect of calls that set data | All qubes policies names are actually the name of a call to qrexec, so the method of trying qrexec calls should be comprehensive for all calls that get data (the effect of calls that set data may not be obvious :) |
| Ideally we'd like to turn on debugging info for qrexec so we can get a log of all the details of all the actual requests coming in. Unfortunately, this is not possible (see comment below). The following things will be missing from logs (and notifications) about qrexec calls: * dom0 entirely bypasses policy, so any calls done via dom0 will not show up in the logs (or policy). * (later in this document, we will show you ways around this by making the calls from others VMs) * It's missing some of the parameters to the call. Some calls take parameters. We'd like to know what they were. But they get stripped from the logs/notifications about policy accepted/denied actions and adding them back would be difficult (see comment on this below). I have not tried it yet, but the next thing to try is doing something like this in the VM you are sending the qrexec requests from, before sending requests: ``` sudo mv /var/run/qubes/qrexec-agent /var/run/qubes/qrexec-agent.original sudo socat -t100 -x -v UNIX-LISTEN:/var/run/qubes/qrexec-agent,mode=777,reuseaddr,fork UNIX-CONNECT:/var/run/qubes/qrexec-agent.original ``` In theory that should display all the information from your qrexec requests from that qube to that terminal screen, but it may be in a entirely unreadable form. | |
| Similarly, if this information was available we would be able to watch all qrexec calls happening every time we clicked a button and would start learning the policy names/API *really* quickly.
| Similarly, if this information was available we would be able to watch all qrexec calls happening every time we clicked a button and would start learning the policy names/API *really* quickly. |
| [Open question: Is it mentioned anywhere what people should do to learn qubes that we can point to? Things like how it's preferable to learn and make your mistakes on a system that does not have security critical data on it, and not on a security critical production system?]
| [Open question: Is it mentioned anywhere what people should do to learn qubes that we can point to? Things like how it's preferable to learn and make your mistakes on a system that does not have security critical data on it, and not on a security critical production system?] # Getting the names of all the available policies (without descriptions): |
| ## Try | # Figuring out what a policy of a given name actually does: This gives you some approaches on how to figure out what the policies do. ## Try using it as a qrexec call and see what gets returned |
| ## Attempting to use documentation to get hints on what | ## Attempting to use documentation to get hints on what it does |
| # Figuring out which | # Figuring out which of those policy names a particular qubes command or widget uses: |
| (Note: dom0 | (Note: dom0 bypasses the policy system, so "just try it" will not get you your error notifications (or log messages) you wanted if you try using the commands/widgets in dom0) |
| #### This was accidently pasted in the middle of aprevious paragraph... What was this supposed to be referencing?? :) (same with `qrexec-client-vm dom0 admin.label.List`) Obviously qubes needs `admin.vm.List` to operate, so qrexec is working, there is just some kind of missing information on how to interact with it |
| - How to find the names and | - How to find the names of all the available policies, and how to figure out what those policies do (or at least attempt to) |
| This includes the following major sections: - How to find the names and functions of various policies (or at least attempt to) - How to find which policies are needed to use a particular qubes command or qubes widget - Policy Information discovered so far (I.E. best information/guesses so far for what they actually do) | |
| ## Getting the names of all the available policies ( | ## Getting the names of all the available policies (without descriptions): |
| Now while we have the names of the policies/services document now, it still would also be nice to know what they actually do! :slight_smile:
## | Now while we have the names of the policies/services document now, it still would also be nice to know what they actually do! :slight_smile: ## Try doing it as a qrexec call and see what gets returned |
| From any qubes *other* then dom0, you can do qrexec calls via qrexec-client-vm. For example, lets say you are using a qube called "test-qube" and want to know what admin.vm.List does. In that case it would work by | From any qubes *other* then dom0, you can do qrexec calls via qrexec-client-vm. For example, lets say you are using a qube called "test-qube" and want to know what admin.vm.List does. In that case it would work by you typing this in test-qube: |
| After adding that policy | After adding that policy try running the command again and this time you should be able to figure out what it does from the results it returns. |
| [/details]
| [/details] |
| After a couple days I found a [old post talking about it in the old format](https://github.com/QubesOS/qubes-posts/blob/0d410fef83d0bbb708d6904142cb063145440f55/2017-06-27-qubes-admin-api.md?plain=1#L187) , saved in a "qubes-posts" repo on github that confirms it's supposed to be the qvm-ls list
# | After a couple days I found a [old post talking about it in the old format](https://github.com/QubesOS/qubes-posts/blob/0d410fef83d0bbb708d6904142cb063145440f55/2017-06-27-qubes-admin-api.md?plain=1#L187) , saved in a "qubes-posts" repo on github that confirms it's supposed to be the qvm-ls list # Figuring out which policy/services the various qubes commands and widgets use: Lets face it, you probably want to know about the policies to you can figure out how to get specific qubes CLI commands (example "qvm-ls") and qubes GUI widgets (example: the start menu) working. So this section gives you some approaches on how to figure out what policies a particular command or widget needs to work. |
| (Note: dom0 seems to bypass the policy system, so "just try it" will not get you your error notifications you wanted if you try the commands/widgets in dom0) |
| - Try doing it as a qrexec call direc### You can try doing it as a qrexec call All qubes policies names are actually the name of a call to qrexec, so the method of trying qrexec calls should be comprehensive for all calls that get data (the effect of calls that set data may not be obvious :) From any qubes *other* then dom0, you can do qrexec calls via qrexec-client-vm. For example, lets say you are using a qube called "test-qube" and want to know what admin.vm.List does. In that case it would work by doing this: ``` qrexec-client-vm work admin.vm.List < /dev/null ``` That command should fail, which you can fix by giving test-qube permissions to run that command by adding this line to dom0:/etc/qubes/policy.d/30-user.policy): ``` admin.vm.List * test-qube @adminvm allow target=@adminvm ``` After adding that policy run the command again and you should be able to figure out what it does from the results it returns. ### Possible future way to do it - logging?: It's possible there is a way to turn on debugging info for qrexec so we can get a log of all the details of all the actual requests coming in (including accepted ask and denied). (Currently the logs (including the systemd log) do not seem to provide any more detail then the notification messages whenever qubes denies a request (for example, provide both what computer the request was for **and** what computer the request got redirected to)) If this information was available and we were able to turn this on, one could just filter the log for the policy you are interested and try to correlate the timestamps to your qubes activites. Similarly, if this information was available we would be able to watch all qrexec calls happening every time we clicked a button and would start learning the policy names/API *really* quickly. Does anyone know if such a thing is possible? tly | |
| # | # Figuring out what the policy/services do: This gives you some approaches on how to figure out what the policies do. ## Getting the names of all the available policies (with no descriptions): In the current (2024-10-29) policy format, each policy begins with a name. For example, one usable name is: `qubes.vm.List` |
| ```
| ``` [details="If you know how to use shell scripts, ignore the next section and move on. If you need some examples of how you might reduce the ammount of typing, then uncollapse and read this text."] In order to see the list of all the possible policies that can be run on your current system, running this next part in dom0 will show you a list of all the possible commands that will show you policy options in various qubes. (I.E. lets you cut and paste the comands rather then type them out yourself) |
| [/details] | |
| ## You can try doing it as a qrexec call | |
| ## Attempting to use documentation to get hints on what all the policies/services actually do Some of the policies have been partially documented here: [list of the names of the policy/service calls](https://www.qubes-os.org/doc/admin-api/) ( [alternate version?](https://current-qubes-docrtd.readthedocs.io/en/latest/developer/services/admin-api.html)), the detailed explanation of what they actually do does not appear to be well documented. NOTE: the table should have 6 columns. If you do not see 6 columns, then you need to scroll the table horizontally [details="Maybe still useful (since last edit)?"] What seems to be a partial list of the qubes.* policies/services can be found at: https://github.com/QubesOS/qubes-doc/blob/78b074236271586a3522caa2a793cc951cfe812d/developer/debugging/vm-interface.md?plain=1#L203 There is also a partial list of the policies/services in the filenames in this directory: https://github.com/QubesOS/qubes-core-admin/tree/b4df77dc253343f86f01b96c41f0bb732a88e268/qubes-rpc [/details] So this document will be split into a "how to try to figure it out" section, and a "best information/guesses so far for what they actually do" section. # Figuring out which policy/services the various qubes commands and widgets use: This section gives you some approaches on how to figure out what the various qubes commands (example "qvm-ls") and qubes widgets (example: the start menu) use. ## If you know the name of the policy/service and want to know what it does: |
| # | # Approaches to figure out what the policy/services do: |
| # Approaches to figure out | # Approaches to figure out which policy/services the various qubes commands and widgets use: |
| For example, we are able to find that it does not work for the "qubes domains" try icon in certain cases: There is a blue cube try icon in the tray in the upper left corer of the qubes screen. If you hover your mouse over it, it should display the text "qubes domains". We can find the filename of this application by running: `ps aux | grep '^user' | less` in dom0. Note the line `/usr/bin/bash /usr/bin/widget-wrapper qui-domains` which matches the hover text, so this line is probably it. You wont be able to run qui-domains from a normal qube like the "work" qube. They are normally only installed on dom0 and sys-gui type qubes. |
| ### | ### Possible future way to do it - logging?: It's possible there is a way to turn on debugging info for qrexec so we can get a log of all the details of all the actual requests coming in (including accepted ask and denied). (Currently the logs (including the systemd log) do not seem to provide any more detail then the notification messages whenever qubes denies a request (for example, provide both what computer the request was for **and** what computer the request got redirected to)) If this information was available and we were able to turn this on, one could just filter the log for the policy you are interested and try to correlate the timestamps to your qubes activites. Similarly, if this information was available we would be able to watch all qrexec calls happening every time we clicked a button and would start learning the policy names/API *really* quickly. Does anyone know if such a thing is possible? |
| - Try doing qrexec | - Try doing it as a qrexec call directly |
| ### You can try doing qrexec | ### You can try doing it as a qrexec call All qubes policies names are actually the name of a call to qrexec, so the method of trying qrexec calls should be comprehensive for all calls that get data (the effect of calls that set data may not be obvious :) From any qubes *other* then dom0, you can do qrexec calls via qrexec-client-vm. For example, lets say you are using a qube called "test-qube" and want to know what admin.vm.List does. In that case it would work by doing this: |
| ```
| ``` That command should fail, which you can fix by giving test-qube permissions to run that command by adding this line to dom0:/etc/qubes/policy.d/30-user.policy): ``` admin.vm.List * test-qube @adminvm allow target=@adminvm ``` After adding that policy run the command again and you should be able to figure out what it does from the results it returns. #### Possible future enhancement: Maybe there is a way to turn on debugging info for qrexec so we can get a log of **all** the details of **all** the actual requests coming in (accepted and denied)? Currently the logs (including the systemd log) do not seem to provide any more detail then the notification messages whenever qubes denies a request |
| - Try doing qrexec calls directly | |
| - Try doing qrexec calls directly | |
| ### You can try doing qrexec calls From any qubes *other* then dom0, you can do qrexec calls. For example, by doing things like ``` qrexec-client-vm work admin.vm.List < /dev/null ``` {Todo: add the policy here with a target=dom0 on it} Maybe there is a way to turn on debugging info for qrexec so we can get a log of the actual requests coming in? Currently the logs (including the systemd log) do not seem to provide any more detail then the notification messages whenever qubes denies a request | |
| ### You can try doing qrexec calls From any qubes *other* then dom0, you can do qrexec calls. For example, by doing things like ``` qrexec-client-vm work admin.vm.List < /dev/null ``` {Todo: add the policy here with a target=dom0 on it} Maybe there is a way to turn on debugging info for qrexec so we can get a log of the actual requests coming in? Currently the logs (including the systemd log) do not seem to provide any more detail then the notification messages whenever qubes denies a request |
| ## | ## You know the command you will want to run, but dont know the policy name to give it permissions: |
| `qubes.VMShell * {current qube} work allow`
| `qubes.VMShell * {current qube} work allow` |
| While the same procedure as is listed above for CLI commands may work for some graphical qubes apps, some of the time, there are cases where it does not work as one might hope. One case of this is when running in sys-gui. ##### ignore this subsection for now: documenting one specific graphical application |
| The following things are included in | The following things are included in this page: - If you know the name of the call: |
| Summary: sys-gui-vnc's #1 use seems to be as a debugging tool. To use it for remote administration is possible, but requires special setup. | Summary: sys-gui-vnc's #1 use seems to be as a debugging tool. To use it for remote administration is possible, but requires special setup. #### This was accidently pasted in the middle of aprevious paragraph... What was this supposed to be referencing?? :) (same with `qrexec-client-vm dom0 admin.label.List`) Obviously qubes needs `admin.vm.List` to operate, so qrexec is working, there is just some kind of missing information on how to interact with it |
| In the current policy format (as of 2024-10-29), each policy begins with a name. For example, one usable name is: `qubes.vm.List` ## Names of all the available policies: Each policy will be backed by some code that will run somewhere, either in dom0 or in a qube. You can see all the policy options (services) that can run on dom0 by doing this in dom0: ``` ls /etc/qubes-rpc/ ``` While that shows the policy options that can be run on dom0, that still leaves all the policy options that can be run on the various qubes. They can be seen by running on dom0 things like: ``` qvm-run --pass-io sys-whonix 'ls /etc/qubes-rpc/' ``` To see you list of all the possible policies that can be run on your current system running this in dom0 will show you a list of all the possible commands that will show you policy options in various qubes. ``` qvm-ls --fields=NAME --raw-list | xargs -I $$ echo qvm-run --pass-io $$ 'ls /etc/qubes-rpc/' ``` If you have enough memory on your system to run every qube on your system at the same time (which is probably less then 1% of users, (so dont actually run this one)), you could remove the word "echo" and sort it to get all full list of all the non-dom0 policy options, by doing this in dom0: ``` qvm-ls --fields=NAME --raw-list | xargs -I $$ qvm-run --pass-io $$ 'ls /etc/qubes-rpc/' | sort | uniq -c ``` I don't expect you to actually do that one, but am just showing you that it's possible to do something like that. (you are welcome to add a discussion below in the comment of a better way of extracting that information) As you view the policies available on the qubes, you'll end up noting that most qubes will have the same basic policy options, and a couple of the qubes might have a few extras. (like whonix qubes, and any that you installed extra qubes support for (example: whonix-bookmarks or "open in qube" [TODO: add some github links so people understand what I'm talking about]) Now we have a complete list of all the names of the options for policies you can write. [[[ Can someone confirm what I just said? ]]] Now while we have the names of the policies/services document now, it still would also be nice to know what they actually do! :slight_smile: ## Attempting to use documentation to get hints on what all the policies/services actually do | |
| You can see all the whonix related policies available by listing the whonix templates. Assuming your templates are named whonix-gateway-17 and whonix-workstation-17, the following would reveal the names to you: ``` qvm-run --pass-io whonix-gateway-17 'ls /etc/qubes-rpc/' qvm-run --pass-io whonix-workstation-17 'ls /etc/qubes-rpc/' ``` Currently the whonix policies are named: |
| This is the best information we have so far. If you have any better/more information, please contribute it in a comment below! | |
| Setting this policy: ``` admin.vm.List * {qube1} {qube2} allow target=dom0 ``` | |
| Most of | Most of the qubes.* policies (maybe all of them?) are for functions that are actually carried out in some way by the target qube itself. (for example, copying a file to the qube requires the qube to actually do something, as opposed to admin.* policies that just provide information about the qube, that the qube itself does not necicarly have). Rarely would these need a "target=dom0" at the end of them. |
| ## Proposed Section Headers #### admin.* policies: Administrative commands. Any policies intending to allow this will need either a "target=dom0" at the end or a "target=@adminvm" at the end #### admin.vm.* policies: A vm is the same thing as a qube which is the same thing as a domain. They are first column that is output when you run `qvm-ls` in dom0 #### admin.vm.feature.* policies: A feature is what gets listed when you type `qvm-features {qube name} in dom0`. The output is quite sparse though. You can find a much more complete list of features in the man page (I.E. run "man qvm-features in dom0) #### admin.vm.properties.* policies: A property is the same thing as a preference. It is what gets listed when you type `qvm-prefs {qube name} in dom0`. #### admin.label.* policies: A label is probably referencing a "security label". You can see the available security labels in qubes by adding this policy to /etc/qubes/policy.d/30-user.policy: | |
| #### policy.* policies: Administrative functions relating to viewing or setting the policies themselves - any policies intending to allow this will need either a "target=dom0" at the end or a "target=@adminvm" at the end #### qubes.* policies: Most of these (all of these?) are functions that are actually carried out in some way by the target qube itself. (for example, copying a file to the qube requires the qube to actually do something, as opposed to admin.* policies that just provide information about the qube, that the qube itself does not necicarly have). Rarely would these need a "target=dom0" at the end of them. #### whonix.* policies: These are obviously whonix related functions of some form. NOTE: note that the whonix.* policies are *not* listed in /etc/qubes-rpc/ . Some whonix polices are: * whonix.GatewayCommand * whonix.NewStatus * whonix.SdwdateStatus (of course this does not explain what the above policies *do*) |
| The following things are included in | The following things are included in twillhis page: |
| admin.* - Administrative commands - any policies intending to allow this will need either a "target=dom0" at the end or a "target=@adminvm" at the end
admin.vm.* - A vm is the same thing as a qube which is the same thing as a domain. They are first column that is output when you run `qvm-ls` in dom0
admin.vm.feature.* - A feature is what gets listed when you type `qvm-features {qube name} in dom0`. The output is quite sparse though. You can find a much more complete list of features in the man page (I.E. run "man qvm-features in dom0)
admin.vm.properties.* - A property is the same thing as a preference. It is what gets listed when you type `qvm-prefs {qube name} in dom0`.
admin.label.* - A label is probably referencing a "security label". | **admin.*** - Administrative commands - any policies intending to allow this will need either a "target=dom0" at the end or a "target=@adminvm" at the end **admin.vm.*** - A vm is the same thing as a qube which is the same thing as a domain. They are first column that is output when you run `qvm-ls` in dom0 **admin.vm.feature.*** - A feature is what gets listed when you type `qvm-features {qube name} in dom0`. The output is quite sparse though. You can find a much more complete list of features in the man page (I.E. run "man qvm-features in dom0) **admin.vm.properties.*** - A property is the same thing as a preference. It is what gets listed when you type `qvm-prefs {qube name} in dom0`. **admin.label.*** - A label is probably referencing a "security label". You can see the available security labels in qubes by adding this policy to /etc/qubes/policy.d/30-user.policy: ``` admin.lable.List * {name of qube} dom0 allow ``` then in the qube that you named in the policy, doing: ``` qrexec-client-vm dom0 admin.label.List < /dev/null ``` as of 2024-10-29, the labels available are: * 0_red * orange * yellow * green * gray * blue * purple * black (this may change in the future) **policy.*** - Administrative functions relating to viewing or setting the policies themselves - any policies intending to allow this will need either a "target=dom0" at the end or a "target=@adminvm" at the end **qubes.*** - Most of these (all of these?) are functions that are actually carried out in some way by the target qube itself. (for example, copying a file to the qube requires the qube to actually do something, as opposed to admin.* policies that just provide information about the qube, that the qube itself does not necicarly have). Rarely would these need a "target=dom0" at the end of them. **whonix.*** - These are obviously whonix related functions of some form. NOTE: note that the whonix.* policies are *not* listed in /etc/qubes-rpc/ |
| admin.* - Administrative commands - | admin.* - Administrative commands - any policies intending to allow this will need either a "target=dom0" at the end or a "target=@adminvm" at the end |
| admin.label.* - A label is probably referencing a "security label". Currently in qubes the only thing assigned to a label is the color the qube. (source: https://dev.qubes-os.org/projects/core-admin-client/en/latest/_modules/qubesadmin/label.html ) policy.* - Administrative functions relating to viewing or setting the policies themselves - any policies intending to allow this will need either a "target=dom0" at the end or a "target=@adminvm" at the end qubes.* - Most of these (all of these?) are functions that are actually carried out in some way by the target qube itself. (for example, copying a file to the qube requires the qube to actually do something, as opposed to admin.* policies that just provide information about the qube, that the qube itself does not necicarly have). Rarely would these need a "target=dom0" at the end of them. whonix.* - These are obviously whonix related functions of some form. NOTE: note that the whonix.* policies are *not* listed in /etc/qubes-rpc/ |
| (same with `qrexec-client-vm dom0 admin.label.List`) Obviously qubes needs `admin.vm.List` to operate, so qrexec is working, there is just some kind of missing information on how to interact with it | |
| admin.* - Administrative commands - all of these will need either a "target=dom0" at the end or a "target=@adminvm" at the end |
| qrexec-client-vm work admin.vm. | qrexec-client-vm work admin.vm.List < /dev/null |
| {Todo: add the policy here with a target=dom0 on it} |
| While the names of the policies/services have been documented [list of the names of the policy/service calls](https://www.qubes-os.org/doc/admin-api/) ( [alternate version?](https://current-qubes-docrtd.readthedocs.io/en/latest/developer/services/admin-api.html)), the detailed explanation of what they actually do does not appear to be well documented. | The names of all the policies/services appear to be listable by doing `ls /etc/qubes-rpc/` in dom0 While the names of the policies/services are documented there, it would also be nice to know what they do! :slight_smile: actually it looks like they are missing the whonix.* policies, so that list might not be complete. Some of the policies have been partially documented here: [list of the names of the policy/service calls](https://www.qubes-os.org/doc/admin-api/) ( [alternate version?](https://current-qubes-docrtd.readthedocs.io/en/latest/developer/services/admin-api.html)), the detailed explanation of what they actually do does not appear to be well documented. |
| [details="Maybe still useful (since last edit)?"] | |
| [/details] |
| What seems to be a partial list of the qubes.* policies/services can be found at: https://github.com/QubesOS/qubes-doc/blob/78b074236271586a3522caa2a793cc951cfe812d/developer/debugging/vm-interface.md?plain=1#L203 | |
| There are also whonix.* policies
| What seems to be a partial list of the qubes.* policies/services can be found at: https://github.com/QubesOS/qubes-doc/blob/78b074236271586a3522caa2a793cc951cfe812d/developer/debugging/vm-interface.md?plain=1#L203 There is also a partial list of the policies/services in the filenames in this directory: https://github.com/QubesOS/qubes-core-admin/tree/b4df77dc253343f86f01b96c41f0bb732a88e268/qubes-rpc Maybe it would be possible to write a script that git clones all the qubes repos and extracts the list of current serivces? There are also whonix.* policies |
| NOTE: the table should have 6 columns. If you do not see 6 columns, then you need to scroll the table horizontally | NOTE: the table should have 6 columns. If you do not see 6 columns, then you need to scroll the table horizontally What seems to be a partial list of the qubes.* policies/services can be found at: https://github.com/QubesOS/qubes-doc/blob/78b074236271586a3522caa2a793cc951cfe812d/developer/debugging/vm-interface.md?plain=1#L203 It would be nice to find a full list of the qubes.* policies There are also whonix.* policies And its not obvious if there are more policy.* policies then is listed in the first link. |
| admin.vm.* - A vm is the same thing as a qube which is the same thing as a domain. They are | admin.vm.* - A vm is the same thing as a qube which is the same thing as a domain. They are first column that is output when you run `qvm-ls` in dom0 |
| | `admin.vm.property.Set +{property} {qube1} {qube2} allow` | Verified: Allow qube1 to set the property {property} for qube2 (verified by inserting a deny policy for admin.property.Set (due to crashing issue)) (note: you have to actually type the + before the property, it's not a meta characte) | | `admin.vm.property.Set * {qube1} {qube2} allow` | Allow qube1 to set *any* property listed by qvm-prefs for qube2 (same as above, just using a wildcard) | | We should probably group them, and then put in section headers like: admin.vm.* - A vm is the same thing as a qube which is the same thing as a domain. They are what is output when you run `qvm-ls` in dom0 admin.vm.feature.* - A feature is what gets listed when you type `qvm-features {qube name} in dom0`. The output is quite sparse though. You can find a much more complete list of features in the man page (I.E. run "man qvm-features in dom0) admin.vm.properties.* - A property is the same thing as a preference. It is what gets listed when you type `qvm-prefs {qube name} in dom0`. admin.label.* - A label is probably referencing a "security label". Currently in qubes the only thing assigned to a label is the color the qube. (source: https://dev.qubes-os.org/projects/core-admin-client/en/latest/_modules/qubesadmin/label.html ) |
| but even when you set the policy to allow it, the above still returns nothing. | but even when you set the policy to allow it, the above still returns nothing. and going: ``` qrexec-client-vm dom0 admin.vm.List ``` just seems to hang when you give it permission. (same with `qrexec-client-vm dom0 admin.label.List`) Obviously qubes needs `admin.vm.List` to operate, so qrexec is working, there is just some kind of missing information on how to interact with it Maybe there is a way to turn on debugging info for qrexec so we can get a log of the actual requests coming in? Currently the logs (including the systemd log) do not seem to provide any more detail then the notification messages whenever qubes denies a request |
| Note: this page is intended to collect all related information to what the individual qubes policies mean Hopefully it'll be a wiki that everyone can add to. Please contribute any information that you may have on the definitions of the policies. | Note: this page is intended to collect all related information to what the individual qubes policies mean Hopefully it'll be a wiki that everyone can add to. Please contribute any information that you may have on the definitions of the policies. The following things are included in this page: - If you know the name of the call - Searching the source code - Try doing qrexec calls directly - You know what you want to do, but dont know the name: - Just try it and read notifications - Just try it using sys-gui - Just try it using a sys-gui-vnc with no networking enabled and read notifications (much faster) |
| qrexec-client-vm | qrexec-client-vm work admin.vm.List |
| [Open question: Is it mentioned anywhere what people should do to learn qubes that we can point to? | [Open question: Is it mentioned anywhere what people should do to learn qubes that we can point to? Things like how it's preferable to learn and make your mistakes on a system that does not have security critical data on it, and not on a security critical production system?] |
| From any qubes *other* then dom0, you can do qrexec | From any qubes *other* then dom0, you can do qrexec calls. For example, by doing things like ``` qrexec-client-vm {qube2} admin.vm.List ``` but even when you set the policy to allow it, the above still returns nothing. |
| While the names of the policies/services have been documented [list of the names of the policy/service calls](https://current-qubes-docrtd.readthedocs.io/en/latest/developer/services/admin-api.html), the detailed explanation of what they actually do does not appear to be well documented. | While the names of the policies/services have been documented [list of the names of the policy/service calls](https://www.qubes-os.org/doc/admin-api/) ( [alternate version?](https://current-qubes-docrtd.readthedocs.io/en/latest/developer/services/admin-api.html)), the detailed explanation of what they actually do does not appear to be well documented. |