freeVSD  - Protocol                         
===================

This document provides a brief description of the freeVSD protocol.

Contents
========
1.   Conventions
2.     freeVSD Protocol Overview
	   2.1 freeVSD Protocol Definition
	   2.2 freeVSD Protocol Format
		   2.2.1 Connection/Disconnection Message Format
           2.2.2 Input Format of freeVSD Protocol Commands
		   2.2.3 Output Format of freeVSD Protocol Commands
           2.2.4 Examples of Commands and Messages
3.     freeVSD Protocol Command Descriptions
	   3.1 Specification of the 'mod_apache' Module
	   3.2 Specification of the 'mod_priv' Module
	   3.3 Specification of the 'mod_quota' Module
       3.4 Specification of the 'mod_sendmail' Module
       3.5 Specification of the 'mod_user' Module
	   3.6 Specification of the 'mod_vs' Module

1. Conventions
==============

This document 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. <arg1>, then `arg1' is a required argument
for the command. If the argument is written within square-brackets,
e.g. [arg2], then `arg2' is an optional argument.
This document also uses the following example host server to illustrate the
freeVSD protocol: myserver.net v1.4.1.

2. freeVSD Protocol Overview
============================

The following sertion defines the freeVSD protocol and explains the format
of the commands and virtual server connection/disconnection messaging.

2.1 freeVSD Protocol Definition
================================

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.    

2.2 freeVSD Protocol Format
============================

The freeVSD protocol includes unique input/output formats for commands as well as 
connection/disconnection messaging. 

2.2.1 Connection/Disconnection Message Format
=============================================  

I/O is line oriented and there are no limits on the length of the line.

Upon connection to port 1725 the client receives the following message:
  +OK freeVSD Virtual Server administrator myserver.net v1.4.1 server ready

When freeVSD disconnects, the client receives the following message:
  +OK Virtual server admin signing off


2.2.2 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.

   virtual-server {
     command [args]
     command [args] {
   <data>
     }
   }
   virtual-server {
     command [args]
     command [args]
   }
   EOF

2.2.3 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 shut down the connection.

2.2.4 Examples of Commands and Messages
========================================

The following shows an example of the commands that are provided by the client to the virtual server.

a) Get a list of all users on the virtual server test1:

   +OK freeVSD Virtual Server administrator myserver.net v1.3.0 server ready
   test1 {
   USER_LIST
   }
   EOF
   test1 {
     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


b) A slightly more complicated example, retrieving more than one item of data:


   +OK freeVSD Virtual Server administrator myserver.net v1.3.0 server ready
   test1 {
     SENDMAIL_CWLIST
     USER_LIST
     APACHE_VHENUM
   }
   EOF
   test1 {
     SENDMAIL_CWLIST {
   myserver.net
     }
     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="myserver.net"
   
     }
   }
   EOF
   +OK Virtual server admin signing off


Where a command requires a more complex input of commands, data can be enclosed in curly-brackets:  

   +OK freeVSD Virtual Server administrator myserver.net v1.3.0 server ready
   test1 {
     APACHE_VHADD {
   <VirtualHost vsone>
   ServerName vsone
   </VirtualHost>
   }
   }
   EOF
   test1 {
     APACHE_VHADD {
     }

   }
   }
   EOF
   +OK Virtual server admin signing off


3. freeVSD Protocol Command Descriptions
========================================

The commands supported by freeVSD are implemented by modules. The following
is a list of modules and the commands that they provide.


3.1. Specification of the 'mod_apache' Module
=============================================

This module includes commands for Apache VirtualHost declarations.

APACHE_VHENUM
	Description:  
		List all VirtualHost declarations in httpd.conf

	Output:     vh="..." sn="..."
     	  	    vh="..." sn="..."
     `vh' is the content of the VirtualHost header.
     `sn' is the value of the ServerName directive within the VirtualHost.


APACHE_VHADD {
<virtual-host data>
}
   Description:
     Adds a configuration for a VirtualHost

   Input:
     A LF (line feed) terminated string is shown in the following example:
        <VirtualHost domain.com>
        ServerName domain.com
        </VirtualHost>
     An error will be flagged if the VirtualHost doesn't contain a
     ServerName directive.

   Output:
     Nothing.

