------------------------------------------------------------------
 Linux Secure Virtual Hosting Extension HOWTO (2003/04/30)
------------------------------------------------------------------
1. Preparation

1.1 Extra configuration for mobile processors.

Mobile processor provides automatic stabilizer of CPU frequency.
Our CPU capacity reservation mechansim requires fixed CPU
frequency, therefore you have to disable automatic stabilizers
mechanism of mobile processor.

1.1.1 Mobile Pentium II/III

BIOS provides specifying CPU frequency for Mobile pentium
II/III.
Settle highest CPU frequency and disable CPU frequency changing.
See manual your PC or motherboard for details.

1.1.2 Crusoe
Longrun mechanism of Crusoe can be controled utilizing longrun
utility program.
The longrun utility is released on anonymous ftp site. URI is 

	ftp://ftp.kernel.org/pub/linux/utils/cpu/crusoe/longrun-0.9.tar.gz

To fix CPU frequency disable CPU frequency changing, do as follows;

	# longrun -f performance
	# longrun -s 100 100

These operations requires whenever your PC is booted.
If you may want to do at boot time, append to the rc script
(typically rc.local).

1.2 Making complete file tree for virtual host

Our functionality of providing virtual host environment makes
use of chroot(2) system call, therefore you have to create
complete file tree of Linux host.
Duplicating file tree requires typically 1〜2GB disk space per 
a tree.
We show a sample shell script which duplicates file tree as
follows;

	#!/bin/sh
	#
	# COPY_DIR : make directory and copy all files.
	# MAKE_DIR : make directory only.

	COPY_DIR="/boot /etc /var /bin /sbin /lib /dev /usr"
	MAKE_DIR="/tmp /proc"

	if [ $# -ne 1 ]; then
	        echo "Usage: $0 <chroot dir>";
	        exit 1;
	fi

	TARGET_DIR=$1

	if [ ! -d ${TARGET_DIR} ]; then
	        mkdir ${TARGET_DIR}
	fi

	if [ ! -d ${TARGET_DIR} ]; then
	        echo "chroot directory not found."
	        exit 1;
	fi

	for i in ${COPY_DIR}; do
	        echo "mkdir ${TARGET_DIR}$i"
	        mkdir ${TARGET_DIR}$i
	        echo "copy files from $i to ${TARGET_DIR}$i"
	        (cd $i; tar cf - . )|(cd ${TARGET_DIR}$i; tar xf -)
	done

	for i in ${MAKE_DIR}; do
	        echo "mkdir ${TARGET_DIR}$i"
	        mkdir ${TARGET_DIR}$i
	done

--------------------------------------------------------------------
2. Starting software

2.1 load kernel modules
Before using resource reservation, you have to load a extend CPU
scheduler module.

	# insmod crow_rk

If you may want to activate resource reservation at boot time,
append the following lines to the rc script (typically rc.local).

	RELVER=`uname -r`
	if [ x$RELVER = x"2.2.25-svh1.0" ]; then
	        insmod crow_rk
	fi

2.2 Creating protection barrier 
    (resource reservation and/or virtual host envirnment).

2.2.1 Command usage

[for creating resource reservation]
	crow_exec [--wait] --cpu cpu_rate --mem mem_rate 
		  --exec "progname arguments"

        --cpu cpu_rate	make CPU reservation with rate(%)
        --mem mem_rate	make Physical memory reservation with MB
	--exec		specify to be executed program and arguments
	--wait		don't fork when invoke execve(2).


[for creating virtual host]
	jail --chroot path --hostname hostname --ip ip-number 
		--uidmin uid_min --uidmax uid_max 
		--gidmin gid_min --gidmax gid_max 
		--exec "command ..."

	path		new root directory
	hostname	hostname of virtual host
	ip-number	IP address of virtual host
	uid_min		minimum uid number allowed in virtual host
	uid_max		maximum uid number allowed in virtual host
	gid_min		minimum gid number allowed in virtual host
	gid_max		maximum gid number allowed in virtual host
	command		specify to be executed program and arguments

2.2.2 creating resource reservation only.

If you want to allocate CPU and memory resources to specify
applications, you can use the 'crow_exec' program.

Example) allocate CPU 30% Memory 100MB to httpd

	# crow_exec --cpu 30 --mem 100 --wait \
		--exec "/etc/rc.d/init.d/httpd start"

2.2.3 creating virtual host environment only.

If you want to create virtual host for specify applications, you
can use the 'jail' program.

