Skip to content

Home

Jump to bottom Edit New page
OSPanel edited this page Jun 4, 2024 · 409 revisions

Attention!

This documentation has been translated into English using machine technologies. The text may contain typos, inaccuracies and semantic errors.

Introduction

Open Server Panel is a powerful alternative to WAMP stacks like Xampp, Wampserver, Herd, EasyPHP, Vertrigo, and similar solutions. This application runs on the Windows operating system, supports Apache and Nginx as web servers, and provides the ability to run various versions of PHP, MySQL, PostgreSQL, MongoDB, and other popular modules. If you have experience with similar software, mastering Open Server Panel will be straightforward.

The application can be used in both stationary and portable modes. In portable mode, you can freely move the program folder across the disk or copy it to another computer. However, note that on older versions of Windows, full portability may be limited (due to the 255-character path limit). The package includes the System Preparation Tool, designed to prepare Windows for working with Open Server Panel. It requires administrator rights to run.

You can manage Open Server Panel in three ways:

  • Web interface (under development).
  • Command-line interface (CLI).
  • System tray menu.

Key Changes

Open Server Panel 6 is a completely redesigned product written from scratch.

Advantages of OSPanel 6

  • Full Customization: Users have full access to the settings of all modules.
  • Flexible Management: Management is carried out through the console, tray menu, or web interface (in development).
  • Reliable Process Control: Monitoring and automatic recovery after failures.
  • Parallel Module Operation: Ability to run all modules simultaneously, including launching multiple versions of the same module (e.g., MySQL 5.5 and MySQL 8.0).
  • Configuration Profiles: Creating profiles with individual module settings, including configurations and data.
  • Domain Personalization: Individual settings for each domain, from IP address to PHP version.
  • Built-in SSL and IPv6 Support: Works "out of the box" and does not require additional configuration.
  • Optimized Environment: Pre-configured environment for each module, including quick access to shell/cli.
  • Convenient Environment Switching: Instant switching between environments in the console.
  • Rich Set of PHP Extensions: Over 115 available extensions.
  • Built-in Functionality: Task scheduler and SMTP server.
  • Composer and Node.js: Managing Node.js versions with NVM. Composer is available in all PHP modules.
  • Improved Stability: No bugs, freezes, or encoding issues.
  • Accessibility: All settings, templates, language files, and documentation are available on GitHub.

Disadvantages of OSPanel 5

  • Limited PHP Compatibility: It is not possible to connect different PHP versions for different projects.
  • Lack of Environment Configuration: Inability to configure the environment of modules, which makes it difficult to work with them in the console.
  • Difficulties Adding Modules: Adding non-standard modules is impossible due to hardcoded launch commands in the program code.
  • Encoding Issues: Modules may not start due to incorrect encoding of configuration files in some Windows configurations.
  • Risk of Data Corruption: There is a possibility of database corruption when Windows shuts down.
  • Unstable Module Operation: The outdated method of launching modules negatively affects their stability.
  • Limited Set of PHP Extensions: Small selection of PHP extensions and limited Apache and PHP configuration options.
  • Lack of Checks: Insufficient checks of the file system and system settings.
  • Task Scheduler Failures: Failures are possible during prolonged operation of the task scheduler.
  • Compatibility Issues: Compatibility issues with new versions of Windows.
  • Outdated Code: Many other issues typical of outdated software.

Open Server Panel 6 is a significant step forward in the development of the platform, offering improved functionality, stability, and security. Upgrading to the new version is recommended for increased development efficiency.

System Requirements

For Open Server Panel to function properly, the following is required:

Component Requirements
Operating System Windows 10 (version 1607 or later), Windows Server 2016 or later.
32-bit systems are not supported.
Versions for Linux and MacOS are not available.
Hardware Resources At least 3 GB of RAM and 10 GB of free disk space.
Required Software MSVC++ 2005-2022 Redistributable Packages (x86/x64, included).
File System NTFS (network drives are not supported).

Note: With limited RAM (less than 3 GB), it may be necessary to limit the number of modules running simultaneously. On low-performance computers, it is recommended to run no more than one module of each type at a time.

Support for Legacy Operating Systems

Open Server Panel can run on older versions of Windows (x64), but with some limitations:

  • Not all modules are available.
  • File paths cannot exceed 255 characters.
Operating System Version Number Support Level
Windows 7 SP1 6.1.7601 Limited
Windows Server 2008 R2 SP1 6.1.7601 Limited
Windows Home Server 2011 6.1.8400 Limited
Windows Server 2012 6.2.9200 Limited
Windows 8 6.2.9200 Limited
Windows 8.1 6.3.9600 Limited
Windows Server 2012 R2 6.3.9600 Limited
Windows 10 v1507 10.0.10240 Limited
Windows 10 v1511 10.0.10586 Limited

Getting Started

Directory Structure

.
├── addons                    # Add-ons
│   └── <addon_name>          # Main addon directory
│       └── ospanel_data      # Service files (source settings and configurations)
├── bin                       # Common executable files
├── config                    # Settings
│   ├── <module_name>         # Module settings
│   │   ├── default           # Default profile directory
│   │   │   ├── templates     # Configuration templates
│   │   │   └── settings.ini  # Module settings for the Default profile
│   │   └── module.ini        # Basic module settings (on/off + profile name)
│   ├── menu.ini              # Menu settings
│   └── program.ini           # Program settings
├── data                      # Data storage (databases, etc.)
├── home                      # User projects (domains)
├── licenses                  # Licenses for third-party components
├── logs                      # Log files
│   ├── domains               # Project logs
│   └── mail                  # Mail storage
├── modules                   # Modules
│   └── <module_name>         # Main module directory
│       └── ospanel_data      # Service files (source settings and configurations)
├── system                    # Program service directory
│   └── lang                  # Language files
├── temp                      # Temporary files
└── user                      # User data
    └── ssl                   # Custom SSL files (keys, certificates, etc.)

Installation Recommendations

  • Operating System: For optimal performance, it is recommended to use Windows 10 or later.
  • Installation Location: Install Open Server Panel on an SSD drive, if available, to improve module performance.
  • Unsupported Configurations:
    • USB Flash Drives: It is not recommended to use USB flash drives to install Open Server Panel, as this can lead to rapid device wear and significantly reduce performance.
    • External Drives with USB 2.0: Using external storage devices with the outdated USB 2.0 interface is not recommended due to low data transfer speeds.

Installation

  1. Downloading the Distribution:

  2. Running the Installer:

    • It is recommended to install Open Server Panel to the root of a drive (for example, C:\OSPanel).
    • Allowed Characters in the Directory Path: A-Za-z0-9-+\_.\:
    • Portable Installation: Choose this option only if you plan to use Open Server Panel on different computers and are installing it on a portable drive. In other cases, standard installation is recommended.

  3. Running the System Preparation Tool:

    • After the installation is complete, run the System Preparation Tool. This utility requires administrator rights to run.
    • Exceptions: Running the System Preparation Tool is not required if you are only installing missing modules, and the same version of Open Server Panel is already installed.

  4. Configuring the Firewall/Antivirus:

    • Exceptions: Add the Open Server Panel directory to your firewall/antivirus exceptions.
    • Protecting the HOSTS File: If your firewall/antivirus is protecting the HOSTS file and ignoring added exceptions, disable this feature.

Important: Incorrect firewall/antivirus configuration can significantly reduce the performance of Open Server Panel. Constantly scanning files used by modules creates an additional load on the system. On older computers with HDD drives, this can lead to a serious drop in performance, making it practically impossible to work with Open Server Panel.

First Launch

