H-Sphere VPS Scripts

H-Sphere VPS is a set of scripts that serve as the backend for advanced VPS management via H-Sphere CP but they can also run from the command-line mode. The latter is the subject of this document that covers:

• Default VPS Configuration File
• Other VPS-Related Configuration Files
• VPS Scripts Location
• Perl Modules Used By VPS Scripts
• VPS Configuration
• Create VPS
• Migrate VPS
• Delete VPS
• VPS Cron Scripts
  • (HS VPS 1.4-1+) VPS Network Reconfiguration Cron
• VPS Configuration Scripts
• View List of Installed VPS's
• Install/Uninstall Additional Packages
• Check VPS Files For Changes
• VPS IP Migration Tool
• (HS VPS 1.4-1+) VPS Network Configuration Tools
• (HS 2.5 RC 2+, HS VPS 1.4-4+) Device Management

Default VPS Configuration File

The default VPS configuration file is /hsphere/local/config/vserver/vps.cfg.

If you need to set parameters to the configuration file, run VPS configuration script (/hsphere/shared/scripts/vps-configure.pl).

See also configuration parameters set in the VPS configuration file.

Other VPS Related Configuration Files

a) Template configuration files located in $HSINSTALLPKG (Default: /hsphere/local/config/vserver/<Your OS code>/):
where <Your OS code>:
RH73 - Red Hat Linux release 7.3
RHES3 - Red Hat Enterprise Linux ES release 3
RHAS3 - Red Hat Enterprise Linux AS release 3
RHWS3 - Red Hat Enterprise Linux WS release 3
WBEL3 - White Box Enterprise Linux release 3
CentOS3 - CentOS release 3

rpm_base.cfg - base and core of Linux;
rpm_development-tools.cfg - Development Tools
rpm_dns-server.cfg - DNS Name Server
rpm_ftp-server.cfg - FTP Server
rpm_kernel-vps.cfg - kernel emulator for VPS
rpm_mail-server.cfg - Mail Server
rpm_mysql-server.cfg - MySQL Database
rpm_news-server.cfg - News Server
rpm_perl-full.cfg - Perl programing language modules
rpm_pgsql-server.cfg - Postgresql SQL Database
rpm_quota.cfg - quota tools for VPS
rpm_samba-server.cfg - Windows File Server
rpm_system-tools.cfg - System Tools
rpm_web-server.cfg - Web Server

b) VPS box configuration files located in $VPSCONFIGS (Default: /hsphere/local/config/vserver/):

vps.cfg - the main configuration file for all Virtual Private Servers.
vps.cfg.bak - the main configuration file backup.
vps.cfg.default - default configuration for all Virtual Private Servers.
vps.list - the list of all known VPS and the list of Virtual Private Servers scheduled for removal.

VPS Scripts Location

All VPS scripts are located in the $VPSSCRIPTS directory (Default: /hsphere/shared/scripts).
Cron scripts are located in the $VPSSCRIPTS/cron (Default: /hsphere/shared/scripts/cron).

Perl Modules Used By VPS Scripts

Note: We provide the hsphere-vps package only for:

Red Hat Linux 7.3 with Perl 5.6.1 installed.
Red Hat Enterprise Linux release 3, CentOS 3.x, White Box Enterprise Linux release 3 with Perl 5.8.0 installed.

If you wish to install this package with other versions of Perl, you need to build your own H-Sphere VPS binaries.

Perl modules:
Red Hat Linux 7.3: Perl v5.6.1 modules are installed in [/usr/lib/perl5/site_perl/5.6.1/VServer/]
Red Hat Enterprise Linux release 3, CentOS 3.x, White Box Enterprise Linux release 3: Perl v5.8.0 modules are installed in [/usr/lib/perl5/site_perl/5.8.0/VServer]

Addon.pm
Admin.pm
Net.pm
Util.pm
Vars.pm
Vrpm.pm

VPS Configuration

Enter the $VPSSCRIPTS directory (Default: /hsphere/shared/scripts) to run the vps_configure.pl script.

SYNTAX:

./vps-configure.pl [-d|-r|-h]
OPTIONS:
        --defaults|-d   load default settings
        --restore|-r    restore settings you made before
        --help|-h       display this help message

Run vps_configure.pl:

# /hsphere/shared/scripts/vps-configure.pl
Do you really want to reconfigure your VPSs [y/n]?

Kernel: 2.4.21-freevps-1.2-1hugemem
FreeVPS patch build: 1080548030
Base FreeVPS tools package: freevps-tools-1.2-1
H-Sphere VPS scripts package: hsphere-vps-1.2-1
RedHat release: RH73

To perform basic configuration for all virtual servers, run the scipt and follow the instructions step by step.

Create VPS

To create new Virtual Private Server, run the vps-post-config.pl script:

./vps-post-config.pl VPS_HOST_NAME

And put in the following parameters to STDIN:

IP=ADDRESS:MASK:HDEV - IP to be assigned to this VPS and allowed on network interface HDEV on your VPS box;
DLIMIT=XXXX - Disk limit in Mb;
MLIMIT=XXXX - Memory Limit in Mb;
PLIMIT=XXXX - Limit on the number of running processes;
FILELIMIT=XXXX - Number of opened files limit;
TCPLIMIT=XXXX - TCP sockets limit;
ROOTPWD=**** - User root password;
CTRL+D - Press Ctrl+d to stop data input.

Example:

Create a VPS with the following configuration:

Hostname: 231.tst
IP address: 192.168.112.231, mask: 255.255.255.0
Disk limit: 3000Mb
Memory limit: 512Mb
Limit on the number of running processes: 1000
Root password: 1

[root@vps scripts]# ./vps-post-config.pl 231.tst

    IP=192.168.112.231:255.255.255.0[press Enter]
    DLIMIT=3000[press Enter]
    MLIMIT=512[press Enter]
    PLIMIT=1000[press Enter]
    ROOTPWD=1[press Enter]
    [press Ctrl+d] (end of data input)

vps-post-config.pl creates the $HSVPSFILES/231.tst/231.tst.in file (Default: /hsphere/local/config/vserver/cp/231.tst/231.tst.in) with the input parameters, and registers VPS in the list of known vservers: $VPSCONFIGS/vps.list (Default: /hsphere/local/config/vserver/vps.list)

Check the list of VPSs:

[root@vps scripts]# cat /hsphere/local/config/vserver/vps.list

You would get something like this:

DELETE=""
VSERVERS="3:231.tst"

Format:

DELETE="HOSTNAME1 HOSTNAME2 HOSTNAME3" - the list of VPSs scheduled for deletion, separated with whitespaces;
VSERVERS="CONTEXT_ID1:HOSTNAME1 CONTEXT_ID2:HOSTNAME2" - the list of known VPSs, separated with whitespaces; CONTEXT_ID is a virtual server ID

Migrate VPS

HS VPS 1.3-6.4 and up

VPS migration is performed by the vps-migrate.pl script that moves VPS(s) to another host. This script uses:

• OpenSSH client:
  • for secure copying (scp remote file copy program)
  • for executing commands on a remote machine
• tar archiving utility.

To perform a migration, access to remote servers and logging into them automatically without entering the password each time is required from the "source" box. So, the access keys should be copied from the "source" box into the destination box. If such keys are not uploaded, the script does it for you (use the --put-ssh-key option).

Preparation:

1. Suspend the VPS server on the "source" box.
2. Configure the destination machine to be VPS server host:
   • Install all required packages (FreeVPS kernel, FreeVPS tools, H-Sphere VPS scripts).
   • Complete all configuration tasks.

Actions performed by the script:

• The remote host VPS servers configuration is loaded and checked
• Platform compatibity is checked for the VPS box and the destination host. For example, a VPS under Enterprise Linux can't be moved to a host under RedHat Linux release 7.3.
• The script checks whether a VPS with the same name as the migrated one exists on the destination box
• Available free disk space on the destination host VPS home partition is checked as Free_space > VPS_disk_usage*1.5
• The script checks if the VPS server virtual context number exists on the destination box:
  • if the migrated VPS server virtual context does not exist on the destination box, the VPS is created with this context
  • if it does exist, the first free virtual context is used for the migrated VPS.
