5e0cc42ab2
1) "action"="list_categories" (optional argument: "repo"). This will list all the known categories within the given repository (local repository used by default if none specified). WARNING: Just because a category is listed from here does not mean there are packages existing within that category. This might be corrected later on to only return categories where packages reside. 2) "action"="list_repos" (no other arguments). This will scan the pkg repo config files and return any repos that pkg is currently aware of. NOTE: All of the repos returns by this function are valid as the optional "repo" argument for the other sysadm/pkg API calls. API Call #1: REST Request: ------------------------------- PUT /sysadm/pkg { "repo" : "local", "action" : "list_categories" } WebSocket Request: ------------------------------- { "id" : "fooid", "args" : { "action" : "list_categories", "repo" : "local" }, "namespace" : "sysadm", "name" : "pkg" } Response: ------------------------------- { "args": { "list_categories": [ "ports-mgmt", "x11", "gnome", "textproc", "devel", "python", "misc", "print", "graphics", "security", "x11-fonts", "lang", "ipv6", "perl5", "converters", "math", "x11-toolkits", "sysutils", "dns", "net", "accessibility", "databases", "shells", "x11-themes", "multimedia", "audio", "www", "ftp", "net-im", "archivers", "comms", "java", "deskutils", "kde", "mail", "editors", "emulators", "games", "irc", "japanese", "news", "x11-servers", "tk", "net-mgmt", "ruby", "x11-drivers", "x11-wm", "x11-clocks", "kld", "tcl", "enlightenment", "linux" ] }, "id": "fooid", "name": "response", "namespace": "sysadm" } API Call #2 REST Request: ------------------------------- PUT /sysadm/pkg { "action" : "list_repos" } WebSocket Request: ------------------------------- { "id" : "fooid", "namespace" : "sysadm", "name" : "pkg", "args" : { "action" : "list_repos" } } Response: ------------------------------- { "args": { "list_repos": [ "local", "pcbsd-major" ] }, "id": "fooid", "name": "response", "namespace": "sysadm" }
Table of Contents generated with DocToc
SysAdm
Official repo for PC-BSD's sysadm middleware WebSocket & REST server
This middleware acts as the core for controlling a PC-BSD or FreeBSD
system either locally or remotely via WebSockets or REST. It is also the
server component to PC-BSD's SysAdm GUI client.
Required Qt Modules
Qt5 Core (pkg install qt5-core)
Qt5 Concurrent (pkg install qt5-concurrent)
Qt5 Websockets (pkg install qt5-websockets)
Building SysAdm
% git clone https://github.com/pcbsd/sysadm.git
% cd sysadm/src
% /usr/local/lib/qt5/bin/qmake -recursive
% make && sudo make install
Starting SysAdm
(For WebSockets - Required for SysAdm Client)
% sudo sysrc -f /etc/rc.conf sysadm_enable="YES"
% sudo service sysadm start
(Optional for REST)
% sudo sysrc -f /etc/rc.conf sysadm_rest_enable="YES"
% sudo service sysadm-rest start
API Documentation
Contributing new API calls
SysAdm is written using the Qt toolkit, which has excellent reference documentation.
All Qt Core classes (I.E. non-gui) can be used in SysAdm server.
Adding new API calls to the middleware is very straight-forward, simply
add a new function which accepts JSON in, and returns JSON, then connect
it to the backend.
Example:
4d3b590f46
Adding new Classes for API calls
Adding a new API class requires tweaking a few more files than a new API call only.
Example:
1ba65b3388
Testing new API calls / classes
Before committing or sending a pull request, you'll need to run our
"api-test.sh" script and confirm it works properly. To do so, first add
your new call and restart the websocket server. Next do the following:
% cd sysadm/tests
% ./api-test.sh
The api-test script will prompt you to enter username, password, and some
information about which class / API call to run. When that is done, and you
have verified the functionality of your new call you should add the output
of the test script (either from copy-n-paste, or from the file /tmp/api-response)
to your commit. (This will allow us to document the new call / class)