# vi: set tabstop=4:
///////////////////////////////////////////////////////////////////////////////////////////////////////////
//
//  Second Life Proxy System = Relay Server + Cache Server + Infomation Server + Voice Relay Server   sl_proxy v1.8.x '10 4/25
//
//                              Copyright (C) 2007  Second Life Proxy System by Fumi.Iseki (Tokyo Joho Univ. TUIS)
//                                                  Second Life: Fumi Hax
//                                                  http://www.nsl.tuis.ac.jp/
//                                                  http://www.opensim.tuis.ac.jp/
//                                                  mailto:iseki@solar-system.tuis.ac.jp
//
//  Simplicity Document of Second Life Proxy System
//   

0. Recommendation

  Please see also http://www.nsl.tuis.ac.jp/xoops/modules/xpwiki/?sl_proxy%20%28E%29 about sl_proxy.

  If you can read Japanese, please read README.euc. README.euc is more detailed as this document.




1. Outline
 
  This system consists of Relay Server(sl_relay), Cache Server(sl_cache), Information Server(sl_info) and Voice Chat 
(SLVoice(*)) Relay Server(sl_voice_relay) for Second Life on Linux.  
  So, sl_proxy = sl_relay + sl_cache + sl_info + sl_voice_relay. 

  sl_voice_relay relays the packets of the SIP system of the Vivox, and enables to use of the voice chat of Second Life 
for PC in the firewall. The SIP forwarding part of sl_voice_relay (sip_forwarder) is independent from sl_relay.  But, 
it is automatically built in, when sl_voice_relay is compiled.
  It is also possible to stop sip_forwarder function in sl_voice_relay, and to start sip_forwarder with another machine (for debug).

	sl_relay: Proxy Server of UDP/HTTP(S) packets for Second Life.
	sl_cache: Cache Server of UDP tecture data of Second Life.
	sl_info:  Infomation Server that monitors usage condition of sl_relay. 
			  The giving filtering information by the white list of SIM is also possible. 
	sl_voice_relay: Proxy Server of SIP(RTP/RTCP) for SLVoice. SLVoice is voice chat system for Second Life by Vivox.


  	Functions
		 1. You can execute Second Life from PC with private IP address in the firewall. 
		 2. Specification of use port number for fire wall setting is possible. 
		 3. The access control for viewer is possible.
	 	 4. Full HTTPS access between Viewer and Relay Server is possible. (default is HTTP)
		 5. External WEB Proxy (ex. squid) connection is supportted. Moreover, an original WEB Proxy function is built in.  
		 6. OpenSim(*) is supported. (Test version)
		 7. Texture data caching is enable.
		 8. When cache server (sl_cache) is down or the delay is generated, sl_relay is automatic disconnected from .
			cache server after few delay.
		 9. The user of sl_relay can be monitored by sl_info. 
		10. SIM that can be accessed can be limited by making the white list of SIM. 
		11. You can execute voice chat of Second Life from PC with private IP address in the firewall. 

  	Inconvenience or Bugs.
		1.  Caching data with  SQL DB is not supported.
		2.  Caching Parameters are not adjystmented. Download speed from cache server should not be too early. 
		3.  It is necessary to make the data base beforehand to use the function of sl_info. (Making is very easy.)
		4.  Stress test is untried.


(*) OpenSim: OpenSim is open source server system that is compatible with Second Life Server.
			 http://www.opensimulator.org/

(*) SLVoice: SIP UA software made by Vivox. This is used at voice chat of Second Life.



