Plugin Configuration & Installation

Plugin install

install_cp_plugin https://example.com/plugin_name.zip

This page describes the configuration required to add a 3rd-party plugin by php to OLSPanel. The configuration file should be included in the root zip file of the plugin.

Example Configuration File

# The Display name.
name=RoundCube webmail

# The application's service.
service=user_panel

# Physical path: /usr/local/lsws/Example/html/mypanel/3rdparty/index.php
# Literal URL path: $server:$port/3rdparty/plugin_folder/name/index.php
url=/3rdparty/roundcube/index.php
auto_login_url=/3rdparty/roundcube/?_task=login

# Pass parameters via HTTP headers
header[HTTP_AUTOLOGINUSER]=%email%
header[HTTP_AUTOLOGINPASS]=%email_password%

# System user and group to run process as
user=$authuser
group=$authuser

# Features required
features=mail

# Media required
icon=/media/icon/roundcube.png

# Short order
sorder=0

target=_blank

# System user and group to run process as second path optional
user2=root
group2=root
path2=auto_index.php

Configuration Fields

Field	Description	Usage / Notes
name	The display name of the plugin as shown in the panel.	Example: `RoundCube webmail`
service	The type of panel service this plugin belongs to.	Common values: `user_panel`, `admin_panel`. Determines access and available actions.
url	Physical path of the plugin relative to the panel root.	Example: `/3rdparty/roundcube/index.php`. This must point to the plugin’s main PHP entry file.
auto_login_url	URL used for automatic login to the plugin.	Example: `/3rdparty/roundcube/?_task=login`. This URL will be accessed using credentials passed via HTTP headers.
header[]	HTTP headers sent to the plugin for auto-login.	Can include any of these placeholders: `%email%` – user email `%email_password%` – email password `%username%` – panel username `%userid%` – panel user ID `%dbinfo%` – database connection info `%usertoken%` – secure user token Example: `header[HTTP_AUTOLOGINUSER]=%email%` `header[HTTP_AUTOLOGINPASS]=%email_password%`
user / group	System user and group under which the plugin PHP process runs.	Can use `$authuser` (panel system user), `nobody`, or any valid system user/group. Ensures correct file permissions and process ownership.
user2 / group2	System user and group under which the plugin PHP process runs for sparte path.	Can use `$authuser` (panel system user), `nobody`, or any valid system user/group. path2=auto_index.php Ensures correct file permissions and process ownership.
features	Required system features or capabilities for the plugin.	Supported features (lowercase): `domains`, `files`, `security`, `database`, `email`, `mail`, `advance`, `software`. Multiple features can be comma-separated: `features=mail,email`
target	Open links in a new browser tab.	To make a link open in a new tab, use the HTML attribute `target= _blank` inside your tag.
icon	Path to the plugin icon to display in the panel interface.	Example: `/media/icon/roundcube.png`
display_hide	Controls whether the plugin should be shown or hidden in the interface. If set to `true`, the plugin will not appear in the list.	Example: `display_hide = true`

Usage

After adding the plugin configuration in the root zip file and uploading it to OLSPanel, the plugin will appear in the 3rd-party section of the panel. Auto-login will use the provided headers if configured.

Notes

Ensure the url path matches the actual location of the plugin files.
Header placeholders like %email%, %username%, etc. will be replaced automatically by OLSPanel during login.
Set user and group to the panel user or nobody if necessary for permissions.

Plugin Configuration File

Each plugin requires a corresponding configuration file with the extension .conf. The system automatically detects the plugin’s nickname from the plugin name specified inside the configuration file. By convention, the configuration file should be named as plugin_<nickname>.conf, for example, plugin_roundcube.conf. This file must be placed inside the panel’s root directory, alongside the plugin’s main entry file (e.g., index.php).

The plugin icon file must also reside in the root of the plugin ZIP archive and must be named following the convention plugin_icon.png, for example, plugin_icon.png. This ensures the panel can automatically display the icon in the plugin listing.

Example directory structure for the RoundCube plugin:

zip/
├── index.php
├── plugin_roundcube.conf
├── plugin_icon.png

The system will automatically read the configuration file to determine the plugin’s display name, service, headers, and other settings required for proper integration and auto-login.

Display Links

The system automatically detects plugin links from JSON files placed inside the plugin/ directory. Each file must have a .json extension — for example, wordpress_link.json or cms_links.json.

Every JSON file can contain either:

Single object — one plugin link definition
Array of objects — multiple plugin links in one file

The system automatically handles both formats.

✅ Example JSON (multiple plugin entries)

[
  {
    "icon": "/media/icon/wordpress.png",
    "order": -1,
    "name": "Install WordPress",
    "url": "/3rdparty/olsapp/indexb.live.php?view=install&app=wordpress",
    "features": "database",
    "service": "user_panel",
    "target": "_blank"
  },
  {
    "icon": "/media/icon/joomla.png",
    "order": 1,
    "name": "Install Joomla",
    "url": "/3rdparty/olsapp/indexb.live.php?view=install&app=joomla",
    "features": "database",
    "service": "user_panel",
    "target": "_blank"
  }
]

You can also use a single plugin entry file, for example:

{
  "icon": "/media/icon/php.svg",
  "order": 10,
  "name": "PHP Info",
  "url": "/phpinfo/",
  "features": "system",
  "service": "admin_panel",
  "target": "_self"
}

The following fields are supported:

name — Display name of the plugin link
icon — Icon URL or path shown in the panel
url — Full or relative link target
order — Sort order (lower numbers appear first)
features — Optional feature tag (e.g. database, system)
service — Optional service scope (admin_panel, user_panel, or both)
target — Optional link target (e.g. _blank for new tab)
display_hide — If set to true, the plugin will be hidden

📁 Example Directory Structure


plugin/
├── cms_links.json
├── wordpress_link.json
├── custom_admin.json

The system automatically loads and merges all valid JSON files from this directory. Each file is read only once, and hidden entries (display_hide=true) are skipped.

Module Development Guide (Python / Django)

OLSPanel supports dynamic module creation using the Django framework. Each module can extend the Admin and User dashboards with its own templates and views. To learn how to create and integrate your own module, visit the detailed development guide below:

👉 Open OLSPanel Module Development Guide

This guide includes examples for:

Folder structure under modules/
Django views and URL configuration
Using @alogin_required and @login_required
Rendering home_right.html and admin_home_top.html