TOCPREVNEXTINDEX

Ensim Corporation


Chapter 2
Using Command Line
Interface scripts

Introduction

This chapter provides information on using Command Line Interface scripts.

Topics include:


Note icon

Command Line Interface scripts are advanced features for which limited Customer Support is available. The syntax of these commands may change in future releases of Ensim Pro.

Some of the commands in this chapter include the shell primitive \ which is used to enter a new line, without the shell executing the command. This is included for reasons of clarity and can be omitted if your command fits in one line.


About Command Line Interface scripts

Ensim offers Command Line Interface scripts for automating some of the tasks you perform as an ISP or Appliance Administrator. Most of these scripts reside in the directory /usr/local/bin and some in /usr/sbin. Use any Telnet or SSH client to access the server running Ensim Pro and execute these scripts.

The command line is composed of PERL programs and modules. The arguments for a script are passed in an encoded format by the interface to avoid security problems with special shell escapes. As a rule the interface fills in defaults and the command line tool checks all the arguments it receives.

The error messages go to STDERR and the output goes to STDOUT. If the command fails, it exits with code 1. If there are error messages on STDERR and the exit code is 0, it means that the operation succeeded, but some problems were encountered.

Functions that add information try to delete all the changes they made if an error occurs (so they either totally succeed with no warning messages, or fail). Functions that delete information try to push through even if some errors (other than invalid parameters or domain not found in the configuration file or some other major problem in the very beginning) occur.

These operations can succeed and still give warnings. The operations that change information behave somewhat similarly to the ones that delete them.

To see the syntax for any command, type the following at the command line.

<script name> --help

Using Command Line Interface scripts

This section explains the usage and syntax of scripts that you can use for:

Looking up site information

The Ensim Pro file system maintains site information by assigning each domain a number and a corresponding top-level UNIX user through which it identifies the site’s following basic information.

Each site on your server is known to the file system as site<n> (called the site handle). The top-level UNIX user is known as admin<n>, where n is a number matching the site number.

The top-level UNIX user is the user handle to the site. Process lists will not show Site Administrator names, but instead show top-level UNIX user names.


Note icon

Using the ps command will not show which process belongs to which domain. Use the sitelookup command after ps, to map a UNIX user to a site and view information about the sites on your server.


Syntax

/usr/local/bin/sitelookup [-a] [-w <wp_user>] [-s <site_handle>] \
[-d <
domain>] [-u <site_admin>] \
[domain, wp_user, site_handle, site_root, site_admin]

where:

The command returns the following information, as instructed.

The following section lists some examples of this syntax.


Example icon

1

The command:

sitelookup -w admin1 domain,site_handle

returns the following information associated with the top level UNIX user admin1:

For example:

example.com,site1


Example icon

2

The command:

sitelookup -s site25 site_root

returns the name of the root directory of the site with the site handle site25.

For example:

/home/virtual/example1.example.com


Example icon

3

The command:

sitelookup -a

returns the following for all the sites you manage.

For example:

example1.example.com,admin1,site1,
 /home/virtual/example1.example.com,Pawan

example2.example.com,admin2,site2,
 /home/virtual/example2.example.com,Dave

Changing the Appliance Administrator password

To change the password of the Appliance Administrator (appliance owner), use the passwd_appl_admin script. The new password must be entered on standard input to complete the script. The change is effected immediately without the need to restart Ensim Pro.

Syntax

/usr/sbin/passwd_appl_admin <appl_admin_name>

where:

<appl_admin_name> is the login name of the Appliance Administrator.

Changing the Site Administrator password

To change the password of the Site Administrator (domain owner), use the ChangeDomainPasswd script. This script will not exit until you complete the operation by entering the new password for the domain on standard input.

Syntax

/usr/local/bin/ChangeDomainPasswd <domain name> <domain password on stdin>

where:

Changing the Site Administrator email address

To change the Site Administrator‘s email address, use the ChangeEmail script.

Syntax

/usr/local/bin/ChangeEmail <domain name> <email address>

where:

Changing the User Administrator password

To change the password of the User Administrator (domain user), use the ChangePasswdVirtUser script. This script will not exit until you complete the operation by entering the user’s new password on standard input.

Syntax

/usr/local/bin/ChangePasswdVirtUser <domain name> <username>

<user’s password on stdin>

where:


Example icon

ChangePasswdVirtUser example.com myname newpass

In this example, the script changes a user’s password with the following specifications.

Adding a Service Plan

Ensim Pro is shipped with a single default Service Plan that contains all the services and options you need to create and make Ensim Pro domains usable by your customers. However, you can add any number of additional Service Plans to suit the needs of your customers and their businesses.

Many Internet service providers find it most efficient to use a template-type Service Plan that provides the basic services and options that all their customers will use; then create additional Service Plans that add other optional services to meet specific customer needs. This way, they do not have to specify all services and options whenever they create a new Service Plan. By using a template Service Plan, they can automatically assign most services and options; then add specific additional services and options for new Service Plans.

To add a new Service Plan, use the AddPlan script.

Syntax

/usr/local/bin/AddPlan

[-p <source plan> | -s <source site> | -d <source domain> |
-i <
source IP> | -t <source path>]
[-c <
service>,<option>=<value>,[on|off],... ...]
[-f | --force] <
target plan>

where:


Note icon

If the -t option is used, the path will be /home/virtual/<sourcepath>/info/current.


The following services, with a description of their options, if any, are available.

Table 2-1 lists the services you can specify when you create a new Service Plan, as well as the services’ options and their values.

