Plugin Manager
About
The plugin manager is a new page for managing your VNS3 plugins. It is currently in Beta. We welcome all feedback. Let us know with a support ticket.
Beta released with VNS3 version 5.X.X.
Alpha released with VNS3 version 4.X.X.
The plugin manager provides a interface for accomplishing the following tasks:
- View all firewall rules related to this running plugin’s IP address
- Create common firewall rules for your plugin like SSH,internet access and port maps
- Edit and revert plugin configuration files located inside your running plugin container
- Run process commands for the main executable inside your plugin
- View plugin logs
Manager Configuration
Currently the plugin manager expects a plugin configuration file located inside the running container. This config file should be placed at /opt/plugin-manager/config.json. The configuration file should have the following form:
{
"log_files": [
{
"path": "/opt/app/logs/app.log",
"description": "Basic app output"
}
],
"configuration_files": [
{
"name": "Main config",
"path": "/opt/app/conf/config.json",
},
{
"name": "Other",
"path": "/opt/app/conf/other.json"
}
],
"ports": [
{
"port": 4444,
"protocol": "tcp",
"ui": true,
"ssl": false,
"ui_path": "/login"
}
],
"process_manager": {
"name": "supervisor",
"subprocesses": [
"ui",
"app"
]
},
"executables": [{
"path": "/opt/app/bin/manage",
"commands": {
"start": "start",
"stop": "stop",
"restart": "restart",
"status": "status"
}
}]
}
Fields
- log_files - List of objects with the following fields. These can then be viewed via the UI or API.
- path - Full path in the plugin to the log file
- description - Human readable description of log file contents
- configuration_files - List of objects with the following fields. These can then be viewed and edited via the UI or API.
- name - Name of the configuration file for this plugin. e.g. nginx.conf
- path - Full path to the configuration file. e.g. /etc/nginx/nginx.conf
- description - Human readable description of configuration file
- ports - List of objects with the following fields. These can then be viewed and mapped via the UI or API.
- port - Port number
- protocol - Protocol for this port, e.g. tcp or udp
- ui - true/false. If UI is true, Plugin manager will provide a link
- ssl - true/false. Use HTTPS for UI
- ui_path - Path for UI. defaults to “/”
- process_manager - if yor plugin container’s main process (PID 1 keeping the container running) is a common management control system such as supervisord, you can enter subprocesses for action execution from the Plugin manager
- name - currently we support
supervisorandservicecommands. Note, service commands wrap systemctl or init.d depending on the underlying OS - subprocesses - list of names of programs/processes managed by the process manager
- name - currently we support
- executables - List of objects. If the main process that runs this plugin’s functionality has an executable for common commands like start and stop, you can provide that information here. We will expose a UI and API for running these executable commands. For instance, you might have supervisord manage a process that is started with
/opt/app/bin/manage start.- path - Path to the excutable
- commands - This object expects the following keys:
start,stop,restartandstatus.- start - Command to pass to the executable to start the process
- stop - Command to pass to the executable to stop the process
- restart - Command to pass to the executable to restart the process
- status - Command to pass to the executable to get the process’s status
Fields supported in Alpha, removed in Beta
- ui_port - if the plugin exposes a UI on a port, you can provide that here. We will provide a link in the UI if a port mapping exists for this port.
- ui_port_ssl - use https for UI link
- executable - Replaced with “executables” for supporting more than 1 executable.
Field specs updated in Beta
- process_manager - The process manager key now expects an object with the specification provided above
- ports - Port objects now support
ui,sslandui_pathfields
Plugin Manager UI
Currently, the plugin’s management UI can only be accessed when the plugin is running and the running plugin has a configuration file located at /opt/plugin-manager/config.json.
You can access the plugin manager UI by navigating to the plugin’s container page: Containers > Click your running plugin > From the actions drop down, click “Manage”. This will only show up on the container’s page, it will not show in the container list page.
The functionality appearing on your plugin management page will depend on your manager configuration file. Here’s a UI based on the configuration file provided above.
Managing Plugin Firewall
The manager page allows you to view all firewall rules related to your plugin. You can view these rules by clicking “Manage” under Firewall.
There are some common firewall rules used for plugins. The manager UI provides an interface for creating these rules. They include:
- Internet - Granting the plugin access to the internet
- SSH - Directing SSH traffic to your plugin so you can SSH into the running plugin
- Port mapping Directing traffic to your plugin from VNS3 for any port and protocol
For more complex firewall requirements, the full firewall can be viewed and edited at /firewall in the VNS3 App.
Plugin Internet Access Rule
To create a firewall rule allowing your plugin access to the internet, click “Manage” under Firewall in the left column of the page.
If the plugin does not already have an internet access rule, you will see a button “Create internet rule”. Click “Create internet rule”.
Advanced
The rule we use to grant internet access to your firewall looks like the following:
MACRO_CUST -o eth0 -s <Plugin IP>/32 -j MASQUERADE
This rule is a little permissive (but likely totally fine). If you’d like to add a more restrictive policy, you can do so with the following 2 rules:
POSTROUTING_CUST -o eth0 -s <Plugin IP>/32 -j SNAT --to <VNS3 public IP or private IP>
FORWARD_CUST -s <Plugin IP>/32 -j ACCEPT
This only forwards along your specific running plugin’s traffic.
Plugin SSH Access Rule
To create a SSH rule allowing you to SSH into your plugin, click “Manage” under Firewall in the left column of the page.
If the plugin does not already have a SSH rule, you will see a button “Create SSH rule”. Click “Create SSH rule”.
You can then view the SSH rule to use by clicking “SSH”, located at the bottom of the left column.
Advanced
The rule we use to grant internet SSH is a simply DNAT rule that looks like the following:
PREROUTING_CUST -i eth0 -p tcp -s 0.0.0.0/0 --dport 44 -j DNAT --to 198.51.100.2:22
We select an unused port to map to your plugin’s port 22. In this example, it is port 44.
Port Mapping
Requires the ports key in the manager configuration file.
If your plugin runs a process on a particular port, you can map traffic from VNS3 to your running plugin container. For example, if my plugin is running a process listening on port 9000 for TCP traffic, I can create a port mapping rule so TCP traffic sent to VNS3 port 9000 will be forwarded on my plugin’s port 9000.
Under Ports, click “Map port” for the port you would like to create a port mapping rule for. A form will display for creating your rule:
- Enter the VNS3 server’s port you’d like to map
- Enter the container port you’d like to direct traffic for (this will default to the port selected)
- Enter the protocol this rule should apply to. For example, TCP.
Click “Create firewall rule”
Advanced
The firewall rule we create is a simple DNAT rule that maps all protocol traffic sent to the VNS3 port provided on to the container port. The rule looks something like this:
PREROUTING_CUST -i eth0 -p tcp -s 0.0.0.0/0 --dport 9000 -j DNAT --to 198.51.100.2:9000
If you’d like to lock down the source of your traffic, you can do so view the Firewall page.
Editing Plugin Conf Files
Requires the configuration_files key in the manager configuration file.
You can edit plugin configuration files directly from the UI. In the column on the right your configuration files will load automatically. Click “Edit” to edit your conf file. Once done, click “Save new version”. This will reload the page.
Note: You may need to restart your container for the new conf file to be loaded by your plugin
Reverting a conf file
If you have create a few new versions of your conf file, you may find you’d like to revert to an earlier version. Simply click “Revert to version” for the version you’d like to revert to. This will cause the page to reload and the new Current Version will reflect your reversion.
Executing Commands
Requires the executable key in the manager configuration file.
You can execute commands from the UI. In the left column, under Process > Executable > Commands there will be a button for each command provided in the configuration. Click on the command you want to execute. In the modal that appears, click “Run:
View Plugin Logs
Requires the log_files key in the manager configuration file.
You can view your plugin’s internal log files directly from the plugin manager UI. From the left column under Logging you will see each of the log files defined in your plugin configuration file. To view each log, click “View” for the corresponding log.
