Configuration

Halcyon database connectivity

After compiling the source there are a few configuration changes that need to be completed before Halcyon will run.

To initialize your SQL database, navigate to the bin/ directory of halcyon in a command prompt and run one of the following commands, depending on your platform:

In Windows:

hc-database.exe --init --type core -h database_host -u database_username -p password

NOTE: If you downloaded a release zipfile under windows, unblock the zip file first using the right click, properties and click the Unblock button before extracting and compiling it, otherwise you will have to unblock all executable files in the /bin directory before halcyon will run properly. This can be done by using powershell as noted here: https://marcofranssen.nl/unblock-downloaded-files-with-powershell/

Linux or OSX:

mono hc-database.exe --init --type core -h database_host -u database_username -p password

After these commands run successfully, you should make a copy of Halcyon.sample.ini in the bin/ folder, rename the copy to Halcyon.ini, and update it to reflect your MySQL and WHIP server locations.

Halcyon.ini configuration

Todo... -Improve formatting- Split sections into separate pages...

[VivoxVoice]
    ; NOTE: This requires contacting Vivox and putting in an application with them for small non commercial grids.
    ; ## Apply for Vivox at http://support.vivox.com/opensim/ for your free account. See listed terms there.

Alternative is the newly added MOSES FreeSwitch module.

Halcyon can have three Economy configuration modes:
No Economy - Default setting. No in world cash operation, any sales are $0.

Economy Settings as Control of Features - uses prices on uploads and Group creation to limit who has access to those features. Only give the price amount set for each option to the individuals who will use them. ie. upload price = $1, group price = $10 where those who are assigned $1 in world may upload items to the grid. Those who have $10 may upload and create groups. This option would be for those who would restrict any world guests / visitors to not allow upload in any location, while grid staff may upload or create groups in addition to any member group settings applied.

[Economy]
    ; In grid mode, this is the land XMLRPC server. Leave blank for normal functionality
    ; This process is called by the viewer to verify a land purchase and process it.
    LandServer = "http://Domain.com/path/landtool.aspx" ; (any web page able to support this process, php, or .Net flavor)
    ; Money Unit fee to upload textures, animations etc
    PriceUpload = 1
    ; Money Unit fee to create groups
    PriceGroupCreate = 10
    ; This is the account Money goes to for fees. Remember, economy requires that money circulates somewhere... even if it's an upload fee. The UUID is the user account assigned to be the World Bank.
    CurrencyAccount = < userUUID > 

Full economy - full economy options apply. Needs website support to function.

[Economy]
    ; In grid mode, this is the land XMLRPC server. Leave blank for normal functionality  
    ; This process is called by the viewer to verify a land purchase and process it.  
    LandServer = "http://Domain.com/path/landtool.aspx" ; (any web page able to support this process, php, or .Net flavor)  
    ; Money Unit fee to upload textures, animations etc.  
    PriceUpload = 0  
    ; Money Unit fee to create groups  
    PriceGroupCreate = 0  
    ; This is the account Money goes to for fees. Remember, economy requires that money circulates somewhere... even if it's an upload fee. The UUID is the user account assigned to be the World Bank.  
    CurrencyAccount = < userUUID > 

Architecture Implementation

For each of these implementation options, it presumes you also have web hosting, MySQL server for the database access and Whip for Asset store management. If not, those are required in addition to the Halcyon setup. Halcyon can be operated without a website, but setting up one makes life a lot easier. @Vinhold has posted his My World open source .Net VB website for Halcyon based grids at My World Source.

Single server 1-10 regions Server will need to have MySQL Server installed and Whip for asset management. It is convenient to also have website services for a grid website.
The grid services each run in a console window. (In Windows 64 that would be the DOS window) and each region simulator runs in its own window. If the entire grid structure was placed in one folder it helps to organize how you can manage the grid. Each folder defined has a full copy of the compiled list of folders and programs.
ie.

    C:\MyWorld - would hold all the grid related folders.  
        \Bin - holds the grid services configurations and supporting programs.  
        \9500 - holds region 1 configuration  
        \9501 - second region folder
         ...
        \9509 - tenth region folder

The region folder named for the port the region will run on helps to reduce manual maintenance of the regions in the host server. It also make it easy to see what ports were assigned to each region. This also becomes more important when using a website to manage estates and regions in the grid and being able to change server assignments there, not on the servers. Even if not using a website for management, the only place needed to set the region information would be the region.xml file. The less manual changes to be made in each region host server is less work in maintenance of the grid later on!

See below for use of batch files to launch grid. One copy of Halcyon.ini may reside in the MyWorld folder and be referenced by all running region instances in that server; a duplicate copy in the Bin folder for the grid services.

Windows Icon settings for the grid services:
User Server
Target: C:\MyWorld\Bin\OpenSim.Grid.UserServer.exe
Start In: C:\MyWorld\Bin

