Using the Plugin Server¶
This server implements an API server using rest-like API endpoints. The server is implemented in Python using aiohttp. The server has various configuraiton options, which you should be familiar with. These options and formats are described in the Configuration document.
Endpoints and Routes¶
A route is a path the server uses to retrieve and serve data from a plugin. For example, /systeminfo would be a route.
An endpoint is the full path for the request, e.g.,
https://server.domain.tld:port/systeminfo.
Requests made to an endpoint, invokes the server’s route handler, which is typically a plugin which returns data to the server, which, in turn, returns data to the device making the request.
File Endpoints¶
If the fileserver plugin is enabled, endpoints within the file server’s base request paht, are served as files.
Features¶
Plugins¶
Plugins perform the API handling for the server and create the API endpoints. When the server recives a request, the path portion of the URL is the endpoint, and, the server uses that path to route the request to the appropriate plugin. Plugins are discussed in detail in the Plugins section.
Plugin Utilities¶
The server sets up a few API endpoints to allow for managing plugins. When authentication is configured, the global apikey is used to authenticate these utilities.
These are the Plugin Utilities:
Route |
Usage |
|---|---|
|
Retrieves a list of active plugins |
|
Reloadss a plgin |
|
Reloads all plugins |
|
todo: load a plugin while the server is running |
When reloading the plugin utilities the config file is re-read and any changes will be reflected in the reloaded plugin.
Security¶
Security is managed a few different ways. The first is to set up SSL. Please see the section on SSL for details on configuring SSL.
Authentication¶
There are a few ways to authenticate the server operations. Please see Authentication for details.
Static File Service¶
As this is a server based on plugins, the server component that serves static files is implemented as a plugin. Thus, the server be configured to serve static files. For configuration and operational details please see the File Server section.
Principle of Operation¶
Startup¶
On startup the server reads the configuration file and looks for the optional SSL and CORS settings. If these settings are enabled and configured properly, they are enabled.
The [paths] section of the configuration is checked for the plugins key and loads any Python files there as plugins.
Operation¶
Once the server is configured it listens to the port on the bindto address in the configuration file. Each plugin is serviced by a route. The server and route become an API endpoint, which looks like http[s]://server.domain.tld:port/<plugin>. Making a request to this endpoint will return a JSON object by the server.
The server will run until terminated by ^C, SIGTERM or SIGKILL.
Prograam Control¶
In addition to the Plugin Utilities, the server itself can be reloaded with a SIGHUB signal. On Startup the server prints its PID. So do restart it you can run
kill -HUP <pid>
Program Termination¶
This will let the server gracefully shutdown and restart. The program will gracefully terminate on SIGINT, SIGTERM and SIGABRT.