2. Compile, Install snd Setting.

	2-0. This software needs OpenSSL, zlib and Berkeley DB(4.2) developement environment (but, Berkeley DB is optinal). 
	   	 Please install them previously if you do not install. 
		 If you use Gentoo Linux, please read README_on_gentoo_1.6.1, too.

	2-1. Compile & Install    [ ] is possible to omit it.

		# zcat sl_proxy-1.8.x.tgz | tar xfv -
		# cd JunkBox_Lib					// JunkBox_Lib is new version of TUIS_Lib
		# ./configure  [--enable-db]        // --enable-db is option for Berkeley DB
		# make
		# cd ..

		# cd sl_proxy-1.8.x
		# ./configure  [--enable-db]        // --enable-db is option for Berkeley DB
		# make
		# make install


	2-2. Setting and Start

		# vi /etc/init.d/sl_relay 			// edit for setup of Relay Server
		# vi /etc/init.d/sl_cache 			// edit for setup of Cache Server
		# vi /etc/init.d/sl_info 			// edit for setup of Information Server
		# vi /etc/init.d/sl_voice_relay 	// edit for setup of Voice Relay Server

		# /etc/init.d/sl_voice_relay  start
		# /etc/init.d/sl_info  start
		# /etc/init.d/sl_cache start
		# /etc/init.d/sl_relay start


	2-3. Monitering

		# tail -f /var/sl_proxy/sl_info_agent.log


	2-4. Uninstall

		# cd sl_proxy-1.8.x
		# make clean-install				// However, the data base is not deleted.


	2-5. Configration

		sl_relay Configuration file.   
			default is /usr/local/etc/sl_proxy/sl_relay.conf 

		sl_cache Configuration file.   
			default is /usr/local/etc/sl_proxy/sl_cahe.conf 

		sl_info Configuration file.   
			default is /usr/local/etc/sl_proxy/sl_info.conf 

		sl_relay access control file 
			default is /usr/local/etc/sl_proxy/hosts_relay.allow 
			IP address/Subnet mask, CIDR and FQDN can be used.

		sl_cache access control file for sl_relay
			default is /usr/local/etc/sl_proxy/hosts_cache.allow 
			IP address/Subnet mask, CIDR and FQDN can be used.

		sl_info access control file for sl_relay
			default is /usr/local/etc/sl_proxy/hosts_info.allow 
			IP address/Subnet mask, CIDR and FQDN can be used.

		Relay allow file of internal WEB proxy of sl_relay by restricted proxy mode
			default is /usr/local/etc/sl_proxy/proxy_dist.allow
			FQDN only

		White list file for sl_info
			default is /var/sl_proxy/filter/white_sim.list
			It is possible to set the limitation of each avatar by /var/sl_proxy/filter/(avatar name), 
			and it is possible to set the limitation of each machine with IP by /var/sl_proxy/filter/(machine IP), too.
			The priority of the setting is Avatar -> Machine -> whole(white_sim.list).
			The name of SIM is described about one line one by one. 
			@ALL shows all SIM as a special setting and @PG shows the PG SIM. 
	
		Working directory. 
			default is /var/sl_proxy
			The effect user should be able to write it. 

		sl_cahe's GetPacketNum is Pakets Number that is downloaded from cache server at once. 
		When it is too large, Communication with Simulater is obstructed.

		sl_voice_relay relays the packets of the SIP system of the Vivox, and enables to use of the voice chat of Second Life 
		for PC in the firewall. The SIP forwarding part of sl_voice_relay is an independent program named sip_forwarder. 
		But, it is automatically built in, when sl_voice_relay is compiled.
		It is also possible to stop sip_forwarder function in sl_voice_relay, and to start only sip_forwarder with another 
		machine (for debug).


		Please see sample file in conf directory.


	2-5. About FireWall

		Because all communications from the Second Life server become "Response",  in the firewall that permits all outside 
		communications, it is not necessary to puncture it toward inside. 

		sl_voice_relay does the UDP hole punching to the firewall for the last ACK packet when the INVITE request of SIP is received.
		When the hole doesn't open in the firewall in this, it is necessary to puncture the firewall manually. 


	2-6. HTTPS communications between Viewer and Relay Server(sl_relay)
	
		If you want use HTTPS between Viewer and Relay Server(sl_relay). You need secret key file(PEM),
		certificate file(PEM) of Relay Server, and CA file(PEM) of Certificate Authority.

		Certificate file's Common Name should be IP address of Relay Server. 
		You should add CA file to C:\Program Files\SecondLife\app_settings\CA.pem. Because CA.pem is 
		important file, you should take the backup. 

		Those files are specified in configration file.  Finally, you add command option '-as' to sl_relay. 

		For more detail to make HTTPS(SSL) setting files, please read OpenSSL documentations.
		


