From 428e8d93b04fcd40d5e28f4f005583879b873ee9 Mon Sep 17 00:00:00 2001 From: dlavigne Date: Mon, 28 Mar 2016 10:23:34 -0400 Subject: [PATCH] Prep for changes to pkg class. --- api/classes/packages.rst | 510 --------------------------------------- api/classes/pkg.rst | 6 + api/connection.rst | 61 ++++- 3 files changed, 63 insertions(+), 514 deletions(-) delete mode 100644 api/classes/packages.rst create mode 100644 api/classes/pkg.rst diff --git a/api/classes/packages.rst b/api/classes/packages.rst deleted file mode 100644 index 31991a4..0000000 --- a/api/classes/packages.rst +++ /dev/null @@ -1,510 +0,0 @@ -.. _packages: - -packages -******** - -Resources related to the packages class. - -.. _webclient: - -webclient -========= - -The webclient resource is used to... - -For up-to-date request options, use :command:`help [pkg | pbi | jail | search]` to query the sysadm daemon for the available options for the specified parameter. This section covers most -of the common queries and replies. - -.. _note: whenever ** is used in a query, it can be replaced by - *#system* to probe the local system or by a jail ID for to specify a particular jail on the system. - -.. _Event Notifications: - -Event Notifications -------------------- - -The dispatcher provides support for the client to subscribe to per-connection event notifications. Event requests use the following parameters: - -+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -| **Parameter** | **Value** | **Description** | -| | | | -+=================================+===============+======================================================================================================================+ -| id | | any unique value for the request; examples include a hash, checksum, or uuid | -| | | | -+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -| name | subscribe | use the desired action | -| | unsubscribe | | -+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -| namespace | events | | -| | | | -+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -| args | dispatcher | | -| | | | -+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ - -To subscribe from dispatcher events: - -.. code-block:: json - - { - "namespace" : "events", - "name" : "subscribe", - "id" : "sampleID", - "args" : ["dispatcher"] - } - -To unsubscribe from dispatcher events: - -.. code-block:: json - - { - "namespace" : "events", - "name" : "unsubscribe", - "id" : "sampleID", - "args" : ["dispatcher"] - } - -This response indicates that a dispatcher event occurred: - -.. code-block:: json - - { - "namespace" : "events", - "name" : "event", - "id" : "", - "args" : { - "name" : "dispatcher", - "args" : "} - -* pkgupdate {__system__|} - -* service {start|stop|restart} {servicetag} {servicerc} {__system__|} - -* getcfg {pbicdir} {__system__|} {key} - -* setcfg {pbicdir} {__system__|} {key} {value} - -* donecfg {pbicdir} {__system__|} - -* daemon - -* status - -* results - -* log {hash} - -.. _General sysadm Information: - -General sysadm Information --------------------------- - -Queries for information from the sysadm daemon use the following parameters: - -+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -| **Parameter** | **Value** | **Description** | -| | | | -+=================================+===============+======================================================================================================================+ -| id | | any unique value for the request; examples include a hash, checksum, or uuid | -| | | | -+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -| name | sysadm | | -| | | | -+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -| namespace | rpc | | -| | | | -+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -| args | | comma delimited list of information to request | -| | | | -+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ - -The following *args* are supported. Note that -*"app-summary"* and -*"cage-summary"* are specifically designed for getting enough information for lots of small app icons in fewer sysadm requests. - -+---------------------------------+----------------------------------------------------------------------------------------------------------------------+ -| **Value** | **Description** | -| | | -+=================================+======================================================================================================================+ -| startsync | Manually start a system information sync (usually unnecessary) | -| | | -+---------------------------------+----------------------------------------------------------------------------------------------------------------------+ -| needsreboot | Check if the system needs to reboot to finish updates | -| | | -+---------------------------------+----------------------------------------------------------------------------------------------------------------------+ -| isupdating | Check if the system is currently performing updates | -| | | -+---------------------------------+----------------------------------------------------------------------------------------------------------------------+ -| hasupdates | Check if system updates are available | -| | | -+---------------------------------+----------------------------------------------------------------------------------------------------------------------+ -| updatelog | Raw text output from the check for system updates | -| | | -+---------------------------------+----------------------------------------------------------------------------------------------------------------------+ -| hasmajorupdates | Check if FreeBSD system updates are available | -| | | -+---------------------------------+----------------------------------------------------------------------------------------------------------------------+ -| majorupdatelog | Details about the major update(s) | -| | | -+---------------------------------+----------------------------------------------------------------------------------------------------------------------+ -| hassecurityupdates | Check if FreeBSD security updates are available | -| | | -+---------------------------------+----------------------------------------------------------------------------------------------------------------------+ -| securityupdatelog | Details about any security update(s) | -| | | -+---------------------------------+----------------------------------------------------------------------------------------------------------------------+ -| haspcbsdupdates | Check if any PC-BSD hotfixes are available | -| | | -+---------------------------------+----------------------------------------------------------------------------------------------------------------------+ -| pcbsdupdatelog | Details about any PC-BSD hotfixes | -| | | -+---------------------------------+----------------------------------------------------------------------------------------------------------------------+ -| app-summary | Summary of information for an application | -| | | -+---------------------------------+----------------------------------------------------------------------------------------------------------------------+ -| cage-summary | Summary of information for a PBI cage | -| | | -+---------------------------------+----------------------------------------------------------------------------------------------------------------------+ - -**Request** - -.. code-block:: json - - { - "namespace" : "rpc", - "name" : "sysadm", - "id" : "someUniqueID", - "args" : ["needsreboot", "hasupdates", "updatelog", "#system app-summary mail/thunderbird", "cage-summary multimedia/plexmediaserver"] - } - -As seen in the following example response, the *"app-summary"* return array is: - -* pkg origin -* name -* version -* icon path -* rating (out of 5) -* type -* comment -* configuration directory -* isInstalled -* canRemove - -The *"cage-summary"* return array is: - -* origin -* name -* icon path -* architecture -* FreeBSD version - -**Response** - -.. code-block:: json - - { - "args": { - "#system app-summary mail/thunderbird": [ - "mail/thunderbird", - "Thunderbird", - "38.2.0_1", - "/var/db/pbi/index/mail/thunderbird/icon.png", - "5.00", - "Graphical", - "Mozilla Thunderbird is standalone mail and news that stands above ", - "/var/db/pbi/index/mail/thunderbird", - "true", - "true" - ], - "cage-summary multimedia/plexmediaserver": [ - "multimedia/plexmediaserver", - "Plex Media Server", - "/var/db/pbi/cage-index/multimedia/plexmediaserver/icon.png", - "amd64", - "10.1-RELEASE" - ], - "hasupdates": "false", - "needsreboot": "false", - "updatelog": "Checking for FreeBSD updates...
Your system is up to date!" - }, - "id": "someUniqueID", - "name": "response", - "namespace": "rpc" - } - -.. _PBI Database Queries: - -PBI and PKG Database Queries ----------------------------- - -The following query types are supported when gathering information about installed PBIs. Use the required command and its syntax in the *args* parameter of the request. - -+----------------+---------------------------------+------------------------------------------------------------------------------------------------------------------------+ -| **Query Type** | **Command** | ** Syntax** | -| | | | -+================+=================================+========================================================================================================================+ -| List | "pbi list " | "[all/server/graphical/text]apps", "[all/server/graphical/text]cats", or "cages" | -| | | | -+----------------+---------------------------------+------------------------------------------------------------------------------------------------------------------------+ -| App | "pbi app " | "author", "category", "confdir", "dependencies", "origin", "plugins, "rating", "relatedapps", "screenshots", | -| | | "type", "tags", "comment", "description", "license", "maintainer", "name", "options", or "website" | -| | | | -+----------------+---------------------------------+------------------------------------------------------------------------------------------------------------------------+ -| Cage | "pbi cage " | "icon", "name", "description", "arch" fbsdver", "git", "gitbranch", "screenshots", "tags", "website" | -| | | | -+----------------+---------------------------------+------------------------------------------------------------------------------------------------------------------------+ -| Category | "pbi cat " | "icon", "name", "origin", "comment" | -| | | | -+----------------+---------------------------------+------------------------------------------------------------------------------------------------------------------------+ - -Here is an example of a list and an app query which request five types of information: - -.. code-block:: json - - { - "namespace" : "rpc", - "name" : "sysadm", - "id" : "someUniqueID", - "args" : ["pbi list graphicalapps", "pbi list cages", "pbi app www/firefox author", "pbi app www/firefox category", "pbi list graphicalcats" ] - } - -And its response: - -.. code-block:: json - - { - "args": { - "pbi app www/firefox author": "Mozilla", - "pbi app www/firefox category": "Web", - "pbi list cages": [ - "archivers/elephantdrive", - "multimedia/plexmediaserver" - ], - "pbi list graphicalapps": [ - "math/R", - "www/WebMagick", - "editors/abiword", - "audio/abraca", - (SHORTENED FOR BREVITY - THIS IS USUALLY QUITE LONG) - "x11/zenity", - "security/zenmap", - "games/zephulor", - "www/zope213" - ], - "pbi list graphicalcats": [ - "accessibility", - "archivers", - "astro", - "audio", - (SHORTENED FOR BREVITY - THIS IS USUALLY QUITE LONG) - "x11-themes", - "x11-toolkits", - "x11-wm" - ] - }, - "id": "someUniqueID", - "name": "response", - "namespace": "rpc" - } - -Here is an example of a category query and its response: - -.. code-block:: json - - { - "namespace" : "rpc", - "name" : "sysadm", - "id" : "someUniqueID", - "args" : ["pbi cat www name", "pbi cat www icon", "pbi cat www comment", "pbi cat www origin" ] - } - -**Response** - -.. code-block:: json - - { - "args": { - "pbi cat www comment": "Web browsers, and other applications used for the web such as RSS readers", - "pbi cat www icon": "/var/db/pbi/index/PBI-cat-icons/www.png", - "pbi cat www name": "Web", - "pbi cat www origin": "www" - }, - "id": "someUniqueID", - "name": "response", - "namespace": "rpc" - } - -Here is an example of a cage query and its response: - -.. code-block:: json - - { - "namespace" : "rpc", - "name" : "sysadm", - "id" : "someUniqueID", - "args" : ["pbi cage multimedia/plexmediaserver tags", "pbi cage multimedia/plexmediaserver website", "pbi cage multimedia/plexmediaserver description", "pbi cage multimedia/plexmediaserver name"] - } - -**Response** - -.. code-block:: json - - { - "args": { - "pbi cage multimedia/plexmediaserver description": "Plex stores all of your audio, video, and photo files in your free Plex Media Server so you can access them from all your devices and stream from anywhere.", - "pbi cage multimedia/plexmediaserver name": "Plex Media Server", - "pbi cage multimedia/plexmediaserver tags": "streaming, multimedia, server", - "pbi cage multimedia/plexmediaserver website": "https://plex.tv" - }, - "id": "someUniqueID", - "name": "response", - "namespace": "rpc" - } - -Two types of queries are available for retrieving information from the PKG database: - -+----------------+-------------------------------------------------+---------------------------------------------------------------------------------------------------------------+ -| **Query Type** | **Command** | ** Syntax** | -| | | | -+================+=================================================+===============================================================================================================+ -| General | "pkg " | "remotelist", "installedlist", "hasupdates" (true/false returned), or "updatemessage" | -| | | | -+----------------+-------------------------------------------------+---------------------------------------------------------------------------------------------------------------+ -| Individual | "pkg " | "origin", "name", "version", "maintainer", "comment", "description", "website", "size", "arch", "message", | -| | | "dependencies", "rdependencies", "categories", "options", "license" | -| | | | -+----------------+-------------------------------------------------+---------------------------------------------------------------------------------------------------------------+ - -Note that is used for installed applications while is for information available on the global repository and might not match what is currently installed. For -pkg queries, there are some additional options: "timestamp", "isOrphan", "isLocked", "files", "users", and "groups". - -When specifying a jail, precede the jail's name with a *#*: - -**Request** - -.. code-block:: json - - { - "namespace" : "rpc", - "name" : "sysadm", - "id" : "someUniqueID", - "args" : ["pkg #system installedlist", "pkg #system local mail/thunderbird version", "pkg #system remote mail/thunderbird version", "pkg #system local mail/thunderbird files" ] - } - -**Response** - -.. code-block:: json - - { - "args": { - "pkg #system installedlist": [ - "graphics/ImageMagick", - "devel/ORBit2", - "graphics/OpenEXR", - (SHORTENED FOR BREVITY - THIS GETS QUITE LONG) - "archivers/zip", - "devel/zziplib" - ], - "pkg #system local mail/thunderbird files": [ - "/usr/local/bin/thunderbird", - "/usr/local/lib/thunderbird/application.ini", - "/usr/local/lib/thunderbird/blocklist.xml", - "/usr/local/lib/thunderbird/chrome.manifest", - (SHORTENED FOR BREVITY - THIS GETS QUITE LONG) - "/usr/local/share/applications/thunderbird.desktop", - "/usr/local/share/pixmaps/thunderbird.png" - ], - "pkg #system local mail/thunderbird version": "38.2.0_1", - "pkg #system remote mail/thunderbird version": "38.2.0_1" - }, - "id": "someUniqueID", - "name": "response", - "namespace": "rpc" - } - -Both PBIs and PKGs support the following search query syntax: " search [/] [result minimum]". - -When performing a search, note that: - -* The search query always returns an array of , organized in order of priority where the first element is highest priority and the last element is the lowest priority. - -* probes the PBI database of end-user applications and is independent of what is actually available or installed. searches all available and installed packages. whether or - not they are designed for end-users. - -* may only be used for pkg searches and corresponds to normal syntax (using "#system" or jail ID). If a jail is not specified, it assumes a search for the - local system (#system). - -* may only be used for PBI searches to restrict the type of application being looked for, and may be "all" "[not]graphical", "[not]server", and "[not]text". The - default value is "all" if no option is supplied. - -* [result minimum] is the number of results the search should try to return, where 10 is the default when not specified. The search is done by putting all the apps into various priority - groups, and only the highest-priority groups which result in the minimum desired results will be used. For example, if the search comes up with grouping of 3-highest priority, - 5-medium priority, and 20-low priority, then a minimum search of 2 will only return the highest priority group, a minimum search of 4 will return the highest and medium priority - groups, and a minimum of 9+ will result in all the groups being returned. - -**Request** - -.. code-block:: json - - { - "namespace" : "rpc", - "name" : "sysadm", - "id" : "someUniqueID", - "args" : ["pbi search \"thun\" ", "pbi search \"thun\" text", "pkg search \"thun\""] - } - -**Response** - -.. code-block:: json - - { - "args": { - "pbi search \"thun\" ": [ - "x11-fm/thunar", - "mail/thunderbird", - "www/thundercache", - "www/thundersnarf", - "x11/alltray", - "deskutils/gbirthday", - "audio/gtkpod", - "www/libxul" - ], - "pbi search \"thun\" text": "www/thundersnarf", - "pkg search \"thun\"": " " - }, - "id": "someUniqueID", - "name": "response", - "namespace": "rpc" - } diff --git a/api/classes/pkg.rst b/api/classes/pkg.rst new file mode 100644 index 0000000..b6376ea --- /dev/null +++ b/api/classes/pkg.rst @@ -0,0 +1,6 @@ +.. _pkg: + +pkg +*** + +Resources related to the packages class. \ No newline at end of file diff --git a/api/connection.rst b/api/connection.rst index a411577..532f290 100644 --- a/api/connection.rst +++ b/api/connection.rst @@ -228,11 +228,66 @@ revoke a certificate belonging to another user. Dispatcher Subsystem ==================== -The dispatcher subsystem is designed for running external utilities or scripts in an asynchronous fashion. Any connected client may receive notifications about dispatcher processes through -the events system, but only users in the *wheel* group have the authority to directly submit new jobs for the dispatcher. +The dispatcher subsystem is designed for running external utilities or scripts in an asynchronous fashion. Any connected client can subscribe to per-connection event notifications about +dispatcher processes through the events system, but only users in the *wheel* group have the authority to directly submit new jobs for the dispatcher. .. note:: other subsystems may also use the dispatcher for long-running processes in the background, and these subsystems may allow non-wheel group users to perform these tasks as necessary. +The user needs to first subscribe to "dispatcher" event notifications: + ++---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ +| **Parameter** | **Value** | **Description** | +| | | | ++=================================+===============+======================================================================================================================+ +| id | | any unique value for the request; examples include a hash, checksum, or uuid | +| | | | ++---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ +| name | subscribe | use the desired action | +| | unsubscribe | | ++---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ +| namespace | events | | +| | | | ++---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ +| args | dispatcher | | +| | | | ++---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ + +For example, to subscribe to dispatcher events: + +.. code-block:: json + + { + "namespace" : "events", + "name" : "subscribe", + "id" : "sampleID", + "args" : ["dispatcher"] + } + +To unsubscribe from dispatcher events: + +.. code-block:: json + + { + "namespace" : "events", + "name" : "unsubscribe", + "id" : "sampleID", + "args" : ["dispatcher"] + } + +This response indicates that a dispatcher event occurred: + +.. code-block:: json + + { + "namespace" : "events", + "name" : "event", + "id" : "", + "args" : { + "name" : "dispatcher", + "args" : "