freeVSD Protocol Guide ====================== Introduction ------------ This document provides a reference to the freeVSD protocol and uses characters to denote optional and required arguments of the freeVSD protocol. Frequently a command will require arguments. If the argument is written within angled- brackets, e.g. , then it is a required argument for the command. If the argument is written within square-brackets, e.g. [arg2], then it is an optional argument. freeVSD Protocol Overview ------------------------- The following section defines the freeVSD protocol and explains the format of the commands and virtual server connection/disconnection messaging. The freeVSD protocol consists of commands and modules that provide instructions from the client operating the virtual server to the virtual server itself. In addition, the protocol also provides instructions for host server administration. freeVSD Protocol Format ----------------------- The freeVSD protocol includes unique input/output formats for commands as well as connection/disconnection messaging. I/O is line oriented and there are no limits on the length of the line. Upon the initiation of a connection to port 1725 on the host server, the client receives the following message: +OK freeVSD Virtual Server administrator host.isp.net v1.4.1 server ready When the connection is closed, the client receives the following message: +OK Virtual server admin signing off Input Format of freeVSD Protocol Commands ----------------------------------------- Within a single connection multiple commands can be applied to multiple virtual servers. The token `EOF' terminates input. Curly-brackets are used to group commands together, to associate commands with a virtual server, or to associate data with a command, ie virtual-server { command [args] command [args] { } } virtual-server { command [args] command [args] } EOF Output Format of freeVSD Protocol Commands ------------------------------------------ Commands that operate on the same virtual server are grouped together. Each command is seperated by curly brackets. virtual-server { command { result-code/result-data } command { result-code/result-data } } EOF The token `EOF' terminates output. Once output has completed, freeVSD will automatically close the connection. Example Commands and Output --------------------------- The following examples show how the freeVSD protocol can be used for remote server configuration. Task: Get a list of all users on the virtual server vsclient +OK freeVSD Virtual Server administrator host.isp.net v1.4.1 server ready vsclient { USER_LIST } EOF vsclient { USER_LIST { name=admin uid=1000 home="/root" shell="/bin/bash" name=web uid=1001 home="/home/web" shell="/bin/bash" name=ftp uid=1002 home="/home/ftp" shell="/bin/bash" } } EOF +OK Virtual server admin signing off Task: Retrieve a list of all users on the virtual server, and domains configured in Sendmail and Apache. +OK freeVSD Virtual Server administrator host.isp.net v1.4.1 server ready vsclient { SENDMAIL_CWLIST USER_LIST APACHE_VHENUM } EOF vsclient { SENDMAIL_CWLIST { clientdomain.com } USER_LIST { name=admin uid=1000 home="/root" shell="/bin/bash" name=web uid=1001 home="/home/web" shell="/bin/bash" name=ftp uid=1002 home="/home/ftp" shell="/bin/bash" } APACHE_VHENUM { vh="_default_:443" sn="clientdomain.com" } } EOF +OK Virtual server admin signing off Task: Add a new virtual host definition to Apache +OK freeVSD Virtual Server administrator myserver.net v1.4.1 server ready vsclient { APACHE_VHADD { ServerName clientdomain.com DocumentRoot /home/httpd/htdocs/clientdomain } } EOF vsclient { APACHE_VHADD { } } } EOF +OK Virtual server admin signing off freeVSD Protocol Command Reference ================================== The commands supported by freeVSD are implemented by modules. The following is a list of modules and the commands that they provide. Specification of the 'mod_apache' Module ---------------------------------------- This module includes commands for Apache web server administration. APACHE_VHENUM Description: List all VirtualHost declarations in httpd.conf Output: vh="..." sn="..." vh="..." sn="..." Where `vh' is the content of the VirtualHost header. `sn' is the value of the ServerName directive within the VirtualHost. APACHE_VHADD { } Description: Adds a configuration for a VirtualHost, where is a collection of valid Apache directives, eg ServerName clientdomain.com DocumentRoot /home/httpd/htdocs/clientdomain NOTE: An error will be returned if the VirtualHost doesn't contain a ServerName directive. Output: Nothing APACHE_VHDELETE Description: Deletes a VirtualHost declaration, where is the content of the VirtualHost header is the argument of the ServerName directive Output: Nothing APACHE_VHMODIFY { } Description: Modify a VirtualHost declaration, where is the content of the VirtualHost header is the argument of the ServerName directive is a collection of valid Apache directives NOTE: An error will be returned if the VirtualHost doesn't contain a ServerName directive. Output: Nothing. APACHE_VHGET Description: Return the contents of a VirtualHost declaration, where is the content of the VirtualHost header is the parameter to the ServerName directive. Output: The text between > and is copied verbatim into the output. Specification of the 'mod_priv' Module -------------------------------------- This module includes commands for user privileges on a virtual server. PRIV_AVAIL Description: Return a list of valid privileges for a virtual server. Output: A list of available privileges where entries are listed on a separate line PRIV_MODIFY <+|-> Description: Set privileges for a user on a virtual server, where is the name of the user to be changed is the privilege to be added or removed Output: Nothing PRIV_LIST [] Description: List privileges that are assigned to a user, where is the user to be listed NOTE: If no username is specified, all users' privileges will be listed. Output: user=... uid=... rights=...;...;...; Where 'user' is the user name being output 'uid' is the uid of the user as a decimal integer 'rights' is a semicolon seperated list of privileges NOTE: If the user has no rights then the string '[none]' will be returned. Specification of the 'mod_quota' Module --------------------------------------- This module provides commands for modifying user quotas on a virtual server. QUOTA_VSSET {K|M} Description: Assigns the disk quota limit for a virtual server. Output: Nothing QUOTA_VSGET Description: Obtains disk quota limits for a virtual server. Output: vsquota=... Where `vsquota' is the disk quota limit as a decimal integer (in bytes) QUOTA_USERGET Description: List disk quota limits for a user, where is the name of the user to be listed Output: uid=... hardb=... softb=... curb=... Where `uid' is the uid of the user as a decimal integer `hardb' is the disk quota hard limit as a decimal integer in bytes `softb' is the disk quota soft limit as a decimal integer in bytes `curb' is a decimal integer in bytes representing the total disk space that user has consumed QUOTA_USERSET [+|-]{K|M} Description: Assigns disk quota limits for a user, where is the user whose quota is being assigned Output: Nothing QUOTA_STATS Description: Gets disk quota details for all users on a server. Output: For each user on the virtual server, a line has the following output: user=... uid=... hardb=... softb=... curb=... Then the disk quota and current use settings for the virtual server are sent using the following format: hardb=... softb... curb... Where `user' is the user name `uid' is the uid of the user as a decimal integer `hardb' is the disk quota hard limit as a decimal integer in bytes `softb' is the disk quota soft limit as a decimal integer in bytes `curb' is the current disk usages as a decimal integer in bytes Specification for the 'mod_sendmail' Module ------------------------------------------- This module includes commands for Sendmail configuration. SENDMAIL_CWADD Description: Adds a domain name to /etc/sendmail.cw, where is the domain name to be added Output: Nothing SENDMAIL_CWDELETE Description: Deletes a domain name from /etc/sendmail.cw, where is the domain name to be deleted Output: Nothing SENDMAIL_CWLIST Description: Lists all domain names in /etc/sendmail.cw Output: A list of domain names separated by a new line. SENDMAIL_VLIST Description: Lists e-mail aliases in /etc/virtusertable for a specific domain name, where is the domain name to be listed Output: alias="..." address="..." alias="..." address="..." alias="..." address="..." Where `alias' is an incoming alias enclosed in double-quotes `address' is the destination mail address, enclosed in double-quotes SENDMAIL_VMODIFY {