Important: Running Open Server Panel with administrator rights is not recommended. This can pose a potential security risk and is not a requirement for the program to work.

  1. Launching the Program:

    • Launch Open Server Panel from the Start menu or manually by running the .\bin\ospanel.exe file (for portable installation).
    • Make sure the Open Server Panel icon appears in the Windows notification area.

  2. Analyzing Launch Errors (if necessary):

    • If the program does not start, check the log file: .\logs\general.log.
    • Common Web Server Errors:
      • Address already in use (#10048 in listen: Bind): The specified IP address and port are already in use by another application. Change the IP/port settings in the Open Server Panel configuration or in the settings of the conflicting application.
      • Permission denied (#10013 in listen: Bind): Permission to use the specified IP address and port is denied. Configure the system firewall to allow Open Server Panel network access.

  3. Launching the CLI Interface:

    • Open the CLI interface: Menu -> Command Line Interface.
    • Error The system cannot write to the specified device: Change the console font to one compatible with UTF-8 encoding (for example, Consolas) and restart the CLI interface.
    • Checking Logs: Run the command osp log general in the CLI interface to check for errors or warnings in the program log.

  4. Initializing the Root CA Certificate (if necessary):

    • If the root CA certificate was not created during installation, run the command osp cacert init in the CLI interface.

  5. Preparing the System (if necessary):

    • If the System Preparation Tool was not run during installation, run it using the command osp sysprep in the CLI interface.
    • Important: After completing the system preparation, be sure to restart your computer.

Warning: Open Server Panel will not work correctly without first preparing the system using the System Preparation Tool. Learn more about the utility's functions here.

Installing Additional Modules

To install additional modules, run the Open Server Panel installer again.

Using the Portable Version on Another Computer

When using the portable version of Open Server Panel on another computer, you need to install the root SSL certificate and prepare the system on that computer. To do this, launch the CLI interface and run the commands osp cacert init and osp sysprep.

Creating Projects

Setting Up Project Search Paths

  1. Open the Configuration File: .\config\program.ini

  2. Specify Paths to Projects:

    • In the projects_search_path parameter, list the drives or directories where your projects are located, separated by semicolons (;).
    • Allowed Characters: A-Za-z0-9-+_.\:
    • Example: projects_search_path = C:\OSPanel\home;D:\projects

  3. Save the changes and restart Open Server Panel.

Creating a Project Configuration File

  1. Create a Directory: In the root directory of each project, create a subdirectory named .osp.

  2. Create a Configuration File: Inside the .osp directory, create a file named project.ini with the following content:

    [domain_name]

    Replace [domain_name] with the desired domain name for your project.

Choosing the Server Configuration

After restarting Open Server Panel, you can select the desired PHP and Nginx versions for your projects through the program menu.

Web Server Organization Options:

  • Apache + PHP: Select only the PHP module for your project.
  • Nginx + Apache + PHP: Select the Nginx and PHP modules for your project. In this configuration, Nginx acts as a proxy server.
  • Nginx + PHP-FCGI: Select the Nginx and PHP-FCGI modules for your project.
  • Nginx Only (without PHP): Select only the Nginx module for your project.

Important:

  • To access the domain in a browser, you need to enable the corresponding PHP engine and/or Nginx engine.
  • Enable other modules required for your project to work.
  • PHP modules without the FCGI prefix are composite modules Apache-2.4.x + PHP-x.x.x and are named as such for ease of selection in the console.

Importing the Root SSL Certificate

If your browser does not use the Windows certificate store (for example, Firefox), manually import the Open Server Panel root certificate:

  1. Firefox: Settings -> Privacy & Security -> Certificates -> View Certificates... -> Authorities tab -> Import...
  2. Path to the Certificate: data\ssl\root\cert.crt

Important: Repeat the certificate import after each regeneration of the root certificate using the command osp cacert init.

Additional Information

  • Detailed information about project configuration is available here.
  • Examples of domains available by default after installing Open Server Panel can be found in the home directory.

Working in the Console

Choosing the Console

Open Server Panel uses CMD.exe (the standard Windows command-line interpreter) by default. To view environment variables and their values, use the set command.

Recommendation: For a more convenient and modern experience, it is recommended to install and use Windows Terminal. Windows Terminal is a new application for working with the command line that supports various shells, including Command Prompt, PowerShell, and WSL.

You can control the console selection using the use_win_terminal parameter in the configuration file.

Important:

  • PowerShell is not supported. Do not use PowerShell to work with Open Server Panel.
  • When using Windows Terminal, choose the "Command Prompt" profile, not "Windows PowerShell".

Management (CLI)

Usage: osp <command> [<arguments>]

Environment Management:

add     <MODULE|ADDON>      Merge the environment of the module/addon with the current environment
info                        Show information about the current environment
project <DOMAIN>   [start]  Activate the project environment and navigate to its root directory
                            Use [start] to launch the project (if configured)
reset   [init]              Reset the current environment (original system environment)
                            Use [init] to initialize the command line interface
use     <MODULE|ADDON>      Apply the environment of the specified module or addon
                            If the module is disabled, then working with some of its utilities or
                            commands, including working with data (databases), may be unavailable!

Module Management:

init    <MODULE> [PROFILE]  Reread module settings and recreate temporary files (configurations)
                            Specify a new active module settings profile if necessary
                            This command is not available for modules that are currently active!
                            Reapply the module environment (using the "use" or "add" command) if it
                            is currently active, and the settings or settings profile have changed!
off     <MODULE>            Disable the module
on      <MODULE> [PROFILE]  Enable the module (specify a new active profile if necessary)
restart <MODULE> [PROFILE]  Restart the module (specify a new active profile if necessary)
shell   <MODULE>            Launch the module's shell or command line interface (if available)
status  <MODULE>            Show module status information

Node.js Management:

node    install <N> [ARCH]  Install Node.js version. As version number <N> you can specify
                            a specific version, "latest" for the latest current version, or "lts"
                            for the latest LTS version. Set the [ARCH] parameter to 32 or 64 to
                            install the 32-bit or 64-bit version (default), or specify
                            "all" to install both versions simultaneously. To work with the
                            environment of the new Node.js, use the commands "osp use Node-x.x.x"
                            and "osp add Node-x.x.x", specifying the version number with a prefix.
node    list   [available]  Show a list of installed Node.js versions
                            Use the [available] flag to view available Node.js versions
node    mode    <N> [ARCH]  Show the current bitness of Node.js version <N>
                            Set [ARCH] to 32 or 64 to change the current bitness
node    node_mirror  [URL]  Set the node mirror. Default: https://nodejs.org/dist/
                            Leave [URL] blank to set the default URL
node    npm_mirror   [URL]  Set the npm mirror. Default: https://github.com/npm/cli/archive/
                            Leave [URL] blank to set the default URL
node    proxy        [URL]  Set the proxy server to use when downloading Node.js
                            Leave [URL] blank to view the current proxy
                            Set [URL] to "none" to disable the proxy
node    uninstall <N>       Uninstall a previously installed version of Node.js

Other Commands:

addons                      Show information about addons
cacert  <init|show|deinit>  Generate and install|show|remove the root certificate (CA)
                            When installing a new one, old root certificates (CA) will be deleted
convert <DOMAIN>            Convert domain name from/to Punycode
exit                        Terminate the program (the current environment will be reset)
log     <PATTERN> [N]       Show logs by file path filter (last N lines)
                            Use a regular expression to select the logs to display
                            Show all logs for the PHP-8.0 module: osp log php-8\.0
                            Show all domain access logs: osp log domains\\(.+)_access
                            Show all program logs: osp log "\\(general|api|scheduler|smtp)"
                            Show all available logs (last 15 lines): osp log . 15
modules                     Show information about modules
projects                    Show information about projects
status                      Show the status of all systems (tasks, domains, addons and modules)
sysprep [silent|ssd]        Run the operating system preparation tool
                            Add [silent] to run system preparation in silent mode
                            The [ssd] flag is similar to [silent] (with optimized settings for SSD)
                            Silent preparation occurs automatically and without progress tracking,
                            after the procedure is completed, a reboot will be performed!
tasks                       Show scheduler task information
version                     Show program version information

Usage examples:

osp exit & ospanel          Restart the program
osp use PostgreSQL-9.6      Applying the PostgreSQL-9.6 module environment in the console
osp on PHP-8.1 myprofile    Enabling PHP-8.1 module with changing the settings profile to MyProfile
osp restart mysql-8.0       Restarting the MySQL-8.0 module (the module name is case-insensitive)
osp reset & osp add bind    Merging the system environment with the Bind environment

Auxiliary Utilities:

aria2c                      Utility for downloading files via HTTP(S), (S)FTP and BitTorrent
bat                         Clone of cat (linux) with syntax highlighting and Git integration
brotli                      Open source lossless data compression utility
curl                        Command line tool for transferring data using URLs
dust                        A utility similar to du (linux), but more intuitive and understandable!
fd                          Simple and fast utility for finding records in the file system
gzip                        File compression and restoration utility using the Deflate algorithm
jq                          Lightweight and flexible command-line JSON processor
mmdbinspect                 A tool for finding records in one or more .mmdb databases
sass                        Dart Sass is a popular SASS/SCSS file compiler
sd                          An intuitive program for finding and replacing text in files
wget                        Non-interactive console program for downloading files over the network
xh                          Convenient and fast tool for sending HTTP requests

For the following CLI commands, the silent argument is available, which suppresses the output of all informational messages except warnings and error messages:

  • osp use ...
  • osp add ...
  • osp project ...
  • osp reset
  • osp reset init

For the osp reset init command, instead of the silent argument, you can use the noprint argument to suppress the output of environment information.

For the following CLI commands, you can use the all argument instead of the module name:

  • osp init
  • osp off
  • osp on
  • osp restart
  • osp status

Important: Only use the all argument if you are absolutely sure of your actions.

Process Environment

A process environment is a set of variables and their values that determine the behavior of the operating system and applications running in that environment. These variables are used to store information required by applications and to configure system parameters.

  • Each running process in the system has its own environment, so it is often referred to as the process environment.
  • In the console, use the set command to view environment variables and their values.

Environment Inheritance

Open Server Panel inherits the environment of the parent process (usually explorer.exe, i.e., the standard system environment) when it starts and retains it until it exits.

  • All processes launched by Open Server Panel through the menu, console (only for the "System" environment), or task scheduler also inherit this environment.
  • Important: If the environment settings in your system have changed while Open Server Panel is running, you may need to restart the program.

Isolated Module Environment

Open Server Panel modules run in their own isolated environment, which is formed as follows:

  1. System Environment Filtering: Variables not specified in the allowed_env_vars parameter of the configuration file are removed from the system environment.
  2. Adding Variables: Variables specified in the environment section of the Open Server Panel settings are added to the filtered environment.

Module Environment Management

  • Pre-Configured Environment: All Open Server Panel modules have a ready-to-use environment that can be activated with the osp use ... command.
  • Quick Launch of shell/cli: To launch the shell/cli shell of a module, use the osp shell ... command. No activation or attachment of the module environment is required.

Changing the Environment

The current environment is always displayed in the console window title (or tab name), for example: PHP-8.0 + MySQL-5.7 | Open Server Panel.

  • Combining Environments: Modules of different types can be combined into one environment using the osp add ... command.
  • Variable Name Conflicts: If variables with the same name exist in different environments, the final variable value is taken from the environment of the module that was connected last (except for the PATH variable, whose values are combined).
  • Switching Between Projects: To switch between projects in the console, use the osp project ... command, which activates the project environment (PHP/Nginx/Node + modules and add-ons specified by the environment option in the project.ini file) and navigates to its root directory (see project_dir).

Important: PHP modules are combined (except for modules with the FCGI prefix) and include Apache and PHP.

Enabling Multiple Modules

To run multiple modules simultaneously, use the osp on command for each module:

osp on Redis-7.0
osp on MySQL-5.7
osp on PHP-7.4

Important: For correct setting of the path to the temporary files directory (variables TMP and TEMP), connect the most important module last.

Combining Environments

Without PATH Variable Isolation

To combine the environments of several modules without isolation from the system PATH variable, use the following commands:

osp reset
osp add Redis-7.0
osp add MySQL-5.7
osp add PHP-7.4

With PATH Variable Isolation

To combine the environments of several modules with isolation from the system PATH variable, use the following commands:

osp use Redis-7.0
osp add MySQL-5.7
osp add PHP-7.4

Example Console Output

After executing the commands, you will see the following output in the console:

Redis-7.0: Module worker process started successfully
MySQL-5.7: Module worker process started successfully
PHP-7.4: Module worker process started successfully
Current environment: Redis-7.0
Current environment: Redis-7.0 + MySQL-5.7
Current environment: Redis-7.0 + MySQL-5.7 + PHP-7.4

Using the Combined Environment

Now you can work with PHP-7.4, Apache-2.4, MySQL-5.7, and Redis-7.0 simultaneously:

php -v
httpd -V
mysql -V
redis-cli -v

Working with Development Tools

Composer

  • Ready to Use: Composer is pre-installed and ready to use without additional configuration.
  • Environment Activation: To work with Composer in the console, activate the environment of any project or PHP module.
  • Isolated Versions: Each PHP module has its own version of Composer and a separate home directory.

Example of installing Zephir in PHP 7.4 using Composer:

  1. Enable the Extension: Uncomment the line extension=zephir_parser in the .\config\PHP-7.4\default\templates\php.ini file.
  2. Restart PHP: Run the command osp restart php-7.4 in the CLI interface (Menu -> Command Line Interface).
  3. Activate the Environment: Run the command osp use php-7.4.
  4. Install Zephir: 
    cd %COMPOSER_HOME%
composer require phalcon/zephir
  5. Verify Installation: Run the command zephir help.

NVM (Node Version Manager)

  • Built-in Tool: NVM is included in the Open Server Panel distribution and is installed as an add-on.
  • Working Through a Layer: Interaction with NVM is carried out through a special layer using the command osp node ....
  • Important:
    • Pay attention only to error messages from NVM.
    • Ignore NVM advice on using nvm ... commands - they are not available in Open Server Panel.
    • This NVM implementation is due to the fact that the original NVM does not support the simultaneous use of multiple versions of Node.js.

Recommendation: For convenient application launching, use nodemon. An example of using nodemon can be found here.

  • Configuring the Launch Command: Specify the application launch command in the project settings using the start_command parameter.
  • Example: start_command = nodemon app.js

Task Scheduler

The built-in task scheduler works similarly to the Cron daemon in Unix systems. Scheduler tasks are described in the <project>\.osp\tasks.ini file.

Important: To apply changes to the tasks.ini file, you must restart Open Server Panel.

  • Base Directory: All tasks are run in the base directory of the project (see base_dir).
  • Project Status: Tasks are not executed if the project is in the "Off" or "Error" state.

Section [domain_name]

Each section in the tasks.ini file describes a set of tasks for the project, the name of which is specified in the section title.

The task execution schedule consists of 7 columns separated by spaces. The columns specify the execution time and task settings (minute, hour, day, month, day of the week, limit, switch). The first 5 columns can contain a number, a list of numbers separated by commas, a range of numbers separated by a hyphen, the characters * or /. Columns 6-7 can only contain numbers and the * symbol.

* * * * * * * command
- - - - - - -
| | | | | | |
| | | | | | ----- enable/disable task (* or 1 - enabled, 0 - disabled)
| | | | | ------- limit on the number of launches (* or 0 - unlimited)
| | | | --------- day of the week (1-7)
| | | ----------- month (1-12)
| | ------------- day of the month (1-31)
| --------------- hour (0-23)
----------------- minute (0-59)

Examples:

15 14 1 * * * *       # execute on the 1st of every month at 14:15
0 22 * * 1-5 * *      # every weekday at 22:00
23 */2 * * * * *      # execute at 0:23, 2:23, 4:23, etc.
5 4 * * 7 * *         # execute at 4:05 on Sundays
15 10,13 * * 1,4 * *  # execute on Monday and Thursday at 10:15 and 13:15
* * * * * * *         # execute every minute
0-59/2 * * * * * *    # execute on even minutes
1-59/2 * * * * * *    # execute on odd minutes
*/5 * * * * * *       # execute every 5 minutes
* * * * * 1 0         # execute once after starting the program (task disabled)

You can use the following template variables in scheduled tasks:

Variable Description
{root_dir} Open Server Panel root directory (full path)
{root_drive} Root directory drive letter
{root_path} Path to the Open Server Panel root directory
{base_dir} Project base directory
{host} Domain name (Punycode is used for internationalized domain names)
{host_decoded} Visible domain name (without Punycode)
{nginx_engine} Nginx engine
{node_engine} Node.js engine
{php_engine} PHP engine
{project_dir} Project root directory
{project_url} Project URL
{public_dir} Project public directory
{start_command} Project launch command (if configured)
{terminal_codepage} Console encoding (see terminal_codepage)

In addition to template variables, you can use any Windows environment variables, for example: %COMSPEC%, %SYSTEMDRIVE%, %USERNAME%, %PATH%, etc.

Please note that if you need to execute a command within the project environment, you need to specify the path to cmd.exe (using the %COMSPEC% environment variable) and activate the project environment using osp project before executing the command itself.

Executing a Command in a Project Environment

To execute a command in a project environment:

  1. Specify the path to cmd.exe using the %COMSPEC% environment variable.
  2. Activate the project environment using the osp project command before executing the command.

Example of the tasks.ini file:

[example.local]

Launch Node App         = * * * * * 1 *      "%COMSPEC%" /c "osp project {host} start"
Backup                  = */5 * * * * * *    "%COMSPEC%" /c "tar -czf {base_dir}\.osp\backup\{host_decoded}.tar.gz -C {public_dir} *"
Laravel Schedule        = * * * * * * *      "%COMSPEC%" /c "osp project {host} & php artisan schedule:run"

[forum.example.local]

Call cron.php via HTTPS = */30 * * * * * 0   wget --secure-protocol=TLSv1_2 -q --no-cache https://{host}/cron.php -O nul
Call cron.php from PHP  = 0-59/2 * * * * * * "%COMSPEC%" /c "osp project {host} & php -f cron.php"
Backup                  = */5 * * * * 1 *    "%COMSPEC%" /c "tar -czf {base_dir}\.osp\backup\{host_decoded}.tar.gz -C {public_dir} *"

Example of a task with saving output to a file:

[my-project.loc]

Test Task               = * * * * * * *      "%COMSPEC%" /c "osp project {host} & php -f {base_dir}\script.php >> {base_dir}\log.txt"

In this example, the task will run every minute and execute the script.php script using the PHP engine selected for the project. The result of the script execution will be written to the log.txt file.

Working with Modules

Basic Principles

  • Modules are disabled by default: Before you start, enable the modules you need.
  • Parallel operation: Modules can be launched in parallel without conflicts.
  • Isolated environment: Each module runs in its own isolated environment, which prevents conflicts with other software.
  • Support for modules of the same type: You can run multiple versions of the same module simultaneously (for example, MySQL 5.5 and MySQL 8.0).
  • Local IP addresses: By default, all modules are configured to use only local IP addresses (except for Bind and Unbound).
  • Standard ports and credentials: Standard ports and logins are used. There are no default passwords or restrictions. These settings can be changed.

Important:

  • PostgreSQL and UAC: Launching PostgreSQL modules is not possible when User Account Control (UAC) is disabled or when Open Server Panel is run with administrator rights.
  • Security: Running Open Server Panel on public IP addresses without additional protection is extremely dangerous. This can lead to unauthorized access to your computer, up to and including complete control over the system and data loss.

Security recommendations:

  • Strong passwords: Set strong passwords for all users whenever possible.
  • Access restriction: Configure firewall rules, allowing access to modules only from trusted IP addresses.

Additional Features

  • Built-in mail server: A built-in mail server is available for all PHP modules. Emails sent from PHP are saved to the .\logs\mail directory.
  • Support for .user.ini: PHP FCGI modules support .user.ini files at the directory level. PHP looks for .user.ini in each directory, starting with the directory of the requested PHP file, and continues searching up to the root directory of the project. Only INI settings with INI_PERDIR and INI_USER modes are recognized in .user.ini files.

Module Initialization

  • When Open Server Panel starts, all available modules are initialized.
  • During initialization, the module configuration is checked and temporary files are created.
  • This allows you to use the console utilities and commands of the module, regardless of whether it is enabled or not.
  • Important: Some utilities and commands may not work if the module is disabled.

Initializing modules without enabling them can be useful for:

  • Restoring databases
  • Updating the data store
  • Checking temporary configuration files

Module Launch Scheme

The diagram below shows the module launch scheme in Open Server Panel:

%%{init: {'theme':'forest'}}%%
graph TD;

      A(Start<br>Open Server Panel)-->B(Module Initialization);
      B-->|"Fail"| C(Status<br>'Error');
      B-->|"Success"| D(Status Check);
      D-->|"If disabled"| F(Status<br>'Disabled');
      D-->|"If enabled"| G(Module Launch);
      G-->|"Fail"| C;
      G-->|"Success"| H(Status<br>'Enabled');
      H-->|"If process<br>unexpectedly terminates<br>during probation"| C;
      H-->|"If process<br>unexpectedly terminates"| G;

Description:

  1. Start Open Server Panel: When Open Server Panel starts, all available modules are initialized.
  2. Module Initialization: The module configuration is checked and temporary files are created.
  3. "Error" Status: If initialization fails, the module enters the "Error" state.
  4. Status Check: If initialization is successful, the module status is checked (enabled/disabled).
  5. "Disabled" Status: If the module is disabled, it remains in this state.
  6. Module Launch: If the module is enabled, it is launched.
  7. "Enabled" Status: If the launch is successful, the module enters the "Enabled" state.
  8. Process Termination During Probation: If the module process unexpectedly terminates during the probation period (see the probation parameter in the module settings), the module enters the "Error" state.
  9. Process Termination: If the module process unexpectedly terminates after the probation period, the module is restarted.

Connecting to Modules

To connect to modules from PHP scripts and third-party applications, use the following parameters:

  • Host: Module name (for example, MySQL-5.7). Case does not matter (mysql-5.7 or MYSQL-5.7 are also valid). You can add .local for compatibility with applications that require a domain name (for example, mysql-5.7.local).
  • Port: Standard port of the module.
  • User: Standard module user (if applicable).
  • Password: No password (if applicable).

Connection Examples

Module Host Port User Password
MySQL-5.7 MySQL-5.7, mysql-5.7, mysql-5.7.local 3306 root -
Memcached-1.6 Memcached-1.6 11211 - -
MongoDB-4.4 MongoDB-4.4 27017 - -
PostgreSQL-12 PostgreSQL-12 5432 postgres -
RabbitMQ-3.13 RabbitMQ-3.13 5672 - -
Redis-5.0 Redis-5.0 6379 - -
SMTP ospanel (see api_domain option) 25 - -

SMTP Server:

  • For the SMTP server to successfully process an email, the sent email must contain a FROM header.
  • If the FROM header is missing, activate and fill in the sendmail_from variable in the php.ini file template.

Important:

  • Do not use internal module IP addresses: Internal IP addresses are used only for internal module operation and are subject to change. They are not intended for connecting to modules.

Recommendation

It is recommended to use DBeaver as a universal database manager. DBeaver supports various types of databases (MySQL, MariaDB, PostgreSQL, SQLite), is regularly updated, and works stably.

PHP Extensions

Open Server Panel includes over 115 PHP extensions, which are disabled by default.

To enable an extension:

  1. Uncomment the corresponding line in the PHP configuration file template (php.ini).
  2. Restart the PHP module.

PHPINFO: PHP 7.2 | PHP 7.3 | PHP 7.4 | PHP 8.0 | PHP 8.1 | PHP 8.2 | PHP 8.3

Note: If an extension is not available for a particular version of PHP, it means that the extension developers do not provide, develop, or compile a Windows version for that version of PHP.

Extension Compatibility

Important:

  • Do not change the order of extensions in the php.ini file template. Extensions are connected in a certain order, depending on each other, and may not work if the activation order is changed.
  • Enable only the extensions you need. Activate an extension only if it is really required by your projects.
Extension Dependency Incompatibility
blackfire Caution! The extension may cause a memory leak. ioncube, opcache, opencensus, pcov, xdebug, xhprof
crypto openssl
ev openssl, sockets
event openssl, sockets
exif mbstring
http curl, intl, propro, psr, raphf, sockets
http_message psr
ioncube Caution! The extension may cause PHP to malfunction. blackfire, opencensus, pcov, xhprof, xdebug
libevent sockets
mailparse mbstring
memcached igbinare
oauth curl
opcache blackfire
Enabling xdebug or pcov disables JIT compilation.
opencensus blackfire, ioncube, pcov, xdebug, xhprof
pcov blackfire, ioncube, opencensus, xdebug, xhprof
phalcon curl, fileinfo, gd2, gettext,
imagick, mbstring, openssl, pdo
rdkafka simple_kafka_client
redis igbinary
simple_kafka_client rdkafka
solr curl
ssh2 openssl
stomp openssl
xdebug blackfire, ioncube, opencensus, pcov, xhprof
xhprof blackfire, ioncube, opencensus, pcov, xdebug
yac Simultaneous activation in multiple PHP modules is not allowed!
yar curl

Apache Modules

Open Server Panel uses Apache version 2.4.54 (VC15) for PHP 7.2-7.4 and Apache version 2.4.59 (VS17) for PHP 8.0-8.3. The distribution includes additional Apache modules listed in the table below.

Module Version Link
mod_antiloris 0.6.0 https://www.monshouwer.eu/download/mod_antiloris/
mod_apreq2 2.16 https://httpd.apache.org/apreq/docs/libapreq2/group__mod__apreq2.html
mod_authn_ntlm 1.0.8 https://github.com/YvesR/mod_authn_ntlm
mod_fcgid 2.3.10 https://httpd.apache.org/mod_fcgid/mod/mod_fcgid.html
mod_jk 1.2.46 (PHP 7.2-7.4)
1.2.48 (PHP 8.0-8.3)		 https://tomcat.apache.org/connectors-doc/reference/apache.html
mod_limitipconn 0.24 https://dominia.org/djao/limitipconn2.html
mod_log_dbd 1.0.6 https://sourceforge.net/p/dbd-modules/wiki/mod_log_dbd/
mod_log_rotate 1.00a (PHP 7.2-7.4)
1.0.2 (PHP 8.0-8.3)		 https://github.com/JBlond/mod_log_rotate
mod_maxminddb 1.1.0 (PHP 7.3-7.4)
1.2.0 (PHP 8.0-8.3)		 https://github.com/maxmind/mod_maxminddb
mod_perl 2.0.12 https://perl.apache.org
mod_vhost_dbd 1.0.6 https://sourceforge.net/p/dbd-modules/wiki/mod_vhost_dbd/
mod_view 2.2
mod_watch 4.3P https://github.com/pld-linux/apache-mod_watch
mod_xsendfile 1.0-P1 https://tn123.org/mod_xsendfile/

Nginx Modules

The following Nginx modules have been added to the Open Server Panel distribution, which are not available in the original Nginx distribution:

  • brotli_module
  • fancyindex_module
  • http_geoip_module
  • http_geoip2_module
  • http_image_filter_module
  • poll_module
  • stream_geoip_module
  • stream_realip_module
  • stream_ssl_preread_module

Program configuration

Open Server Panel and its modules store their settings in the .\config\program.ini file.

Important: You need to restart Open Server Panel to apply any changes.

Section [main]

This section contains the main settings of Open Server Panel:

Parameter Description
api_domain Local domain for API and web interface.
VPN/proxy: Add this domain to VPN/proxy exceptions, if used.
Default value: ospanel
api_ip IPv4 address for API and web interface.
VPN/proxy: Add this IP address to VPN/proxy exceptions, if used.
Default value: 127.127.127.127
api_port Port for API and web interface. Open Server Panel will not start if this port is already in use.
Default value: 80
clear_dns_cache Clear the system DNS cache when the HOSTS file changes (on/off).
Disabling: Only disable this option in the following cases:
- You manually edited the HOSTS file, cleared the DNS cache, and are not planning to make any further changes to Open Server Panel or its modules.
- You are only using the localhost domain.
Default value: on
lang Language of the Open Server Panel interface. Use the name of any language file from the .\system\lang directory.
auto value (default): The system language will be used if the corresponding language file is available.
log_max_filesize Maximum log file size (0 — no limit).
Log files: program, API, mail server.
File recreation: If the log file size exceeds the specified value, the file will be recreated.
Units: B (bytes), K (kilobytes), M (megabytes), G (gigabytes), T (terabytes).
Log cleaning on startup: Set the value to 1 (byte) to clear logs on every startup.
projects_search_depth Maximum depth for project search.
Performance: Increasing this value may slow down Open Server Panel startup if the directories specified in projects_search_path contain many subdirectories.
Default value: 3
projects_search_path Directories to search for projects. Use a semicolon (;) to separate multiple directories.
Exclusions: node_modules and vendor subdirectories are ignored.
Default value: {root_dir}\home
task_scheduler Enable/disable the built-in task scheduler (on/off).
Default value: on
terminal_ansi_fix Enable ANSI color code support in the console (on/off/auto).
auto value (default):
- Fix is applied only for Windows 7, Windows 8, Windows 10 up to version 1903 (inclusive). Newer versions of Windows already support ANSI codes.
- Fix is not applied for some advanced terminal emulators (e.g., Windows Terminal).
update_check Enable Open Server Panel update check (requires internet connection) (on/off).
Default value: on
use_hosts_file Use the HOSTS file (on/off).
Organizations with restricted access to HOSTS:
1. Configure all necessary modules and projects.
2. Ask the administrator to unlock the HOSTS file and fix its state after starting Open Server Panel.
3. After the administrator fixes the changes, you can disable this option.
Important: Do not disable use_hosts_file unless you are sure of your actions.
Default value: on
use_win_terminal Use Windows Terminal (on/off). Windows Terminal must be installed on the system and available through the PATH system variable.
Windows Terminal as cmd.exe: In newer versions of Windows, Windows Terminal can replace cmd.exe and be written to the %COMSPEC% system variable. In this case, leave this option enabled, even if Windows Terminal always launches instead of cmd.exe.
New Windows Terminal instances: If Windows Terminal opens new windows instead of tabs, change the settings: Settings -> Startup -> New instance behavior -> Attach to the most recently used window.
Default value: off

Section [menu]

This section contains the settings for the Open Server Panel menu.

  • Detailed menu configuration: For detailed customization of menu items, use the menu.ini file. For more information about menu customization, see here.
Parameter Description
do_not_group_single_item Do not group lists containing only one item (see show_addons_in_groups, show_modules_in_groups and show_projects_in_groups).
Default value: on
show_icons Show icons in the Open Server Panel menu (on/off).
Default value: on
show_addons Show the Add-ons menu (on/off).
Default value: on
show_addons_in_groups Group add-ons in the menu (on/off).
Default value: on
show_addons_in_submenu Show the Add-ons menu in a separate submenu (on/off).
Default value: on
show_modules Show the Modules management menu (on/off).
Default value: on
show_modules_in_groups Group modules in the menu (on/off).
Default value: on
show_modules_in_submenu Show the Modules menu in a separate submenu (on/off).
Default value: on
show_projects Show the Projects management menu (on/off).
Default value: on
show_projects_in_groups Group projects by domain zone in the menu (on/off).
Default value: off
show_projects_in_submenu Show the Projects menu in a separate submenu (on/off).
Default value: off
show_tray_icon Show the Open Server Panel icon in the notification area (on/off).
Disabling: Disable this option if you are running Open Server Panel in Windows Server Core environment or using an autostart type that does not require a Windows user login (Windows Task Scheduler -> Start up at computer startup).
Default value: on
show_hr_after_addons Show a separator after the Add-ons menu (on/off).
Default value: on
show_hr_after_modules Show a separator after the Modules menu (on/off).
Default value: on
show_hr_after_projects Show a separator after the Projects menu (on/off).
Default value: on

Section [projects]

This section contains global project settings. They are applied if other values are not specified in the settings of a specific project. The values from this section can be overridden in the project configuration file (<project>\.osp\project.ini).

Section [modules]

This section contains global settings for modules. They are applied if the auto value (default) is specified in the module settings. Values from this section can be overridden in the module configuration file (.\config\<module_name>\<profile_name>\settings.ini).

Section [smtp]

This section contains settings for the built-in SMTP server.

Parameter Description
open_email_after_saving Open emails after saving (on/off).
Important: Use this option with caution when locally testing email sending.
Default value: off
saved_email_extension Extension of saved email files.
Default value: .eml
smtp_port Port of the built-in SMTP server.
Default value: 25
smtp_server Enable/disable the built-in SMTP server (on/off).
Default value: on

Section [environment]

This section contains global environment variables for modules.

  • Overriding/removing: For each module, these variables can be overridden or removed in its settings file (.\config\<module_name>\<profile_name>\settings.ini).
  • Removing a variable: Set an empty value or use a special filter (see allowed_env_vars).

Template variables

Variable Description
{root_dir} Open Server Panel root directory (full path)
{root_drive} Root directory drive
{root_path} Path to Open Server Panel root directory
{terminal_codepage} Console codepage (see terminal_codepage)
{time_zone} Time zone in Etc/GMT format (see time_zone)

In addition to template variables, you can use any Windows environment variables, for example: %COMSPEC%, %SYSTEMDRIVE%, %USERNAME%, %PATH%, etc.

Project configuration

Configuration file

Project settings are stored in the <project>\.osp\project.ini file.

  • Multiple domains/subdomains: If a project contains multiple domains or subdomains, add a separate section for each in the project.ini file.

Important:

  • Applying changes: Restart Open Server Panel to apply changes. If necessary, clear your browser's DNS cache.
  • Switching PHP/Nginx/Node.js versions: Restarting Open Server Panel is not required when changing the PHP, Nginx, or Node.js version through the program menu. All necessary restarts and initializations are performed automatically.
  • Chromium-based browsers and IPv6: Chromium-based browsers (Chrome, Edge, Vivaldi, Yandex.Browser, etc.) cannot see local domains with IPv6 addresses without IPv6 internet access. To work with such domains, use Firefox or disable IPv6 for PHP/Nginx modules and domains.
  • VPN and proxy: Local domains may be unavailable when using VPN or proxy. Add all local domains to VPN/proxy exceptions.
  • Name conflicts: Do not create domains with names that match the names of modules or add-ons.
  • localhost: Do not use localhost as a domain name. If this is absolutely necessary, specify 127.0.0.1 as the domain's ip.

Section [domain_name]

This section contains the main project settings. All parameters are optional.

  • Internationalized domains: Both regular and Punycode representations are allowed.
  • IP addresses as domain names: Using an IP address as a domain name is prohibited. For direct access to a domain by IP, use aliases.
Parameter Description
aliases Domain aliases (space-separated).
Subdomains: Aliases without a dot (.) are considered subdomains and are appended with the domain name (for example, www -> www.test.local).
Other domains: You can use other domains as aliases (for example, when moving a site to a new domain).
Important: Do not use * as a wildcard character. Aliases like *.example.local are not supported in Windows.
Inheritance: If the parameter is not set, the global value from the main Open Server Panel settings is used.
Default value: www
enabled Enable/disable the project (on/off).
Inheritance: If the parameter is not set, the global value from the main Open Server Panel settings is used.
Default value: on
environment A list of add-ons and modules (space-separated), whose environments are appended to the project environment when it is activated with the osp project <DOMAIN> command.
System (default): Allows you to use programs installed on the system (for example, git.exe or ssh.exe). Only disable System if there are conflicts with system software.
PHP/Nginx/Node.js modules: The environments of these modules are always connected (if set for the domain) and do not need to be specified in this parameter.
Inheritance: If the parameter is not set, the global value from the main Open Server Panel settings is used.
Default value: System
ip IP address of the domain.
Multiple IP addresses: You can specify multiple IP addresses (space-separated) and use IPv6. When updating the HOSTS file, the first specified IP will be assigned to the domain.
Important: Do not assign the same IP address to domains with different values for php_engine or nginx_engine.
Automatic assignment: Leave the value blank for automatic IP address assignment.
Inheritance: If the parameter is not set, the global value from the main Open Server Panel settings is used.
Default value: (empty)
nginx_engine The Nginx engine used as a web server for this domain.
FCGI: When using nginx_engine, select the FCGI PHP module.
Proxy server: Select a regular PHP module (not FCGI) if Nginx is used as a proxy server for Apache.
Non-existent module: If the specified Nginx module is not installed, the domain will be ignored.
Inheritance: If the parameter is not set, the global value from the main Open Server Panel settings is used.
Default value: (empty)
node_engine The Node.js engine used to run Node.js applications for this domain.
Node.js installation: First install the required version of Node.js using the NVM add-on.
Inheritance: If the parameter is not set, the global value from the main Open Server Panel settings is used.
Default value: (empty)
php_engine The PHP engine used to process PHP files for this domain.
Non-existent module: If the specified PHP module is not installed, the domain will be ignored.
Inheritance: If the parameter is not set, the global value from the main Open Server Panel settings is used.
Default value: (empty)
project_dir The project's root directory, used by the osp project <DOMAIN> command.
Inheritance: If the parameter is not set, the global value from the main Open Server Panel settings is used.
Default value: {base_dir}
project_url The URL opened when selecting the Open project in browser item in the Open Server Panel menu.
Admin panel: Use this parameter to specify the URL of the CMS admin panel.
Default value: https://{host_decoded}
public_dir The project's public directory. Template variables can be used.
Inheritance: If the parameter is not set, the global value from the main Open Server Panel settings is used.
Default value: {base_dir}
ssl Enable/disable SSL (on/off). If SSL is disabled, working with the domain over HTTPS will not be possible.
Inheritance: If the parameter is not set, the global value from the main Open Server Panel settings is used.
Default value: on
ssl_cert_file Certificate file. Template variables can be used.
Default value: automatically generated certificate
ssl_key_file Key file. Template variables can be used.
Default value: automatically generated key
start_command Project start command (for example, nodemon app.js).
Encoding: By default, encoding 65001 (UTF-8) is used. You can change the encoding with the command chcp <CODEPAGE>.
Inheritance: If the parameter is not set, the global value from the main Open Server Panel settings is used.
Default value: (empty)
terminal_codepage Console codepage when working with the project environment (for example, 65001 or 1251). If the parameter is not set locally and globally, the codepage set for the PHP module environment will be used.
Inheritance: If the parameter is not set locally, the global value from the main Open Server Panel settings is used.
Default value: (empty)

Template variables

Variable Description
{base_dir} The project's root directory (where the .osp directory is located)
{host} Domain name (Punycode is used for internationalized domains)
{host_decoded} Displayed domain name (without Punycode)
{root_dir} Open Server Panel root directory (full path)
{root_drive} Root directory drive
{root_path} Path to Open Server Panel root directory

Manual configuration setup

Universal configuration

Open Server Panel uses a universal domain configuration.

  • Apache: Configuration is set using a macro in the httpd.conf template.
  • Nginx: Configuration is set in the virtual_*_host.conf files located in the module's conf directory.

Method 1. Configuration addition

To add your own domain configuration inside the automatically configured <VirtualHost> (Apache) or Server{} (Nginx) block:

  1. Create a directory and a file: Create a <project>\.osp\Apache or <project>\.osp\Nginx directory and a <domain_name>.conf file in this directory.
    • Example: <project>\.osp\Apache\example.local.conf
    • Punycode: Use Punycode for internationalized domains.
  2. Add configuration: Add the necessary directives to the created file.
  3. Restart Open Server Panel.

Recommendation: This method allows you to use your own configuration without having to configure the host parameters in detail. Keep in mind that you are already inside the <VirtualHost> (Apache) or Server{} (Nginx) block, and the main host parameters are already set.

Method 2. Configuration replacement

To create your own <VirtualHost> (Apache) or Server{} (Nginx) block:

  1. Create a directory and a file: Create a <project>\.osp\Apache or <project>\.osp\Nginx directory and a <domain_name>.conf file in this directory.
    • Example: <project>\.osp\Apache\example.local.conf
    • Punycode: Use Punycode for internationalized domains.
  2. Add the configuration block: Add the <VirtualHost> (Apache) or Server{} (Nginx) block with the full domain configuration to the created file.
  3. Restart Open Server Panel.

Important: This method requires advanced knowledge of Apache/Nginx and Open Server Panel.

Other features

  • Directory .\osp\bin: Create a .osp\bin directory in the project directory to store utility scripts. This directory will be added to the PATH variable when activating the project environment. The project's base and public directories are always added to PATH.
  • Additional menu items and language constants: A project can add items to the Open Server Panel menu and define its own language constants. You can find an example in the full-example.local project, available after installing Open Server Panel.

Setting environment variables

To configure project environment variables, create a .osp\env.ini file.

Example:

[full-example.local]
ANY_VALUE = SOMETHING

Menu configuration

The Open Server Panel menu provides access to basic settings (choosing a PHP version, choosing a profile, etc.) and commands (restarting modules, launching a shell, etc.).

Important:

  • Automatic initialization/restart: When changing the PHP version of a project or the profile of a module's settings through the menu, the affected modules will be automatically initialized or restarted. Consider this when performing lengthy operations on the server.

The menu configuration is stored in the .\config\menu.ini file. You can also create additional menu items in this file. Restart Open Server Panel to apply the changes.

To create a new menu item, add a new section to the menu.ini file.

Section [ID]

This section contains the settings for the menu item. All parameters are optional.

  • ID: Unique identifier of the section.
  • Sorting order: Menu items are sorted in the same order as the corresponding sections are located in the menu.ini file.

Important: Do not use the same ID for different sections.

Parameter Description
caption The text of the menu item. You can use language constants (for example, {lang_xxx}).
Default value: (empty)
category Category of the menu item. You can use language constants (for example, {lang_xxx}).
Subcategories: One level of nesting is allowed (for example, My Bookmarks\Work).
Menu root: If no category is specified, the item will be created in the menu root.
Special values:
- projects, modules, addons: The item will be added to the action menu for projects, modules, or add-ons.
- projects\<domain_name>, modules\<module_name>, addons\<addon_name>: The item will be added to the action menu for a specific project, module, or add-on.
Default value: (empty)
command The command to execute when selecting this menu item. If no command is specified, the menu item will be ignored.
Default value: (empty)
enabled Show the menu item (on/off).
Default value: on
hide Hide the window of the called application (on/off).
Note: This option only affects the called subroutine and does not affect new processes created by this subroutine.
Default value: off
hr_after Display a separator below the menu item (on/off).
Default value: off
hr_before Display a separator above the menu item (on/off).
Default value: off
icon Icon name from the Font Awesome Free (Solid/Regular/Brands) set.
Default value: (empty)
need_category Show the menu item only for modules or add-ons belonging to the specified category (MySQL, PHP, etc.). Not to be confused with the menu item category.
Supported categories: modules, addons, modules\<module_name>, addons\<addon_name>.
Default value: (empty)
need_module_shell Show the menu item only if the module specified in the parent menu item has/doesn't have a shell/cli shell.
Supported categories: modules, modules\<module_name>.
Default value: (empty)
Allowed values: on, off
need_state Show the menu item only when the module specified in the parent menu item is in the desired state (enabled/disabled).
Supported categories: modules, modules\<module_name>.
Default value: (empty)
Allowed values: on, off
need_start_command Show the menu item only if a start command is specified in the project settings (see start_command).
Supported categories: projects, projects\<domain_name>.
Default value: (empty)
Allowed values: on, off
need_use_win_terminal Show the menu item only when the use_win_terminal option is enabled/disabled in the Open Server Panel settings.
Default value: (empty)
Allowed values: on, off
work_directory Working directory to execute the command (see command).
Important: The current directory may change during the execution of some commands (for example, osp project ...) and may not match the initial working directory.
Default value: {root_dir}

Template variables

The following template variables can be used in the command and work_directory parameters:

Variable Description
{root_dir} Open Server Panel root directory (full path)
{root_drive} Root directory drive
{root_path} Path to Open Server Panel root directory
{web_panel_url} Web interface URL
Special variables (only for projects and projects\<domain_name>)
{base_dir} Project base directory
{host} Domain name (Punycode)
{host_decoded} Displayed domain name (without Punycode)
{nginx_engine} Nginx engine
{node_engine} Node.js engine
{php_engine} PHP engine
{project_dir} Project root directory
{project_url} Project URL
{public_dir} Project public directory
{start_command} Project start command (if configured)
{terminal_codepage} Console codepage (see terminal_codepage)
Special variables (only for addons and addons\<addon_name>)
{addon_name} Add-on name
{terminal_codepage} Console codepage (see terminal_codepage)
Special variables (only for modules and modules\<module_name>)
{ip} Module IP address
{log_level} Error logging level
{module_name} Module name
{port} Module port
{profile_name} Name of the current module settings profile
{query_log_level} Query logging level
{shell_command} Command to launch the module's shell/cli shell (if configured)
{terminal_codepage} Console codepage (see terminal_codepage)
{time_zone} Time zone

In addition to template variables, you can use Windows environment variables, for example: %COMSPEC%, %SYSTEMDRIVE%, %USERNAME%, %PATH%, etc.

Examples of use

[21]
caption  = Open in PhpStorm
category = projects
command  = "%COMSPEC%" /c "osp project {host_decoded} & start "" "C:\Program Files\JetBrains\PhpStorm 2018.2\bin\phpstorm64.exe" "{project_dir}""
hide     = on
icon     = code

[22]
caption  = Google
category = My Bookmarks\Search Engines
command  = "%COMSPEC%" /c "start "" "https://google.com""
hide     = on
icon     = bookmark

cmd.exe options:

  • /c: Execute the command and close the terminal.
  • /k: Execute the command and leave the terminal open.

Module configuration

The settings for each module are stored in the .\config\<module_name>\<profile_name>\settings.ini file.

  • Default profile: default.
  • Changing profile: The active profile can be changed through the Open Server Panel menu.
  • Backups:
    • Original settings and configuration files: .\modules\<module_name>\ospanel_data\default.
    • Original data files (if any): .\modules\<module_name>\ospanel_data\default_data.
    • Future functionality: This data will be used to restore the original module configuration in the control panel.

Important:

  • Applying settings changes: Restart Open Server Panel.
  • Applying changes to templates: Restart or reinitialize the module.
  • Do not edit the .\config\<module_name>\module.ini file: This file is managed automatically.

Creating additional profiles

To create a new settings profile:

  1. Copy an existing profile: Copy the directory of an existing profile (for example, .\config\<module_name>\Default) to a new directory (for example, .\config\<module_name>\MyProfile).
  2. Copy data (if any): If the module uses data from the .\data directory, copy the data directory of the existing profile (for example, .\data\<module_name>\Default) to a new directory (for example, .\data\<module_name>\MyProfile).
  3. Using original settings and data: Instead of copying an existing profile, you can use the original settings and data of the module from the .\modules\<module_name>\ospanel_data\default and .\modules\<module_name>\ospanel_data\default_data directories, respectively.
  • Allowed characters in the profile name: A-Za-z0-9-+_.
  • Advantages of additional profiles:
    • Testing new configurations
    • Experimenting with settings

Section [main]

This section contains the main settings of the module. All parameters are optional.

Parameter Description
ip IP address of the module.
Multiple IP addresses: You can specify multiple IP addresses (space-separated) and use IPv6 if the module supports it. When updating the HOSTS file, the first IP address specified will be used.
DNS: This parameter is ignored for DNS modules.
port Port of the module.
PHP/Nginx/DNS: This parameter is ignored for PHP, Nginx, and DNS modules.
clean_directories Directories to be cleared before starting the module (space-separated). For example: cache, temporary files, etc. Template variables can be used.
log_directory Directory for storing module logs. Created automatically if it doesn't exist. Template variables can be used.
log_level_values Available logging levels (not supported by all modules).
log_level Logging level (value from log_level_values).
query_log_values Available query logging levels (not supported by all modules).
query_log_level Query logging level (value from query_log_values).
shell_command Command to launch the module's shell/cli shell. Template variables can be used.
ssl_auto_cert Automatic generation and use of SSL certificate (on/off).
Disabling:
- This parameter is always set to off if the module's IP address is not specified.
- When disabling this parameter, you must manually configure the module's SSL settings (disable SSL or specify your own keys and certificates).
- Browsers without Windows Certificate Store (e.g., Firefox): Import the Open Server Panel root certificate (data\ssl\root\cert.crt) into the browser. Repeat the import after each regeneration of the root certificate with the command osp cacert init.
start_command Command to start the module. Template variables can be used.
start_directory Module start directory (must exist). Template variables can be used.
work_directories Directories required for the module to work (space-separated). Created automatically if they don't exist. Template variables can be used.
used_addons_environment List of add-ons (space-separated) whose environments (if any) are appended to the module's environment. Information indicators in the console do not display these additional environments.
Important: Use this option only if you fully understand its purpose.
allowed_system_env_vars List of Windows environment variables (space-separated) passed to the module's environment.
Purpose: Filtering the module's working environment from the environment of similar software installed on the system.
Important: Only modify this list if you fully understand the consequences.
auto value (default): The global value from the main Open Server Panel settings is used.
log_max_filesize Maximum log file size (0 — no limit).
File recreation: When the specified size is exceeded, the log file will be recreated on the next module startup.
auto value (default): The global value from the main Open Server Panel settings is used.
Units: B (bytes), K (kilobytes), M (megabytes), G (gigabytes), T (terabytes).
Log cleaning on startup: Set the value to 1 (byte) to clear logs on every module startup.
log_write_title Add a header to the log file each time the module is started (on/off). Useful for separating work sessions if automatic log cleaning is disabled.
auto value (default): The global value from the main Open Server Panel settings is used.
max_probation_fails Maximum number of consecutive (in a row) unsuccessful module starts (see probation), after which the module will go into the "Error" state.
auto value (default): The global value from the main Open Server Panel settings is used.
max_shutdown_time Maximum module shutdown time (0 — no limit).
Forced shutdown: If the module does not shut down within the specified time, it will be forcibly terminated.
Minimum value: 30 seconds.
Important: Do not set this limit without fully understanding the consequences. Premature termination of the module can lead to problems (data corruption, incomplete log writing, etc.).
auto value (default): The global value from the main Open Server Panel settings is used.
Units: s (seconds), m (minutes), h (hours), d (days).
probation Module health check time (probation period).
Countdown start: From the moment the module starts successfully.
"Error" state: If the module terminates unexpectedly during the probation period, it will not be restarted and will go into the "Error" state. This state is also set if the module cannot start at the system level.
Disabling: A value of 0 disables the probation period. The module will always be restarted on failure.
Recommendations: It is not recommended to set a value of 0 or a very short check period (less than 30 seconds).
auto value (default): The global value from the main Open Server Panel settings is used.
Units: s (seconds), m (minutes), h (hours), d (days).
silent_mode Silent mode (on/off). This mode disables pop-up error messages from the Windows Error Reporting service and the module itself.
Disabling: Only disable this mode to diagnose problems with the module.
auto value (default): The global value from the main Open Server Panel settings is used.
terminal_codepage Console codepage when working with the module's environment.
Special values:
- system: System codepage.
- auto: Global value from the main Open Server Panel settings.
Empty value: The console codepage will not change when activating the module's environment or its shell/cli shell.
time_zone Time zone in Etc/GMT format (for example, Etc/GMT-3).
Special values:
- system: System time zone.
- auto: Global value from the main Open Server Panel settings.
Important: The Etc/GMT format differs from UTC in reverse order (for example, Etc/GMT-3 = UTC/GMT+3 = UTC+03:00 = Europe/Moscow).

Template variables

The following template variables can be used in the clean_directories, log_directory, shell_command, start_command, start_directory, and work_directories parameters:

Variable Description
{module_name} Module name
{profile_name} Name of the current module settings profile
{root_dir} Open Server Panel root directory (full path)
{root_drive} Root directory drive
{root_path} Path to Open Server Panel root directory

The following variables are also available in the shell_command and start_command parameters if the corresponding parameters are set in the same section:

Variable Description
{ip} Module IP address(es)
{port} Module port
{log_level} Logging level
{query_log_level} Query logging level
{terminal_codepage} Console codepage
{time_zone} Time zone in Etc/GMT format

In addition to template variables, you can use Windows environment variables, for example: %COMSPEC%, %SYSTEMDRIVE%, %USERNAME%, %PATH%, etc.

Section [environment]

In this section, you can set/override the module's environment variables (supported variables depend on the module).

  • Deleting a variable: Set an empty value.

Template variables

Variable Description
{module_name} Module name
{profile_name} Name of the current module settings profile
{root_dir} Open Server Panel root directory (full path)
{root_drive} Root directory drive
{root_path} Path to Open Server Panel root directory

The following variables are also available if the corresponding parameters are set in the [main] section:

Variable Description
{ip} Module IP address(es)
{port} Module port
{log_level} Logging level
{query_log_level} Query logging level
{terminal_codepage} Console codepage
{time_zone} Time zone in Etc/GMT format

In addition to template variables, you can use Windows environment variables, for example: %COMSPEC%, %SYSTEMDRIVE%, %USERNAME%, %PATH%, etc.

Section [filename]

Sections with this name describe working with configuration file templates and other module service files. The number of such sections is not limited.

  • Location of templates: .\config\<module_name>\<profile_name>\templates.
  • Temporary files: During module initialization, templates are converted into temporary working files.
Parameter Required Description
comment Yes The comment character used in the configuration file.
destination Yes Path to the temporary file. This file is recreated every time the module is initialized and cannot be edited.
enabled No Enable/disable the use of this configuration file (on/off).
off value: The file is temporarily not used.
Default value: on
encoding No Configuration file encoding.
Allowed values: UTF8, ANSI, ASCII.
Default value: UTF8
directory_separator Yes The directory separator used in resource paths.
source_dir No Directory to search for the source template file.
Default value: .\config\<module_name>\<profile_name>\templates

Template variables

The following template variables can be used in the destination and source_dir parameters:

Variable Description
{module_name} Module name
{profile_name} Name of the current module settings profile
{root_dir} Open Server Panel root directory (full path)
{root_drive} Root directory drive
{root_path} Path to Open Server Panel root directory

Template variables in template files

The following template variables can be used in template files:

Variable Description
{module_name} Module name
{profile_name} Name of the current module settings profile
{root_dir} Open Server Panel root directory (full path)
{root_drive} Root directory drive
{root_path} Path to Open Server Panel root directory
Special variables (only if set in the [main] section)
{ip} Module IP address(es)
{port} Module port
{log_level} Logging level
{query_log_level} Query logging level
{shell_command} Command to launch the module's shell/cli shell
{terminal_codepage} Console codepage
{time_zone} Time zone in Etc/GMT format
Service variables (for module developers only)
{apache_hosts} Apache hosts configuration block
{api_domain} API domain
{cmd_api_url} API URL for the command line interface
{environment} Module environment formation block (Batch script format)
{lang_N} Text string with number N from the language file (current language)
{nginx_hosts} Nginx hosts configuration block
{osp_version} Open Server Panel version
{osp_version_datetime} Version release date (compilation date)
{web_api_url} API URL for the web interface
{web_panel_url} Web interface URL
{windows_environment} Windows environment (original, formed when Open Server Panel starts)

In addition to template variables, you can use Windows environment variables, for example: %COMSPEC%, %SYSTEMDRIVE%, %USERNAME%, %PATH%, etc.

Section [services]

This section describes the system service configuration required by the module.

  • Purpose: Checking the status of Windows services before starting the module.
  • Service management: This section does not manage the state of services.

Example:

[services]
Dhcp     = on
EMDMgmt  = off
SysMain  = on

Creating modules

Module structure

Each Open Server Panel module has the following minimum file structure:

.
├── data
│   └── <module_name>                  # Module data directory (optional)
└── modules
    └── <module_name>                  # Main module directory
        └── ospanel_data              # Service files (source settings and configurations)
            ├── default               # Original profile directory
            │   ├── settings.ini      # Module settings file
            │   └── templates         # Templates directory
            ├── default_data          # Original profile data directory (optional)
            ├── module.dat            # Module description file
            ├── menu.ini              # Module menu configuration file (additional items)
            └── lang                  # Language files directory (English.ini, Russian.ini, etc.)

Creating a module

  1. Create a directory structure: Create directories as shown in the example above.
  2. Language files (optional):
    • Location: .\modules\<module_name>\ospanel_data\lang
    • Content: Module constants in the [main] section.
    • Unique prefix: Use a unique prefix in the constant names (for example, mymod_...).
  3. Additional menu (optional):
    • Location: .\modules\<module_name>\ospanel_data\menu.ini
    • Unique IDs: Use unique IDs for sections that do not match the IDs from the .\config\menu.ini file. It is recommended to use a prefix equal to the module name.
  4. Settings file:
    • Location: .\modules\<module_name>\ospanel_data\default\settings.ini
  5. Configuration file templates:
    • Location: .\modules\<module_name>\ospanel_data\default\templates
  6. Source data (optional):
    • Location: .\modules\<module_name>\ospanel_data\default_data (for example, databases)
  7. Description file:

    • Location: .\modules\<module_name>\ospanel_data\module.dat

    • Format: INI file

    • Section [main] with parameters:

      Parameter Description
      architecture Module architecture: x64 or x86
      category Module category (you can use existing categories or create a new one)
      fast_start Fast module start (without waiting for console initialization): yes or no
      fast_stop Fast module stop (forced process termination): yes or no
      ipv6_support IPv6 support: yes or no
      ip_separator IP address separator in the module configuration (if multiple IP addresses are supported)
      kill_names List of processes to terminate forcibly if the module cannot stop them on its own (for example, epmd.exe test.exe)
      license Link to the module license
      license_type Type of module license
      min_windows_ver Minimum supported Windows version (see the table below)
      timestamp Module release timestamp
      version Module version

    • Minimum Windows version:

      Version number Windows version
      6.1.7601 Windows 7 SP1
      6.2.9200 Windows 8
      6.3.9600 Windows 8.1
      10.0.10240 Windows 10 1507
      10.0.10586 Windows 10 1511
      10.0.14393 Windows 10 1607
      10.0.15063 Windows 10 1703
      10.0.16299 Windows 10 1709
      10.0.17134 Windows 10 1803
      10.0.17763 Windows 10 1809
      10.0.18362 Windows 10 1903
      10.0.18363 Windows 10 1909
      10.0.19041 Windows 10 2004
      10.0.19042 Windows 10 20H2
      10.0.19043 Windows 10 21H1
      10.0.19044 Windows 10 21H2
      10.0.19045 Windows 10 22H2
      10.0.22000 Windows 11 21H2
      10.0.22621 Windows 11 22H2
  8. Copying settings and data:
    • Settings: Create a directory .\config\<module_name>\default and copy the contents of the directory .\modules\<module_name>\ospanel_data\default into it.
    • Data: Create a directory .\data\<module_name>\default and copy the contents of the directory .\modules\<module_name>\ospanel_data\default_data into it (if any).
  9. Restart Open Server Panel.

Important: Do not use the directories .\modules\<module_name>\ospanel_data\default and .\modules\<module_name>\ospanel_data\default_data to work with the module. These directories store the original profile and are used to restore the module settings.

Add a custom footer
Add a custom sidebar
Clone this wiki locally