Table 2-1. Service Plan services and options - I 
Service
Option
Value
Description
siteinfo
enabled
1 (enabled)
or
0 (disabled)
Whether site information is enabled or disabled for the site.
spam_filter
None
on (enabled)
or
off (disabled)
Whether spamfilter is enabled or disabled for the site.
mailscanner
 
on (enabled)
or
off (disabled)
Whether virus scanning is enabled or disabled for the site.
 
scan_incoming
1 (enabled)
or
0(disabled)
Whether virus scanning is enabled or disabled for incoming emails to the site.
 
scan_outgoing
1 (enabled)
or
0(disabled)
Whether virus scanning is enabled or disabled for outgoing emails from the site.
 
domain
plain text
(for example: myco.com)
The default domain name for a site created with this Service Plan.
admin_user
plain text
The user name for the Site Administrator.
password
plain text
The Site Administrator’s password. The administrator will be prompted for the plain text password.
tpasswd
plain text
The Site Administrator’s password. Specify the password by typing tpasswd=<plain text password> at the command line.
cpasswd
encrypted text
The Site Administrator’s password. Specify the password by typing cpasswd=<password in encrypted text> at the command line.
email
plain text
(for example: admin@myco.com)
The Site Administrator’s email address.
aliases
enabled
1 (enabled)
or
0 (disabled)
Whether the aliases option is enabled or disabled for the site.
 
aliases
list of text items
The domain’s aliases. Each alias can be used as the domain portion of an email address, a URL, or the target host of an FTP, Telnet, SSH, IMAP, or POP connection. This must be specified as a list, as described for ipaddrs (see ).
analog
enabled
1 (enabled)
or
0 (disabled)
Whether Analog log analyzer is enabled or disabled for the site.
logrotate
enabled
1 (enabled)
or
0 (disabled)
Whether logrorate is enabled or disabled for the site.
ipinfo
namebased
1 (name-based).
or
0 (IP-based)
Whether the site is name-based or IP-based.
ipaddrs
One or more IP addresses, separated by commas.
The list of IP addresses that will be configured if this site is IP-based. The format requires brackets:
[<address1>,<address2>]

Note: Some shells treat brackets as special characters. You may need to include escape characters for the brackets:

\[<address1>,<address2>\]
diskquota
enabled
1 (enabled)
or
0 (disabled)
Whether disk quota is enabled or disabled for the site.
units
  • B or b for bytes
  • KB or kb for kilobytes
  • MB or mb for megabytes
  • GB or gb for gigabytes
The unit of measurement for the disk quota.
quota
<quota> <unit>
(for example: 500 MB)
The number specifying the size of the quota, in the units specified.
telnet
enabled
1 (enabled)
or
0 (disabled)
Whether Telnet is enabled or disabled for the site.
jail
1 or 0
If set to 1, the Site Administrator's shell access to the site through Telnet will be jailed within the site's file system.
If set to 0, the Site Administrator may browse the entire server's file system, except where restricted by directory ownership or permissions.
bandwidth
enabled
1 (enabled)
or
0 (disabled)
Whether bandwidth montoring is enabled or disabled for the site.

Important: Disabling bandwidth while adding a domain using the AddVirtDomain script induces erratic mail behavior. Do not disable bandwidth when you add a domain using the AddVirtDomain script.

threshold
number
The number of bytes, after which the Site Administrator should be notified that the site has exceeded its bandwidth allocation.
rollover
number
(any number between 1 and 31)
The date that will be used to calculate monthly totals.

Note: If set to 0, the last date of each month will be used.

units
B or b (Bytes)
KB or kb (Kilobytes)
MB or mb (Megabytes)
GB or gb (Gigabytes)
The unit of measurement used to indicate bandwidth threshold.
ssh
enabled
1 (enabled)
or
0 (disabled)
Whether SSH access is enabled or disabled for the site.
jail
1 or 0
If set to 1, the Site Administrator's shell access to the site through SSH will be jailed within the site's file system.
If set to 0, the Site Administrator may browse the entire server's file system, except where restricted by directory ownership or permissions.
imap
enabled
1 (enabled)
or
0 (disabled)
Whether the IMAP mail protocol is enabled or disabled for the site.
bind
enabled
1 (enabled)
or
0 (disabled)
Whether the BIND name server protocol is enabled or disabled for the site.
users
maxusers
number
The maximum number of users allowed on this site.
proftpd
ftpserver
plain text
The FTP server’s domain name.

Note: If you are using domain aliasing, and the name of this server contains a prefix (such as FTP), followed by the domain name as specified in siteinfo (see ), the aliasing function will attach this prefix to all other aliases to generate FTP server names.

apache
enabled
1 (enabled)
or
0 (disabled)
Whether the Apache Web server protocol is enabled or disabled for the site.
jail
1 (enabled)
or
0 (disabled)
If set to 1, a high security site will be created.
If set to 0, a 3.1 compatible site or low security site will be created.
 
webserver
plain text
The Apache Web server’s domain name.

Note: If you are using domain aliasing, and the name of this server contains a prefix (such as apache), followed by the domain name as specified in siteinfo (see ), the aliasing function will attach this prefix to all other aliases to generate Web server names.

jail
1 or 0
If set to 1, certain Apache features and Apache-related services will either be restricted or constrained to prevent access to other sites' data. In particular, mod_perl and mod_php will be disabled for the domain (interpretation and execution of PHP and Perl scripts will be re-routed through jailed CGI versions of PHP and Perl), and the use of "Options FollowSymlinks" will be denied.
If set to 0, these restrictions will be removed.
 