3. Execution
	
	3-1. Options
	
	sl_relay	[-s server_name[:port]] [-p port] [-f config_file] [-u user_name] [-i interface_address]
				[-pid pid_file] [-l [log_file]] [-v syslog_level]
				[-cs [cache_server:port]] [-cg] [-cp]
				[-is [info_server:port]] [-wf]
				[-vs [voice_relay_server:port]]
				[-as] [-aca] [-ano]
				[-xp [web_proxy_server:porti]] [-ip [port]] [-ipx [port]] [-mm]
				[-ver version]
				[-d] [-x] [-xt] [-xu] [-xuf]
				[--version] [--help] [-h]

		-s   : specify login server of Second Life. default is login.agni.lindenlab.com:443 
		-p   : port number that Viewer connects. default is 8100.
		-f   : configuration file. default is /usr/local/etc/sl_proxy/sl_relay.conf
		-u   : specify effective user.
		-i   : specify Viewer side network interface IP address. if your server has two or more network interfaces, 
			   you need to use this option.

		-pid : specify pid file.
		-l   : specify log file. default is /var/sl_proxy/sl_relay.log 
 		-v   : level of syslog. default is LOG_INFO (7).

		-cs  : specify sl_cache cache server. default is localhost:8200
		-cg  : only get cache data. do not save data.
		-cp  : only save cache data. do not get data.

		-is  : specify sl_info infomation server. default is localhost:8086
		-wf	 : The access limitation to SIM by the white list is done in cooperation with sl_info. 

		-vs  : specify sl_voice_relay server. default is localhost:8088

		-as  : use HTTPS between Viewer and Relay Server. 
		-aca : confirms Second Life Server by using C:\Program Files\SecondLife\app_settings\CA.pem
		-ano : no HTTPS communication. Do not use, usually. It is for OpenSim olny. (Experimental option)

		-xp  : specify external web proxy server. 
		-ip  : use internal web proxy function with full access mode. excute internal web proxy process. port number can be specified.
		-ipx : use internal web proxy function with restricted mode. excute internal web proxy process.  port number can be specified.
		-mm  : relay MusicURL and MediaURL(High 23). If it is possible, to use web proxy function of viewer.

		-ver : rewrite Viewer version. Please use this temporarily only when you cannot immediately install new Viewer. 
			   It is dangerous to use this lasting long, and never do it!! 

		-d   : debug mode. display debug information
		-x   : TCP(HTTP/HTTPS) packets are saved at working directory and UDP packet headers are printed.
		-xt  : TCP(HTTP/HTTPS) packets are saved at working directory.
		-xu  : UDP packet headers are printed.
		-xuf : UDP packet is full dumped.

 		--version  : display Version information.
		--help, -h : display this Help messages.


	sl_cache 	[-p port_no] [-f config_file] [-u user_name] [-i interface_address]
				[-pid pid_file] [-l [hitrate_logfile]] [-v syslog_level]
				[-xpr [expire_days]] [-lx [expire_logfile]]
				[-fdb] [-d] 
				[--version] [--help] [-h]

		-p   : port number that Relay Server(sl_relay) connects. default is 8200.
		-f   : configuration file. default is /usr/local/etc/sl_proxy/sl_cahe.conf
		-u   : specify effective user.
		-i   : specify sl_relay side network interface IP address. 
			   if your server has two or more network interfaces, you need to use this option.

		-pid : specify pid file.
		-l   : create hit rate log file. default file name is /var/sl_proxy/sl_cache_hitrate.log
 		-v   : level of syslog. default is LOG_INFO (7).

		-xpr : execute the cache expire daemon. The expire time can be continuously specified by day unit. default is the 30days. 
			   the expire demon retrieves at random and deletes data without the access during the specified days. 
		-lx  : create cache expire log file. default file name is /var/sl_proxy/sl_expire_cache.log

		-fdb : Berkeley DB is used for the data base. default is plane file.

		-d   : debug mode. display debug information.

 		--version  : display Version information.
		--help, -h : display this Help messages.


	sl_info 	[-p port_no] [-f config_file] [-u user_name] [-i interface_address]
				[-pid pid_file] [-l [agent_log]] [-v syslog_level] 
				[-fdb] [-wf [white_list]] [-d] 
				[--version] [--help] [-h]

		-p   : port number that Relay Server(sl_relay) connects. default is 8200.
		-f   : configuration file. default is /usr/local/etc/sl_proxy/sl_cahe.conf
		-u   : specify effective user.
		-i   : specify sl_relay side network interface IP address. 
			   if your server has two network interface and more, you need to use this option.

		-pid : specify pid file.
		-l   : specify log file. default log file is /var/sl_proxy/slcache.log
 		-v   : level of syslog. default is LOG_INFO (7).

		-wf  : Information on the white list is offered. 
			   The access limitation to SIM is done in cooperation with sl_relay. 

		-fdb : Berkeley DB is used for the data base. default is plain file.
		-d   : debug mode. display debug information.

 		--version  : display Version information.
		--help, -h : display this Help messages.


	sl_voice_relay  [-p port] [-r sip_forwarder:port]
				[-f config_file] [-u user_name] 
				[-i internal_ip_address] [-ii internal_ip_address] [-ie external_ip_address]
				[-pid pid_file] [-l [logfile]] [-v syslog_level] 
				[-as] [-aca]
				[-d] [-x] [-xt] [-xu]
				[--version] [--help] [-h]

		-p   : port number that sl_relay connects. default is 8088. It doesn't change usually. 
		-r   : when external SIP relay server (sip_forwarder) is used, the address and the port number of the sip 
			   relay server are specified. if this option is specified, sip_forwarder built in sl_voice_relay stops. 
			   specify the address seen from SLVoice (it does not become 127.0.0.1). default is to use internal sip_forwarder.

		-f   : configuration file. default is /usr/local/etc/sl_proxy/sl_voice_relay.conf
		-u   : specify effective user.

		-i	 : if your server has two or more network interfaces, specify IP address of internal network. 
		-ii  : same as -i option. 
		-ie	 : if your server has two or more network interfaces, specify IP address of external network. 
			   usually, it is detected automatically.

		-pid : specify pid file.
		-l   : specify log file. default is /var/sl_proxy/sl_voice_relay.log
 		-v   : level of syslog. default is LOG_INFO (7).

		-as  : use HTTPS between sl_voice and Voice Relay Server.
		-aca : confirms Vivox Server by using C:\Program Files\SecondLife\app_settings\CA.pem 

		-d   : debug mode. display debug information.
		-x   : TCP packets are printed and saved part at working directory. SIP's UDP packets are printed.
		-xt  : TCP packets are printed and saved part at working directory.
		-xu  : SIP's UDP packet are printed.
  
 		--version  : display Version information.
		--help, -h : display this Help messages.



	3-2. Example of execution (Server)

  		Server ex.1
  			$ /usr/local/bin/sl_relay -f ./sl_relay.conf &

  		Server ex.2 (use cache, infomation server and voice relay server)
			$ /usr/local/bin/sl_voice_relay -f ~/sl_proxy/sl_voice_relay.conf -d &
			$ /usr/local/bin/sl_info  -f ~/sl_proxy/sl_info.conf -wf ~/sl_proxy/white.list &
			$ /usr/local/bin/sl_cache -f ~/sl_proxy/sl_cache.conf &
			$ /usr/local/bin/sl_relay -f ~/sl_proxy/sl_relay.conf -p 8000 -cs -is -wf -vs &

  		Server ex.3
			# /etc/init.d/sl_voice_relay  start
			# /etc/init.d/sl_info  start
			# /etc/init.d/sl_cache start
			# /etc/init.d/sl_relay start


	3-3. Example of execution (Viewer of Windows)

  		Viewer ex.1
  			> SecondLife.exe -loginuri http://FQDN:8100/cgi-bin/login.cgi

  			FQDN is proxy server's FQDN or IP address. 8100 is port number that Viewer connects.(-p option)
			Please edit shortcut icon.

  		Viewer ex.2  use HTTPS between Viewer and Relay Server
  			> SecondLife.exe -loginuri https://FQDN:8100/cgi-bin/login.cgi

			Protocol is https



	3-4. Example to stop server 

  		Server ex.1
			$ kill -INT  PID

  		Server ex.2
			# /etc/init.d/sl_relay stop
			# /etc/init.d/sl_cache stop
			# /etc/init.d/sl_info  stop
			# /etc/init.d/sl_voice_relay stop