Grid Server
Target: C:\MyWorld\Bin\OpenSim.Grid.GridServer.exe
Start In: C:\MyWorld\Bin

Message Server
Target: C:\MyWorld\Bin\OpenSim.Grid.MessagingServer.exe
Start In: C:\MyWorld\Bin

Aperture
Target: C:\MyWorld\Bin\aperture.exe
Start In: C:\MyWorld\Bin

Region 1
Target: C:\MyWorld\Halcyon.bat --inimaster=..\Halcyon.ini --inifile=Region.ini
Start In: C:\MyWorld\9500

At the time this was documented, each region requires its own folder space for its data store and settings. This differs from other grid software that allows multiple regions per simulator instance.

The Region.ini is a subset of the Halcyon.ini that contains only the region specific settings: This example is set up to use the default Regions/region.xml file and includes the option to use the website source.

    [Startup]
	; Determine where to load the region information from.
	; Defaults to "filesystem" if this setting isn't present
	; Options: webserver - web server url for region xml data. regionload_webserver_url must be set up.
	;          filesystem - local path to Regions folder for region xml files to load.
	;                       regionload_regionsdir may be set up.
	; region_info_source = "webserver"
        ; regionload_webserver_url = "%WebsiteURL%/Regxml.aspx?Region=%InternalIP%:9500"

	region_info_source = "filesystem"

	; specified path to Region xml files when region_info_source = "filesystem".  
	; default is "Regions" indicating the folder where the region xml files are.  
	; May be set to an alternate path to load regions.
	regionload_regionsdir = "Regions" 

    [Network]
        http_listener_port = 9500					; Set to this region's port number

This region.ini example uses the website page call to get the region xml data:

    [Startup]
	; Determine where to load the region information from.
	; Defaults to "filesystem" if this setting isn't present
	; Options: webserver - web server url for region xml data. regionload_webserver_url must be set up.
	;          filesystem - local path to Regions folder for region xml files to load.
	;                       regionload_regionsdir may be set up.
	region_info_source = "webserver"
        regionload_webserver_url = "%WebsiteURL%/Regxml.aspx?Region=%InternalIP%:9500"

	;region_info_source = "filesystem"

	; specified path to Region xml files when region_info_source = "filesystem".  
	; default is "Regions" indicating the folder where the region xml files are.  
	; May be set to an alternate path to load regions.
	;regionload_regionsdir = "Regions" 

    [Network]
        http_listener_port = 9500					; Set to this region's port number

NOTE: Use of the %InternalIP%: port number provides a way to look up the region assigned to that server and port in the regionxml table of the website DB. This way there are no later changes to be made manually on the server if a region is changed and an new one is assigned to the server and port. %WebsiteURL% and %InternalIP% are replacement tags used in the MyWorld grid configuration. They are simply replaced with the indicated content.

Grid start up Order:
1. Whip, 2. User Server, 3. Grid Server, 4. Message Server, 5. Aperture, 6. Start each region in order of preference.

Firewall settings:
Firewall settings to be set for each of the grid services, Aperture and each region to allow external communication by port and application.

Medium grid size 11 - 100 regions
This requires either servers or virtual machines in a server to be set up to manage the higher load of expected user connections. Virtual Machines are presumed for this example.
Needed:
1 VM for web host. Linux or Windows Server.
1 VM for MySQL server. Linux.
1 VM for Grid services. Windows Server or Linux.
1 VM for Whip Asset Server. May be Windows or Linux.
1 VM for each one of Region servers hosting 10 regions each. Currently Windows Server only. (Windows Web Server 2008 R2 works very well)
Region servers would each have an Aperture instance along with each region console run in it. Halcyon.ini setup is for each region server configuration and may use per region override as outlined for Single Server.
At this size consider implementing one of the grid management programs. While it can use the batch file process, it becomes more tedious with more region servers to keep up with.
Grid startup is the same order, where MySQL, Whip must be running before starting Grid services, then regions in all region servers.

Large grid size 101 - 1000+ regions
This configuration is much like the Medium size grid, but may require addition of NAS drive units for very large distributed asset stores with multiple instances of Whip servers and MySQL databases to keep up with data traffic and number of users online at any given time. Use of the grid management programs is critical at this level.

Use of Batch Files:
Use of a batch file when launched by desktop icons is very handy, each having process specific parameters set.
Example Windows Batch file:

@Echo off
:Halcyon Control Batch Program
:loop
Halcyon.exe %*
@echo Error %errorlevel%
:ErrorLevels 0=sim called restart, 1=Region Crashed, 63=Console Restart given, 64=Console shutdown
if ERRORLEVEL 64 goto End
goto loop
:End
Exit

This batch file will only terminate if the commands: Shutdown, Quit or ctrl C are used. When using ctrl + C to let the batch file know you want to stop, enter Y when the batch process asks if you want to end the batch process. (Release 0.9.34 allowed the Ctrl + C to be a fast quit command.)