mailserver
plain text
The mail server’s domain name.

Note: If you are using domain aliasing, and the name of this server contains a prefix (such as mail), followed by the domain name as specified in siteinfo (see ), the aliasing function will attach this prefix to all other aliases to generate mail server names.

preference
number
The preference to give to MX records for the mail server names.
anonftp
enabled
1 (enabled)
or
0 (disabled)
Whether Anonymous FTP access enabled or disabled for the site.
openssl
enabled
1 (enabled)
or
0 (disabled)
Whether OpenSSL access is enabled or disabled for the site.
cgi
enabled
1 (enabled)
or
0 (disabled)
Whether CGI scripting is enabled or disabled for the site.
 
scriptalias
plain text
The leading component (after the host name) of URLs referencing CGI scripts for this site.
mod_perl
enabled
1 (enabled)
or
0 (disabled)
Whether mod_perl for Apache is enabled or disabled for the site.
 
alias
plain text
The leading component (after the host name) of URLs referencing Perl scripts for this site.
reseller
enabled
1 (enabled)
or
0 (disabled)
Whether reseller access is enabled or disabled for the site.
 
reseller_id
plain text
The name of the reseller.
tomcat4
enabled
1 (enabled)
or
0 (disabled)
Whether Tomcat is enabled or disabled for the site.
develenv
enabled
1 (enabled)
or
0 (disabled)
Whether GNU development tools is enabled or disabled for the site.
ssi
enabled
1 (enabled)
or
0 (disabled)
Whether Server Side Includes (SSI) is enabled or disabled for the site.
sendmail
enabled
1 (enabled)
or
0 (disabled)
Whether the Sendmail mail server protocol is enabled or disabled for the site.
subdomain
enabled
1 (enabled)
or
0 (disabled)
Whether subdomains are enabled or disabled for the site.
max
number
The maximum number of subdomains that can be created for a site.

Note: -1 indicates unlimited subdomains for a site.

wildcards
1 (enabled)
or
0 (disabled)
Whether subdomain wildcards are enabled or disabled for the site.

Note: Enabling subdomain wildcards for a site (for example, example1.com), will cause the range of (sub)domain names, “*.example1.com” to be reserved for the site. No other site on the Ensim Pro server will be allowed to have a site name like 'xxx.example1.com'.

base
plain text
This indicates the base directory, relative to the site's file system, under which all subdomains for the site will be located.

Note: This restriction only applies to regular subdomains. User subdomains will have their directory in
/home/<owner>/ public_html/

weblogs
enabled
1 (enabled)
or
0 (disabled)
Whether Web logs is enabled or disabled for the site.
vacation
enabled
1 (enabled)
or
0 (disabled)
Whether vacation message is enabled or disabled for the site.
majordomo
enabled
1 (enabled)
or
0 (disabled)
Whether Majordomo mailing lists is enabled or disabled for the site.
sqmail
enabled
1 (enabled)
or
0 (disabled)
Whether SquirrelMail Web-based email is enabled or disabled for the site.
frontpage
enabled
1 (enabled)
or
0 (disabled)
Whether Microsoft FrontPage is enabled or disabled for the site.
mivamerchant
enabled
1 (enabled)
or
0 (disabled)
Whether Miva Merchant is enabled or disabled for the site.
webalizer
enabled
1 (enabled)
or
0 (disabled)
Whether Webalizer log analysis is enabled or disabled for the site.
mysql
enabled
1 (enabled)
or
0 (disabled)
Whether the MySQL database server protocol is enabled or disabled for the site.
 
dbaseadmin
plain text
The user name of the site’s database administrator.
dbaseprefix
plain text
The specified string that will be prefixed to the name of any database that the Site Administrator creates.

Note: Since this prefix defaults to the first 30 characters of the main site domain name, we recommend that you not change this unless it conflicts with an already existing prefix.

dbasenum
number
The number of databases that can be created by the Site Administrator.
vhbackup
enabled
1 (enabled)
or
0 (disabled)
Whether site and user level backup is available for a site.
files
enabled
1 (enabled)
or
0 (disabled)
Whether File Manager access is enabled or disabled for the site.
Power Tools
scriptsmgr
enabled
on (enabled)
or
off (disabled)
Whether Power Tools is enabled or disabled for the site.
  • formmail-4.2b
  • gallery-1.3.4
  • invboard-1.1.2
  • oscommerce-2.2ms2
  • phpbb-2.0.6
  • phpnuke-6.9
  • phpopenchat-3.0.0b3
  • postnuke-0.7.2.6
enabled
1 (enabled)
or
0 (disabled)
Whether the tools are enabled or disabled for the site. You must specify the appropriate value for each tool.
Ignite services
aspmgr
enabled
1 (enabled)
or
0 (disabled)
Whether the service Ignite is enabled or disabled for the site.
siteopti_add
1 (enabled)
or
0 (disabled)
Whether the Site Administrator is enabled to subscribe to the Site Optimization service.
siteopti_manage
1 (enabled)
or
0 (disabled)
Whether the Site Administrator is enabled to manage the Site Optimization service.
sslcerts_add
1 (enabled)
or
off (disabled)
Whether the Site Administrator is enabled to subscribe to the SSL Certs service.
sslcerts_manage
1 (enabled)
or
0 (disabled)
Whether the Site Administrator is enabled to manage the SSL Certs service.
payment_add
1 (enabled)
or
0 (disabled)
Whether the Site Administrator is enabled to subscribe to the Payment Processing service.
payment_manage
1 (enabled)
or
0 (disabled)
Whether the Site Administrator is enabled to manage the Payment Processing service.
emailmark_add
1 (enabled)
or
0 (disabled)
Whether the Site Administrator is enabled to subscribe to the Email Marketing service.
emailmark_manage
1 (enabled)
or
0 (disabled)
Whether the Site Administrator is enabled to manage the Email Marketing service.