Example) Virtual host configuration for httpd
		new root :  /home/jail
		hostname : svh.foo.com
		IPaddress : 129.168.124.1
		uid_min : 100
		uid_max : 10000
		gid_min : 100
		gid_max : 65535
	
	# jail --chroot /home/jail --hostname svh0.foo.com \
		--ip 192.168.124.1 --uidmin 100 --uidmax 10000 \
		--gidmin 100 --gidmax 65535 \
		--exec "/etc/rc.d/init.d/httpd start"

2.2.4 creating resource reservation and virtual host environment
      simultaneously.

If you want to both allocate CPU and memory resources and create
virtual host for specify applications, you can use the
'crow_exec' program and 'jail' program simultaneously.

Example) resource and virtual host configuration for httpd
		CPU : 30 %
		Memory : 100MB
		new root :  /home/jail
		hostname : svh0.foo.com
		IPaddress : 129.168.124.1
		uid_min : 100
		uid_max : 10000
		gid_min : 100
		gid_max : 65535

	# crow_exec --cpu 30 --mem 100 --wait \
		--exec "jail --chroot /home/jail \
		--hostname svh0.foo.com --ip 192.168.124.1 \
		--uidmin 100 --uidmax 10000 \
		--gidmin 100 --gidmax 65535 \
		/etc/rc.d/init.d/rc.httpd start"

If you may want to execute multiple program, you can make a
script and use it when invoke by crow_exec or jail.

Example) script for typical web server
	#!/bin/sh

	LANG=C;
	export LANG;

	#echo $1;

	case "$1" in
		stop)
			sh /etc/rc.d/init.d/syslog stop
			sh /etc/rc.d/init.d/xinetd stop
			sh /etc/rc.d/init.d/sshd stop
			sh /etc/rc.d/init.d/httpd stop
			killall minilogd
			echo "unmouting /dev/pts"
			umount /dev/pts
			echo "unmouting /proc"
			umount /proc
			;;
		restart)
			if [ -f /etc/mtab ]; then
				cat /etc/mtab | grep -v /proc | grep -v /dev/pts > /etc/mtab.new
				mv -f /etc/mtab.new /etc/mtab
			fi
			echo "mouting /proc"
			/bin/mount /proc
			echo "mouting /dev/pts"
			/bin/mount /dev/pts
			sh /etc/rc.d/init.d/syslog restart
			sh /etc/rc.d/init.d/xinetd restart
			sh /etc/rc.d/init.d/sshd restart
			sh /etc/rc.d/init.d/httpd restart
			;;
		start)
			if [ -f /etc/mtab ]; then
				cat /etc/mtab | grep -v /proc | grep -v /dev/pts > /etc/mtab.new
				mv -f /etc/mtab.new /etc/mtab
			fi
			echo "mouting /proc"
			/bin/mount /proc
			echo "mouting /dev/pts"
			/bin/mount /dev/pts
			sh /etc/rc.d/init.d/syslog start
			sh /etc/rc.d/init.d/xinetd start
			sh /etc/rc.d/init.d/sshd start
			sh /etc/rc.d/init.d/httpd start
			;;
		*)
			;;
	esac

2.2.5 destroy resource reservation and/or virtual host environment.

linux-svh kernel may destroy automatically when any process is
finished. 
If you want to destroy resource reservation and/or virutal host
environment, kill every processes in resource reservation and/or
virutal host environment.

--------------------------------------------------------------------
3. kernel MIB 

set_hostname_allowed    : permission of using sethostname(2) 
			  (default 0 == off)
			  Note: Each prision has individual name space.
socket_unixiproute_only : constraint of socket type
			  (default 1 == enable)
jail_sysvipc_allowed    : permissino of using SysVIPC
			  (default 1 == on)
			  Note: Each prision has individual name space
			        and resource space.
jail_enable_uid_divide  : switch of dividing in uid range for prison
			  (default 1 == on)
jail_enable_gid_divide  : switch of dividing in gid range for prison
			  (default 0 == off)
jail_shared_uid_min     : minimum uid of shared by every prison.
			  (default 0)
jail_shared_uid_max     : maximum uid of shared by every prison.
			  (default 99)
jail_shared_gid_min     : minimum gid of shared by every prison.
			  (default 0)
jail_shared_gid_max     : maximum uid of shared by every prison.
			  (default 99)
set_reserve_allowed     : permission of using system call of resource 
			  reservation from prison.
			  (default 0 == disable)
jail_mount_restriction  : constraint to be able to mount pseudo filesystem
			  only.
			  (default 1 == enable)