mirror of
https://github.com/outbackdingo/sysadm.git
synced 2026-01-27 10:20:26 +00:00
511 lines
28 KiB
ReStructuredText
511 lines
28 KiB
ReStructuredText
.. _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 *<jail>* 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" : "<message"
|
|
}
|
|
}
|
|
|
|
.. _Dispatcher Usage:
|
|
|
|
Dispatcher Usage
|
|
----------------
|
|
|
|
Dispatcher requests use the following parameters:
|
|
|
|
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
|
|
| **Parameter** | **Value** | **Description** |
|
|
| | | |
|
|
+=================================+===============+======================================================================================================================+
|
|
| id | | any unique value for the request; examples include a hash, checksum, or uuid |
|
|
| | | |
|
|
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
|
|
| name | dispatcher | |
|
|
| | | |
|
|
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
|
|
| namespace | rpc | |
|
|
| | | |
|
|
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
|
|
| args | | values vary by type of request |
|
|
| | | |
|
|
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
|
|
|
|
The following arguments are supported:
|
|
|
|
* iocage {cmd} [args]
|
|
|
|
* queue {pkg|pbi} {origin} {install/delete/info} {__system__|<jailname>}
|
|
|
|
* pkgupdate {__system__|<jailname>}
|
|
|
|
* service {start|stop|restart} {servicetag} {servicerc} {__system__|<jid>}
|
|
|
|
* getcfg {pbicdir} {__system__|<jid>} {key}
|
|
|
|
* setcfg {pbicdir} {__system__|<jid>} {key} {value}
|
|
|
|
* donecfg {pbicdir} {__system__|<jid>}
|
|
|
|
* 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 |
|
|
| | |
|
|
+---------------------------------+----------------------------------------------------------------------------------------------------------------------+
|
|
| <jail> app-summary <pkg origin> | Summary of information for an application |
|
|
| | |
|
|
+---------------------------------+----------------------------------------------------------------------------------------------------------------------+
|
|
| cage-summary <origin> | 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...<br>Your system is up to date!"
|
|
},
|
|
"id": "someUniqueID",
|
|
"name": "response",
|
|
"namespace": "rpc"
|
|
}
|
|
|
|
.. _PBI Database Queries:
|
|
|
|
PBI Database Queries
|
|
--------------------
|
|
|
|
The following query types are supported when gathering information about installed applications/PBIs. Use the required syntax in the *args* parameter of the request.
|
|
|
|
+----------------+---------------------------------+------------------------------------------------------------------------------------------------------------------------+
|
|
| **Query Type** | **Command** | **<info> Syntax** |
|
|
| | | |
|
|
+================+=================================+========================================================================================================================+
|
|
| List | "pbi list <info>" | "[all/server/graphical/text]apps", "[all/server/graphical/text]cats", or "cages" |
|
|
| | | |
|
|
+----------------+---------------------------------+------------------------------------------------------------------------------------------------------------------------+
|
|
| App | "pbi app <pkg origin> <info>" | "author", "category", "confdir", "dependencies", "origin", "plugins, "rating", "relatedapps", "screenshots", |
|
|
| | | "type", "tags", "comment", "description", "license", "maintainer", "name", "options", or "website" |
|
|
| | | |
|
|
+----------------+---------------------------------+------------------------------------------------------------------------------------------------------------------------+
|
|
| Cage | "pbi cage <origin> <info>" | "icon", "name", "description", "arch" fbsdver", "git", "gitbranch", "screenshots", "tags", "website" |
|
|
| | | |
|
|
+----------------+---------------------------------+------------------------------------------------------------------------------------------------------------------------+
|
|
| Category | "pbi cat <pkg category> <info>" | "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"
|
|
}
|
|
|
|
|
|
.. _PKG Database Information:
|
|
|
|
PKG Database Information
|
|
------------------------
|
|
|
|
General Queries: "pkg <jail> <info>" where <info> can be: "remotelist", "installedlist", "hasupdates" (true/false returned), or "updatemessage".
|
|
|
|
Individual pkg queries: "pkg <jail> <local/remote> <pkg origin> <info>"
|
|
|
|
.. _note: "local" is used for installed applications while "remote" is for information available on the global repository and might not match what is currently installed.
|
|
|
|
<info> may be: "origin", "name", "version", "maintainer", "comment", "description", "website", "size", "arch", "message", "dependencies", "rdependencies", "categories", "options", "license"
|
|
|
|
For "local" pkgs, there are some additional <info> options: "timestamp", "isOrphan", "isLocked", "files", "users", and "groups"
|
|
|
|
**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"
|
|
}
|
|
|
|
.. _Search Capabilities:
|
|
|
|
Search Capabilities
|
|
-------------------
|
|
|
|
Query Syntax: "<pkg/pbi> search <search term> [<pkg jail>/<pbi filter>] [result minimum]
|
|
|
|
The search always returns an array of <pkg origin>, organized in order of priority where the first element is highest priority and the last element is the lowest priority.
|
|
|
|
"pbi" probes the PBI database of end-user applications (independent of what is actually available/installed), whereas "pkg" searches all available/installed packages. whether they are
|
|
designed for end-users or not.
|
|
|
|
The "<pkg jail>" option may only be used for pkg searches and corresponds to normal <jail> syntax (using "#system" or jail ID). If it is not supplied, it assumes a search for the local
|
|
system (#system).
|
|
|
|
The "<pbi filter>" option 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 that option is not supplied).
|
|
|
|
The "result minimum" is the number of results the search should try to return (10 by default). 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 getting 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"
|
|
}
|