The following section lists some examples of the service plan syntax.


Example icon

1

This example adds a new Service Plan called Gold. Gold uses the default Service Plan as its template, but excludes the CGI service.

AddPlan -p default -c cgi,off Gold


Example icon

2

This example adds a new Service Plan called Gold. Gold uses the default Service Plan as its template, but includes the aliases service.

AddPlan -p default -c aliases,on,aliases=\[.org,.net\] Gold

Modifying a Service Plan

To modify a Service Plan, use the EditPlan script.

Syntax

/usr/local/bin/EditPlan

[-p <source plan> | -s <source site> | -d <source domain> |
-i <
source IP> | -t <source path>]
[-c <
service>,<option>=<value>,[on|off],... ...]
[-f | --force] <
target plan>

where:


Note icon

If the -t option is used, the path will be /home/virtual/<sourcepath>/info/current.


See Table 2-1 for a list of the services you can change or add to a Service Plan, as well as the services’ options and their values.

Removing a Service Plan

To remove a Service Plan, use the DeletePlan script.

Syntax

/usr/local/bin/DeletePlan <plan name>

where <plan name> is the name of the Service Plan you want to remove.

Adding a domain

To add a domain, use the AddVirtDomain script. This script adds a domain with the specified domain information and services. If you want to create a domain using pre-configured settings, specify the name of the corresponding Service Plan.


Important icon

Disabling bandwidth while adding a domain using the AddVirtDomain script induces erratic mail behavior. Do not disable bandwidth when you add a domain using the AddVirtDomain script.


Enabling Power Tools for a domain

Power Tools, a powerful new feature of Ensim Pro, can be enabled for a site using the scriptsmgr option. Once you enable Power Tools, Site Administrators can install and manage these tools using the Site Administrator control panel. Each tool follows the naming convention <tool_name>-<tool_version>, where <tool_name> is the name of the tool and <tool_version> is the version number of the tool. Example. gallery-1.3.4. Refer to the tabulated section Power Tools for the list of tools that are provided by Ensim Pro.

To enable Power Tools for a domain, enable the scriptsmgr option and the individual tools you want to enable. Individual tools that are not explicitly enabled will not be available to the site even if you enable the scriptsmgr option. Please refer to the example for help on enabling Power Tools for a domain.

Enabling email scanning services for a domain

Beginning with Ensim Pro 3.7, you can offer the following email scanning services for a site.

Please refer to the example for help on enabling the email scanning services for a domain.

Enabling Ignite services for a domain

Ensim Pro 4.0.3 introduces a suite of Web services called Ignite that provide cutting-edge business solutions to help enhance your business. Services include email marketing solutions to help you market your product and services, search engine optimization services to help you promote your Web site, and payment systems and site authentication services for your ecommerce business. These services are also available to your resellers.

You can enable Ignite services when you create or update a Service Plan or a site.

Please refer to the example for help on enabling the Ignite services for a domain. The tabulated section Ignite services lists the various Ignite options you can use on the command line.

Syntax

/usr/local/bin/AddVirtDomain

[-p <source plan> | -s <source site> | -d <source domain> |

-i <source IP> |-t <source path>]

[-c <service>,<option>=<value>,[on|off],... ...] [-f | --force]

where:


Note icon

If the -t option is used, the path will be /home/virtual/<sourcepath>/info/current.


See Table 2-1 for a list of service options, and their respective values, that you can specify on the command line while adding a domain.


Note icon

Options specified on the command line override the corresponding default values set in the Service Plan.



Example icon

To add a domain

AddVirtDomain -p default \
-c siteinfo,domain=example.com,admin_user=myname,tpasswd=go12 \
-c ipinfo,namebased=0,ipaddrs=\[10.8.3.65\] \
-c telnet,off \
-c analog,on \
-c scriptsmgr,on,formmail-4.2b=1,gallery-1.3.4=1 \
-c users,maxusers=75 \
-c spam_filter,on \
-c mailscanner,on,scan_incoming=1,scan_outgoing=1 \
-c aspmgr,on,siteopti_add=1,siteopti_manage=1,emailmark_manage=1

In this example, the script adds a domain example.com with the following specifications.

Changing the domain quota

To change the disk space allocated to a domain, use the ChangeQuota script.

Syntax

/usr/local/bin/ChangeQuota <domain name> <quota>

where:

Modifying a domain

To modify a domain’s information or Service Plan, use the EditVirtDomain script. The script allows you to update domain information and service settings, and enable or disable Power Tools and other services for a domain. Please refer to the examples for help on usage of the script.

Syntax

/usr/local/bin/EditVirtDomain

[-p <source plan> | -s <source site> | -d <source domain> |

-i <source IP> |-t <source path>]

[-c <service>,<option>=<value>,[on|off],... ...]

[-f | --force]

[<target site> | -I <target IP> | -D <target domain>]

where:


Note icon

If the -t option is used, the path will be /home/virtual/<sourcepath>/info/current.


See Table 2-1 for a list of service options you can change or add to a domain, as well as the options’ values.

The following section lists some examples of this syntax.


Example icon

1

In this example, the script changes the Service Plan of the domain example.com to Gold, disables the formmail-4.2b tool, and enables the phpnuke-6.9 tool and CGI service for the domain, not originally a part of the Gold Service Plan.

