1. cPanel & WHM Documentation
  2. cPanel Knowledge Base
  3. Web Services
  4. The cpuser_service_manager Script and the Ubic Subsystem
services

The cpuser_service_manager Script and the Ubic Subsystem

Last modified: July 9, 2024

Overview

Note:
This script is for cPanel users. It only configures services for the user that runs the script.

The cpuser_service_manager script adds and removes user-managed and monitored services for your cPanel account. User-managed services are programs that you want your server to run all the time, such as a web application that runs in either Apache Tomcat®, PSGI, Rails, or WSGI, among others. Use this script to manage services run as the user, rather than the root user.

This script also configures the Ubic subsystem on your account, which allows you to easily manage your services, and adds a watchdog cron job to monitor your services.

Important:

You must possess terminal access to use this script and the Ubic subsystem. Your hosting provider controls this access in WHM’s Manage Shell Access interface (WHM » Home » Account Functions » Manage Shell Access).

The cpuser_service_manager script

To use this script, run the following command on the command line: 

/usr/local/cpanel/scripts/cpuser_service_manager [argument] [options]

Arguments

Note:
When you run this script, it will also configure the Ubic subsystem and add a watchdog cron job if necessary. A watchdog cron job monitors the status of your services.

The /usr/local/cpanel/scripts/cpuser_service_manager script accepts the following arguments, where service_name represents the name of a service and path represents a file path:

Argument Description Example
add service_name --init-script=path Set up a user-managed and monitored service.
Note:
  • If you use the --init-script option, your script must be a Linux Standard Base (LSB)-compliant script.
  • If you use the --ubic-service option, your script must be a Ubic-compliant script.
  • The path variable must use an absolute path.
 /usr/local/cpanel/scripts/cpuser_service_manager add my_psgi_app --init-script=/path/to/init.file
add service_name --ubic-service=path Set up a user-managed and monitored service.
Note:
  • If you use the --init-script option, your script must be a Linux Standard Base (LSB)-compliant script.
  • If you use the --ubic-service option, your script must be a Ubic-compliant script.
  • The path variable must use an absolute path.
 /usr/local/cpanel/scripts/cpuser_service_manager add my_psgi_app --ubic-service=/path/to/ubic.file
info Display information about how the script works and what it does. /usr/local/cpanel/scripts/cpuser_service_manager info
list Display a list of the user-managed and monitored services. /usr/local/cpanel/scripts/cpuser_service_manager list
remove service_name Remove a service. /usr/local/cpanel/scripts/cpuser_service_manager remove my_psgi_app
hint [argument] Display the abbreviated help information.
Note:
The argument is optional. If you specify an argument, only that argument’s abbreviated help information appears.
/usr/local/cpanel/scripts/cpuser_service_manager hint add
help [argument] Display the script’s help information.
Note:
The argument is optional. If you specify an argument, only that argument’s abbreviated help information displays.
/usr/local/cpanel/scripts/cpuser_service_manager help add

The Ubic subsystem

The /scripts/cpuser_service_manager script configures the Ubic subsystem if necessary, when you add a service to your cPanel account. This subsystem enables easy management of your system’s services on the command line. Use this subsystem to stop, start, restart, and see the status of your account’s services.

The Ubic subsystem configuration adds the following to your account:

  • The ~/ubic directory

  • The ~/.ubic.cfg file

    Important:
    Do not edit the the ~/.ubic.cfg file or it will not function correctly.

  • A cron job that includes a Ubic watchdog process to monitor the status of your service.

To use the Ubic subsystem, run the following command on the command line: 

ubic [argument] [service_name]

Note:
If ubic does not exist in your PATH, you must add it to your configuration. For example, you might add the following line to your .bashrc file: 
export PATH=$(dirname $(readlink /usr/local/cpanel/3rdparty/bin/perl)):$PATH
Important:
Jailshell users cannot see the status of their previously started Tomcat service. The default jailshell permissions only allow users to view their current session’s processes. If they attempt to restart a service that is already active with Ubic, the system launches a duplicate process.

You can use the following arguments to manage your services with Ubic, where service_name represents the name of the service that you wish to modify:

Argument Description Example
status service_name Display the status of a service. ubic status my_psgi_app
start service_name Start a service. ubic start my_psgi_app
stop service_name Stop a service. ubic stop my_psgi_app
restart service_name Restart a service. ubic restart my_psgi_app

You can view other possible arguments with the perldoc /usr/local/cpanel/3rdparty/perl/528/bin/ubic command.

Additional Documentation