4. Schedule for the Future.

	1. sleep, and read the books piled up.
	2. will think about the system of communication between different metaverse.
	3. doctor's order to stop my job.



5. License.

  This software is free with non-commercial use. The re-distribution and the use library is also free. 
  Please distribute in complete shape when re-distributing it. Please describe Copyright clearly in the use of 
  the library. 

  If you use this software with business (when you demand the value from sales, use, and the setting of this 
  software), please send e-mail to iseki@solar-system.tuis.ac.jp. 



6. Donations.

  If your group is interest group like enterprise, please donate some to our laboratory in Univ. So, we are very glad!!
  Please send e-mail to iseki@solar-system.tuis.ac.jp

  It is enough also to donate to Moodle, Sloodle, OpenSim or UNICEF, instead of donation to us. 

  Moodle:  http://www.moodle.org/
  Sloodle: http://www.sloodle.org/
  OpenSim: http://www.opensimulator.org/
  UNICEF:  http://www.unicef.org/



7. Exemption from responsibility.

  This software is not guaranteed at all. The author doesn't assume the responsibility for the 
  problem that occurs along with use, remodeling, and the re-distribution of this software at all.
  Please use everything by the self-responsibility. 


  
8. Address of thanks.

  This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit. 
  (http://www.openssl.org/)

  This product use zlib library.  http://www.zlib.net/

  It referred to web pages of libsecondlife(http://www.libsecondlife.org/) for Second Life protocols.

  GNU autoconf is used for the construction of the program. 

  Subversion is used for the version management of the program. 

  README_on_gentoo_1.6.1 is writed by Uwe aka slick.

  Proofreading and some corrections to the sl_proxy English Wiki pages were done by David Gamble.

  Thank you very much everyone!!!

 