EditVirtDomain -p Gold -c cgi,on, -c scriptsmgr,on,formmail-4.2b=0,phpnuke-6.9=1 example.com


Example icon

2

In this example, the script changes the Service Plan of the domain example.com to Basic, disables the Spam Filtering service, disables virus scanning for outgoing emails, and enables the aliases service for the domain.

EditVirtDomain -p Basic -c spam_filter,off \
-c mailscanner,on,scan_outgoing=0 \
-c aliases,on,aliases=\[domainname.org,domainname.net\] \
-c aspmgr,siteopti_add=1,siteopti_manage=1,emailmark_manage=0 \ example.com

Disabling a domain

Disabling a domain can be useful in managing customers whose accounts are overdue or in question. To disable a domain, use the DisableVirtDomain script.

Syntax

/usr/local/bin/DisableVirtDomain <domain name>

where <domain name> is the name of the domain you want to disable.

Enabling a domain

To enable a domain, use the EnableVirtDomain script.

Syntax

/usr/local/bin/EnableVirtDomain <domain name>

where <domain name> is the name of the domain you want to enable.

Viewing a list of all the domains

To view a list of all the domains on a specific Ensim Pro server, use the ListAllVirtDomains script.

This script returns the following:

Syntax

/usr/local/bin/ListAllVirtDomains

Removing a domain

To remove a domain from a server, use the DeleteVirtDomain script.

Syntax

/usr/local/bin/DeleteVirtDomain <domain name>

where <domain name> is the name of the domain you want to remove.

Disabling a service

To disable a service on a specific domain, use the DisableVirtOption script. This script disables a specific service, but otherwise does not change the domain’s Service Plan.

Syntax

/usr/local/bin/DisableVirtOption <domain name> <service>

where:

Enabling a service

To enable a service on a specific domain, use the EnableVirtOption script.

Syntax

/usr/local/bin/EnableVirtOption <domain name> <service>

where:

Hiding a service

To hide a service, use the hide_service script. This script removes the service from the Ensim Pro control panel so that the Appliance Administrator cannot create domains with this service enabled.


Note icon

The services that you can hide or reveal are:
* bind
* mivamerchant
* mysql
* telnet
* tomcat


Syntax

/usr/local/bin/hide_service <service>

where <service> is the name of the service you want to hide from the Ensim Pro control panel.

Example:

/usr/local/bin/hide_service bind

or

/usr/local/bin/hide_service telnet

Revealing (unhiding) a service

To reveal a hidden service, use the unhide_service script. This script reinstates the service in the Ensim Pro control panel.


Note icon

The services that you can hide or reveal are:
* bind
* mivamerchant
* mysql
* telnet
* tomcat


Syntax

/usr/local/bin/unhide_service <service>

where <service> is the name of the service you want to reinstate in the Ensim Pro control panel.

Example:

/usr/local/bin/unhide_service bind

or

/usr/local/bin/unhide_service telnet

Adding a user to a domain

To add a user to a domain, use the AddVirtUser script. This script adds a user to a domain, specifying the information Ensim Pro needs to establish the user, as well as the server applications to which the user should be granted access.

You can specify the user’s password in either of two ways.

Syntax

/usr/local/bin/AddVirtUser [tpasswd=<ctxtpwd> | cpasswd=<crpwd> | passwd] \ <domain name> <username> <user’s full name> <user’s disk quota> \ <service>=<value>

where:


Note icon

To use this option, you first need to employ encryption software to encrypt the password. Enter the encrypted text in this variable.



Note icon

Use any one of the above three options to enter the user’s password depending on the security level desired while entering the password.



Note icon

The services currently available are Telnet, ProFTPd, and SSH.



Example icon

AddVirtUser tpasswd=MTVrules example.com JoBoy “John Doe” 20 \

telnet=1 ssh=1 proftpd=1

In this example, the script adds a user with the following specifications.

Changing the number of users allowed on a domain

To change the maximum number of users allowed on a domain, use the ChangeMaxUsers script.

Syntax

/usr/local/bin/ChangeMaxUsers <domain name> <number of users>

where:

Changing a user’s full name

To change a user’s full name, use the ChangeFullNameVirtUser script.

Syntax

/usr/local/bin/ChangeFullNameVirtUser <domain name> <username> <user’s full name>

where:


Example icon

ChangeFullNameVirtUser example.com Myname “Myname New”

Here, the script changes the user’s full name with the following specifications.

Changing a user’s information

To change a user’s information, use the ChangeInfoVirtUser script. This script changes a user’s full name and the amount of disk space allocated to the user.

Syntax

/usr/local/bin/ChangeInfoVirtUser <domain name> <username> <user’s full name> <quota>

where:


Example icon

ChangeInfoVirtUser example.com Myname “Myname New” 30

Here, the script changes the user’s information with the following specifications.

Removing a user from a domain

To remove a user from a domain, use the DeleteVirtUser script.

Syntax

/usr/local/bin/DeleteVirtUser <domain name> <username>

where:

Configuring logrotate

To configure logrotate settings, use the logrotate_be script

Syntax

logrotate_be [options]

Options

Notes

Getting quota reports

You can use the quota_report script to obtain a statistical report on the storage limits and usage of disk space allocated to “users” or “groups”. When you run the script, it invokes a system call quotactl that returns the following quota storage and usage information, one line for each unit of information, for the specified user ID and group ID.

Each line in the output translates to the following information:

Output Line 1: User quota enabled/disabled : Group quota enabled/disabled.
Uses “1” or “0” to indicate whether the user or group quotas are enabled or disabled respectively.

Output Line 2: Current disk space occupied by quotas (in 1024-byte blocks)
Displays the current disk space occupied by quotas in blocks of 1024-bytes.

Output Line 3: Preferred limit on disk space (in Kilobytes)
The preferred or “soft” limit indicates the maximum amount of disk space a user has on a partition. If you set the absolute limit and the time limit for excessive disk usage then the user can exceed the preferred limit and continue to use additional disk space until:

Once the absolute limit or the time limit expires, the user is prevented from using additional disk space until the user moderates disk space usage below the preferred limit. This resets the time limit assigned for excessive disk usage.


Important icon

If the absolute limit or the time limit for excessive disk usage is not set the user cannot use disk space in excess of the preferred limit.


Output Line 4: Absolute limit on disk space (in Kilobytes)
The absolute or “hard” limit indicates the maximum permissible limit for disk space usage within the set time limit. On exceeding the limit or the time period, the user is prevented from using additional disk space until disk space consumption is moderated below the preferred limit.

Output Line 5: Time limit for excessive disk usage
The time, in number of minutes, available for using or allocating disk space in excess of the “preferred” limit. On expiry of the time limit you will be unable to allocate or use additional disk space. The default time limit is set to one week or seven days.

Output Line 6: Number of inodes used currently
The number of inodes that are used currently.

Output Line 7: Preferred limit for inodes
The preferred or “soft” limit indicates the maximum number of inodes that can be stored on a user’s allocated disk space. If you set the absolute limit and the time limit for additional inodes then the user can exceed the preferred limit for inodes until:

Once the absolute limit or the time limit expires, additional inodes cannot be created until the user reduces disk space usage below the preferred limit. This resets the time limit assigned for additional inodes.


Important icon

If the absolute limit or the time limit for additional inodes is not set then inodes in excess of the preferred limit cannot be supported.


Output Line 8: Absolute limit on inodes
The absolute or “hard” limit indicates the maximum permissible limit for the number of inodes that can be stored on the disk space within the set time limit. If the absolute limit or the time period is exceeded, no additional inodes can be created until disk space consumption is moderated below the preferred limit.

Output Line 9: Time limit for excessive inode usage
The time, in number of minutes, available for supporting additional inodes in excess of the “preferred” limit. On expiry of the time limit you will be unable to support additional inodes. The default time limit is set to one week or seven days.


Note icon

Ensim Pro sets and manages quotas with the following default parameters.
* The “preferred” and “absolute” quota limits are equal.
* inode limits are not set.


Syntax

/usr/bin/quota_report -d <directory> [-q|-u <uid>|-g <gid>]


Example icon

Sample script and output

# quota_report -d / -g 504

1:1

36376

512000

512000

0

4445

0

0

0

Exporting appliance, reseller, site, or user’s data for backup

To export appliance, reseller, site, or user’s data for backup, use the vhexport script.

Syntax

/usr/local/bin/vhexport

-h|--help

-a|--appliance-info

-r|--reseller reseller1[,info][,site1,site2,...,site<n>]

-s|--sites site1,site2,...,site<n>

-u|--users site1,user1,user2,...,user<n> ...

-u|--users user1@domain.com,user2@domain.net,... ...

[-U|--URL <destination URL>] [-f|--url-info-file=<file>]

[-t|--split-threshold <size>]

[-z|--compressed]

[-c|--crypt] [-A|--algo=<algorithm>] [-k|--key-from-fd=<fd>]


Note icon

Individual exports will be made for each reseller, site, and user specified. Note that site exports include the necessary information to recreate users when imported. When specifying a <destination URL>, the proper '.tar.gz' or '.tar' ending will automatically be added to the end of the URL, based on whether compression is set or not, respectively.


The <destination URL> may also contain format specifiers for the purpose of automatically generating URLs when one or more exports are being made with a single invocation.