APACHE_VHDELETE <virtual-host> <server-name>
   Description:
     Deletes a VirtualHost declaration.
     <virtual-host> is the content of the VirtualHost header
     <server-name> is the parameter to the ServerName directive.
     The VirtualHost and ServerName definitions included together uniquely identify a  	Virtual Host and ServerName declaration.

   Output:
     Nothing.

APACHE_VHMODIFY <virtual-host> <server-name> { <virtual-host data> }
   Description:
     Modify a VirtualHost declaration
     <virtual-host> is the content of the VirtualHost header
     <server-name> is the parameter to the ServerName directive.

   Input:
     A LF terminated string that, at a minimum, looks something like this:
        <VirtualHost domain.com>
        ServerName domain.com
        </VirtualHost>
     An error will be flagged if the VirtualHost directive doesn't contain a
     ServerName directive.

   Output:
     Nothing.

APACHE_VHGET <virtual-host> <server-name>
   Description:
     Return the contents of a VirtualHost declaration
     <virtual-host> is the content of the VirtualHost header
     <server-name> is the parameter to the ServerName directive.

   Output:
     The text between <VirtualHost <virtual-host>> and </VirtualHost>
     is copied verbatim into the output.


3.2. 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 seperate line.

PRIV_MODIFY <user> <+|-><privilege>
   Description:
     Set privileges for a user on a virtual server

   Output:
     Nothing.

PRIV_LIST [<user>]
   Description:
     List privileges that are assigned to a user

   Output:
     user=... uid=... rights=...;...;...;

     `user' - optional user name. If the username is not supplied, it will then list  privileges for all users. 
     `uid' - the uid of the user as a decimal integer
     `rights' - a semicolon seperated list of privileges that the user has.
	        If the user has no rights then the string `[none]' will be
		returned.


3.3. Specification of the 'mod_quota' Module
============================================

This module includes commands for user quotas on a virtual server.

QUOTA_VSSET <quota>{K|M}
   Description:
     Assigns disk quota limits for a virtual server.

   Output:
     Nothing.

QUOTA_VSGET
   Description:
     Obtains disk quota limits for a virtual server.

   Output:
     vsquota=...

     `vsquota' - the virtual server disk quota limit as a decimal integer
	         in bytes.

QUOTA_USERGET <user>
   Description:
     Obtains disk quota limits for a user.

   Output:
     uid=... hardb=... softb=... curb=...

     `uid' - the uid of the user as a decimal integer
     `hardb' - the disk quota hard limit as a decimal integer in bytes
     `softb' - the disk quota soft limit as a decimal integer in bytes
     `curb' - a decimal integer in bytes representing the total disk space
	      that the user has used.

QUOTA_USERSET <user> [+|-]>size>{K|M}
   Description:
     Assigns disk quota limits for a user.

   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...

     `user' - user name
     `uid' - the uid of the user as a decimal integer
     `hardb' - the disk quota hard limit as a decimal integer in bytes
     `softb' - the disk quota soft limit as a decimal integer in bytes
     `curb' - the current disk usages as a decimal integer in bytes


3.4. Specification for the 'mod_sendmail' Module
================================================

This module includes commands for handling Sendmail configurations.

SENDMAIL_CWADD <domain-name>
   Description:
     Adds a domain-name to /etc/sendmail.cw

   Output:
     Nothing.

SENDMAIL_CWDELETE <domain-name>
   Description:
     Deletes a domain-name from /etc/sendmail.cw

   Output:
     Nothing:

SENDMAIL_CWLIST
   Description:
     Lists all domain names in /etc/sendmail.cw

   Output:
     A list of domain names seperated by a new line.

SENDMAIL_VLIST <domain-name>
   Description:
     Lists e-mail aliases in /etc/virtusertable for a domain-name

   Output:
     alias="..." address="..."
     alias="..." address="..."
     alias="..." address="..."

     `alias' - mail alias enclosed in double-quotes.
     `address' - mail address, enclosed in double-quotes.