• Network interface which all the virtual network interfaces were attached to is checked. If a network interface doesn't exist on the destination host, new one is used, and the VPS network is reconfigured to be used to assign virtual network interfaces.
• VPS home is archived using the tar utility filtered through gzip
• MD5SUM for the source file is compared with that of the file copied to the remote host
• VPS traffic data is migrated to the destination box
• Post-migration:
  • Migrated VPS server(s) are scheduled for fix and configuration restore. The configuration (virtual context creation, limits comfiguration, disk usage quota check) is restored within 3 minutes by the crpn/vps-cron-fix.pl cron
  • Migrated VPS is suspended on the destination box, and should be resumed via H-Sphere or manualy.

For help, run:

# ./vps-migrate.pl --help
vps-migrate.pl         # Moves VPS(s) to another host.

Usage:
   vps-migrate.pl --host=<host> [--user=<name>] --vps=v<ps_name>|--all [--put-ssh-key] [--help]

--host            # <host> - host (DNS name/IP address) to migrate VPS(s) to.
--user            # <name> - username to be used to log into the host.
                  # If username is not specified, the name of the user executing the script will be taken.
--vps             # <vps_name> - VPS to be migrated.
--all             # Migrate all known VPSs.
--put-ssh-key     # Generate and upload public SSH keys to remote box.
--help            # Print this help information.

Delete VPS

vps-delete.pl

SYNTAX:
./vps-delete.pl VPS_HOST_NAME

1. It removes existing VPS [VPS_HOST_NAME], all its configuration files, removes [VPS_HOST_NAME] from the list of known VPS.
2. If [VPS_HOST_NAME] is being created by cron at the moment, [vps-delete.pl] posts deletion request for VPS (sets the DELETE parameter in the vps.list file)
3. All deletion requests are processed by vps-cron-delete.pl cron every 4 minutes.

VPS Cron Scripts

These are VPS scripts scheduled in cron on the host server:

*/5 * * * * /hsphere/shared/scripts/cron/vps-cron.pl >/dev/null 2>&1
59 */1 * * * /hsphere/shared/scripts/cron/vps-cron-traf.pl >/dev/null 2>&1
*/4 * * * * /hsphere/shared/scripts/cron/vps-cron-delete.pl >/dev/null 2>&1
*/3 * * * * /hsphere/shared/scripts/cron/vps-cron-fix.pl >/dev/null 2>&1

1. vps-cron.pl

The $VPSSCRIPTS/cron/vps-cron.pl script (Default: /hsphere/shared/scripts/cron/vps-cron.pl) runs every 5 minutes. It is used to install and configure new Virtual Private Servers.

The script works as follows:

1. It checks the list of known vservers and takes each VPS and processes requested tasks from the $HSVPSFILES/VPS_NAME/VPS_NAME.in file (Default: .../cp/VPS_NAME/VPS_NAME.in).
2. If the requested task is successfully done, it creates a note in the $HSVPSFILES/VPS_NAME/VPS_NAME.out file (Default: .../cp/VPS_NAME/VPS_NAME.out)
3. If all of the requested tasks are done, it creates the DONE file: $HSVPSFILES/VPS_NAME/VPS_NAME.done (Default: .../cp/VPS_NAME/VPS_NAME.done), and deletes the request file: $HSVPSFILES/VPS_NAME/VPS_NAME.in (Default: .../cp/VPS_NAME/VPS_NAME.in).
4. It creates the FLAG file: $STATCRONPID (Default: /var/log/hsphere/vps_cron.pid) with its own PID, to prevent executing another copy of it.
5. It creates all configuration files required for VPSs: $VPSCONFIGS/VPS_NAME.conf (Default: /hsphere/local/config/vserver/VPS_NAME.conf) $VPSCONFIGS/VPS_NAME.sh (Default: /hsphere/local/config/vserver/VPS_NAME.sh)
6. It installs basic Linux RH7.3 packages and additional packages if configured, creates services, set limits, assigns IPs, and finally, starts VPS.

2. vps-cron-traf.pl

Processes VPS network traffic statistics. Creates files with VPS daily traffic statistics: /hsphere/local/var/statistic/DD.MM.YYYY.vps.txt

3. vps-cron-delete.pl

This cron script that runs every 4 minutes deletes VPS server(s) scheduled for removing.

VPS server is scheduled for removing in case it can't be deleted immediately after the removing request was sent, e.g. when other tasks need to be finished first.

Names of the VPS servers(s) scheduled for removing are listed delimited with whitespace in the DELETE parameter of the /hsphere/local/config/vserver/vps.list configuration file.