The following time-related format specifiers are allowed (these are the format specifiers as understood by the server's C library strftime() function; please see the strftime() manual reference for more information):

In addition, the following format specifiers allow you to include information about the type of export being made:

For example, the command:

vhexport -u joe@mydomain.com,bob@yourdomain.net -U file:///tmp/%H_%t_%N_%Y_%B_%

on the server appliance.ensim.com will result in the following exports being created (assuming the date is December 23, 2002):

/tmp/appliance.ensim.com_user_joe@mydomain.com_2002_December_23.tar

/tmp/appliance.ensim.com_user_bob@yourdomain.net_2002_December_23.tar

If the -z option was specified, the resulting exports would have been:

/tmp/appliance.ensim.com_user_joe@mydomain.com_2002_December_23.tar.gz

/tmp/appliance.ensim.com_user_bob@yourdomain.net_2002_December_23.tar.gz

-f|--url-info-file specifies a file that contains additional information to be used with any URLs specified. It is generally not safe to include a password on the command line; you can use this option to point to a file that contains the password information. Note that if you choose to do this, you should make sure that the file is readable only by you. The file may contain two or three bits of information: host and user are mandatory; pass is optional.

An example file might contain:

-t|--split-threshold-size determines how large each output file is allowed to grow before another output file is started, and may only be specified if the -U|--URL argument is specified too. The argument must be a number optionally followed by a unit; the unit may be any one of b (1), kd (1000), k (1024), md (1,000,000), m (1,024,768), gd (1,000,000,000) or g (1,073,741,824), and defaults to “m”. This option is useful when exporting a large site or user, and the target server cannot handle files that are larger than a certain size.

For example, assume the site example.com would consume 3 GB of space, but the destination server cannot handle files larger than 1 GB. The command:

vhexport --sites example.com -U ftp://mybackupserver.com/%t_%N -t 1g

will result in the following files being created:

When importing, only the first URL in the above list should be specified. The import process will automatically attempt to retrieve the other files.

-c|--crypt specifies that the resulting export data should be encrypted before being written to the destination. A symmetric cipher is used. If the -k|--key-from-fd option is not specified, you will be prompted to enter a passphrase. -k|--key-from-fd may be used to specify a file descriptor from which the passphrase may be read. If set to 0, this will be equivalent to reading from standard in. -a|--algo allows you to change the cipher algorithm used (this option is not currently supported; that is, there is only a single type of cipher). Note that you must use the -U|--URL argument to specify the export destination if you don't use the -k|--key-from-fd option.

Importing appliance, reseller, site, or user’s data from a backup

To import appliance, reseller, site, or user’s data from a backup, use the vhimport script.

Syntax

/usr/local/bin/vhimport

-r|--role=appliance

reseller:<reseller name or id>

siteadmin:<domain name or site id>

siteuser:<user@domain or user@site id>

[-t|--target=<reseller name or id>]

[-t|--target=<domain name or site id>]

[-t|--target=<user@domain or user@site id>]

[--restore-user-configs] [--restore-site-configs]

[--restore-reseller-configs] [--overwrite-data]

[-U|--URL=<source URL>] [-R|--recurse]

[-f|--url-info-file=<file>]

[-S|--services service1,...]

[-d|--decrypt] [-A|--algo=<algorithm>] [-k|--key-from-
fd=<fd>]

If the role argument is not appliance, you must specify additional information to identify the reseller, site administrator, or site user on whose behalf the import is being performed.

If only importing a single file, you may specify the intended target of the import. For example, if the role was set to appliance or reseller, the user would be able to import a backup made from site A into an existing site B, by specifying site B as the target. Targets may only be specified for imports where the imported entity has fewer privileges than the importing role, and the importing role must control the intended target. That is, an appliance may specify any target for reseller, site, or user imports, whereas a reseller may only specify a target for site or user imports, and the target must be a site or user under his or her control.

If a target is not specified, the target will either be assumed from the role argument or from the import data. For example, if the role was set to reseller and the import file was a reseller backup, then the target would be the reseller given with the role identifier. If the import file had been a site backup, then the target would be the domain described by the import file, and will be allowed as long as the specified reseller owns that site, or the site does not exist.

The --overwrite-data option signifies that the import should overwrite existing data. If not specified, only data present in the import but not in the target will be restored. Note that this flag does not affect reseller, site, or user configurations.

The --restore-user-configs option signifies that if any user imports are encountered, and the user currently exists, then the user's configuration will be set to the configuration saved in the archive. Without this option, an existing user's configuration will not be changed.

The --restore-site-configs option signifies that if any site imports are encountered, and the site currently exists, then the site's configuration will be set to the configuration saved in the archive. Without this option, an existing site's configuration will not be changed.

The --restore-reseller-configs option signifies that if any reseller imports are encountered, and the reseller currently exists, then the reseller's configuration will be set to the configuration saved in the archive. Without this option, an existing reseller's configuration will not be changed.

The --restore-all-configs option is equivalent to specifying --restore-user-configs --restore-site-configs --restore-reseller-configs together.

The --recurse option will cause any imports made at the same time as one of the imports specified on the command line to be imported as well. For example, if a user exported everything on the server (appliance, resellers, sites) in a single invocation of vhexport, then all the user would have to do to completely recover the system is import the appliance backup by specifying the --recurse option.

-f|--url-info-file specifies a file that contains additional information to be used with any URLs specified. It is generally not safe to include a password on the command line; you can use this option to point to a file that contains the password information. Note that if you choose to do this, you should make sure that the file is readable only by you. The file may contain two or three bits of information; host and user are mandatory, and pass is optional. An example file might contain:

-c|--crypt specifies that the import data is encrypted and must be decrypted before being restored. If the -k|--key-from-fd option is not specified, you will be prompted to enter a passphrase. -k|--key-from-fd may be used to specify a file descriptor from which the passphrase may be read. If set to 0, this will be equivalent to reading from standard in. -a|--algo allows you to change the cipher algorithm used (this option is not currently supported; that is, there is only a single type of cipher). Note that you must use the -U|--URL argument to specify the import source if you don't use the -k|--key-from-fd option, or if you set the -k|--key-from-fd option to 0.

Using the Reseller Command Line Interface scripts

This section explains the usage and syntax of scripts you can use to manage reseller accounts.

You can use command line scripts for:

Refer to Table 2-2 for the complete list of services, options, and values that you can specify for a reseller account.


Note icon

You must specify values for services or options that you want to enable; no default values are set other than those explicitly specified in the table. Further, you cannot leave an option blank.


Table 2-2 lists the services, options, and values that you can specify for a reseller account.

Table 2-2. Services and options - II
Service
Option
Value
Description
apache
jail
1 (enabled)
or
0 (disabled)
If set to 1, a reseller can only create “jailed” sites (sites that restrict the apache daemon to the chrooted portion of the site’s file system).
If set to 0, a reseller can create “jailed” or “non-jailed” sites.
ssh
jail
1 (enabled)
or
0 (disabled)
If set to 1, a reseller can only create sites where the SSH remote access service is “jailed” ( remote shell access to the site using SSH is restricted to the chrooted portion of the site’s file system).
If set to 0, a reseller can create sites with “jailed” or “non-jailed” SSH access.
telnet
jail
1 (enabled)
or
0 (disabled)
If set to 1, a reseller can only create sites where the Telnet remote access service is “jailed” (remote shell access to the site using Telnet is restricted to the chrooted portion of the site’s file system).
If set to 0, a reseller can create sites with “jailed” or “non-jailed” Telnet access.
bandwidth
units
B or b (Bytes)
KB or kb (Kilobytes)
MB or mb (Megabytes)
GB or gb (Gigabytes)
The unit for measuring the rate of data transmission.
The default is B.
threshold
number
The total bandwidth (in the selected units) that can be assigned to sites created by a reseller.
diskquota
 
units
B or b (Bytes)
KB or kb (Kilobytes)
MB or mb (Megabytes)
GB or gb (Gigabytes)
The unit for measuring the disk space allocated to a reseller.
The default is B.
quota
number
The total disk space (in the selected units), that can be assigned to sites created by a reseller.
ipinfo
ipbased
number
The maximum number of IP-based sites that can be created by a reseller.
namebased
number
The maximum number of name-based sites that can be created by a reseller.
reseller
username
plain text
The user name of the reseller
fullname
plain text
The full name of the reseller
email
plain text
(for example, admin@example.com)
The email address of the reseller
passwd
plain text
The reseller’s password. The reseller will be prompted for the plain text password.
tpasswd
plain text
The reseller’s password. Specify the password by typing the following at the command line prompt:
tpasswd=<plain text password>
cpasswd
encrypted text
The reseller’s password. Specify the password by typing the following at the command line prompt:
cpasswd=<encrypted text password>
enabled
1 (enabled)
or
0 (disabled)
Indicates whether the reseller account is enabled or disabled.
users
maxusers
number
The total number of user accounts for sites created by a reseller.

Viewing the list of reseller accounts

To view the list of reseller accounts, use the ListResellers script. The script returns the list of resellers, one line of text for each reseller, with the specified account information, services, enabled options, and the corresponding values. In addition to the services and options enabled for the reseller, the list will also display the following information for the specified service.

Table 2-3. Additional information displayed in the script output
Service
Attribute
Value
Description
diskquota
alloc_quota
number
The actual amount of disk space allocated to the sites created by the reseller.
bandwidth
alloc_threshold
number
The actual amount of bandwidth allocated to the sites created by the reseller.
ipinfo
alloc_ipbased
number
The actual number of IP-based sites created by the reseller.
alloc_namebased
number
The actual number of name-based sites created by the reseller.
users
alloc_maxusers
 
The number of users that can be created for all the sites by the reseller.
reseller
reseller_id
number
The reseller ID of the reseller.


Note icon

*The password of a reseller will not be listed in the script output. Some values may have backslash-quoted characters (for example, spaces in the reseller full name).
*Bandwidth and quota values are returned in bytes.


Syntax

/usr/local/bin/ListResellers


Example icon

A sample output produced by the ListResellers script

apache,jail=0 users,maxusers=100,alloc_maxusers=0 ssh,jail=0 diskquota,alloc_quota=0,quota=524288000 reseller,username=Myname,fullname=Myname,enabled=1,reseller_id=4,
email=myname@example.com ipinfo,alloc_ipbased=0,namebased=10,alloc_namebased=0,ipbased=10

Note icon

The sample output used in the example has been word-wrapped for readability. The actual output is displayed in a single line, with the various services separated by a single space.


In this example, the script lists a reseller with the following account information:

Creating a reseller account

To create a reseller account, use the AddReseller script. If you want to create reseller accounts that have a common set of services, you can use an existing reseller account as a template for the new reseller.

See Table 2-2 for the list of services, with corresponding options and values, that you can enable for the reseller account. On successful creation of the account, the message, Reseller <reseller name> successfully created, is displayed.

Syntax

/usr/local/bin/AddReseller [ -r <source reseller> ] [ -c <service>,<option>=<value>,... ...]

where:


Example icon

Creating a reseller account without using a template

AddReseller -c apache,jail=0 -c bandwidth,threshold=10485760000 -c users,maxusers=100 -c ssh,jail=0 -c diskquota,quota=524288000 -c reseller,username=Myname,fullname=Myname,enabled=1,
passwd,email=myname@example.com -c telnet,jail=0 -c ipinfo,namebased=10,ipbased=10

In this example, the script adds a reseller account with the following account information:

AddReseller -r reseller1 -c reseller,username=reseller2

In this example, the script creates a new reseller account, with the user name reseller2, using another reseller account, reseller1, as the template on which to base the account information.

Modifying a reseller account

To modify a reseller account, use the EditReseller script. See Table 2-2 for the list of services, with corresponding options and values, that you can specify for the reseller account. On successful modification, the message, Reseller, <reseller_name> successfully updated, is displayed.

Syntax

/usr/local/bin/EditReseller [ -r <source reseller> ] [ -c <service>,<option>=<value>,... ...] <reseller username>...

where:

In this example, the script modifies the user name and site information for an existing reseller account.

Removing a reseller account

To remove a reseller account, use the DeleteReseller script.

Syntax

/usr/local/bin/DeleteReseller <reseller username>

where

<reseller username> is the user name of the reseller you want to remove


Example icon

/usr/local/bin/DeleteReseller reseller1

In this example, the script removes the reseller account with the user name, reseller1.


Ensim Corporation
www.ensim.com

Contact Ensim
www.ensim.com/about/contact.html

TOCPREVNEXTINDEX