SENDMAIL_VMODIFY {
<script>
}
   Description:
     Modifies e-mail aliases in /etc/virtusertable.

   Input:
     Pass lines of the following form on seperate lines:
       add <alias> <address>
       delete <alias> <address>

     `add' will add a new alias with address.
     `delete' will delete an existing alias with address.

   Output:
     Nothing.

SENDMAIL_ALIST
	Description:
		Lists mapping entries in /etc/aliases

	Output:
	key="..." value="..."
	key="..." value="..."
	key="..." value="..."

	'key' - key to be mapped, enclosed in double-quotes.
	'value' - mapped value, enclosed in double-quotes.

SENDMAIL_AMODIFY {
<script>
}
	Description:
		Modifies mapping entries in /etc/aliases.

	Input:
		Pass lines of the following form, entered on separate lines.
		add <key> <value>
		del <key> <value>

			'add' will add a new key/value pair.
			'del' will delete an existing key/value pair.
		Output:
			Nothing.



3.5. Specification for the 'mod_user' Module
============================================

This includes commands for handling virtual server users.

USER_ADD <user name> [--pass=<password>] [--home=<home directory>]

   Description:
     Creates a new user in a virtual server. The command also allows a password and home 
     directory to be set through the optional home directory and password arguments. If no home directory is specified then the default location of  /home/<user name> will be used.  If the home directory doesn't exist, then it will be created and ownership will be set to the 'uid' and 'gid' of the new user.

   Output:
     Nothing.

USER_DEL <user name>

   Description:
     Deletes an existing user from a virtual server. The 'admin', 'web', 'ftp' and 'mail users cannot be deleted.  Currently, this command will delete the privileges set
     for the user but it will not delete the user's home directory, fixup files owned by 	that user, or the user's group.

USER_MOD <user name> [--pass=<password>] [--home=<home directory>]
		     [--shell=<default shell>] [--login=<login-name>]
		     [--gecos=<gecos>]

Description:
     Modifies an existing user account though changing the password, home directory, login shell, login username, and general comments. This is done by supplying the --pass, --home, --shell, --login and --gecos arguments respectively.

USER_LIST
   Description:
     Lists all users on a virtual server.

   Output:
     name=... uid=... home="..." shell="..."

     `name' - the user name on a virtual server.
     `uid' - a positive integer representation of the user's id.
     `home' - path to the user's home directory, enclosed in double-quotes.
     `shell' - path to the user's default shell, enclosed in double-quotes.

USER_CHPASS <user name> <old password> <new password>
   Description:
     Changes the password for a user.

   Output:
     Nothing.

USER_GRADD <group>
   Description:
     Creates a new user group for a user.

   Output:
     Nothing.

USER_GRDEL <group>
   Description:
     Delete an existing user group. However, it is not possible to delete the user groups
     'admin', 'ftp', 'web' or 'mail'.

   Output:
     Nothing.

USER_GRLIST
   Description:
     List all user groups on a virtual server.

   Output:
     name=... gid=... members="..."

     `name' - the user group name
     `gid' - a positive integer representation of the group id.
     `members' - a comma seperated list of usernames that are members
	         of the user group.


3.6. Specification for the 'mod_vs' Module
==========================================

This module includes commands for administrating virtual servers.

VS_REBOOT
   Description:
     Restart virtual server services.

   Output:
     The output is sent verbatim back to the client.

VS_SIGNAL <signal number>
   Description:
     Sends a signal to all processes on the virtual server. The signal number uniquely identifies the process.

   Output:
     Nothing.


The following commands are only accessible through the root directory of the virtual
server.


VS_CREATE <virtual server> <ip address> <fqdn> <numuid> <quota> [<pri ns>] [<sec ns>]

   Description:
     Creates an entry in /etc/vsd.conf for a new virtual server. It will assign an IP address as well as a fully qualified domain name. It will also allocate space for  users and a hard disk quota of in Kbytes.  Optionally, a primary and secondary name server
     that the virtual server will use to resolve domains are specified
     with the <pri ns> and <sec ns> arguments.

     This command does not actually create the virtual server account - this
     is left up to a script called `vs-batch.pl' which is executed
     periodically through a cron job.

   Output:
     Nothing.