Example:

4. vps-cron-fix.pl

(HS VPS 1.3-6.4 and up)

This script fixes some VPS(s) configuration: limits, usage, etc.

For instance, it can fix VPS server(s) configuration that was "lost" when you upgraded the FreeVPS kernel after the host system (physical box) reboot.

Fixed parameters:

The script runs as a cron job and is configured to fix corrupted configuration every 3 minutes. The script also checks and fixes VPS servers(s) daily.

If needed, you can run the script manually. Use --vps to fix a particular VPS and -f|--force to forcefully fix a virtual server(s) even if its(their) configuration is uncorrupted.

For help, run:

# vps-cron-fix.pl --help
vps-cron-fix.pl   # Script for checking and fixing VPS(s) configuration: limits, usage, etc.
                  # The script is configured to check (and to fix if needed) VPS(s) configuration
                  every 3 minutes (run as a cron job).
                  # VPS(s) are fixed daily anyway.

Usage:
   vps-cron-fix.pl [--vps=<name>|-v <name>] [--force|-f]

-v|--vps    # Fixes particular VPS.
            # If not set - script will fix all known VPS servers.
-f|--force  # Run script by force (even if it was run today already).
--help      # Print this help information.

5. vps-cron-net-reconfig.pl (VPS Network Reconfiguration Cron)

HS VPS 1.4-1 and up

Location: $VPSSCRIPTS/cron/vps-cron-net-reconfig.pl (by default /hsphere/shared/scripts/cron/vps-cron-net-reconfig.pl)

This script runs every 5 minutes as cron to reconfigure virtual servers' network. If subnet configuration is changed, it reconfigures all affected virtual servers' configuration. If subnet default gateway or mask is changed, it reconfigures and restarts network for each virtual server. If network interface is changed on a virtual server, it restarts this virtual server.

Usage:

vps-cron-net-reconfig.pl [--vps=<name>] [--force]

--vps       # Process particular VPS.
           # If not set - script will process all registered virtual servers.
--force     # Run script by force
--help      # Print this help information.

Examples:

vps-cron-net-reconfig.pl --vps=vps.test --force
   # Process VPS server vps.test forcefully, even if the reconfig flag is not set

vps-cron-net-reconfig.pl --vps=vps.test
   # Process VPS server vps.test if the reconfig flag is set

vps-cron-net-reconfig.pl --force
   # Process all registered virtual servers, even if reconfigure flag is not set

vps-cron-net-reconfig.pl
   # Process all registered VPS server(s) if the reconfig flag is set

VPS Configuration Scripts

1) ./vps-addip.pl VPS_HOST_NAME IP:MASK
Assigns new IP address to the VPS_HOST_NAME virtual server.

2) ./vps-rmip.pl VPS_HOST_NAME IP[:MASK]
Removes IP from VPS_HOST_NAME.

3) ./vps-dlimit-set VPS_HOST_NAME DISK_LIMIT_VALUE
Sets disk usage limit for VPS_HOST_NAME to DISK_LIMIT_VALUE, in Mb.

4) ./vps-dlimit-get VPS_HOST_NAME
Returns disk limit and disk usage for VPS_HOST_NAME.

5) ./vps-mlimit-set VPS_HOST_NAME MEMORY_LIMIT_VALUE
Sets memory limit for the VPS_HOST_NAME server to MEMORY_LIMIT_VALUE, in Mb

6) ./vps-mlimit-get VPS_HOST_NAME
Returns memory limit and memory usage for VPS_HOST_NAME

7) ./vps-plimit-set VPS_HOST_NAME PROCESS_LIMIT_VALUE
Sets limit on the number of processes running on VPS_HOST_NAME to PROCESS_LIMIT_VALUE, in Mb

8) ./vps-plimit-get VPS_HOST_NAME
Returns the limit on and the number of processes running on VPS_HOST_NAME

9) ./vps-flimit-get VPS_HOST_NAME
Returns file handlers limit, and the number of opened at this moment files VPS_HOST_NAME

10) ./vps-flimit-set VPS_HOST_NAME
Sets file handlers limit for VPS_HOST_NAME

11) ./vps-tcplimit-get VPS_HOST_NAME
Returns the limit on socket connections and the number of established connections for VPS VPS_HOST_NAME

