mirror of
https://github.com/outbackdingo/sysadm.git
synced 2026-01-27 10:20:26 +00:00
511 lines
30 KiB
ReStructuredText
511 lines
30 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 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** | **<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"
|
|
}
|
|
|
|
Two types of queries are available for retrieving information from the PKG database:
|
|
|
|
+----------------+-------------------------------------------------+---------------------------------------------------------------------------------------------------------------+
|
|
| **Query Type** | **Command** | **<info> Syntax** |
|
|
| | | |
|
|
+================+=================================================+===============================================================================================================+
|
|
| General | "pkg <jail> <info>" | "remotelist", "installedlist", "hasupdates" (true/false returned), or "updatemessage" |
|
|
| | | |
|
|
+----------------+-------------------------------------------------+---------------------------------------------------------------------------------------------------------------+
|
|
| Individual | "pkg <jail> <local/remote> <pkg origin> <info>" | "origin", "name", "version", "maintainer", "comment", "description", "website", "size", "arch", "message", |
|
|
| | | "dependencies", "rdependencies", "categories", "options", "license" |
|
|
| | | |
|
|
+----------------+-------------------------------------------------+---------------------------------------------------------------------------------------------------------------+
|
|
|
|
Note that <local> is used for installed applications while <remote> is for information available on the global repository and might not match what is currently installed. For <local>
|
|
pkg queries, there are some additional <info> 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: "<pkg/pbi> search <search term> [<pkg jail>/<pbi filter>] [result minimum]".
|
|
|
|
When performing a search, note that:
|
|
|
|
* The search query 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 and is independent of what is actually available or installed. <pkg> searches all available and installed packages. whether or
|
|
not they are designed for end-users.
|
|
|
|
* <pkg jail> may only be used for pkg searches and corresponds to normal <jail> syntax (using "#system" or jail ID). If a jail is not specified, it assumes a search for the
|
|
local system (#system).
|
|
|
|
* <pbi filter> 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"
|
|
}
|