OpenSimulator - User contributions [en]

Database Settings

2014-10-12T11:52:45Z

Amitgoel: /* MySQL */

{{Quicklinks}}

If you want to quick know the walkthrough for database setup, see [[#Quick Setup]].

'''TODO: This page needs to be improved for setting up database usage in Robust, though the config parameters are identical to the StandaloneCommon.ini/GridCommon.ini files.

= Structure =

On OpenSimulator 0.7.1 and later, you need to set '''StorageProvider''' and '''ConnectionString''' so that OpenSimulator can connect to a database. Usually you'll need to edit '''StandaloneCommon.ini''' for standalone or '''GridCommon.ini''' for grid mode.

In those files, you'll find the [DatabaseService] section. This is where the database is configured. There are number of entries - the only ones that should be uncommented (by removing the beginning semi-colon) are those which apply to the database that you want. All the others must be commented out (by adding a semi-colon to the front of the line).

==Examples==

===MySQL===

For MySQL you will uncomment the required lines and configure as appropriate. For instance, the lines

<pre>
StorageProvider = "OpenSim.Data.MySQL.dll"
ConnectionString = "Data Source=localhost;Database=opensimdb;User ID=opensim;Password=h0tgrits;Old Guids=true;"
</pre>

In this case, it will connect to a MySQL database called opensimdb on the same machine running the simulator (localhost). The user connecting is opensim with the password h0tgrits.

===PostgreSQL===

For PostgreSQL you will uncomment the required lines and configure as appropriate. For instance, the lines

<pre>
StorageProvider = "OpenSim.Data.PGSQL.dll"
ConnectionString = "Data Source=localhost;Database=opensimdb;User ID=opensim;Password=h0tgrits;Port=5432;"
</pre>

In this case, it will connect to a PostgreSQL database called opensimdb on the same machine running the simulator (localhost). The user connecting is opensim with the password h0tgrits. If you changed the port number on PostgreSQL installation, you may add to connection string "Port=5432" where 5432 you may change to the installed port.

* PostgreSQL database module isn't in 0.7.6 release. It is still on the bleeding edge source code.

===SQLite===

SQLite is slightly different. Instead you would uncomment (or leave uncommented) the line.

Or, you can include another ini files. You'll find a line like that:
<pre>
Include-Storage = "config-include/storage/SQLiteStandalone.ini";
</pre>

This will go on to read config-include/storage/SQLiteStandalone.ini after reading this ini file. If you open SQLiteStandalone.ini file, you'll find StrageProvider and ConnectionString lines in each sections. As SQLite does not require users or passwords to be setup, there is no further configuration to be done unless you want sqlite to use different filenames for its databases.

===MSSQL===

'''NOTE: There had been another way to connect to MSSQL database, which was using "mssql_connection.ini" in bin/ directory. On OpenSimulator 0.7.1 or later, it will NOT be read even if you set it properly. Use ConnectionString in *Common.ini instead. For more specific details, see the section [[#MSSQL]].'''

== Database Parameters ==

{|border="1" cellspacing="0"
|- style="background-color:#DDDDFF;"
| Parameter
| Possible Values
| Description

|-
| StorageProvider
| "OpenSim.Data.SQLite.dll" (SQLite) "OpenSim.Data.MySQL.dll" (MySQL) "OpenSim.Data.PGSQL.dll" (PostgreSQL) "OpenSim.Data.MSSQL.dll" (Microsoft SQL Server) "OpenSim.Data.Null.dll" (disable persistence)
| The name of the storage provider modules, which can be found in bin/ folder. The three above are which OpenSimulator officially support (though MSSQL is partially). If you choose "OpenSim.Data.Null.dll", OpenSimulator will keep all data in its memory instead of using DBMS.

|-
| ConnectionString
| See [[#ConnectionString Syntax]]
| A string that OpenSimulator specifies information about a data source. Usually it may include the hostname or ip addresses of database server, database service names, username, schema name and password. The syntax varies between databases.

|-
| EstateConnectionString
| See [[#ConnectionString Syntax]]
| The same as ConnectionString, but it will be used only for Estate Service. (optional)
|}

== ConnectionString Syntax ==

=== MySQL ===

''Data Source=[1];Database=[2];User ID=[3];Password=[4];Old Guids=true;''

* [1] The hostname or ip address of database server
* [2] Database name
* [3] Username for the database above
* [4] Password for the user above

Example: If you have created the database "opensim" in localhost, and then created
the user "opensimuser" and its password is "opensimpassword", it will be:
<pre>
ConnectionString = "Data Source=localhost;Database=opensim;User ID=opensimuser;Password=opensimpassword;Old Guids=true;"
</pre>

=== PostgreSQL ===

''Data Source=[1];Database=[2];User ID=[3];Password=[4];Port=[5]''

* [1] The hostname or ip address of database server
* [2] Database name
* [3] Username for the database above
* [4] Password for the user above
* [5] Port number for the server (default=5432)

Example: If you have created the database "opensim" in localhost, and then created
the user "opensimuser" and its password is "opensimpassword", and the server port number is 5435 it will be:
<pre>
ConnectionString = "Data Source=localhost;Database=opensim;User ID=opensimuser;Password=opensimpassword;Port=5435"
</pre>

=== SQLite ===

''URI=file:[1],version=3,UseUTF16Encoding=True;''

* [1] The path to the database file (relative to the bin/ directory - If there is no file on this path, it will be created automatically)

Example: If you want to create the database for Inventory Service in the directory "bin/db", it will be:
<pre>
ConnectionString = "URI=file:db/inventory.db,version=3,UseUTF16Encoding=True"
</pre>

=== MSSQL ===

''Server=[1];Database=[2];User Id=[3]; password=[4];''

* [1] "servername\instance name" - You can see this string in SQL Server Managerment Studio login dialog(Server:).
* [2] Database name
* [3] Username for the database above
* [4] Password for the user above

Example: If you have installed Microsoft SQL Server Express Edition with default settings on your local machine
, created the database "opensim" in localhost, and then created the user "opensimuser" and its password is "opensimpassword", it will be:
<pre>
ConnectionString = "Server=localhost\SQLEXPRESS;Database=opensim;User Id=opensimuser; password=opensimpassword;"
</pre>

== Using different database settings for different services ==

'''Note: This is extremely advanced configuration and needs to be updated for ROBUST configuration as well as standalone (which is what is implied here).'''

Currently there are several services in OpenSimulator.
* [InventoryService]
* [AssetService]
* [AvatarService]
* [AuthenticationService]
* [UserAccountService]
* [GridUserService]
* [FriendsService]
* [EstateDataStore]
* [SimulationDataStore]
* [PresenceService]
* [AuthorizationService]
* [GridService]

You can use a different database for each service by overriding the StorageProvider and ConnectionString properties as we saw in the general [DatabaseService] section above. For instance, if you want to use MySQL 'opensim' in general but MySQL 'opensim2' for Inventory Service and MSSQL for Authentication Service, you'll need to write in StandaloneCommon.ini something like:

<pre>
[DatabaseService]
StorageProvider = "OpenSim.Data.MySQL.dll"
ConnectionString = "Data Source=localhost;Database=opensim;User ID=opensim;Password=***;Old Guids=true;"
...
[InventoryService]
ConnectionString = "Data Source=localhost;Database=opensim2;User ID=opensim;Password=***;Old Guids=true;"
...
[AuthenticationService]
...(another parameters for authentication service)...
StorageProvider = "OpenSim.Data.MSSQL.dll"
ConnectionString = "Data Source=(local);Database=opensim;User=opensim;password=********;"
</pre>

If OpenSimulator can't find StorageProvider or ConnectionString in each service's section, it will use those in [DatabaseService] section. If OpenSimulator find each or them, it will use the parameter in each service's section. Thus, then the settings in these sections override those in [DatabaseService] section.

In this case, Inventory Service will:
* read [DatabaseService]StorageProvider
* read [DatabaseService]ConnectionString -> read [InventoryService]ConnectionString and override

Authentication Service will:
* read [DatabaseService]StorageProvider -> read [AuthenticationService]StorageProvider and override
* read [DatabaseService]ConnectionString -> read [AuthenticationService]ConnectionString and override

Note: SQLite and MSSQL providers don't support some services.

Note: For Estate Service, there is another parameter EstateConnectionString in [DatabaseService]. It is the middle priority between [DatabaseService] and [EstateDataStore] ConnectionStrings. OpenSimulator reads ConnectionString in [DatabaseService] section first, next EstateConnectionString, finally ConnectionString in [EstateDataService] section and overrides.

= Quick Setup =

== SQLite Walkthrough ==

By default, OpenSimulator will automatically create its SQLite database files(*.db) in bin/ directory. You don't need to do anything generally.
If you want to create the database files in another directory, you can change by editing ConnectionString in bin/config-include/storage/SQLiteStandalone.ini included by config-include/*Commons.ini. See [[#SQLite]] section for the detailed syntax.

== MySQL Walkthrough ==

=== Download ===
Download and install "MySQL Community Server" from [http://dev.mysql.com/downloads/mysql/ MySQL Downloads Page]. On Linux, you can even fetch "mysql-server" or "mysql-community-server" with your native package manager.

=== Installing MySQL Server ===
On Windows:
Download MSI and run it. Select "Typical". After installation, it will launch "MySQL Server Instance Configuration Wizard". Select "Standard Configuration". In the next screen, you might be happy later if you check "Include Bin Directory in Windows PATH". In the next screen, provide mysql root password. It will complete settings for mysql and startup its service automatically. See [http://dev.mysql.com/doc/refman/5.5/en/windows-installation.html MySQL Documentation] for more details.

On Mac OS X:
Download DMG package and install it normally. After install the server package, you can even install MySQL Startup Item if you want MySQL to start automatically during system startup. After that, startup your MySQL by following commands. See [http://dev.mysql.com/doc/refman/5.5/en/macosx-installation.html MySQL Documentation] for more details.

MySQL must be configured to use UTF8 as its default character set. In the config file /etc/my.cnf (Linux) or my.ini (Windows), add these settings:

<pre>
[mysqld]
character-set-server=utf8

[client]
default-character-set=utf8
</pre>

And it's ready to run.

<pre>
$ cd /usr/local/mysql
$ sudo ./bin/mysqld_safe
(enter your password, if necessary)
(press ctrl-Z)
$ bg
(press ctrl-D or enter "exit" to exit the shell)
</pre>

On Linux:
RPM install the downloaded package or install "mysql-server" or "mysql-community-server" with your package manager. For more instructions for installation, see [http://dev.mysql.com/doc/refman/5.5/en/linux-installation.html MySQL Documentation]. After that, startup your MySQL with following command.
<pre>
$ /etc/init.d/mysqld start
</pre>

If you want to startup MySQL server automatically, see [http://dev.mysql.com/doc/refman/5.5/en/automatic-start.html 2.10.1.2. Starting and Stopping MySQL Automatically in MySQL 5.5 Reference Manual].

=== Creating MySQL Database ===
Now you can configure your MySQL with the command line tools.
<pre>
$ mysql -u root --password
(enter your password, or if you haven't set password for MySQL server, type "mysql -u root" instead)
</pre>
You can even use MySQL Command Line Client on Start menu on Windows. After login, create user and database for OpenSimulator.
<pre>
mysql> create database opensim;
mysql> use opensim;
mysql> create user 'opensimuser'@'localhost' identified by 'opensimpassword';
mysql> grant all on opensim.* to 'opensimuser'@'localhost';
mysql> quit
</pre>

=== Configuring OpenSimulator ===
Open StandaloneCommon.ini or GridCommon.ini with your editor. First, comment-out the line for SQLite.
<pre>
; SQLite
;Include-Storage = "config-include/storage/SQLiteStandalone.ini";
</pre>
After that, uncomment StorageProvider and ConnectionString property lines in [DatabaseService] section and change the line like that:
<pre>
; MySql
StorageProvider = "OpenSim.Data.MySQL.dll"
ConnectionString = "Data Source=localhost;Database=opensim;User ID=opensimuser;Password=opensimpassword;Old Guids=true;"
</pre>
Note that "Data Source=localhost;" actually specifies a TCP socket. If your MySQL server is set up to refuse remote connections (i.e. with skip-networking enabled) you'll need to replace "localhost" with the path to MySQL's UNIX socket.
<pre>
ConnectionString = "Data Source=/var/run/mysqld/mysqld.lock;Database=opensim;User ID=opensimuser;Password=opensimpassword;Old Guids=true;"
</pre>
You can find the path to the socket that your MySQL server is using with mysqladmin.
<pre>
$ mysqladmin -p -u root version
</pre>

Save and start OpenSimulator. It will access to your new MySQL database instead of the default SQLite databases.

== PostgreSQL Walkthrough ==

=== Download ===
Download and install PostgreSQL server from [http://www.postgresql.org/download/ PostgreSQL Downloads Page]. On Linux, you can even fetch "postgresql" with your native package manager.

== MSSQL Walkthrough ==

=== Download ===
To download Microsoft SQL Server 2008 Express edition: [http://www.microsoft.com/Sqlserver/2008/en/us/express.aspx]
Make sure you download Microsoft SQL Server 2008 Express with Tools ([http://www.microsoft.com/downloads/details.aspx?FamilyId=7522A683-4CB2-454E-B908-E805E9BD4E28]) since you will likely want a nice tool to work with your database. If you already downloaded Microsoft SQL Server before, skip to "Checking Instance Configurations" step.

=== Installing Microsoft SQL Server ===
Double-click the downloaded executable and select click Installation and "New SQL Server stand-alone installation or add features to an existing installation". It will start installation process, you only need to click "OK", "Next" or "Install" until you come across the "Feature Selection". In this screen, you need to check "Database Engine Service" and "Management Tools - Basic", then click "Next". In next screen "Instance Configuration", check what is filled in "Named instance:" property - you will later use this later. For example, for default Express Edition, you'll see "SQLEXPRESS". Click "Next". Then go on default until you reach "Server Configuration". In this screen, fill in Account Name and Password field with you windows login name and password. In next "Database Engine Configuration" screen, you will need to enable '''Mixed Mode'''. After that provide password, click "Add Current User", and then continue clicking "Next" or "OK" until it completes the installation process. After that, you'll find the entry "SQL Server Managerment Studio" in "Microsoft SQL Server 2008" on the Windows Start menu. Open it and click "connect" to connect to your instance.

=== Checking Instance Configurations ===
Right-click on your database server in Management Studio and select Properties, then go to the Security tab and select '''SQL Server and Windows Authentication mode''', click OK. If you have already installed SQL Server before and you find "Windows Authentication mode" enabled instead, change it.

=== Creating User for Database ===
Expand the Security node, then right-click the Logins node. Select "New Login..." to open "Login - New" dialog. In this screen, fill "Login name" with the string whatever you like, select "SQL Server authentication", give it a strong password, uncheck "User must change password at next login", and click "OK". In this tutorial, we'll assume you have typed "opensimuser" for Login name, and "opensimpassword" for password.

=== Creating Database ===
Right-click on the Databases node and and select "New Database..." to open "New Database" dialog. In "Database name" field, you provide any names for the new database, which we'll assume is "opensim". In "Owner" field, provide the name of newly created database user("opensimuser" in this tutorial). Accept all defaults and click "OK".

=== Configuring OpenSimulator ===
Open StandaloneCommon.ini or GridCommon.ini with your editor. First, comment-out the line for SQLite.
<pre>
; SQLite
;Include-Storage = "config-include/storage/SQLiteStandalone.ini";
</pre>
After that, add these line in [DatabaseService] section. As of OpenSimulator 0.7.1, there is no sample configurations for MSSQL(Microsoft SQL Server), so you need to add them by yourself.
<pre>
; MSSQL
StorageProvider = "OpenSim.Data.MSSQL.dll"
ConnectionString = "Server=localhost\SQLEXPRESS;Database=opensim;User Id=opensimuser; password=opensimpassword;"
</pre>

Save and start OpenSimulator. It will access to your new SQL Server database instead of the default SQLite databases.

= Additional Settings =
== MySQL ==
MySQL's own configuration is handled in its my.ini file (found in "C:\ProgramData\MySQL\MySQL Server x.y" on recent versions of MySQL on Windows) or my.cnf file (found at /etc/mysql/my.cnf on Ubuntu Linux systems, for instance).

In general, the default configuration is fine for OpenSimulator. However, you may want to check the max_allowed_packet size. Very large objects, such as linksets with a very large number of parts or large mesh objects may generate OpenSimulator assets that exceed the default BLOB size that MySQL can store. On Ubuntu the max_allowed_packet size is 16M, which should be fine. On Windows MySQL it can be set larger. In early versions of MySQL [http://dev.mysql.com/doc/refman/5.1/en/packet-too-large.html the default is 1M] which may be too small. Windows 5.6 MySQL default is 4M.

Notes: [http://osgrid.org OSGrid] maximum asset size is reported as 45MB at May 2013. [http://vue.ed.ac.uk/openvue/ Openvue] grid maximum asset size is reported as 16MB as at May 2013.

To change this setting, one would add a line like the following in the [mysqld] section of the my.ini or my.cnf file. E.g.,

max_allowed_packet = 16M

On Ubuntu 14.04.1 with MySQL latest, this setting was already found to be 16M.

[[Category:Database]]

Configuration

2014-10-11T22:35:00Z

Amitgoel: /* Database */

{{Quicklinks}}
 
== OpenSimulator simulator configuration file ==
The region simulator configuration is managed using a file called OpenSim.ini. This file is used regardless of whether the sim is running in standalone or grid mode. This file references some additional configuration information from the config-include/ directory. Information about the various settings is contained in the OpenSim.ini file itself (or OpenSim.ini.example for reference).

Please note, that the name OpenSim.ini can be changed via [[OpenSim.exe Command Line Options|command line arguments]].

It is also possible to distribute the inifile settings over two files. This is useful if you want to run several OpenSimulator processes where most of your settings are identical except for a few. The master file is read first, then the inifile is read. Settings given in the inifile overrule settings given in the master file. The master file has the same format and the same keywords as the inifile, so the same documentation applies.

== Database ==

'''TODO: Database settings do not apply until we have create the ini files from example files first. Hence Database Section Should be moved below.'''

Opensim supports the following database-engines. Information about setting these up can be found in the OpenSim.ini.example file and the other various example files in bin/config-include. '''If you do not want to use the default SQLite configuration then you will need to setup your database before proceeding further'''. SQLite does not require further configuration. See [[Database Settings]] for the detailed settings.

* '''SQLite''' (default) - a lightweight database that comes bundled with OpenSimulator and can be used without requiring any extra configuration. It is mostly intended to get you up and running quickly, not for production use. It is significantly slower than MySQL. A few features here (such as attachment persistence) have not yet been fully implemented.

* '''MySQL''' (fully supported) - This is the recommended database for any use beyond experimentation or small standalone applications. The minimum MySQL version is 5.1.
::* '''Windows x64 systems:'''  There is currently an unresolved [http://opensimulator.org/mantis/bug_view_advanced_page.php?bug_id=5294 bug_id=5294] found when running OpenSimulator with MySQL 5.5 on Windows x64 systems.
::* '''Opensim 0.7.0.2:'''  Some users have reported problems with MySQL 5.1.55 and up with Opensim 0.7.0.2, see [http://opensim-users.2152040.n2.nabble.com/OpenSim-1-7-0-2-and-MySQL-Versions-td6155064.html this thread] for more information. The issue can be resolved by using an updated version of MySql.Data.dll OR installing an older version of MySQL such as [http://downloads.mysql.com/archives.php?p=mysql-5.1&v=5.1.52 MySQL 5.1.52] with Opensim version 0.7.0.2.  

* '''MSSQL''' (fairly supported) - persistence support for some recent OpenSimulator features may not yet be implemented though the vast majority of them are supported.

== Standalone vs. Grid ==
We recommend that you first get OpenSimulator running in standalone mode before you attempt to connect it to a grid or run your own grid. OpenSimulator will start up in standalone mode out-of-the-box on the binary distributions.

An OpenSimulator configuration consists of regions (run by region simulators) and backend data services (such as user, assets and inventory management).

A system running in '''standalone mode''' runs both the region simulator and all the data services in a single process when you run OpenSim.exe. In this mode you can run as many regions as you like but only on a single machine.

[[Image:Opensim-standalone.png|frame|center|OpenSimulator running in standalone mode. Both simulator and services run in the same process (OpenSim.exe).]]

In '''grid mode''', the data services are not part of the region server process. Instead, they are run in a separate executable called Robust.exe. A Robust shell can run all the services or they can be split amongst any number of Robust instances. This allows them to be run on entirely separate machines if necessary. In this mode, the OpenSim.exe acts solely as the region server, serving one or more regions that communicate with the separate data services. At this point you can run multiple OpenSim.exe region simulators on different machines.

[[Image:Opensim-grid-simple.png|frame|center|OpenSimulator running in grid mode. In this case, all the services are being run within a Robust.exe process. Multiple copies of OpenSim.exe (usually running on different machines) all use the same set of common services.]]

Running in grid mode is more complicated than running in standalone mode. It requires an understanding of UUID, X,Y location, server handshake passwords, estates and estate owners, and a couple of other settings. These require more care and patience to set up. We strongly recommend that you don't attempt this unless you are extremely patient and very technically proficient.

= Running OpenSimulator in Standalone mode =

Binary distributions of OpenSimulator are by default configured to run in standalone mode.

However, if you build OpenSimulator from the source distribution or from the git repository then you will need to:

# Change into the '''''bin''''' folder
# Copy the file '''''OpenSim.ini.example''''' to '''''OpenSim.ini'''''. This configures the 3D simulator itself.
# Change into the '''''bin/config-include''''' folder
# Copy the file '''''StandaloneCommon.ini.example''''' to '''''StandaloneCommon.ini'''''. This configures the in-process data services used by the standalone configuration.
# In the '''[Architecture]''' section of '''''OpenSim.ini''''', near the bottom of the file, uncomment the ''Standalone.ini'' line. To uncomment a line of code, remove the semi-colon (;) comment symbol preceding the line so that it says:

Include-Architecture = "config-include/Standalone.ini"

Running OpenSimulator is then a matter of launching OpenSim.exe. However, you need to have installed all dependencies before that. See [[Dependencies]] for details. After that, open a command prompt (for Windows users, Start menu > Run > cmd) and navigate to the Opensim /bin directory.

On a '''Windows 32-bit''' command prompt:
OpenSim.exe
Under '''Windows 64-bit''', ODE cannot yet be compiled for 64 bit mode, so if using the default ODE physics plugin run:
OpenSim.32BitLaunch.exe
On '''Linux''' run:
mono OpenSim.exe
This can be done under both 32 and 64 bit modes with the ODE physics engine.

== Running for the first time ==

If you're running OpenSimulator for the first time, it will ask you several questions at the console that will set up a single region for you. The configuration options you enter will be written to the bin/Regions/Regions.ini file, which you can then edit at a later date if you need to make changes.

Many of the questions have defaults. Here are some explanations of the questions asked:

* '''New region name'''
::The name for your region. Don't leave this blank!
* '''Region UUID'''
::The unique ID of your region. In pretty much all cases you will want to accept the randomly generated default in the square brackets. The only time when you wouldn't is if you were trying to set up a configuration to point to pre-existing region data. But in this case you are probably better off editing the Regions.ini file directly anyway
* '''Region Location'''
::This is the location of the region on the grid. In standalone mode you can safely leave these as the default (1000,1000). If you were to set up additional regions later on in Regions.ini then they would need different grid co-ordinates (e.g. 1000,1001). OpenSimulator regions can be placed anywhere on a 65536 by 65536 grid, but [[Hypergrid]] enabled regions may need special consideration for region location. See [[Installing and Running Hypergrid#The 4096 Regions Limit]] for more information.
* '''Internal IP address'''
::In virtually all cases this can be left as 0.0.0.0 (this is a wildcard that allows OpenSimulator to listen for UDP connections on any of the server's network interfaces). If you want to restrict UDP connections to only one network interface then you can specify an explicit IP address. This address is only used internally - the '''External host name''' is the one that is actually passed to the viewer (and hence is the important one).
* '''Internal port'''
::This is the IP port for all incoming client connections. The name is a bit misleading since it will be used externally (by a Second Life viewer, for instance) as well as internally. You can make this any port you want, but it is safe to leave at the default 9000. Each region on your server must have a unique port.
* '''Allow alternate ports'''
::This is currently experimental. Please leave it at the default of False.
* '''External host name'''
::If you leave this at the default 'SYSTEMIP' then this will become the LAN network address of the machine (e.g. 192.168.1.2). This is fine if you are connecting only from within your LAN. If you want to connect to it from a client on the internet, this should be the External IP Address of your router. Fully Qualified Domain Names (FQDNs) can also be used though they will be converted to a numeric IP address before being sent to the viewer.

The following details are also asked in OpenSimulator 0.6.9 and earlier.

* '''Master Avatar UUID'''
::This is a legacy OpenSimulator feature and can be left at the default of 00000000-0000-0000-0000-000000000000. Later on, you may want to change this to your own avatar's UUID in Regions.ini if you have problems editing terrain.
* '''Master Avatar first name'''
::This is an alternative way of specifying the master avatar by avatar name rather than UUID. If you press enter here then both this field and the last name field will be left blank. Accepting the blank default is fine - this can always be changed later in Regions.ini file.
* '''Master Avatar last name'''
::The last name of the master avatar.
* '''Master Avatar sandbox password'''
::The password of the master avatar.

In OpenSimulator 0.7 and later, OpenSimulator will ask you to assign each region to an estate during the setup process. If an estate needs to be created then it will also ask you to assign an estate manager. In standalone mode, an estate manager can also be created during the setup process.

Don't forget the account details you use to set up the master avatar (in 0.6.9) or the estate manager (in 0.7 and later). Only this user will initially be able to configure the in-world settings for your region. This is also a user account that you can use to perform your initial login test.

See [[Configuring Regions]] for more information about the Regions.ini file that these questions generate.

If you want to create a user other than the estate manager, then in the server console type:

create user

This will ask you a series of questions for creating a user (such as first name, last name and password).

== Network access for the standalone installation ==
In standalone mode, a viewer connecting to your installation needs the following network access to your installation machine.

1. TCP over the http_listener_port as used in your simulator. This is set in the [Network] section of your OpenSim.ini.

<source lang="ini">
[Network]
http_listener_port = 9000
</source>

This will be the default of 9000 if you have not explicitly changed it.

2. UDP over each region's InternalPort as configured in your region files (such as Regions.ini). For instance, if you have configured

<source lang="ini">
[test]
RegionUUID = dd5b77f8-bf88-45ac-aace-35bd76426c81
Location = 1000,1000
InternalAddress = 0.0.0.0
InternalPort = 9000
AllowAlternatePorts = False
ExternalHostName = mygrid.com

[test2]
RegionUUID = dd5b77f8-bf88-45ac-aace-35bd76426c82
Location = 1000,1001
InternalAddress = 0.0.0.0
InternalPort = 9001
AllowAlternatePorts = False
ExternalHostName = mygrid.com
</source>

then you will need to open ports 9000 and 9001 to UDP traffic.

3. The network address of the machine hosting the OpenSimulator installation must be accessible to connecting viewers. In the example above, the installation machine is reachable from the Internet via the domain name "mygrid.com". If the same installation needs to be accessed by viewers on the same network, it must be possible for them to also successfully resolve that domain name (not all routers, especially home routers, have this "loopback capability").

If the installation only needed to be accessed on the same LAN, then one could you the local IP address of the server (e.g. 192.168.1.2).

== Connecting to a standalone installation ==

To connect to your new sim with your user, start up a Second Life viewer with the following command line switches:

'''Client on same machine as OpenSim:'''
-loginuri http://127.0.0.1:9000

'''Client on same LAN as OpenSim:'''
-loginuri http://lan_ip:9000

'''Client on different machine or internet:'''
-loginuri http://external_ip:9000

Then enter the user name and password you set up in the previous step and your new user should login.

Be aware of [http://osgrid.org/forums/viewtopic.php?f=5&t=400&start=0&st=0&sk=t&sd=a loopback] problems when Running viewer & server(s) on the same machine (LAN) by using the "external" configuration. ('''You might notice endless waiting for region handshake'''.) See also [[Troubleshooting|troubleshoot hints]]. If you're having Connectivity problems, [[Network Settings|be sure to read the Network Configuration Page]]. This is important if you see Region handshake issue.

[[Image:Exclamation.png|left]]
== IMPORTANT NOTE, DIVA DISTRO - 4 Apr. 2012 - ==

'''If you download the latest version of diva-r18611.tar.bz''', it is necessary to first launch the setup program ''configure.exe''
*In Linux or MacOSX : open a terminal and enter "mono /diva-r18611/bin/Configure.exe" (assuming that you have placed the Diva distro in /diva-r18611)
*In Windows, assuming they extracted Diva in My Documents, one would open "Run => cmd" and enter '''cd "%USERPROFILE%\My Documents\diva-r18611\"'', followed by "Configure.exe".
After issuing the command, you can set your sim's domain name, and carefully answer the program's questions, then start the program as instructed in above paragraphs.

The program will install the optimum configuration for OpenSim, example: '''<nowiki>http://<your_IP>:9000</nowiki>''' and WiFi '''<nowiki>http:<your_IP>:9000/wifi</nowiki>'''
In the standalone version, four regions will be set up. You can optionally add other regions later on, so make sure to use the same first name with the addition of a number
(ex: "region 5", "region 6", "region 7", etc. otherwise you can't enter the region and you'd be placed in the nearest free location.

If you wish to enter a different region name, make sure that the "distance" between the island created by the Wifi configuration program and the next,
will be at least 40 positions away from the first installed region)
(command console: create region Johnnyland RegionConfigure.ini)

= Running OpenSimulator in Grid mode =
{|
| style="background:LavenderBlush; color:black" |
[[Image:Exclamation.png|left]]
NOTE: 0.7 is the first OpenSimulator release that fully migrates all services to the ROBUST server shell. OpenSim.Grid.UserServer.exe and MessageServer.exe from OpenSimulator 0.6.9 are no longer necessary. Please see the [[0.7 Release|0.7 release notes]] for more details. For details on how to set up grid services in OpenSimulator 0.6.9 and earlier please see [[OpenSim 0.6.9 Grid Mode Configuration]]
|}

Running OpenSimulator in grid mode is considerably more complicated than running a standalone instance. Instead of running everything in the same process, backend data services (asset, inventory, etc.) run in one or more separate processes, often on a different machine. This allows multiple OpenSim.exe simulator instances to use the same asset and inventory data.

== Step 1: Set up a ROBUST services instance ==

1. In the bin directory, copy Robust.ini.example to Robust.ini. The example file is configured to run all the services in a single ROBUST instance.

2. Configure the [[Database Settings]] in Robust.ini to use your MySQL database. Only MySQL is supported for running grid services.

3. Start up Robust.exe.

mono Robust.exe (Linux, BSD, Mac OS X)

or

Robust.exe (Windows)

If you don't see any errors (in red) on the console then you can move on to the next step.

4. Every region must belong to an estate, and every estate must have an owner which is a valid user account in OpenSim's user account service. Create a user on the ROBUST command console with the following command.

create user

This will ask you for the user's name, password and an optional e-mail. Remember this name since you will need it when you start up the simulator for the first time.

== Step 2: Configure an OpenSim.exe to use the ROBUST services ==

In grid mode, as in standalone mode, you need to configure OpenSim.ini which controls the 3D simulator itself.

However, instead of using and configuring the file config-include/StandaloneCommon.ini, a simulator connecting to a grid needs to use and configure the config-include/GridCommon.ini file, in order to connect to the ROBUST hosted remote data services rather than in-process local ones.

The steps for both these operations are as follows.

1. Copy bin/OpenSim.ini.example to OpenSim.ini

2. Find the [Architecture] section at the very bottom of OpenSim.ini. Make sure that one of the following lines is uncommented:

Include-Architecture = "config-include/Grid.ini" (in OpenSimulator 0.7.1 and later)

or

Include-Grid = "config-include/Grid.ini" (in OpenSimulator 0.7.0.2 and earlier)

The others should remain commented.

3. Go to bin/config-include and copy GridCommon.ini.example to GridCommon.ini.

4. Open GridCommon.ini in a text editor. You will see lots of URL entries, each of which have dummy defaults of http://myassetserver.com:8003, http://myinventoryserver.com:8003, etc. You will need to change each of these to point towards the address of your ROBUST instance. For instance, if you're running ROBUST on a machine with a local IP address of 192.168.1.2, you will need to change AssetServerURI to the setting

AssetServerURI = "http://192.168.1.2:8003"

5. Run OpenSim.exe. If you're running OpenSim.exe for the first time you will get the same questions about setting up the region that occur on a first-run in standalone mode. Please see the standalone section for instructions on how to answer these, or read more information about the Regions.ini file on the [[Configuring Regions]] page.

If everything is set up correctly, when starting up OpenSim.exe you shouldn't see any errors. You should also see the ROBUST console display log lines saying that the region has registered with the grid service. For example,

21:43:45 - [GRID SERVICE]: Region t1 (176cc95e-f693-4b02-8e08-af86e2372faa) registered successfully at 256000-256000
21:43:47 - [GRID SERVICE]: region t1 has 0 neighbours

== Network access for a grid installation ==
In standalone mode, a viewer connecting to your installation needs to access

# The login service over TCP and other configured public services (e.g. grid info, map).
# The http_server_port of each configured simulator over TCP.
# The InternalPort and ExternalHostName of each configured region.

The last two requirements are the same as for standalone installations, except that they apply to each server that hosts a simulator. Please see the standalone section above for more details.

The login service is a little different. Whereas in standalone this uses the same http_server_port as the simulator itself, in grid mode it's running in a separate ROBUST service.

The default port for the login service is 8002. You can see this used in the [ServiceList] section of Robust.ini.example.

<source lang="ini">
[ServiceList]
AssetServiceConnector = "8003/OpenSim.Server.Handlers.dll:AssetServiceConnector"
InventoryInConnector = "8003/OpenSim.Server.Handlers.dll:XInventoryInConnector"
GridServiceConnector = "8003/OpenSim.Server.Handlers.dll:GridServiceConnector"
GridInfoServerInConnector = "8002/OpenSim.Server.Handlers.dll:GridInfoServerInConnector"
AuthenticationServiceConnector = "8003/OpenSim.Server.Handlers.dll:AuthenticationServiceConnector"
OpenIdServerConnector = "8002/OpenSim.Server.Handlers.dll:OpenIdServerConnector"
AvatarServiceConnector = "8003/OpenSim.Server.Handlers.dll:AvatarServiceConnector"
LLLoginServiceInConnector = "8002/OpenSim.Server.Handlers.dll:LLLoginServiceInConnector"
PresenceServiceConnector = "8003/OpenSim.Server.Handlers.dll:PresenceServiceConnector"
UserAccountServiceConnector = "8003/OpenSim.Server.Handlers.dll:UserAccountServiceConnector"
GridUserServiceConnector = "8003/OpenSim.Server.Handlers.dll:GridUserServiceConnector"
FriendsServiceConnector = "8003/OpenSim.Server.Handlers.dll:FriendsServiceConnector"
MapAddServiceConnector = "8003/OpenSim.Server.Handlers.dll:MapAddServiceConnector"
MapGetServiceConnector = "8002/OpenSim.Server.Handlers.dll:MapGetServiceConnector"
</source>

Here all the public services (those where the viewer connects directly to the service) are served on port 8002, with internal services on 8003. So you need to make sure that the viewer can access port 8002 over TCP but you do not want to expose port 8003. Only simulators need to be able to connect to port 8003.

== Connecting to a grid installation ==

Your client startup line will look something like

-loginuri http://mygrid.com:8002

The loginuri needs to be the address to the login service. In standalone mode, this was the same address as the region simulator and the port was 9000 by default. However, in grid mode it will be the address to login service hosted on the ROBUST instance. In this case, the address will be 192.168.1.2. The port number of 8002 is the traditional one for the grid login service and is the default in Robust.ini.example.

If the login is successful, you will see log lines on the ROBUST console (for the login itself) and then log lines on the region simulator console (as the login process tells the simulator to expect the avatar, tells the viewer the address of the region simulator and then when the viewer starts talking to the simulator directly).

= Running multiple ROBUST service instances =

If you are operating a grid, then you can run different services (e.g. asset, inventory) in different ROBUST instances, in order to spread the load. To do this, you will need to edit the ServiceConnectors parameter in the [Startup] section of Robust.ini (or Robust.HG.ini if you're running Hypergrid). The default ServiceConnectors parameter looks something like this

<source lang="ini">
[ServiceList]
AssetServiceConnector = "8003/OpenSim.Server.Handlers.dll:AssetServiceConnector"
InventoryInConnector = "8003/OpenSim.Server.Handlers.dll:XInventoryInConnector"
GridServiceConnector = "8003/OpenSim.Server.Handlers.dll:GridServiceConnector"
GridInfoServerInConnector = "8002/OpenSim.Server.Handlers.dll:GridInfoServerInConnector"
AuthenticationServiceConnector = "8003/OpenSim.Server.Handlers.dll:AuthenticationServiceConnector"
OpenIdServerConnector = "8002/OpenSim.Server.Handlers.dll:OpenIdServerConnector"
AvatarServiceConnector = "8003/OpenSim.Server.Handlers.dll:AvatarServiceConnector"
LLLoginServiceInConnector = "8002/OpenSim.Server.Handlers.dll:LLLoginServiceInConnector"
PresenceServiceConnector = "8003/OpenSim.Server.Handlers.dll:PresenceServiceConnector"
UserAccountServiceConnector = "8003/OpenSim.Server.Handlers.dll:UserAccountServiceConnector"
GridUserServiceConnector = "8003/OpenSim.Server.Handlers.dll:GridUserServiceConnector"
FriendsServiceConnector = "8003/OpenSim.Server.Handlers.dll:FriendsServiceConnector"
MapAddServiceConnector = "8003/OpenSim.Server.Handlers.dll:MapAddServiceConnector"
MapGetServiceConnector = "8002/OpenSim.Server.Handlers.dll:MapGetServiceConnector"
</source>

Each entry has the form

<port-number>/<dll>:<connector-class-name>

For instance, the first entry above

8003/OpenSim.Server.Handlers.dll:AssetServiceConnector

says to start an AssetServiceConnector (and hence an asset service) from the OpenSim.Server.Handlers.dll and to server that from port 8003.

By default, Robust.exe loads a configuration file with the same name but with .ini appended instead of .exe. So Robust.exe will look for an inifile called Robust.ini. You can change this by giving the parameter on the commandline. For instance, to start Robust with HG parameters, one would use

Robust.exe -inifile=Robust.HG.ini

So if you wanted to run every connector apart from assets in one instance of ROBUST and the asset connector in another instance, you would have two ini files. One could remain Robust.ini and have

<source lang="ini">
[ServiceList]
InventoryInConnector = "8003/OpenSim.Server.Handlers.dll:XInventoryInConnector"
GridServiceConnector = "8003/OpenSim.Server.Handlers.dll:GridServiceConnector"
GridInfoServerInConnector = "8002/OpenSim.Server.Handlers.dll:GridInfoServerInConnector"
AuthenticationServiceConnector = "8003/OpenSim.Server.Handlers.dll:AuthenticationServiceConnector"
OpenIdServerConnector = "8002/OpenSim.Server.Handlers.dll:OpenIdServerConnector"
AvatarServiceConnector = "8003/OpenSim.Server.Handlers.dll:AvatarServiceConnector"
LLLoginServiceInConnector = "8002/OpenSim.Server.Handlers.dll:LLLoginServiceInConnector"
PresenceServiceConnector = "8003/OpenSim.Server.Handlers.dll:PresenceServiceConnector"
UserAccountServiceConnector = "8003/OpenSim.Server.Handlers.dll:UserAccountServiceConnector"
GridUserServiceConnector = "8003/OpenSim.Server.Handlers.dll:GridUserServiceConnector"
FriendsServiceConnector = "8003/OpenSim.Server.Handlers.dll:FriendsServiceConnector"
MapAddServiceConnector = "8003/OpenSim.Server.Handlers.dll:MapAddServiceConnector"
MapGetServiceConnector = "8002/OpenSim.Server.Handlers.dll:MapGetServiceConnector"
</source>

The other could be called Robust.Assets.ini and have

<source lang="ini">
[ServiceList]
AssetServiceConnector = "8004/OpenSim.Server.Handlers.dll:AssetServiceConnector"
</source>

Note that this is using port 8004 instead of port 8003. This is necessary since only one executable can use each port at a time. You will need to make sure your simulator configuration files use port 8004 for the asset service as well.

You will also need to change the default network port to 8004 for this second copy of Robust.exe

<pre>
[Network]
port = 8004
</pre>

Once you've created the two ROBUST configuration files (Robust.ini containing all services apart from asset and Robust.Assets.ini containing only the asset service), then you could start the first Robust.exe as usual.

Robust.exe

This will load Robust.ini, as we haven't specified a Robust.ini. Also, the logfile it will use will be Robust.log as we haven't manually specified one.

The second ROBUST instance we would start with

Robust.exe -inifile=Robust.Assets.ini -logfile=Robust.Assets.log

The -inifile switch tells the second Robust instance to load it's configuration from Robust.Assets.ini rather than Robust.ini. The -logfile switch tells Robust.exe to use Robust.Assets.log as its logfile rather than the default Robust.log. If you don't specify this switch then you may see errors on the console about a locked log file.

At this point you should have two running Robust.exe instances.

If you put the ROBUST instances on different machines then don't forget to change the relevant service URIs in each simulator to match.

Since OpenSimulator services are stateless (e.g. every request is unconnected with other requests as long as they affect the same persistent data where necessary), you can also load balance by starting more than one ROBUST instance with a copy of the same service (e.g. multiple asset services using the same database). Requests would be round-robined between the service copies using an HTTP reverse proxy implementation (e.g. nginx). See [[Performance#Services]] for more details.

== Notes ==
[http://opensimulator.org/pipermail/opensim-users/2012-October/011099.html Useful discussion about separating Robust instances]

= Attaching your sim to someone else's grid =

To set up the region server (i.e., <tt>OpenSim.exe</tt>) to connect to an external grid, follow the [[Configuration#Step 2: Configure an OpenSim.exe to use the ROBUST services]] instructions above.

The grid will have already provided with the required services. In step 2 you will need to use the provided URLs for their services.

In your bin/Regions.ini file (or other region config file) you will also need to set the grid co-ordinates to your regions provided from the grid operator. See [[Configuring Regions]] for more information.

= Running an OpenSimulator standalone or grid installation with Hypergrid enabled =
[[Hypergrid]] is an emerging architecture supported by OpenSimulator that allows a user with an account on one standalone or grid to visit other Hypergrid-enabled standalones or grids, and for users from those grids to visit the home grid. This does not require the two installations to share a central set of data services (assets, inventory, etc.). Please see [[Installing and Running Hypergrid]] for more details.

= Further notes =

== Troubleshooting ==

See [[Troubleshooting]]

== Running OpenSimulator 0.6.7 to 0.7.6.1 in 64 bit Windows ==
[[Image:Exclamation.png|left]]

'''NOTE:''' ''Commits 3e5bc75 and e8ca900 move these to the directory ./share/32BitLaunch as they should no longer be needed and are slated for removal from the project'

As of OpenSimulator 0.6.7 and up to release 0.7.6.1, the default physics engine for OpenSimulator was changed to the ODE engine. This is because ODE was the most advanced physics engine plugin at the time in OpenSimulator. Unfortunately, it has the drawback in that its library is not compilable under 64-bit in Windows.

Therefore, in order to launch the region simulator under 64-bit Windows for versions 0.6.7 to 0.7.6.1 using ODE, users may need to run:

OpenSim.32BitLaunch.exe

instead of:

OpenSim.exe

An alternative is to use the basicphysics engine instead or one of the other alternative physics engines bundled with OpenSim, though all these were less functional than the ODE plugin.

From OpenSim 0.8 the default physics engine is BulletSim.
'

== Note About Mono ==

Mono and .NET have a built in threadpool. By default, OpenSimulator is instead configured to use a third-party threadpool called SmartThreadPool for many tasks, partly because of issues with early implementations of the Mono threadpool.

However, even with this setting, some other operations are carried out with the built-in threadpool. At least in some versions of Mono (chiefly prior to 2.6), the default configuration for this can cause issues with OpenSimulator - [http://www.mono-project.com/ThreadPool_DeadLocks ThreadPool_Deadlocks at the mono-project website].

If this is an issue or if the threadpool runs out of available threads, then the operation of your sim will start to break in all sorts of different ways. A common symptom is the freezing of all activity upon login of a new avatar.

The MONO_THREADS_PER_CPU parameter affects the number of existing built-in threadpool worker threads below which Mono will always spawn a new thread when OpenSimulator adds a new task. This is MONO_THREADS_PER_CPU * 4. So if set to 50, the minimum number of worker threads will be 200.

Above this number, Mono will make an internal decision whether to spawn a new thread or wait for an existing thread to complete its task.

The effect of this parameter is extremely implementation dependent, and so dependent upon the version of Mono that you are using. Before 2.6 for instance, it was definitely worth setting a high MONO_THREADS_PER_CPU due to issues with the Mono thread pool. In theory, later versions of Mono should not be susceptible to this issue. Mono 2.10.8.1, for instance, has a default MONO_THREADS_PER_CPU of 1 (despite what the incorrect Mono manpage says).

However, people still report a benefit from setting MONO_THREADS_PER_CPU higher than default. The exact number depends on many factors including: the number of CPUs in your machine, what else you use that machine for, how many regions you have in your sim, how many of them are adjacent, how many scripts you have, and how many avatars you expect to serve at the same time. As a reference, Wright Plaza in OSGrid, which is running as a single region on a sim and routinely hosts meetings with 20 avatars, uses the value 125.

For example: $ export MONO_THREADS_PER_CPU=125

So if you are having problems with avatars freezing and you're hardware meets or exceeds recommended [[Performance]] requirements, then you may want to setting this environment variable.

There is a very basic program for displaying current threadpool configuration settings at https://github.com/justincc/opensimulator-tools/tree/master/analysis/threadpool-info.

All this applies to the min threadpool numbers, not the max thread numbers. OpenSimulator itself will attempt to adjust the max numbers. You can see the output from this very near the top of the OpenSim.log file.

== Increasing the stack reserve level when using OpenDynamicsEngine on *nix ==

If you have problems using the OpenDynamicsEngine on *nix, try setting your stack reserve level higher than the default with the following command;
<tt>ulimit -s 262144</tt> Or, run the opensim-ode.sh to start up OpenSimulator.

== Firewalls ==
Some operation systems or distributions run their own firewall by default. If you can't access to OpenSimulator from remote client, you'll need to check their settings. See [[Firewall Settings]] for details.

== Legacy Configuration Information ==
These are some pages containing some legacy configuration information of unknown accuracy.

[[OpenSim 0.6.6 legacy configuration information]]

== Additional Optional Configuration Tasks ==

=== Further configure OpenSimulator ===
If you've looked through OpenSim.ini.example or any other of the config files, you'll see that there's a very large number of configurable parameters spread across multiple files. See [[Configuring Simulator Parameters]] for more details about the configuration infrastructure and how settings in identically named sections (e.g. [XEngine]) are merged by OpenSimulator on loading.

=== Set up a second region to run on the same simulator ===
See [[Configuring Regions]].

=== Run Multiple Standalone Instances of OpenSimulator on the Same Server ===
For each subsequent instance of OpenSim, change the 'http_listener_port' in OpenSim.ini to the value excluding 9000, and 'InternalPort' in Regions.ini to the value excluding 9000. Also, make sure your regions are using different ports, as explained in [[Configuring Regions]].

=== Load region content ===
You can load content onto regions by using the [[OpenSim Archives|load oar command]]. To load individual OAR files into each region, use the 'change region [regionname]' command and then 'load oar [oar-location]'.

=== OpenSim.exe command line options ===
OpenSim.exe has command line options which allow you to perform actions such as reading configuration files from a different directory. See [[OpenSim.exe Command Line Options]] for more details.

=== Script engine ===
OpenSimulator supports multiple script engines. See [[ScriptEngines]] for details. If you don't know what this means then the default script engine will be fine. In fact, recent versions of OpenSimulator only ship with one script engine, the XEngine.

=== Permissions Configuration ===
OpenSimulator has a quite elaborate set of permissions. See [[Permissions (Server)]] for details. By default, permissions are active on region simulators.

=== Logging ===
By default, OpenSimulator logs information to a file called OpenSim.log in the bin directory. See [[Logging]] for details on how to further configure this if required.

=== Set up other optional modules ===
* [[IRCBridgeModule]]
* [[Freeswitch Module]]
* [[Offline Messaging]]
* [[Enabling Groups]]
* See also [[User_Documentation#Setup]]

=== Configuration of Web Server and Pages ===
OpenSimulator contains a web server that can serve up a variety of pages. Some which come from external files and some are generated internally.
* [[External Files]]
* [[Internally Generated]]

= Where to go from here =

* [[NAT Loopback Routers]] Router and Nat Loopback Information

* [[Upgrading]] from an old OpenSimulator version to a newer one.

* [[Server Commands]] for creating users and controlling the system.

* Fix the bent knees bug: [[FAQ#Why are my knees bent when I stand idle.3F]]

= References =

* [http://dist.opensimulator.org/wiki/opensim-standalone.odg OpenOffice draw file for OpenSimulator standalone diagram]
* [http://dist.opensimulator.org/wiki/opensim-grid-simple.odg OpenOffice draw file for OpenSimulator grid diagram]

[[Category:Configuration]]

Configuration

2014-10-11T22:24:55Z

Amitgoel: /* Database */

{{Quicklinks}}
 
== OpenSimulator simulator configuration file ==
The region simulator configuration is managed using a file called OpenSim.ini. This file is used regardless of whether the sim is running in standalone or grid mode. This file references some additional configuration information from the config-include/ directory. Information about the various settings is contained in the OpenSim.ini file itself (or OpenSim.ini.example for reference).

Please note, that the name OpenSim.ini can be changed via [[OpenSim.exe Command Line Options|command line arguments]].

It is also possible to distribute the inifile settings over two files. This is useful if you want to run several OpenSimulator processes where most of your settings are identical except for a few. The master file is read first, then the inifile is read. Settings given in the inifile overrule settings given in the master file. The master file has the same format and the same keywords as the inifile, so the same documentation applies.

== Database ==

TODO: Database settings do not apply until we have create the ini files from example files first. Hence Database Section Should be moved below.

Opensim supports the following database-engines. Information about setting these up can be found in the OpenSim.ini.example file and the other various example files in bin/config-include. '''If you do not want to use the default SQLite configuration then you will need to setup your database before proceeding further'''. SQLite does not require further configuration. See [[Database Settings]] for the detailed settings.

* '''SQLite''' (default) - a lightweight database that comes bundled with OpenSimulator and can be used without requiring any extra configuration. It is mostly intended to get you up and running quickly, not for production use. It is significantly slower than MySQL. A few features here (such as attachment persistence) have not yet been fully implemented.

* '''MySQL''' (fully supported) - This is the recommended database for any use beyond experimentation or small standalone applications. The minimum MySQL version is 5.1.
::* '''Windows x64 systems:'''  There is currently an unresolved [http://opensimulator.org/mantis/bug_view_advanced_page.php?bug_id=5294 bug_id=5294] found when running OpenSimulator with MySQL 5.5 on Windows x64 systems.
::* '''Opensim 0.7.0.2:'''  Some users have reported problems with MySQL 5.1.55 and up with Opensim 0.7.0.2, see [http://opensim-users.2152040.n2.nabble.com/OpenSim-1-7-0-2-and-MySQL-Versions-td6155064.html this thread] for more information. The issue can be resolved by using an updated version of MySql.Data.dll OR installing an older version of MySQL such as [http://downloads.mysql.com/archives.php?p=mysql-5.1&v=5.1.52 MySQL 5.1.52] with Opensim version 0.7.0.2.  

* '''MSSQL''' (fairly supported) - persistence support for some recent OpenSimulator features may not yet be implemented though the vast majority of them are supported.

== Standalone vs. Grid ==
We recommend that you first get OpenSimulator running in standalone mode before you attempt to connect it to a grid or run your own grid. OpenSimulator will start up in standalone mode out-of-the-box on the binary distributions.

An OpenSimulator configuration consists of regions (run by region simulators) and backend data services (such as user, assets and inventory management).

A system running in '''standalone mode''' runs both the region simulator and all the data services in a single process when you run OpenSim.exe. In this mode you can run as many regions as you like but only on a single machine.

[[Image:Opensim-standalone.png|frame|center|OpenSimulator running in standalone mode. Both simulator and services run in the same process (OpenSim.exe).]]

In '''grid mode''', the data services are not part of the region server process. Instead, they are run in a separate executable called Robust.exe. A Robust shell can run all the services or they can be split amongst any number of Robust instances. This allows them to be run on entirely separate machines if necessary. In this mode, the OpenSim.exe acts solely as the region server, serving one or more regions that communicate with the separate data services. At this point you can run multiple OpenSim.exe region simulators on different machines.

[[Image:Opensim-grid-simple.png|frame|center|OpenSimulator running in grid mode. In this case, all the services are being run within a Robust.exe process. Multiple copies of OpenSim.exe (usually running on different machines) all use the same set of common services.]]

Running in grid mode is more complicated than running in standalone mode. It requires an understanding of UUID, X,Y location, server handshake passwords, estates and estate owners, and a couple of other settings. These require more care and patience to set up. We strongly recommend that you don't attempt this unless you are extremely patient and very technically proficient.

= Running OpenSimulator in Standalone mode =

Binary distributions of OpenSimulator are by default configured to run in standalone mode.

However, if you build OpenSimulator from the source distribution or from the git repository then you will need to:

# Change into the '''''bin''''' folder
# Copy the file '''''OpenSim.ini.example''''' to '''''OpenSim.ini'''''. This configures the 3D simulator itself.
# Change into the '''''bin/config-include''''' folder
# Copy the file '''''StandaloneCommon.ini.example''''' to '''''StandaloneCommon.ini'''''. This configures the in-process data services used by the standalone configuration.
# In the '''[Architecture]''' section of '''''OpenSim.ini''''', near the bottom of the file, uncomment the ''Standalone.ini'' line. To uncomment a line of code, remove the semi-colon (;) comment symbol preceding the line so that it says:

Include-Architecture = "config-include/Standalone.ini"

Running OpenSimulator is then a matter of launching OpenSim.exe. However, you need to have installed all dependencies before that. See [[Dependencies]] for details. After that, open a command prompt (for Windows users, Start menu > Run > cmd) and navigate to the Opensim /bin directory.

On a '''Windows 32-bit''' command prompt:
OpenSim.exe
Under '''Windows 64-bit''', ODE cannot yet be compiled for 64 bit mode, so if using the default ODE physics plugin run:
OpenSim.32BitLaunch.exe
On '''Linux''' run:
mono OpenSim.exe
This can be done under both 32 and 64 bit modes with the ODE physics engine.

== Running for the first time ==

If you're running OpenSimulator for the first time, it will ask you several questions at the console that will set up a single region for you. The configuration options you enter will be written to the bin/Regions/Regions.ini file, which you can then edit at a later date if you need to make changes.

Many of the questions have defaults. Here are some explanations of the questions asked:

* '''New region name'''
::The name for your region. Don't leave this blank!
* '''Region UUID'''
::The unique ID of your region. In pretty much all cases you will want to accept the randomly generated default in the square brackets. The only time when you wouldn't is if you were trying to set up a configuration to point to pre-existing region data. But in this case you are probably better off editing the Regions.ini file directly anyway
* '''Region Location'''
::This is the location of the region on the grid. In standalone mode you can safely leave these as the default (1000,1000). If you were to set up additional regions later on in Regions.ini then they would need different grid co-ordinates (e.g. 1000,1001). OpenSimulator regions can be placed anywhere on a 65536 by 65536 grid, but [[Hypergrid]] enabled regions may need special consideration for region location. See [[Installing and Running Hypergrid#The 4096 Regions Limit]] for more information.
* '''Internal IP address'''
::In virtually all cases this can be left as 0.0.0.0 (this is a wildcard that allows OpenSimulator to listen for UDP connections on any of the server's network interfaces). If you want to restrict UDP connections to only one network interface then you can specify an explicit IP address. This address is only used internally - the '''External host name''' is the one that is actually passed to the viewer (and hence is the important one).
* '''Internal port'''
::This is the IP port for all incoming client connections. The name is a bit misleading since it will be used externally (by a Second Life viewer, for instance) as well as internally. You can make this any port you want, but it is safe to leave at the default 9000. Each region on your server must have a unique port.
* '''Allow alternate ports'''
::This is currently experimental. Please leave it at the default of False.
* '''External host name'''
::If you leave this at the default 'SYSTEMIP' then this will become the LAN network address of the machine (e.g. 192.168.1.2). This is fine if you are connecting only from within your LAN. If you want to connect to it from a client on the internet, this should be the External IP Address of your router. Fully Qualified Domain Names (FQDNs) can also be used though they will be converted to a numeric IP address before being sent to the viewer.

The following details are also asked in OpenSimulator 0.6.9 and earlier.

* '''Master Avatar UUID'''
::This is a legacy OpenSimulator feature and can be left at the default of 00000000-0000-0000-0000-000000000000. Later on, you may want to change this to your own avatar's UUID in Regions.ini if you have problems editing terrain.
* '''Master Avatar first name'''
::This is an alternative way of specifying the master avatar by avatar name rather than UUID. If you press enter here then both this field and the last name field will be left blank. Accepting the blank default is fine - this can always be changed later in Regions.ini file.
* '''Master Avatar last name'''
::The last name of the master avatar.
* '''Master Avatar sandbox password'''
::The password of the master avatar.

In OpenSimulator 0.7 and later, OpenSimulator will ask you to assign each region to an estate during the setup process. If an estate needs to be created then it will also ask you to assign an estate manager. In standalone mode, an estate manager can also be created during the setup process.

Don't forget the account details you use to set up the master avatar (in 0.6.9) or the estate manager (in 0.7 and later). Only this user will initially be able to configure the in-world settings for your region. This is also a user account that you can use to perform your initial login test.

See [[Configuring Regions]] for more information about the Regions.ini file that these questions generate.

If you want to create a user other than the estate manager, then in the server console type:

create user

This will ask you a series of questions for creating a user (such as first name, last name and password).

== Network access for the standalone installation ==
In standalone mode, a viewer connecting to your installation needs the following network access to your installation machine.

1. TCP over the http_listener_port as used in your simulator. This is set in the [Network] section of your OpenSim.ini.

<source lang="ini">
[Network]
http_listener_port = 9000
</source>

This will be the default of 9000 if you have not explicitly changed it.

2. UDP over each region's InternalPort as configured in your region files (such as Regions.ini). For instance, if you have configured

<source lang="ini">
[test]
RegionUUID = dd5b77f8-bf88-45ac-aace-35bd76426c81
Location = 1000,1000
InternalAddress = 0.0.0.0
InternalPort = 9000
AllowAlternatePorts = False
ExternalHostName = mygrid.com

[test2]
RegionUUID = dd5b77f8-bf88-45ac-aace-35bd76426c82
Location = 1000,1001
InternalAddress = 0.0.0.0
InternalPort = 9001
AllowAlternatePorts = False
ExternalHostName = mygrid.com
</source>

then you will need to open ports 9000 and 9001 to UDP traffic.

3. The network address of the machine hosting the OpenSimulator installation must be accessible to connecting viewers. In the example above, the installation machine is reachable from the Internet via the domain name "mygrid.com". If the same installation needs to be accessed by viewers on the same network, it must be possible for them to also successfully resolve that domain name (not all routers, especially home routers, have this "loopback capability").

If the installation only needed to be accessed on the same LAN, then one could you the local IP address of the server (e.g. 192.168.1.2).

== Connecting to a standalone installation ==

To connect to your new sim with your user, start up a Second Life viewer with the following command line switches:

'''Client on same machine as OpenSim:'''
-loginuri http://127.0.0.1:9000

'''Client on same LAN as OpenSim:'''
-loginuri http://lan_ip:9000

'''Client on different machine or internet:'''
-loginuri http://external_ip:9000

Then enter the user name and password you set up in the previous step and your new user should login.

Be aware of [http://osgrid.org/forums/viewtopic.php?f=5&t=400&start=0&st=0&sk=t&sd=a loopback] problems when Running viewer & server(s) on the same machine (LAN) by using the "external" configuration. ('''You might notice endless waiting for region handshake'''.) See also [[Troubleshooting|troubleshoot hints]]. If you're having Connectivity problems, [[Network Settings|be sure to read the Network Configuration Page]]. This is important if you see Region handshake issue.

[[Image:Exclamation.png|left]]
== IMPORTANT NOTE, DIVA DISTRO - 4 Apr. 2012 - ==

'''If you download the latest version of diva-r18611.tar.bz''', it is necessary to first launch the setup program ''configure.exe''
*In Linux or MacOSX : open a terminal and enter "mono /diva-r18611/bin/Configure.exe" (assuming that you have placed the Diva distro in /diva-r18611)
*In Windows, assuming they extracted Diva in My Documents, one would open "Run => cmd" and enter '''cd "%USERPROFILE%\My Documents\diva-r18611\"'', followed by "Configure.exe".
After issuing the command, you can set your sim's domain name, and carefully answer the program's questions, then start the program as instructed in above paragraphs.

The program will install the optimum configuration for OpenSim, example: '''<nowiki>http://<your_IP>:9000</nowiki>''' and WiFi '''<nowiki>http:<your_IP>:9000/wifi</nowiki>'''
In the standalone version, four regions will be set up. You can optionally add other regions later on, so make sure to use the same first name with the addition of a number
(ex: "region 5", "region 6", "region 7", etc. otherwise you can't enter the region and you'd be placed in the nearest free location.

If you wish to enter a different region name, make sure that the "distance" between the island created by the Wifi configuration program and the next,
will be at least 40 positions away from the first installed region)
(command console: create region Johnnyland RegionConfigure.ini)

= Running OpenSimulator in Grid mode =
{|
| style="background:LavenderBlush; color:black" |
[[Image:Exclamation.png|left]]
NOTE: 0.7 is the first OpenSimulator release that fully migrates all services to the ROBUST server shell. OpenSim.Grid.UserServer.exe and MessageServer.exe from OpenSimulator 0.6.9 are no longer necessary. Please see the [[0.7 Release|0.7 release notes]] for more details. For details on how to set up grid services in OpenSimulator 0.6.9 and earlier please see [[OpenSim 0.6.9 Grid Mode Configuration]]
|}

Running OpenSimulator in grid mode is considerably more complicated than running a standalone instance. Instead of running everything in the same process, backend data services (asset, inventory, etc.) run in one or more separate processes, often on a different machine. This allows multiple OpenSim.exe simulator instances to use the same asset and inventory data.

== Step 1: Set up a ROBUST services instance ==

1. In the bin directory, copy Robust.ini.example to Robust.ini. The example file is configured to run all the services in a single ROBUST instance.

2. Configure the [[Database Settings]] in Robust.ini to use your MySQL database. Only MySQL is supported for running grid services.

3. Start up Robust.exe.

mono Robust.exe (Linux, BSD, Mac OS X)

or

Robust.exe (Windows)

If you don't see any errors (in red) on the console then you can move on to the next step.

4. Every region must belong to an estate, and every estate must have an owner which is a valid user account in OpenSim's user account service. Create a user on the ROBUST command console with the following command.

create user

This will ask you for the user's name, password and an optional e-mail. Remember this name since you will need it when you start up the simulator for the first time.

== Step 2: Configure an OpenSim.exe to use the ROBUST services ==

In grid mode, as in standalone mode, you need to configure OpenSim.ini which controls the 3D simulator itself.

However, instead of using and configuring the file config-include/StandaloneCommon.ini, a simulator connecting to a grid needs to use and configure the config-include/GridCommon.ini file, in order to connect to the ROBUST hosted remote data services rather than in-process local ones.

The steps for both these operations are as follows.

1. Copy bin/OpenSim.ini.example to OpenSim.ini

2. Find the [Architecture] section at the very bottom of OpenSim.ini. Make sure that one of the following lines is uncommented:

Include-Architecture = "config-include/Grid.ini" (in OpenSimulator 0.7.1 and later)

or

Include-Grid = "config-include/Grid.ini" (in OpenSimulator 0.7.0.2 and earlier)

The others should remain commented.

3. Go to bin/config-include and copy GridCommon.ini.example to GridCommon.ini.

4. Open GridCommon.ini in a text editor. You will see lots of URL entries, each of which have dummy defaults of http://myassetserver.com:8003, http://myinventoryserver.com:8003, etc. You will need to change each of these to point towards the address of your ROBUST instance. For instance, if you're running ROBUST on a machine with a local IP address of 192.168.1.2, you will need to change AssetServerURI to the setting

AssetServerURI = "http://192.168.1.2:8003"

5. Run OpenSim.exe. If you're running OpenSim.exe for the first time you will get the same questions about setting up the region that occur on a first-run in standalone mode. Please see the standalone section for instructions on how to answer these, or read more information about the Regions.ini file on the [[Configuring Regions]] page.

If everything is set up correctly, when starting up OpenSim.exe you shouldn't see any errors. You should also see the ROBUST console display log lines saying that the region has registered with the grid service. For example,

21:43:45 - [GRID SERVICE]: Region t1 (176cc95e-f693-4b02-8e08-af86e2372faa) registered successfully at 256000-256000
21:43:47 - [GRID SERVICE]: region t1 has 0 neighbours

== Network access for a grid installation ==
In standalone mode, a viewer connecting to your installation needs to access

# The login service over TCP and other configured public services (e.g. grid info, map).
# The http_server_port of each configured simulator over TCP.
# The InternalPort and ExternalHostName of each configured region.

The last two requirements are the same as for standalone installations, except that they apply to each server that hosts a simulator. Please see the standalone section above for more details.

The login service is a little different. Whereas in standalone this uses the same http_server_port as the simulator itself, in grid mode it's running in a separate ROBUST service.

The default port for the login service is 8002. You can see this used in the [ServiceList] section of Robust.ini.example.

<source lang="ini">
[ServiceList]
AssetServiceConnector = "8003/OpenSim.Server.Handlers.dll:AssetServiceConnector"
InventoryInConnector = "8003/OpenSim.Server.Handlers.dll:XInventoryInConnector"
GridServiceConnector = "8003/OpenSim.Server.Handlers.dll:GridServiceConnector"
GridInfoServerInConnector = "8002/OpenSim.Server.Handlers.dll:GridInfoServerInConnector"
AuthenticationServiceConnector = "8003/OpenSim.Server.Handlers.dll:AuthenticationServiceConnector"
OpenIdServerConnector = "8002/OpenSim.Server.Handlers.dll:OpenIdServerConnector"
AvatarServiceConnector = "8003/OpenSim.Server.Handlers.dll:AvatarServiceConnector"
LLLoginServiceInConnector = "8002/OpenSim.Server.Handlers.dll:LLLoginServiceInConnector"
PresenceServiceConnector = "8003/OpenSim.Server.Handlers.dll:PresenceServiceConnector"
UserAccountServiceConnector = "8003/OpenSim.Server.Handlers.dll:UserAccountServiceConnector"
GridUserServiceConnector = "8003/OpenSim.Server.Handlers.dll:GridUserServiceConnector"
FriendsServiceConnector = "8003/OpenSim.Server.Handlers.dll:FriendsServiceConnector"
MapAddServiceConnector = "8003/OpenSim.Server.Handlers.dll:MapAddServiceConnector"
MapGetServiceConnector = "8002/OpenSim.Server.Handlers.dll:MapGetServiceConnector"
</source>

Here all the public services (those where the viewer connects directly to the service) are served on port 8002, with internal services on 8003. So you need to make sure that the viewer can access port 8002 over TCP but you do not want to expose port 8003. Only simulators need to be able to connect to port 8003.

== Connecting to a grid installation ==

Your client startup line will look something like

-loginuri http://mygrid.com:8002

The loginuri needs to be the address to the login service. In standalone mode, this was the same address as the region simulator and the port was 9000 by default. However, in grid mode it will be the address to login service hosted on the ROBUST instance. In this case, the address will be 192.168.1.2. The port number of 8002 is the traditional one for the grid login service and is the default in Robust.ini.example.

If the login is successful, you will see log lines on the ROBUST console (for the login itself) and then log lines on the region simulator console (as the login process tells the simulator to expect the avatar, tells the viewer the address of the region simulator and then when the viewer starts talking to the simulator directly).

= Running multiple ROBUST service instances =

If you are operating a grid, then you can run different services (e.g. asset, inventory) in different ROBUST instances, in order to spread the load. To do this, you will need to edit the ServiceConnectors parameter in the [Startup] section of Robust.ini (or Robust.HG.ini if you're running Hypergrid). The default ServiceConnectors parameter looks something like this

<source lang="ini">
[ServiceList]
AssetServiceConnector = "8003/OpenSim.Server.Handlers.dll:AssetServiceConnector"
InventoryInConnector = "8003/OpenSim.Server.Handlers.dll:XInventoryInConnector"
GridServiceConnector = "8003/OpenSim.Server.Handlers.dll:GridServiceConnector"
GridInfoServerInConnector = "8002/OpenSim.Server.Handlers.dll:GridInfoServerInConnector"
AuthenticationServiceConnector = "8003/OpenSim.Server.Handlers.dll:AuthenticationServiceConnector"
OpenIdServerConnector = "8002/OpenSim.Server.Handlers.dll:OpenIdServerConnector"
AvatarServiceConnector = "8003/OpenSim.Server.Handlers.dll:AvatarServiceConnector"
LLLoginServiceInConnector = "8002/OpenSim.Server.Handlers.dll:LLLoginServiceInConnector"
PresenceServiceConnector = "8003/OpenSim.Server.Handlers.dll:PresenceServiceConnector"
UserAccountServiceConnector = "8003/OpenSim.Server.Handlers.dll:UserAccountServiceConnector"
GridUserServiceConnector = "8003/OpenSim.Server.Handlers.dll:GridUserServiceConnector"
FriendsServiceConnector = "8003/OpenSim.Server.Handlers.dll:FriendsServiceConnector"
MapAddServiceConnector = "8003/OpenSim.Server.Handlers.dll:MapAddServiceConnector"
MapGetServiceConnector = "8002/OpenSim.Server.Handlers.dll:MapGetServiceConnector"
</source>

Each entry has the form

<port-number>/<dll>:<connector-class-name>

For instance, the first entry above

8003/OpenSim.Server.Handlers.dll:AssetServiceConnector

says to start an AssetServiceConnector (and hence an asset service) from the OpenSim.Server.Handlers.dll and to server that from port 8003.

By default, Robust.exe loads a configuration file with the same name but with .ini appended instead of .exe. So Robust.exe will look for an inifile called Robust.ini. You can change this by giving the parameter on the commandline. For instance, to start Robust with HG parameters, one would use

Robust.exe -inifile=Robust.HG.ini

So if you wanted to run every connector apart from assets in one instance of ROBUST and the asset connector in another instance, you would have two ini files. One could remain Robust.ini and have

<source lang="ini">
[ServiceList]
InventoryInConnector = "8003/OpenSim.Server.Handlers.dll:XInventoryInConnector"
GridServiceConnector = "8003/OpenSim.Server.Handlers.dll:GridServiceConnector"
GridInfoServerInConnector = "8002/OpenSim.Server.Handlers.dll:GridInfoServerInConnector"
AuthenticationServiceConnector = "8003/OpenSim.Server.Handlers.dll:AuthenticationServiceConnector"
OpenIdServerConnector = "8002/OpenSim.Server.Handlers.dll:OpenIdServerConnector"
AvatarServiceConnector = "8003/OpenSim.Server.Handlers.dll:AvatarServiceConnector"
LLLoginServiceInConnector = "8002/OpenSim.Server.Handlers.dll:LLLoginServiceInConnector"
PresenceServiceConnector = "8003/OpenSim.Server.Handlers.dll:PresenceServiceConnector"
UserAccountServiceConnector = "8003/OpenSim.Server.Handlers.dll:UserAccountServiceConnector"
GridUserServiceConnector = "8003/OpenSim.Server.Handlers.dll:GridUserServiceConnector"
FriendsServiceConnector = "8003/OpenSim.Server.Handlers.dll:FriendsServiceConnector"
MapAddServiceConnector = "8003/OpenSim.Server.Handlers.dll:MapAddServiceConnector"
MapGetServiceConnector = "8002/OpenSim.Server.Handlers.dll:MapGetServiceConnector"
</source>

The other could be called Robust.Assets.ini and have

<source lang="ini">
[ServiceList]
AssetServiceConnector = "8004/OpenSim.Server.Handlers.dll:AssetServiceConnector"
</source>

Note that this is using port 8004 instead of port 8003. This is necessary since only one executable can use each port at a time. You will need to make sure your simulator configuration files use port 8004 for the asset service as well.

You will also need to change the default network port to 8004 for this second copy of Robust.exe

<pre>
[Network]
port = 8004
</pre>

Once you've created the two ROBUST configuration files (Robust.ini containing all services apart from asset and Robust.Assets.ini containing only the asset service), then you could start the first Robust.exe as usual.

Robust.exe

This will load Robust.ini, as we haven't specified a Robust.ini. Also, the logfile it will use will be Robust.log as we haven't manually specified one.

The second ROBUST instance we would start with

Robust.exe -inifile=Robust.Assets.ini -logfile=Robust.Assets.log

The -inifile switch tells the second Robust instance to load it's configuration from Robust.Assets.ini rather than Robust.ini. The -logfile switch tells Robust.exe to use Robust.Assets.log as its logfile rather than the default Robust.log. If you don't specify this switch then you may see errors on the console about a locked log file.

At this point you should have two running Robust.exe instances.

If you put the ROBUST instances on different machines then don't forget to change the relevant service URIs in each simulator to match.

Since OpenSimulator services are stateless (e.g. every request is unconnected with other requests as long as they affect the same persistent data where necessary), you can also load balance by starting more than one ROBUST instance with a copy of the same service (e.g. multiple asset services using the same database). Requests would be round-robined between the service copies using an HTTP reverse proxy implementation (e.g. nginx). See [[Performance#Services]] for more details.

== Notes ==
[http://opensimulator.org/pipermail/opensim-users/2012-October/011099.html Useful discussion about separating Robust instances]

= Attaching your sim to someone else's grid =

To set up the region server (i.e., <tt>OpenSim.exe</tt>) to connect to an external grid, follow the [[Configuration#Step 2: Configure an OpenSim.exe to use the ROBUST services]] instructions above.

The grid will have already provided with the required services. In step 2 you will need to use the provided URLs for their services.

In your bin/Regions.ini file (or other region config file) you will also need to set the grid co-ordinates to your regions provided from the grid operator. See [[Configuring Regions]] for more information.

= Running an OpenSimulator standalone or grid installation with Hypergrid enabled =
[[Hypergrid]] is an emerging architecture supported by OpenSimulator that allows a user with an account on one standalone or grid to visit other Hypergrid-enabled standalones or grids, and for users from those grids to visit the home grid. This does not require the two installations to share a central set of data services (assets, inventory, etc.). Please see [[Installing and Running Hypergrid]] for more details.

= Further notes =

== Troubleshooting ==

See [[Troubleshooting]]

== Running OpenSimulator 0.6.7 to 0.7.6.1 in 64 bit Windows ==
[[Image:Exclamation.png|left]]

'''NOTE:''' ''Commits 3e5bc75 and e8ca900 move these to the directory ./share/32BitLaunch as they should no longer be needed and are slated for removal from the project'

As of OpenSimulator 0.6.7 and up to release 0.7.6.1, the default physics engine for OpenSimulator was changed to the ODE engine. This is because ODE was the most advanced physics engine plugin at the time in OpenSimulator. Unfortunately, it has the drawback in that its library is not compilable under 64-bit in Windows.

Therefore, in order to launch the region simulator under 64-bit Windows for versions 0.6.7 to 0.7.6.1 using ODE, users may need to run:

OpenSim.32BitLaunch.exe

instead of:

OpenSim.exe

An alternative is to use the basicphysics engine instead or one of the other alternative physics engines bundled with OpenSim, though all these were less functional than the ODE plugin.

From OpenSim 0.8 the default physics engine is BulletSim.
'

== Note About Mono ==

Mono and .NET have a built in threadpool. By default, OpenSimulator is instead configured to use a third-party threadpool called SmartThreadPool for many tasks, partly because of issues with early implementations of the Mono threadpool.

However, even with this setting, some other operations are carried out with the built-in threadpool. At least in some versions of Mono (chiefly prior to 2.6), the default configuration for this can cause issues with OpenSimulator - [http://www.mono-project.com/ThreadPool_DeadLocks ThreadPool_Deadlocks at the mono-project website].

If this is an issue or if the threadpool runs out of available threads, then the operation of your sim will start to break in all sorts of different ways. A common symptom is the freezing of all activity upon login of a new avatar.

The MONO_THREADS_PER_CPU parameter affects the number of existing built-in threadpool worker threads below which Mono will always spawn a new thread when OpenSimulator adds a new task. This is MONO_THREADS_PER_CPU * 4. So if set to 50, the minimum number of worker threads will be 200.

Above this number, Mono will make an internal decision whether to spawn a new thread or wait for an existing thread to complete its task.

The effect of this parameter is extremely implementation dependent, and so dependent upon the version of Mono that you are using. Before 2.6 for instance, it was definitely worth setting a high MONO_THREADS_PER_CPU due to issues with the Mono thread pool. In theory, later versions of Mono should not be susceptible to this issue. Mono 2.10.8.1, for instance, has a default MONO_THREADS_PER_CPU of 1 (despite what the incorrect Mono manpage says).

However, people still report a benefit from setting MONO_THREADS_PER_CPU higher than default. The exact number depends on many factors including: the number of CPUs in your machine, what else you use that machine for, how many regions you have in your sim, how many of them are adjacent, how many scripts you have, and how many avatars you expect to serve at the same time. As a reference, Wright Plaza in OSGrid, which is running as a single region on a sim and routinely hosts meetings with 20 avatars, uses the value 125.

For example: $ export MONO_THREADS_PER_CPU=125

So if you are having problems with avatars freezing and you're hardware meets or exceeds recommended [[Performance]] requirements, then you may want to setting this environment variable.

There is a very basic program for displaying current threadpool configuration settings at https://github.com/justincc/opensimulator-tools/tree/master/analysis/threadpool-info.

All this applies to the min threadpool numbers, not the max thread numbers. OpenSimulator itself will attempt to adjust the max numbers. You can see the output from this very near the top of the OpenSim.log file.

== Increasing the stack reserve level when using OpenDynamicsEngine on *nix ==

If you have problems using the OpenDynamicsEngine on *nix, try setting your stack reserve level higher than the default with the following command;
<tt>ulimit -s 262144</tt> Or, run the opensim-ode.sh to start up OpenSimulator.

== Firewalls ==
Some operation systems or distributions run their own firewall by default. If you can't access to OpenSimulator from remote client, you'll need to check their settings. See [[Firewall Settings]] for details.

== Legacy Configuration Information ==
These are some pages containing some legacy configuration information of unknown accuracy.

[[OpenSim 0.6.6 legacy configuration information]]

== Additional Optional Configuration Tasks ==

=== Further configure OpenSimulator ===
If you've looked through OpenSim.ini.example or any other of the config files, you'll see that there's a very large number of configurable parameters spread across multiple files. See [[Configuring Simulator Parameters]] for more details about the configuration infrastructure and how settings in identically named sections (e.g. [XEngine]) are merged by OpenSimulator on loading.

=== Set up a second region to run on the same simulator ===
See [[Configuring Regions]].

=== Run Multiple Standalone Instances of OpenSimulator on the Same Server ===
For each subsequent instance of OpenSim, change the 'http_listener_port' in OpenSim.ini to the value excluding 9000, and 'InternalPort' in Regions.ini to the value excluding 9000. Also, make sure your regions are using different ports, as explained in [[Configuring Regions]].

=== Load region content ===
You can load content onto regions by using the [[OpenSim Archives|load oar command]]. To load individual OAR files into each region, use the 'change region [regionname]' command and then 'load oar [oar-location]'.

=== OpenSim.exe command line options ===
OpenSim.exe has command line options which allow you to perform actions such as reading configuration files from a different directory. See [[OpenSim.exe Command Line Options]] for more details.

=== Script engine ===
OpenSimulator supports multiple script engines. See [[ScriptEngines]] for details. If you don't know what this means then the default script engine will be fine. In fact, recent versions of OpenSimulator only ship with one script engine, the XEngine.

=== Permissions Configuration ===
OpenSimulator has a quite elaborate set of permissions. See [[Permissions (Server)]] for details. By default, permissions are active on region simulators.

=== Logging ===
By default, OpenSimulator logs information to a file called OpenSim.log in the bin directory. See [[Logging]] for details on how to further configure this if required.

=== Set up other optional modules ===
* [[IRCBridgeModule]]
* [[Freeswitch Module]]
* [[Offline Messaging]]
* [[Enabling Groups]]
* See also [[User_Documentation#Setup]]

=== Configuration of Web Server and Pages ===
OpenSimulator contains a web server that can serve up a variety of pages. Some which come from external files and some are generated internally.
* [[External Files]]
* [[Internally Generated]]

= Where to go from here =

* [[NAT Loopback Routers]] Router and Nat Loopback Information

* [[Upgrading]] from an old OpenSimulator version to a newer one.

* [[Server Commands]] for creating users and controlling the system.

* Fix the bent knees bug: [[FAQ#Why are my knees bent when I stand idle.3F]]

= References =

* [http://dist.opensimulator.org/wiki/opensim-standalone.odg OpenOffice draw file for OpenSimulator standalone diagram]
* [http://dist.opensimulator.org/wiki/opensim-grid-simple.odg OpenOffice draw file for OpenSimulator grid diagram]

[[Category:Configuration]]

Build Instructions

2014-10-11T00:56:16Z

Amitgoel: /* Ubuntu 10.04 and later */

{{Quicklinks}}

This page covers building OpenSimulator from source code on multiple platforms. Please help us keep this page up to date as the project progresses. If you just want to run OpenSimulator, [[Download]] and [[Configuration|run]] the binary build instead. In the most cases, you should be fine with binaries.

= Obtaining the Source Code =

Check out the [[Download]] page for instructions on obtaining an OpenSimulator source release. If you want the current development code (i.e. the Git master branch) see [[Developer_Documentation#Source_Code_Repository_Access]].

= Building =

Although this page is long, building is generally quite simple. See the BUILDING.txt file in the distribution itself for simplified instructions.

== MS Windows ==

OpenSimulator 0.8 and later requires either
* [http://msdn.microsoft.com/en-us/netframework/cc378097 .NET Framework 4.0] on Windows or
* [http://www.go-mono.com/mono-downloads/download.html Mono] on Linux or Mac. Mono 2.10.8 is the minimum version.

=== Supported Compilers ===
* Visual Studio 2010
* Visual Studio 2008 up until OpenSimulator 0.7.6 - current development code requires Visual Studio 2010 or a compiler that can compile .NET 4.0 code.
:Any editions of Visual Studio should work just fine, including free editions [http://www.microsoft.com/express/downloads/ Microsoft Visual C# Express Edition].
:Note that Visual Studio 2005 or earlier are no longer supported([http://www.mail-archive.com/opensim-dev@lists.berlios.de/msg02674.html opensim-dev proposal], [http://www.mail-archive.com/opensim-dev@lists.berlios.de/msg02673.html opensim-dev approved]).

=== Compiling in an IDE ===
# Run "runprebuild.bat" or "runprebuild2010.bat" (if using Visual Studio 2010 with OpenSimulator 0.7.6 source code or earlier).
# Open the resulting "OpenSim.sln" in any Visual Studio IDE.
# Build (or Debug) -> Build Solution.

===Compiling at the Command Prompt ===
# Run "runprebuild.bat".
# Run the resulting "compile.bat" file or run "nant". This will build the executable using MSBuild (the former) or nan t(the latter).

=== Additional Notes ===

* You can run OpenSimulator on 64-bit Windows (Vista, Windows 7 ...) today, but if you want to debug it in Visual Studio, you'll need to add OpenSim.32BitLaunch to the solution and set it as startup project. See [http://blog.tedd.no/2008/12/05/opensim-in-visual-studio-on-win64/ OpenSimulator in Visual Studio on Win64@Tedds blog] for details.

*For those that use a Cygwin shell, you may need to fix DLLs permissions issue by typing "<tt>chmod 755 *.dll *.exe</tt>" in the <tt>bin</tt> directory.

== Mac OS X ==

=== Mac OS X 10.5 and later, Intel ===

Only you have to do is to get :
* Mono SDK from [http://www.go-mono.com/mono-downloads/download.html Mono Download Page]
* MonoDevelop package from [http://monodevelop.com/Download MonoDevelop Download Page] ** MonoDevelop redirects to Xamarin Studio for Mc OS X downloads
and then install them - now no need to install XCode nor MacPort (you can still install mono dev libraries and nant with MacPort though).

When you run nano to build OpenSimulator, it may show an error like "Unable to locate 'mono' module using pkg-config. Download the Mono
development packages". I suspect XCode or MacPort causes something wrong (since it worked fine after I removed both), but I'm not sure. Anyway, insert a line into '''/usr/bin/nant''' script file to manage this problem :
<pre>
#!/bin/sh
export PKG_CONFIG_PATH=/Library/Frameworks/Mono.framework/Libraries/pkgconfig # add this!
exec /Library/Frameworks/Mono.framework/Versions/2.10.2/bin/mono \
/Library/Frameworks/Mono.framework/Versions/2.10.2/share/NAnt/bin/NAnt.exe "$@"
</pre>

You can even compile and debug OpenSimulator with MonoDevelop IDE after running "runprebuild.sh". Open the solution file(*.sln) with MonoDevelop IDE then select Build -> Build All from the menu.

=== Mac OS X 10.4/10.5 on PowerPC ===
OpenSimulator can run on PowerPC Macs (such as G4, G5). These instructions were tested on 10.5.8. Note that two libraries must also be built from source. Caveat: the OpenSimulator app was only briefly tested in self-contained mode. There may well be issues with this build. Feel free to note any issues you find below (or in a new wiki page? discussion?).

Unfortunately, the OpenSimulator version used here must be compiled on one version of Mono (2.6.7) and run on another (2.8.2). This means either upgrading Mono after the build, or having both versions installed and accessing the older version when you want to build. These instructions let you have both versions installed.

* Install Xcode 3.1.4 Developer Tools from from http://developer.apple.com/. You must have a free Apple developer account to access the downloads. 3.1.4 was the last PowerPC Xcode.

* (10.4 only) Install X11 from the Optional Install (or see if it's a Customize option when you install Xcode). 10.5 gets X11 by default (''from OS X or dev tools?'').
* Install Mono 2.6.7 PowerPC Framework from here: http://www.go-mono.com/mono-downloads/download.html (binary OS X Framework, no need to build from source)
* Then install Mono 2.8.2 PowerPC framework. For these instructions to work, you must first install 2.6.7, THEN 2.8.2. (The old framework is not deleted, but "Current" symlinks are updated).
* Download OpenSimulator 0.7.0.2 source tarball: http://dist.opensimulator.org/opensim-0.7.0.2-source.tar.gz Expand to a suitable folder for development and running.
** Feel free to try a newer version of OpenSimulator (the repository is on git now).
** If you used a newer OpenSimulator version, check BUILDING.txt for any changes to build instructions (we fall under "Linux")
* Edit or create .profile or .bash_profile in your OS X home folder, with the following lines:
# remember real PATH
export OSIM_HACK_ORIG_PATH=$PATH

# normal path for running OpenSimulator
export PATH=$PATH:/Library/Frameworks/Mono.framework/Versions/Current/bin:/usr/local/mysql/bin

# Just for nant:
export PKG_CONFIG_PATH=/Library/Frameworks/Mono.framework/Versions/2.6.7/lib/pkgconfig
alias oldpath="export PATH=$OSIM_HACK_ORIG_PATH:/Library/Frameworks/Mono.framework/Versions/2.6.7/bin"

* Open a new Terminal window, and cd to your uncompressed OpenSimulator source folder (shortcut: type "cd " then drag the folder to the Terminal window). The enter these commands:
oldpath
./runprebuild.sh
nant

* nant should take around 10 minutes to compile your OpenSimulator. If you get through that without errors, you're halfway there! (I did get 234 warnings).
* *Important* Before we forget, open a new Terminal window (necessary to avoid the effects of "oldpath").
* Now we need PowerPC versions of two libraries. Build each one and replace the compiled .dylib files in the opensim/bin folder.
** libode.dylib http://cdnetworks-us-1.dl.sourceforge.net/project/opende/ODE/0.11.1/ode-0.11.1.zip
** libopenjpeg-dotnet-2.1.3.0-dotnet-1.dylib (checked out with svn:)
svn co http://libopenmetaverse.googlecode.com/svn/libopenmetaverse/trunk/openjpeg-dotnet libopenmetaverse-read-only
cd libopenmetaverse-read-only
** To build, remove the Makefile file, which is for Linux, and rename Makefile.osx to just Makefile, then give the command: make )
** Remove the other versions of the two libraries (similar names, different extensions, like "libode-x86_64.so". Two libode's and three libopenjpeg's).
* Configure your sim: Copy OpenSim.ini.example to OpenSim.ini and customize it per its comments.
* Likewise copy and customize StandaloneCommon.ini in bin/config-include
* Note that the comments say that the current SQLite plugin doesn't work on OS X. Either solve that, or install MySQL, which requires no compiling and is relatively easy to set up:
** From http://downloads.mysql.com/archives.php?p=mysql-5.1&v=5.1.40, download MySQL 5.1.40 for 10.5 PowerPC (installer, not 64-bit)
** Run the installer. (which installs to /usr/local)
** Install MySQL.prefPane into System Preferences by double-clicking it.
** Open the pref pane and start MySQL.
** (Optional:) For unattended startup, install MySQLStartupItem (doesn't always work for me).
** (Recommended:) In Terminal, do the one-time setup of MySQL with this command: mysql_secure_installation
** In MySQL, create the opensim user per the comments in OpenSim.ini. Give it all the create privileges.
*** Since this is a Mac, you could use Sequel Pro (donationware) to do that in a nice GUI. Standard connection, host: 127.0.0.1 (if on the same Mac)
* You're ready to run OpenSimulator. In that new Terminal window, cd to your OpenSim-source/bin folder.
mono OpenSim.exe
* If all is well, you will be prompted "New region name []: "
* Turn to "Running OpenSimulator for the first time" on wiki page [[Configuration]]
* When fully up and running, the prompt is "Region (<region-name>) #"

== Linux ==

=== Ubuntu ===

For Ubuntu users on older distributions (7.10, 8.04, 9.10 etc.) '''you need''' to upgrade your version of mono to at least 2.4.3 for OpenSimulator 0.7.6 and 2.10.8 for the next OpenSimulator release. We recommend updating to at least Mono 2.10.8 in any case for performance reasons. For anyone who needs to upgrade their Mono, see [[Update Mono on Ubuntu]].

Ubuntu Karmic (9.10) includes mono 2.4.2.3 packages.

Ubuntu Lucid (10.04) includes mono 2.4.4 packages.

Ubuntu Maverick (10.10) includes mono 2.6.7 packages.

Ubuntu Natty (11.04) includes mono 2.6.7 packages.

Ubuntu Oneirc (11.10) to Salamander (13.10) include the mono 2.10.8.1 packages.

==== Ubuntu 10.04 and later ====

In this version, one only needs to install mono-complete - this will pull down all the other required packages as dependencies. Thus, to build:

sudo apt-get install mono-complete
# [[Download]] opensim
cd opensim
./runprebuild.sh
xbuild

As of mono 2.6 series, xbuild works well enough to drive a complete build of OpenSimulator. Since xbuild is included within the '''mono-complete''' package on Ubuntu, you don't have to install any additional packages if you don't have any particular reason to prefer nant over xbuild. They are just two different build systems that invoke the same C# compiler based on two different build script formats.

If you do want to build using nant, then you will need to install the '''nant''' apt-get package and execute

sudo apt-get install nant
nant

instead of

xbuild

after ./runprebuild.sh

'''OPTIONAL (for developers):''' To run the regression test suite, you will also need to install nunit-console, like so

sudo apt-get install nunit-console
nant test

{{anchor|CentOS}}{{anchor|RedHat}}{{anchor|RHEL}}{{anchor|Fedora}}

=== Debian ===

Debian 4 (Etch) is no longer supported by debian.org. Update at least to 5 (Lenny) before running OpenSimulator. See [http://www.debian.org/releases/lenny/i386/release-notes/ch-upgrading.html Upgrades from previous release@debian.org] for detail.

For Debian 5 (Lenny) or later, just type:
<pre>
sudo aptitude install nant
</pre>
before run runprebuild.sh and nant. You can even use apt-get instead of aptitude. They both will also install dependent packages.

Tested on Debian 5 "Lenny" ''oldstable'', Debian 6 "Squeeze" ''stable'' and Debian 7 "Wheezy" ''testing''.

=== Fedora ===

After getting run your OpenSimulator binary distributions, you'll need to get mono development library and install nant to build OpenSimulator from the source. See both sections below.

==== Getting Mono Libraries ====

If you have installed mono packages from the core repository for your distributions [[Dependencies#RedHat|when you run OpenSim.exe binary distribusion]], just type:
<pre>
sudo yum install mono-devel
</pre>

If not, just type (given that [[Dependencies#Installing from Mono Repository|you have already set up yum repository for mono]]) :
<pre>
sudo yum install mono-addon-devel
</pre>

Both command will install its dependencies as well.

==== Installing NAnt ====

Run "yum info nant" to check the version of nant package. If you find the package, then just type:
<pre>
sudo yum install nant
</pre>
You can now run nant out-of-the-box.

If you can't find nant package in yum repository, or you feel its version is too early for building OpenSimulator, obtain NAnt from [http://nant.sourceforge.net/ NAnt Project Site]. See User Manual there for detailed instruction. As of 0.90, you will need to create startup script like that (given you have expanded NAnt to /usr/local/nant) :
<pre>
sudo vi /usr/bin/nant
</pre>
Then inside this file :
<pre>
#!/bin/sh
exec mono /usr/local/nant/bin/NAnt.exe "$@"
</pre>
After that, make it executable :
<pre>
sudo chmod +x /usr/bin/nant
</pre>

You can now run runprebuild.sh and nant to compile OpenSimulator.

=== CentOS, Redhat ===

==== Install EPEL Repo ====

<pre>
wget http://dl.fedoraproject.org/pub/epel/6/x86_64/epel-release-6-8.noarch.rpm
rpm -Uvh epel-release-6-8.noarch.rpm
</pre>

==== Pre-required Package for Mono and GID+ ====

<pre>
yum install bison gettext glib2 freetype fontconfig libpng libpng-devel libX11 \
libX11-devel glib2-devel libgdi* libexif glibc-devel urw-fonts \
unzip gcc gcc-c++ automake autoconf \
libtool make bzip2 wget pixman-devel \
fontconfig-devel freetype-devel libexif-devel \
libjpeg-devel libtiff-devel giflib-devel
</pre>

==== Mono compilation ====

ps: -j 2 equal number of processor (or core)

<pre>
cd /usr/local/src
wget http://download.mono-project.com/sources/mono/mono-3.0.4.tar.bz2
tar -jxvf mono-3.0.4.tar.bz2
cd mono-3.0.4
./configure --libdir=/usr/lib64
make -j 2
make install
</pre>

==== Install GID+ ====
ps: -j 2 equal number of processor (or core)

<pre>
cd /usr/local/src
wget http://download.mono-project.com/sources/libgdiplus/libgdiplus-2.10.9.tar.bz2
tar -xvjf libgdiplus-2.10.9.tar.bz2
cd libgdiplus-2.10.9
./configure
make -j2
make install
</pre>

=== openSUSE ===

Just type:
<pre>
sudo zypper install nant
</pre>
before run runprebuild.sh and nant. It will also install dependent packages.

== FreeBSD ==

FreeBSD is not currently a supported platform for OpenSimulator. However, it is possible to get OpenSimulator running on FreeBSD.

On FreeBSD 6.2 and later

su
cd /usr/ports/devel/subversion/ && make install clean (you may also need to rebuild apr-svn if this step fails)
cd /usr/ports/lang/mono/ && make install clean
cd /usr/ports/devel/nant/ && make install clean
cd /usr/ports/databases/sqlite3/ && make install clean
cd /usr/ports/x11-toolkits/libgdiplus/ && make install clean
cd /opensim/installation/directory/
[[Download]] opensim
cd opensim
./runprebuild.sh
nant

If you get "System.DllNotFoundException: libopenjpeg" errors, follow one of these fixes (depending of the lib appearing in the error message):
* [[Troubleshooting#System.DllNotFoundException:_lib32.2Flibopenjpeg-dotnet-2.1.3.0-dotnet-1-i686|libopenjpeg-mono]]
* [[Troubleshooting#System.DllNotFoundException:_..2Flibopenjpeg-libsl-2.1.2.0.so|libopenjpeg-libsl]]

For ODE Physics you must do the following:
cd /usr/ports/graphics/libGL/ && make install clean
cd /usr/ports/graphics/libGLU/ && make install clean
cd /opensim/installation/directory/
git clone git://opensimulator.org/git/opensim-libs
cd opensim-libs/trunk/unmanaged/OpenDynamicsEngine-r1755
sh autogen.sh
./configure --enable-shared --enable-release --disable-demos --without-x --enable-old-trimesh
make
cp ./ode/src/.libs/libode.so /opensim/installation/directory/opensim/bin/libode.so (32 bit)
cp ./ode/src/.libs/libode.so /opensim/installation/directory/opensim/bin/libode-x86_64.so (64 bit)

= Configuration =

See [[Configuration]].

[[Category:Users]]
[[Category:Users]]
[[Category:Getting Started]]

Build Instructions

2014-10-11T00:19:05Z

Amitgoel: /* Ubuntu 10.04 and later */

{{Quicklinks}}

This page covers building OpenSimulator from source code on multiple platforms. Please help us keep this page up to date as the project progresses. If you just want to run OpenSimulator, [[Download]] and [[Configuration|run]] the binary build instead. In the most cases, you should be fine with binaries.

= Obtaining the Source Code =

Check out the [[Download]] page for instructions on obtaining an OpenSimulator source release. If you want the current development code (i.e. the Git master branch) see [[Developer_Documentation#Source_Code_Repository_Access]].

= Building =

Although this page is long, building is generally quite simple. See the BUILDING.txt file in the distribution itself for simplified instructions.

== MS Windows ==

OpenSimulator 0.8 and later requires either
* [http://msdn.microsoft.com/en-us/netframework/cc378097 .NET Framework 4.0] on Windows or
* [http://www.go-mono.com/mono-downloads/download.html Mono] on Linux or Mac. Mono 2.10.8 is the minimum version.

=== Supported Compilers ===
* Visual Studio 2010
* Visual Studio 2008 up until OpenSimulator 0.7.6 - current development code requires Visual Studio 2010 or a compiler that can compile .NET 4.0 code.
:Any editions of Visual Studio should work just fine, including free editions [http://www.microsoft.com/express/downloads/ Microsoft Visual C# Express Edition].
:Note that Visual Studio 2005 or earlier are no longer supported([http://www.mail-archive.com/opensim-dev@lists.berlios.de/msg02674.html opensim-dev proposal], [http://www.mail-archive.com/opensim-dev@lists.berlios.de/msg02673.html opensim-dev approved]).

=== Compiling in an IDE ===
# Run "runprebuild.bat" or "runprebuild2010.bat" (if using Visual Studio 2010 with OpenSimulator 0.7.6 source code or earlier).
# Open the resulting "OpenSim.sln" in any Visual Studio IDE.
# Build (or Debug) -> Build Solution.

===Compiling at the Command Prompt ===
# Run "runprebuild.bat".
# Run the resulting "compile.bat" file or run "nant". This will build the executable using MSBuild (the former) or nan t(the latter).

=== Additional Notes ===

* You can run OpenSimulator on 64-bit Windows (Vista, Windows 7 ...) today, but if you want to debug it in Visual Studio, you'll need to add OpenSim.32BitLaunch to the solution and set it as startup project. See [http://blog.tedd.no/2008/12/05/opensim-in-visual-studio-on-win64/ OpenSimulator in Visual Studio on Win64@Tedds blog] for details.

*For those that use a Cygwin shell, you may need to fix DLLs permissions issue by typing "<tt>chmod 755 *.dll *.exe</tt>" in the <tt>bin</tt> directory.

== Mac OS X ==

=== Mac OS X 10.5 and later, Intel ===

Only you have to do is to get :
* Mono SDK from [http://www.go-mono.com/mono-downloads/download.html Mono Download Page]
* MonoDevelop package from [http://monodevelop.com/Download MonoDevelop Download Page] ** MonoDevelop redirects to Xamarin Studio for Mc OS X downloads
and then install them - now no need to install XCode nor MacPort (you can still install mono dev libraries and nant with MacPort though).

When you run nano to build OpenSimulator, it may show an error like "Unable to locate 'mono' module using pkg-config. Download the Mono
development packages". I suspect XCode or MacPort causes something wrong (since it worked fine after I removed both), but I'm not sure. Anyway, insert a line into '''/usr/bin/nant''' script file to manage this problem :
<pre>
#!/bin/sh
export PKG_CONFIG_PATH=/Library/Frameworks/Mono.framework/Libraries/pkgconfig # add this!
exec /Library/Frameworks/Mono.framework/Versions/2.10.2/bin/mono \
/Library/Frameworks/Mono.framework/Versions/2.10.2/share/NAnt/bin/NAnt.exe "$@"
</pre>

You can even compile and debug OpenSimulator with MonoDevelop IDE after running "runprebuild.sh". Open the solution file(*.sln) with MonoDevelop IDE then select Build -> Build All from the menu.

=== Mac OS X 10.4/10.5 on PowerPC ===
OpenSimulator can run on PowerPC Macs (such as G4, G5). These instructions were tested on 10.5.8. Note that two libraries must also be built from source. Caveat: the OpenSimulator app was only briefly tested in self-contained mode. There may well be issues with this build. Feel free to note any issues you find below (or in a new wiki page? discussion?).

Unfortunately, the OpenSimulator version used here must be compiled on one version of Mono (2.6.7) and run on another (2.8.2). This means either upgrading Mono after the build, or having both versions installed and accessing the older version when you want to build. These instructions let you have both versions installed.

* Install Xcode 3.1.4 Developer Tools from from http://developer.apple.com/. You must have a free Apple developer account to access the downloads. 3.1.4 was the last PowerPC Xcode.

* (10.4 only) Install X11 from the Optional Install (or see if it's a Customize option when you install Xcode). 10.5 gets X11 by default (''from OS X or dev tools?'').
* Install Mono 2.6.7 PowerPC Framework from here: http://www.go-mono.com/mono-downloads/download.html (binary OS X Framework, no need to build from source)
* Then install Mono 2.8.2 PowerPC framework. For these instructions to work, you must first install 2.6.7, THEN 2.8.2. (The old framework is not deleted, but "Current" symlinks are updated).
* Download OpenSimulator 0.7.0.2 source tarball: http://dist.opensimulator.org/opensim-0.7.0.2-source.tar.gz Expand to a suitable folder for development and running.
** Feel free to try a newer version of OpenSimulator (the repository is on git now).
** If you used a newer OpenSimulator version, check BUILDING.txt for any changes to build instructions (we fall under "Linux")
* Edit or create .profile or .bash_profile in your OS X home folder, with the following lines:
# remember real PATH
export OSIM_HACK_ORIG_PATH=$PATH

# normal path for running OpenSimulator
export PATH=$PATH:/Library/Frameworks/Mono.framework/Versions/Current/bin:/usr/local/mysql/bin

# Just for nant:
export PKG_CONFIG_PATH=/Library/Frameworks/Mono.framework/Versions/2.6.7/lib/pkgconfig
alias oldpath="export PATH=$OSIM_HACK_ORIG_PATH:/Library/Frameworks/Mono.framework/Versions/2.6.7/bin"

* Open a new Terminal window, and cd to your uncompressed OpenSimulator source folder (shortcut: type "cd " then drag the folder to the Terminal window). The enter these commands:
oldpath
./runprebuild.sh
nant

* nant should take around 10 minutes to compile your OpenSimulator. If you get through that without errors, you're halfway there! (I did get 234 warnings).
* *Important* Before we forget, open a new Terminal window (necessary to avoid the effects of "oldpath").
* Now we need PowerPC versions of two libraries. Build each one and replace the compiled .dylib files in the opensim/bin folder.
** libode.dylib http://cdnetworks-us-1.dl.sourceforge.net/project/opende/ODE/0.11.1/ode-0.11.1.zip
** libopenjpeg-dotnet-2.1.3.0-dotnet-1.dylib (checked out with svn:)
svn co http://libopenmetaverse.googlecode.com/svn/libopenmetaverse/trunk/openjpeg-dotnet libopenmetaverse-read-only
cd libopenmetaverse-read-only
** To build, remove the Makefile file, which is for Linux, and rename Makefile.osx to just Makefile, then give the command: make )
** Remove the other versions of the two libraries (similar names, different extensions, like "libode-x86_64.so". Two libode's and three libopenjpeg's).
* Configure your sim: Copy OpenSim.ini.example to OpenSim.ini and customize it per its comments.
* Likewise copy and customize StandaloneCommon.ini in bin/config-include
* Note that the comments say that the current SQLite plugin doesn't work on OS X. Either solve that, or install MySQL, which requires no compiling and is relatively easy to set up:
** From http://downloads.mysql.com/archives.php?p=mysql-5.1&v=5.1.40, download MySQL 5.1.40 for 10.5 PowerPC (installer, not 64-bit)
** Run the installer. (which installs to /usr/local)
** Install MySQL.prefPane into System Preferences by double-clicking it.
** Open the pref pane and start MySQL.
** (Optional:) For unattended startup, install MySQLStartupItem (doesn't always work for me).
** (Recommended:) In Terminal, do the one-time setup of MySQL with this command: mysql_secure_installation
** In MySQL, create the opensim user per the comments in OpenSim.ini. Give it all the create privileges.
*** Since this is a Mac, you could use Sequel Pro (donationware) to do that in a nice GUI. Standard connection, host: 127.0.0.1 (if on the same Mac)
* You're ready to run OpenSimulator. In that new Terminal window, cd to your OpenSim-source/bin folder.
mono OpenSim.exe
* If all is well, you will be prompted "New region name []: "
* Turn to "Running OpenSimulator for the first time" on wiki page [[Configuration]]
* When fully up and running, the prompt is "Region (<region-name>) #"

== Linux ==

=== Ubuntu ===

For Ubuntu users on older distributions (7.10, 8.04, 9.10 etc.) '''you need''' to upgrade your version of mono to at least 2.4.3 for OpenSimulator 0.7.6 and 2.10.8 for the next OpenSimulator release. We recommend updating to at least Mono 2.10.8 in any case for performance reasons. For anyone who needs to upgrade their Mono, see [[Update Mono on Ubuntu]].

Ubuntu Karmic (9.10) includes mono 2.4.2.3 packages.

Ubuntu Lucid (10.04) includes mono 2.4.4 packages.

Ubuntu Maverick (10.10) includes mono 2.6.7 packages.

Ubuntu Natty (11.04) includes mono 2.6.7 packages.

Ubuntu Oneirc (11.10) to Salamander (13.10) include the mono 2.10.8.1 packages.

==== Ubuntu 10.04 and later ====

In this version, one only needs to install mono-complete - this will pull down all the other required packages as dependencies. Thus, to build:

sudo apt-get install mono-complete nant
# [[Download]] opensim
cd opensim
./runprebuild.sh
xbuild

As of mono 2.6 series, xbuild works well enough to drive a complete build of OpenSimulator. Since xbuild is included within the '''mono-complete''' package on Ubuntu, you don't have to install any additional packages if you don't have any particular reason to prefer nant over xbuild. They are just two different build systems that invoke the same C# compiler based on two different build script formats.

If you do want to build using nant, then you will need to install the '''nant''' apt-get package and execute

nant

instead of

xbuild

after ./runprebuild.sh

'''OPTIONAL (for developers):''' To run the regression test suite, you will also need to install nunit-console, like so

sudo apt-get install nunit-console
nant test

{{anchor|CentOS}}{{anchor|RedHat}}{{anchor|RHEL}}{{anchor|Fedora}}

=== Debian ===

Debian 4 (Etch) is no longer supported by debian.org. Update at least to 5 (Lenny) before running OpenSimulator. See [http://www.debian.org/releases/lenny/i386/release-notes/ch-upgrading.html Upgrades from previous release@debian.org] for detail.

For Debian 5 (Lenny) or later, just type:
<pre>
sudo aptitude install nant
</pre>
before run runprebuild.sh and nant. You can even use apt-get instead of aptitude. They both will also install dependent packages.

Tested on Debian 5 "Lenny" ''oldstable'', Debian 6 "Squeeze" ''stable'' and Debian 7 "Wheezy" ''testing''.

=== Fedora ===

After getting run your OpenSimulator binary distributions, you'll need to get mono development library and install nant to build OpenSimulator from the source. See both sections below.

==== Getting Mono Libraries ====

If you have installed mono packages from the core repository for your distributions [[Dependencies#RedHat|when you run OpenSim.exe binary distribusion]], just type:
<pre>
sudo yum install mono-devel
</pre>

If not, just type (given that [[Dependencies#Installing from Mono Repository|you have already set up yum repository for mono]]) :
<pre>
sudo yum install mono-addon-devel
</pre>

Both command will install its dependencies as well.

==== Installing NAnt ====

Run "yum info nant" to check the version of nant package. If you find the package, then just type:
<pre>
sudo yum install nant
</pre>
You can now run nant out-of-the-box.

If you can't find nant package in yum repository, or you feel its version is too early for building OpenSimulator, obtain NAnt from [http://nant.sourceforge.net/ NAnt Project Site]. See User Manual there for detailed instruction. As of 0.90, you will need to create startup script like that (given you have expanded NAnt to /usr/local/nant) :
<pre>
sudo vi /usr/bin/nant
</pre>
Then inside this file :
<pre>
#!/bin/sh
exec mono /usr/local/nant/bin/NAnt.exe "$@"
</pre>
After that, make it executable :
<pre>
sudo chmod +x /usr/bin/nant
</pre>

You can now run runprebuild.sh and nant to compile OpenSimulator.

=== CentOS, Redhat ===

==== Install EPEL Repo ====

<pre>
wget http://dl.fedoraproject.org/pub/epel/6/x86_64/epel-release-6-8.noarch.rpm
rpm -Uvh epel-release-6-8.noarch.rpm
</pre>

==== Pre-required Package for Mono and GID+ ====

<pre>
yum install bison gettext glib2 freetype fontconfig libpng libpng-devel libX11 \
libX11-devel glib2-devel libgdi* libexif glibc-devel urw-fonts \
unzip gcc gcc-c++ automake autoconf \
libtool make bzip2 wget pixman-devel \
fontconfig-devel freetype-devel libexif-devel \
libjpeg-devel libtiff-devel giflib-devel
</pre>

==== Mono compilation ====

ps: -j 2 equal number of processor (or core)

<pre>
cd /usr/local/src
wget http://download.mono-project.com/sources/mono/mono-3.0.4.tar.bz2
tar -jxvf mono-3.0.4.tar.bz2
cd mono-3.0.4
./configure --libdir=/usr/lib64
make -j 2
make install
</pre>

==== Install GID+ ====
ps: -j 2 equal number of processor (or core)

<pre>
cd /usr/local/src
wget http://download.mono-project.com/sources/libgdiplus/libgdiplus-2.10.9.tar.bz2
tar -xvjf libgdiplus-2.10.9.tar.bz2
cd libgdiplus-2.10.9
./configure
make -j2
make install
</pre>

=== openSUSE ===

Just type:
<pre>
sudo zypper install nant
</pre>
before run runprebuild.sh and nant. It will also install dependent packages.

== FreeBSD ==

FreeBSD is not currently a supported platform for OpenSimulator. However, it is possible to get OpenSimulator running on FreeBSD.

On FreeBSD 6.2 and later

su
cd /usr/ports/devel/subversion/ && make install clean (you may also need to rebuild apr-svn if this step fails)
cd /usr/ports/lang/mono/ && make install clean
cd /usr/ports/devel/nant/ && make install clean
cd /usr/ports/databases/sqlite3/ && make install clean
cd /usr/ports/x11-toolkits/libgdiplus/ && make install clean
cd /opensim/installation/directory/
[[Download]] opensim
cd opensim
./runprebuild.sh
nant

If you get "System.DllNotFoundException: libopenjpeg" errors, follow one of these fixes (depending of the lib appearing in the error message):
* [[Troubleshooting#System.DllNotFoundException:_lib32.2Flibopenjpeg-dotnet-2.1.3.0-dotnet-1-i686|libopenjpeg-mono]]
* [[Troubleshooting#System.DllNotFoundException:_..2Flibopenjpeg-libsl-2.1.2.0.so|libopenjpeg-libsl]]

For ODE Physics you must do the following:
cd /usr/ports/graphics/libGL/ && make install clean
cd /usr/ports/graphics/libGLU/ && make install clean
cd /opensim/installation/directory/
git clone git://opensimulator.org/git/opensim-libs
cd opensim-libs/trunk/unmanaged/OpenDynamicsEngine-r1755
sh autogen.sh
./configure --enable-shared --enable-release --disable-demos --without-x --enable-old-trimesh
make
cp ./ode/src/.libs/libode.so /opensim/installation/directory/opensim/bin/libode.so (32 bit)
cp ./ode/src/.libs/libode.so /opensim/installation/directory/opensim/bin/libode-x86_64.so (64 bit)

= Configuration =

See [[Configuration]].

[[Category:Users]]
[[Category:Users]]
[[Category:Getting Started]]

Build Instructions

2014-10-09T23:30:53Z

Amitgoel: /* Mac OS X 10.5 and later, Intel */

{{Quicklinks}}

This page covers building OpenSimulator from source code on multiple platforms. Please help us keep this page up to date as the project progresses. If you just want to run OpenSimulator, [[Download]] and [[Configuration|run]] the binary build instead. In the most cases, you should be fine with binaries.

= Obtaining the Source Code =

Check out the [[Download]] page for instructions on obtaining an OpenSimulator source release. If you want the current development code (i.e. the Git master branch) see [[Developer_Documentation#Source_Code_Repository_Access]].

= Building =

Although this page is long, building is generally quite simple. See the BUILDING.txt file in the distribution itself for simplified instructions.

== MS Windows ==

OpenSimulator 0.8 and later requires either
* [http://msdn.microsoft.com/en-us/netframework/cc378097 .NET Framework 4.0] on Windows or
* [http://www.go-mono.com/mono-downloads/download.html Mono] on Linux or Mac. Mono 2.10.8 is the minimum version.

=== Supported Compilers ===
* Visual Studio 2010
* Visual Studio 2008 up until OpenSimulator 0.7.6 - current development code requires Visual Studio 2010 or a compiler that can compile .NET 4.0 code.
:Any editions of Visual Studio should work just fine, including free editions [http://www.microsoft.com/express/downloads/ Microsoft Visual C# Express Edition].
:Note that Visual Studio 2005 or earlier are no longer supported([http://www.mail-archive.com/opensim-dev@lists.berlios.de/msg02674.html opensim-dev proposal], [http://www.mail-archive.com/opensim-dev@lists.berlios.de/msg02673.html opensim-dev approved]).

=== Compiling in an IDE ===
# Run "runprebuild.bat" or "runprebuild2010.bat" (if using Visual Studio 2010 with OpenSimulator 0.7.6 source code or earlier).
# Open the resulting "OpenSim.sln" in any Visual Studio IDE.
# Build (or Debug) -> Build Solution.

===Compiling at the Command Prompt ===
# Run "runprebuild.bat".
# Run the resulting "compile.bat" file or run "nant". This will build the executable using MSBuild (the former) or nan t(the latter).

=== Additional Notes ===

* You can run OpenSimulator on 64-bit Windows (Vista, Windows 7 ...) today, but if you want to debug it in Visual Studio, you'll need to add OpenSim.32BitLaunch to the solution and set it as startup project. See [http://blog.tedd.no/2008/12/05/opensim-in-visual-studio-on-win64/ OpenSimulator in Visual Studio on Win64@Tedds blog] for details.

*For those that use a Cygwin shell, you may need to fix DLLs permissions issue by typing "<tt>chmod 755 *.dll *.exe</tt>" in the <tt>bin</tt> directory.

== Mac OS X ==

=== Mac OS X 10.5 and later, Intel ===

Only you have to do is to get :
* Mono SDK from [http://www.go-mono.com/mono-downloads/download.html Mono Download Page]
* MonoDevelop package from [http://monodevelop.com/Download MonoDevelop Download Page] ** MonoDevelop redirects to Xamarin Studio for Mc OS X downloads
and then install them - now no need to install XCode nor MacPort (you can still install mono dev libraries and nant with MacPort though).

When you run nano to build OpenSimulator, it may show an error like "Unable to locate 'mono' module using pkg-config. Download the Mono
development packages". I suspect XCode or MacPort causes something wrong (since it worked fine after I removed both), but I'm not sure. Anyway, insert a line into '''/usr/bin/nant''' script file to manage this problem :
<pre>
#!/bin/sh
export PKG_CONFIG_PATH=/Library/Frameworks/Mono.framework/Libraries/pkgconfig # add this!
exec /Library/Frameworks/Mono.framework/Versions/2.10.2/bin/mono \
/Library/Frameworks/Mono.framework/Versions/2.10.2/share/NAnt/bin/NAnt.exe "$@"
</pre>

You can even compile and debug OpenSimulator with MonoDevelop IDE after running "runprebuild.sh". Open the solution file(*.sln) with MonoDevelop IDE then select Build -> Build All from the menu.

=== Mac OS X 10.4/10.5 on PowerPC ===
OpenSimulator can run on PowerPC Macs (such as G4, G5). These instructions were tested on 10.5.8. Note that two libraries must also be built from source. Caveat: the OpenSimulator app was only briefly tested in self-contained mode. There may well be issues with this build. Feel free to note any issues you find below (or in a new wiki page? discussion?).

Unfortunately, the OpenSimulator version used here must be compiled on one version of Mono (2.6.7) and run on another (2.8.2). This means either upgrading Mono after the build, or having both versions installed and accessing the older version when you want to build. These instructions let you have both versions installed.

* Install Xcode 3.1.4 Developer Tools from from http://developer.apple.com/. You must have a free Apple developer account to access the downloads. 3.1.4 was the last PowerPC Xcode.

* (10.4 only) Install X11 from the Optional Install (or see if it's a Customize option when you install Xcode). 10.5 gets X11 by default (''from OS X or dev tools?'').
* Install Mono 2.6.7 PowerPC Framework from here: http://www.go-mono.com/mono-downloads/download.html (binary OS X Framework, no need to build from source)
* Then install Mono 2.8.2 PowerPC framework. For these instructions to work, you must first install 2.6.7, THEN 2.8.2. (The old framework is not deleted, but "Current" symlinks are updated).
* Download OpenSimulator 0.7.0.2 source tarball: http://dist.opensimulator.org/opensim-0.7.0.2-source.tar.gz Expand to a suitable folder for development and running.
** Feel free to try a newer version of OpenSimulator (the repository is on git now).
** If you used a newer OpenSimulator version, check BUILDING.txt for any changes to build instructions (we fall under "Linux")
* Edit or create .profile or .bash_profile in your OS X home folder, with the following lines:
# remember real PATH
export OSIM_HACK_ORIG_PATH=$PATH

# normal path for running OpenSimulator
export PATH=$PATH:/Library/Frameworks/Mono.framework/Versions/Current/bin:/usr/local/mysql/bin

# Just for nant:
export PKG_CONFIG_PATH=/Library/Frameworks/Mono.framework/Versions/2.6.7/lib/pkgconfig
alias oldpath="export PATH=$OSIM_HACK_ORIG_PATH:/Library/Frameworks/Mono.framework/Versions/2.6.7/bin"

* Open a new Terminal window, and cd to your uncompressed OpenSimulator source folder (shortcut: type "cd " then drag the folder to the Terminal window). The enter these commands:
oldpath
./runprebuild.sh
nant

* nant should take around 10 minutes to compile your OpenSimulator. If you get through that without errors, you're halfway there! (I did get 234 warnings).
* *Important* Before we forget, open a new Terminal window (necessary to avoid the effects of "oldpath").
* Now we need PowerPC versions of two libraries. Build each one and replace the compiled .dylib files in the opensim/bin folder.
** libode.dylib http://cdnetworks-us-1.dl.sourceforge.net/project/opende/ODE/0.11.1/ode-0.11.1.zip
** libopenjpeg-dotnet-2.1.3.0-dotnet-1.dylib (checked out with svn:)
svn co http://libopenmetaverse.googlecode.com/svn/libopenmetaverse/trunk/openjpeg-dotnet libopenmetaverse-read-only
cd libopenmetaverse-read-only
** To build, remove the Makefile file, which is for Linux, and rename Makefile.osx to just Makefile, then give the command: make )
** Remove the other versions of the two libraries (similar names, different extensions, like "libode-x86_64.so". Two libode's and three libopenjpeg's).
* Configure your sim: Copy OpenSim.ini.example to OpenSim.ini and customize it per its comments.
* Likewise copy and customize StandaloneCommon.ini in bin/config-include
* Note that the comments say that the current SQLite plugin doesn't work on OS X. Either solve that, or install MySQL, which requires no compiling and is relatively easy to set up:
** From http://downloads.mysql.com/archives.php?p=mysql-5.1&v=5.1.40, download MySQL 5.1.40 for 10.5 PowerPC (installer, not 64-bit)
** Run the installer. (which installs to /usr/local)
** Install MySQL.prefPane into System Preferences by double-clicking it.
** Open the pref pane and start MySQL.
** (Optional:) For unattended startup, install MySQLStartupItem (doesn't always work for me).
** (Recommended:) In Terminal, do the one-time setup of MySQL with this command: mysql_secure_installation
** In MySQL, create the opensim user per the comments in OpenSim.ini. Give it all the create privileges.
*** Since this is a Mac, you could use Sequel Pro (donationware) to do that in a nice GUI. Standard connection, host: 127.0.0.1 (if on the same Mac)
* You're ready to run OpenSimulator. In that new Terminal window, cd to your OpenSim-source/bin folder.
mono OpenSim.exe
* If all is well, you will be prompted "New region name []: "
* Turn to "Running OpenSimulator for the first time" on wiki page [[Configuration]]
* When fully up and running, the prompt is "Region (<region-name>) #"

== Linux ==

=== Ubuntu ===

For Ubuntu users on older distributions (7.10, 8.04, 9.10 etc.) '''you need''' to upgrade your version of mono to at least 2.4.3 for OpenSimulator 0.7.6 and 2.10.8 for the next OpenSimulator release. We recommend updating to at least Mono 2.10.8 in any case for performance reasons. For anyone who needs to upgrade their Mono, see [[Update Mono on Ubuntu]].

Ubuntu Karmic (9.10) includes mono 2.4.2.3 packages.

Ubuntu Lucid (10.04) includes mono 2.4.4 packages.

Ubuntu Maverick (10.10) includes mono 2.6.7 packages.

Ubuntu Natty (11.04) includes mono 2.6.7 packages.

Ubuntu Oneirc (11.10) to Salamander (13.10) include the mono 2.10.8.1 packages.

==== Ubuntu 10.04 and later ====

In this version, one only needs to install mono-complete - this will pull down all the other required packages as dependencies. Thus, to build:

sudo apt-get install mono-complete
# [[Download]] opensim
cd opensim
./runprebuild.sh
xbuild

As of mono 2.6 series, xbuild works well enough to drive a complete build of OpenSimulator. Since xbuild is included within the '''mono-complete''' package on Ubuntu, you don't have to install any additional packages if you don't have any particular reason to prefer nant over xbuild. They are just two different build systems that invoke the same C# compiler based on two different build script formats.

If you do want to build using nant, then you will need to install the '''nant''' apt-get package and execute

nant

instead of

xbuild

after ./runprebuild.sh

'''OPTIONAL (for developers):''' To run the regression test suite, you will also need to install nunit-console, like so

sudo apt-get install nunit-console
nant test

{{anchor|CentOS}}{{anchor|RedHat}}{{anchor|RHEL}}{{anchor|Fedora}}

=== Debian ===

Debian 4 (Etch) is no longer supported by debian.org. Update at least to 5 (Lenny) before running OpenSimulator. See [http://www.debian.org/releases/lenny/i386/release-notes/ch-upgrading.html Upgrades from previous release@debian.org] for detail.

For Debian 5 (Lenny) or later, just type:
<pre>
sudo aptitude install nant
</pre>
before run runprebuild.sh and nant. You can even use apt-get instead of aptitude. They both will also install dependent packages.

Tested on Debian 5 "Lenny" ''oldstable'', Debian 6 "Squeeze" ''stable'' and Debian 7 "Wheezy" ''testing''.

=== Fedora ===

After getting run your OpenSimulator binary distributions, you'll need to get mono development library and install nant to build OpenSimulator from the source. See both sections below.

==== Getting Mono Libraries ====

If you have installed mono packages from the core repository for your distributions [[Dependencies#RedHat|when you run OpenSim.exe binary distribusion]], just type:
<pre>
sudo yum install mono-devel
</pre>

If not, just type (given that [[Dependencies#Installing from Mono Repository|you have already set up yum repository for mono]]) :
<pre>
sudo yum install mono-addon-devel
</pre>

Both command will install its dependencies as well.

==== Installing NAnt ====

Run "yum info nant" to check the version of nant package. If you find the package, then just type:
<pre>
sudo yum install nant
</pre>
You can now run nant out-of-the-box.

If you can't find nant package in yum repository, or you feel its version is too early for building OpenSimulator, obtain NAnt from [http://nant.sourceforge.net/ NAnt Project Site]. See User Manual there for detailed instruction. As of 0.90, you will need to create startup script like that (given you have expanded NAnt to /usr/local/nant) :
<pre>
sudo vi /usr/bin/nant
</pre>
Then inside this file :
<pre>
#!/bin/sh
exec mono /usr/local/nant/bin/NAnt.exe "$@"
</pre>
After that, make it executable :
<pre>
sudo chmod +x /usr/bin/nant
</pre>

You can now run runprebuild.sh and nant to compile OpenSimulator.

=== CentOS, Redhat ===

==== Install EPEL Repo ====

<pre>
wget http://dl.fedoraproject.org/pub/epel/6/x86_64/epel-release-6-8.noarch.rpm
rpm -Uvh epel-release-6-8.noarch.rpm
</pre>

==== Pre-required Package for Mono and GID+ ====

<pre>
yum install bison gettext glib2 freetype fontconfig libpng libpng-devel libX11 \
libX11-devel glib2-devel libgdi* libexif glibc-devel urw-fonts \
unzip gcc gcc-c++ automake autoconf \
libtool make bzip2 wget pixman-devel \
fontconfig-devel freetype-devel libexif-devel \
libjpeg-devel libtiff-devel giflib-devel
</pre>

==== Mono compilation ====

ps: -j 2 equal number of processor (or core)

<pre>
cd /usr/local/src
wget http://download.mono-project.com/sources/mono/mono-3.0.4.tar.bz2
tar -jxvf mono-3.0.4.tar.bz2
cd mono-3.0.4
./configure --libdir=/usr/lib64
make -j 2
make install
</pre>

==== Install GID+ ====
ps: -j 2 equal number of processor (or core)

<pre>
cd /usr/local/src
wget http://download.mono-project.com/sources/libgdiplus/libgdiplus-2.10.9.tar.bz2
tar -xvjf libgdiplus-2.10.9.tar.bz2
cd libgdiplus-2.10.9
./configure
make -j2
make install
</pre>

=== openSUSE ===

Just type:
<pre>
sudo zypper install nant
</pre>
before run runprebuild.sh and nant. It will also install dependent packages.

== FreeBSD ==

FreeBSD is not currently a supported platform for OpenSimulator. However, it is possible to get OpenSimulator running on FreeBSD.

On FreeBSD 6.2 and later

su
cd /usr/ports/devel/subversion/ && make install clean (you may also need to rebuild apr-svn if this step fails)
cd /usr/ports/lang/mono/ && make install clean
cd /usr/ports/devel/nant/ && make install clean
cd /usr/ports/databases/sqlite3/ && make install clean
cd /usr/ports/x11-toolkits/libgdiplus/ && make install clean
cd /opensim/installation/directory/
[[Download]] opensim
cd opensim
./runprebuild.sh
nant

If you get "System.DllNotFoundException: libopenjpeg" errors, follow one of these fixes (depending of the lib appearing in the error message):
* [[Troubleshooting#System.DllNotFoundException:_lib32.2Flibopenjpeg-dotnet-2.1.3.0-dotnet-1-i686|libopenjpeg-mono]]
* [[Troubleshooting#System.DllNotFoundException:_..2Flibopenjpeg-libsl-2.1.2.0.so|libopenjpeg-libsl]]

For ODE Physics you must do the following:
cd /usr/ports/graphics/libGL/ && make install clean
cd /usr/ports/graphics/libGLU/ && make install clean
cd /opensim/installation/directory/
git clone git://opensimulator.org/git/opensim-libs
cd opensim-libs/trunk/unmanaged/OpenDynamicsEngine-r1755
sh autogen.sh
./configure --enable-shared --enable-release --disable-demos --without-x --enable-old-trimesh
make
cp ./ode/src/.libs/libode.so /opensim/installation/directory/opensim/bin/libode.so (32 bit)
cp ./ode/src/.libs/libode.so /opensim/installation/directory/opensim/bin/libode-x86_64.so (64 bit)

= Configuration =

See [[Configuration]].

[[Category:Users]]
[[Category:Users]]
[[Category:Getting Started]]