12) ./vps-tcplimit-set VPS_HOST_NAME
Sets limit for established socket connections for VPS VPS_HOST_NAME

13) ./vps-dev-speed.pl
Tools to get|set the speed of virtual network interface.
Note: Virtual network interface speed must be divisible by 64000.
Usage: vps-eth-speed.pl VPS_NAME [--dev=<device>|-d <device>] --get|--set <SPEED>
For more information, please run: vps-dev-speed.pl --help

14) ./vps-dev-speed-set VPS_NAME [--dev=<device>|-d <device>] <SPEED>
Sets work speed to <SPEED> Kb/sec for virtual network interface <device> on Virtual Private Server VPS_NAME
Note: Virtual network interface speed (<SPEED> value) must be divisible by 64000.
Note: If --dev=<device>|-d <device> option not specified, <SPEED> value will be set to all registered virtual network interfaces on VPS VPS_NAME

15) ./vps-dev-speed-get VPS_NAME [--dev=<device>|-d <device>]
Returns work speed for virtual network interface <device> on Virtual Private Server VPS_NAME
Note: If --dev=<device>|-d <device> option not specified, returns speed for all virtual network interfaces registered on VPS VPS_NAME, in the following format:

VDEV0 SPEED0
VDEV1 SPEED1
...

16) ./vps-start.pl [VPS_HOST_NAME | [-a|--all]]
Turns on VPS_HOST_NAME, or all known stopped VPS servers if the -a|--all option is specified.

17) ./vps-stop.pl [VPS_HOST_NAME | [-a|--all]]
Turns off VPS_HOST_NAME, or all known running VPS servers if the -a|--all option is specified.

18) ./vps-suspend.pl [VPS_HOST_NAME | [-a|--all]]
Suspends (turns off and sets ONBOOT=no) vserver [VPS_HOST_NAME], or all known VPS servers if the -a|--all option is specified.

19) ./vps-resume.pl [VPS_HOST_NAME | [-a|--all]]
Resumes (turns on and sets ONBOOT=yes) vserver [VPS_HOST_NAME], or all known VPS servers if the -a|--all option is specified.

20) ./vps-rootpwd.pl VPS_HOST_NAME
To set new password for user root, send it to STDIN.

21) ./vps-du.pl
Returns disk usage for all known VPSs on the host server in the format required by H-Sphere Control Panel.

22) ./vps-get-config.pl VPS_HOST_NAME
Returns all VPS configuration parameters in the format required by H-Sphere Control Panel.

View List of Installed VPS's

The ./vps-list.pl script returns brief information about all VPS installed on the host server, installed VPS packages, values of configuration variables.

Example:

# ./vps-list.pl

Kernel release: 2.4.21-freevps-1.3-22smp
FreeVPS kernel patch build: 0 [19691231]
FreeVPS tools release: 1.3-9
H-Sphere VPS release: 1.3-6.4 [20050426]
Linux release: CentOS release 3.3 (final) [CentOS3]
Free disk space on VPS home [/home/hsphere/local/vservers]: 9346 Mb

Virtual Private Servers found on the host:
----------------------------------------------------------------------------------------------------------------------------
ID NAME              STATUS VDEV:HDEV:IP/MASK+|-(UP|DOWN) DISK (Mb)     MEMORY (Mb) SWAP   PROCESSES CPU (%)    TRAFFIC
-----------------------------------------------------------------------------------------(Mb)------------s--h--used-----(Mb)
5  vps1.psoft              run. eth0:eth0:10.0.0.2/24-        0     1707.6  0    0.8    0.5    0    5    0  0  0    0.0
6  vps2.psoft              run. eth0:eth0:160.79.224.138/24+  0     425.0   0    2.2    1.4    0    8    0  0  0    0.0
----------------------------------------------------------------------------------------------------------------------------

Display all settings for VPSs on this host [y/n]? 

Install/Uninstall Additional Packages

• To install an additional template or package into completely created virtual server use vps-pkg-inst.pl script.

  Run # ./vps-pkg-inst.pl --help to get help on the script options:

  vps-pkg-inst.pl   # Install template or single package into Virtual Private Server(s)
  
  Usage:
     vps-pkg-inst.pl --vps=|--all --package=|--template=