VS_DELETE <virtual server>

   Description:
     Shuts down all virtual server services. When this is done, the
     ethernet interfaces and IPs aliases for the virtual server are dropped. The account is then added to a queue, pending deletion by `vs-batch.pl'. Therefore
     this command will return as soon as the virtual server has been
     shutdown but this does not indicate that the account has been
     physically deleted from the hosting server.

   Output:
     Nothing.

VS_ENABLE <virtual server>

   Description:
     Re-activates a previously disabled virtual server bringing up the ethernet
     interface and any IP addresses aliased to it. It will then start virtual server services
     and send a SIGHUP to the inetd super-server (for Telnet, FTP and POP3
     services). 

   Output:
     The output from vsboot is sent verbatim back to the client.

VS_DISABLE <virtual server>

   Description:
     This command disables virtual servers by shutting down virtual server services, dropping the ethernet interface and any IPs aliased to it. It then sets the disabled flag in /etc/vsd.conf and sends a SIGHUP to inetd.

   Output:
     The output from 'vsboot' is sent verbatim back to the client.

VS_DETAILS [<virtual server>]
   Description:
      Lists details about all virtual servers on a hosting server.

   Output:
      name="..." ip=... uid=... users=... quota=... path=\"...\" prins=... secns=... aip=...

      `name' - virtual server name
      `ip' - virtual server ip address
      `uid' - start of the uid chunk allocated to the virtual server
      `users' - size of the uid chunk (i.e. number of users that can be made on
	        the virtual server)
      `quota' - disk quota hard limit (in megabytes)
      `path' - pathname to the root of the virtual server
      `prins' - the FQDN of the primary nameserver
      `secns' - the FQDN of the secondary nameserver
      `aip' - Indicates an IP alias. Each IP alias on a virtual server will have one 'aip'. If the VS has no aliases, then no aip field is present.

VS_MODIFY <old-vs> <new-vs> <old-fqdn> <new-fqdn> <old-ip> <new-ip>
  
   Description:  
This command changes virtual server details. It lets the virtual server directory name                 																												to be changed (old-vs/new-vs), the fully qualified domain name (old-fqdn/new-fqdn), or the virtual server IP address (old-ip/new-ip). Normally, the fully qualified domain name of the virtual server is changed at the same time as the directory name of the virtual server. The following files and directories need to be changed:
	     
	 (on the host server)/etc/FQDN         
     (in virtual server)/etc/issue.net    
     (in virtual server)/etc/httpd/conf/httpd.conf  
     (in virtual server)/etc/hosts        
     (in virtual server)/etc/sendmail.cw  
     (in virtual server)/etc/vsd.conf     
    
     If the name of the virtual server doesn't need to be changed, then the following files only need to be changed.

     /etc/FQDN      (in virtual server)
     virtual server directory name (on host server)
     /etc/vsd.conf  (on host server)
     
     If only the virtual server IP address is to be changed, then the following files need to be modified with the updated IP address details: 

     /etc/vsd.conf (on host server)
     /etc/hosts    (in virtual server)
     /etc/httpd/conf/httpd.conf (in virtual server)


VSD_REDIRECT <virtual server IP address>:<origin-Port Number>:<destination-Port Number>
Description

The VSD_REDIRECT command allows requests to be transferred from one port to another.
freeVSD uses redirection for configuring Apache. Apache was originally set up for use on 
port 80, but to allow greater security (where only the root user can configure Apache), it is redirected to port 8080.

Once a virtual server is started, the 'rc' configuration script is triggered. This will then start two port redirection services. These services redirect port 80 to 8080 (for the HTTP server) and port 443 to 8443 (for the HTTPS server). The command can be executed
from within a virtual server (as root) and can be used to perform other redirection tasks besides configuring Apache.












