aboutsummaryrefslogtreecommitdiffstatshomepage
path: root/doc
diff options
context:
space:
mode:
authoronefang2019-09-11 16:36:50 +1000
committeronefang2019-09-11 16:36:50 +1000
commit50cd1ffd32f69228e566f2b0b89f86ea0d9fe489 (patch)
tree52f2ab0c04f1a5d7d6ac5dc872981b4b156447e7 /doc
parentRenamed branch to SledjChisl. (diff)
parentBump to release flavour, build 0. (diff)
downloadopensim-SC-50cd1ffd32f69228e566f2b0b89f86ea0d9fe489.zip
opensim-SC-50cd1ffd32f69228e566f2b0b89f86ea0d9fe489.tar.gz
opensim-SC-50cd1ffd32f69228e566f2b0b89f86ea0d9fe489.tar.bz2
opensim-SC-50cd1ffd32f69228e566f2b0b89f86ea0d9fe489.tar.xz
Merge branch 'SledjChisl'
Diffstat (limited to '')
-rw-r--r--coderDocs/doxygen.conf (renamed from doc/doxygen.conf)0
-rw-r--r--doc/OpenSim_README.md (renamed from README_OpenSim.txt)10
-rw-r--r--doc/README20
-rw-r--r--doc/configuration.html136
-rw-r--r--doc/index.html101
-rw-r--r--doc/scripts.html121
-rw-r--r--doc/web_pages.html44
7 files changed, 410 insertions, 22 deletions
diff --git a/doc/doxygen.conf b/coderDocs/doxygen.conf
index 148de9c..148de9c 100644
--- a/doc/doxygen.conf
+++ b/coderDocs/doxygen.conf
diff --git a/README_OpenSim.txt b/doc/OpenSim_README.md
index 2aea328..59b7553 100644
--- a/README_OpenSim.txt
+++ b/doc/OpenSim_README.md
@@ -1,3 +1,11 @@
1# OpenSim-SC
2
3OpenSim-SC is a fork of OpenSim. See the index.html file for details.
4The rest of this file is the OpenSim README.md, some of which may be out
5of date.
6
7
8
1Welcome to OpenSim! 9Welcome to OpenSim!
2 10
3# Overview 11# Overview
@@ -112,5 +120,3 @@ OpenSim, as well as how to report bugs, and participate in the OpenSim
112project can always be found at http://opensimulator.org. 120project can always be found at http://opensimulator.org.
113 121
114Thanks for trying OpenSim, we hope it is a pleasant experience. 122Thanks for trying OpenSim, we hope it is a pleasant experience.
115
116
diff --git a/doc/README b/doc/README
deleted file mode 100644
index 9c95557..0000000
--- a/doc/README
+++ /dev/null
@@ -1,20 +0,0 @@
1README
2
3This directory does not currently contain any OpenSimulator user level documentation. Such
4documentation can be found at
5
6http://opensimulator.org
7
8instead.
9
10Rather, this directory can contain source-code documentation as generated via the doxygen package.
11
12To do this, either execute
13
14doxygen doxygen.conf
15
16on the command line or run the target
17
18nant doxygen
19
20if you have nant installed.
diff --git a/doc/configuration.html b/doc/configuration.html
new file mode 100644
index 0000000..0f42529
--- /dev/null
+++ b/doc/configuration.html
@@ -0,0 +1,136 @@
1<html>
2<title>opensim-SC configuration documentation</title>
3<head>
4</head>
5<body bgcolor="black" text="white" alink="red" link="blue" vlink="purple">
6
7<p>opensim-SC uses the same configurations as <a
8href="http://opensimulator.org/wiki/Main_Page">OpenSim</a>, with some
9small changes, so please refer to their <a
10href="http://opensimulator.org/wiki/Configuration">documentation</a>.
11Only the differences will be detailed here.</p>
12
13<p>OpenSim ships with some pre-compiled executables and libraries, plus
14other files in it's own bin/ directory, and wants to write the rest of
15it's files there as well. Some existing configuration options let you
16move some of those writable areas out of the tree, but not all.
17opensim-SC tries to move all writable stuff and configuration out of
18tree, to make updates easier. InstallItAll.sh builds this structure in
19/opt/opensim_SC, and copies itself to /opt/opensim_SC/opensim-SC.</p>
20
21<p>The two main configuration files are
22/opt/opensim_SC/opensim-SC/bin/Robust.ini and
23/opt/opensim_SC/opensim-SC/bin/OpenSimDefaults.ini. You should not modify
24those. They include files from
25/opt/opensim_SC/opensim-SC/bin/config-include, which you should also not
26modify. Instead there are various directories and config files in
27/opt/opensim_SC/config where you can over ride the configuration options
28you want to change.</p>
29
30<h1>/opt/opensim_SC/config/config.ini</h1>
31
32<p>This will start as a copy of one of the
33/opt/opensim_SC/opensim-SC/bin/config-include/config_*.ini files. Copy
34config_localhost.ini if you want to run your own grid, or one of the
35others if you want to connect to IG or MG. It is used by both ROBUST and
36by sims. It must be NOT world readable, as it contains your database
37login details.</p>
38
39<p>By default this file includes two sections. [Paths] and [Const], but
40you can add more sections in this file if you need to override those
41sections from the configuration files in the bin/ directory.</p>
42
43<p>[Paths] is the paths to the various movable directories, relative to
44the /opt/opensim_SC/opensim-SC/bin/ directory.
45
46<ul>
47<li>AssetsPath - where your assets are stored.</li>
48<li>BackupPath - where IAR and OAR backup files are created.</li>
49<li>CachePath - the directory that holds various caches.</li>
50<li>ConfigPath - this /opt/opensim_SC/config/ directory that we are describing.</li>
51<li>DbPath - a directory with some small statistics databases.</li>
52<li>LogPath - where the logs and console history are kept.</li>
53<li>WebPath - where the various web pages are served from.</li>
54</ul>
55
56<p>[Const] is various constants used in the rest of the configuration
57files, so you can define these here once.</p>
58
59<ul>
60<li>MOTD - the message that is shown to people when they log on.</li>
61<li>GridName - the name of the grid.</li>
62<li>ShortGridName - the short name of the grid, usually the initials of GridName.</li>
63<li>BaseHostName - a HTTP URL that is used as the base of all other URLs.</li>
64<li>HostName - the domain name of your grid.</li>
65<li>BaseURL - built from BaseHostName usually.</li>
66<li>GridURL - built from BaseHostName usually.</li>
67<li>SSLURL - built from HostName usually.</li>
68<li>PublicPort - public port used by ROBUST services.</li>
69<li>PrivatePort - private port used by ROBUST services.</li>
70<li>PublicSSLPort - public port used by ROBUST services in SSL mode.</li>
71<li>AssetServerPort - public port used by the ROBUST asset service.</li>
72<li>DataProvider - used to select between the various SQL backends, though opensim-SC only supports MariaDB / MySQL.</li>
73<li>ConnectionString - the details of how to connect to your SQL backend. This contains credentials that need to be protected from others reading them.</li>
74</ul>
75
76<p>NOTE - though SSL is mentioned above, SSL is not well supported in
77OpenSims own web server. They wrote their own, the SSL parts are not
78well tested, being rarely used. Probably best to not use SSL now. In
79the next major version of opensim-SC I intend to use an external web
80server, and shift things over to it. Lighttpd is the likely choice.</p>
81
82<h1>/opt/opensim_SC/config/ROBUST/RobustExtra.ini</h1>
83
84<p>This is where you would override ROBUST specific configuration options. By default it will be empty.</p>
85
86<h1>/opt/opensim_SC/config/simXX/ThisSim.ini</h1>
87
88<p>For each sim you need to specify certain options, and you can override
89others. /opt/opensim_SC/config/sim_skeleton/ThisSim.ini is a template
90used by the create_sim script to create this file. Newer versions of
91create_sim might give this file the name of the sim, My_New_Sim.ini.</p>
92
93<p>The "SIM_*" bits get replaced with actual information for each sim.
94It has it's own [Const] section, which only contains mysim, the number of
95this sim. The [Startup] section defines various file locations. The
96[Network] section defines the public port for this sim.</p>
97
98<p>OpenSim had the [Region] section in different files, in two
99different formats, instead opensim-SC includes that info here so it's all
100in one place per sim. RegionName is the name of your sim, the rest are
101described in OpenSims <a
102href="http://opensimulator.org/wiki/Configuring_Regions">Configuring
103Regions</a> page.</p>
104
105<p>The [Performance] section is new to opensim-SC. It includes one of the
106/opt/opensim_SC/opensim-SC/bin/config-include/Sim*.ini files that give
107you a choice of performance trade offs.</p>
108
109<h1>New options.</h1>
110
111<p>There have been some additional options added to support new features. Some have been mentioned above.</p>
112
113<ul>
114 <li>[AuthorizationService]</li>
115 <ul>
116 <li>DefaultRegionAccess - Set the default access restriction for any sim not otherwise mentioned in this section.</li>
117 </ul>
118 <li>[Groups]</li>
119 <ul>
120 <li>AddDefaultGroup - automatically add any members of your grid to this | separated list of groups.</li>
121 <li>AddHGDefaultGroup_othergrid.com - same as above, but for hypergrid visitors from a specific grid.</li>
122 </ul>
123 <li>[GodNames]</li>
124 <ul>
125 <li>FirstNames - similar to the other GodNames options, but this is a list of first names that designate gods for viewers. Note that viewers may not support this.</li>
126 </ul>
127</ul>
128
129<h1>Removed options.</h1>
130
131<p>Some options have been removed. Mostly limitations, or useless cruft.
132You wont miss them. In one instance a viewer bug that had been fixed a
133decade ago, was still being forbidden in OpenSim.</p>
134
135</body>
136</html>
diff --git a/doc/index.html b/doc/index.html
new file mode 100644
index 0000000..ad4352d
--- /dev/null
+++ b/doc/index.html
@@ -0,0 +1,101 @@
1<html>
2<title>opensim-SC documenation</title>
3<head>
4</head>
5<body bgcolor="black" text="white" alink="red" link="blue" vlink="purple">
6<h1>What is opensim-SC?</h1>
7
8<p>opensim-SC is a fork of <a
9href="http://opensimulator.org/wiki/Main_Page">OpenSim</a>, and OpenSim
10is a clean room fork of <a
11href="http://wiki.secondlife.com/wiki/Main_Page">Second Life</a>. They
12are all 3D virtual worlds that are open, users can create their own
13content, these are not games. Second Life is a proprietary server, with
14open source viewer. OpenSim is an open source server that works with
15Second Life viewers.</p>
16
17<p>The SC in opensim-SC stands for SledjChisl, part of the <a href="https://sledjhamr.org/git/docs/index.html">SledjHamr</a> project.</p>
18
19<p>&nbsp;</p>
20
21<h1>What is SledjHamr?</h1>
22
23<p>opensim-SC is part of the SledjHamr project. SledjHamr will be a
24rewrite from scratch of Second Life (SL) / OpenSim (OS) style 3D online
25virtual world client / server. The plan is to use OS server and SL
26clients as crutches, when a bit of SledjHamr is ready, it replaces the
27matching bit in OS/SL.</p>
28
29<h2>SledjHamr - tearing down the garden walls.</h2>
30
31<p>&nbsp;</p>
32<h1>What is SledjChisl?</h1>
33
34<p>While OpenSim is slowly morphing into SledjHamr, it needed a name, so
35I called it SledjChisl. The main differences between opensim-SC and
36OpenSim are listed in <a
37href="../Differences.txt">Differences.txt</a></p>
38
39<h2>SledjChisl - chipping away at OpenSim until it's all gone, and is now SledjHamr.</h2>
40
41<p>&nbsp;</p>
42<h1>Enough of the bad puns, what is it all about?</h1>
43
44<p>It's a 3D open online shared virtual world that is user created. Using a
45specialised bit of software called a viewer you log onto one of these
46worlds, either Second Life, or one of the many OpenSim based worlds. You
47then get to wander around a 3D world that the other users have built,
48and do many things. Including building your own bit of the world using
49the viewer itself.</p>
50
51<h3>It's not a game.</h3>
52
53<p>Many people think of it as a game, but it's missing many of the features
54of a real game, and tends to be more about the social side of things.
55I've even had someone tell me that everything online is a game, even
56pointing out that their bank account is online didn't help. There is no
57goal, no game play, no levelling up, no one keeps score. You do what you
58want in these worlds (within the limits of the local rules), and that
59might include playing games that people have created in the world, but
60you don't have to.</p>
61
62<p>People even do business in them.</p>
63
64
65<h1>What do I do with opensim-SC?</h1>
66
67<p>The easiest thing to do is to just join a world that is running
68opensim-SC, but you don't need this software for doing that. This
69software is for running such a world, or part of it.</p>
70
71<p>Virtual world software is complex software, coz you are simulating an
72entire world. There's lots of things to take care of. While SledjHamr
73aims to make things as simple as possible for ordinary folk, we ain't
74there yet. opensim-SC is slightly easier to setup than OpenSim, so
75progress has been made. opensim-SC tries to remain compatible, so for
76more details, refer to the <a
77href="http://opensimulator.org/wiki/Main_Page">OpenSim</a> and <a
78href="http://wiki.secondlife.com/wiki/Main_Page">Second Life</a>
79documentation.</p>
80
81<p>You'll need to be familiar with command lines. Currently opensim-SC uses
82Linux shell scripts, though that'll change in the next release to be more
83portable to other operating systems. The shell scripts are for setup and
84basic management, the virtual world software itself is written in
85portable C# that runs on .NET and MONO.</p>
86
87<p>The scripts install and manage everything based on a Debian variation
88of Linux, it's been tested under Debian, Devuan, and Ubuntu. Refer to
89INSTALL.md for installation details.</p>
90
91<p>The <a href="scripts.html">scripts are documented here</a>.</p>
92
93<p>The <a href="configuration.html">new configuration setup and options are documented here</a>.</p>
94
95<p>The <a href="web_pages.html">example web pages are documented here</a>.</p>
96
97<p>&nbsp;</p>
98<p>&nbsp;</p>
99<p>&nbsp;</p>
100</body>
101</html>
diff --git a/doc/scripts.html b/doc/scripts.html
new file mode 100644
index 0000000..8551a79
--- /dev/null
+++ b/doc/scripts.html
@@ -0,0 +1,121 @@
1<html>
2<title>opensim-SC scripts documentation</title>
3<head>
4</head>
5<body bgcolor="black" text="white" alink="red" link="blue" vlink="purple">
6<p>There are various scripts included, mostly Bash shell scripts.</p>
7
8<h1>opensim-SC/BuildIt.sh</h1>
9<p>This script will compile, or recompile the entire system.</p>
10
11<h1>opensim-SC/InstallItAll.sh</h1>
12
13<p>Installs everything on a Debian like operating system. You will need
14to know your root/sudo password and your MariaDB root password, though if
15MariaDB isn't installed, it will be installed. Note that some recent
16versions of MariaDB want to be passwordless for root.</p>
17
18<h1>opensim-SC/TestIt.sh</h1>
19<p>Runs unit tests on opensim-SC.</p>
20<h1>opensim-SC/nant-color</h1>
21<p>Obsolete since Debian removed nant, but used to be part of the build system.</p>
22<h1>opensim-SC/runprebuild.bat and opensim-SC/runprebuild.sh</h1>
23<p>Parts of the build system.</p>
24<h1>opensim-SC/example/start.sh</h1>
25<p>An example script that runs a specific sim.</p>
26<h1>opensim-SC/scripts/backup-grid.sh</h1>
27<p>Backup the entire grid into gitAR archive files, which are like IAR and OAR files, only with git info in them, and compressed better.</p>
28<h1>opensim-SC/scripts/backup-inventories.sh</h1>
29<p>Backup inventories of anyone that has logged on in since the last time this was run.</p>
30<h1>opensim-SC/scripts/backup-inventory</h1>
31<p>Backup a single accounts inventory. It's a symlink to start-sim, which figures out what to do based on the name it is called as.</p>
32<h1>opensim-SC/scripts/backup-sims.sh</h1>
33<p>Backup all currently running sims.</p>
34<h1>opensim-SC/scripts/common.sh</h1>
35<p>Common data and functions for the other scripts.</p>
36<h1>opensim-SC/scripts/fix_some_assets.pl</h1>
37<p>An old script to fix some problems caused by a bug in OpenSim. Not sure it's needed anymore, or even if it'll work. Probably best to not use it.</p>
38<h1>opensim-SC/scripts/gitAR.sh</h1>
39<p>Script for dealing with gitARs, though not meant to be used by users.</p>
40<h1>opensim-SC/scripts/show-console</h1>
41<p>Show the tmux consoles.</p>
42
43<h1>opensim-SC/scripts/start-sim</h1>
44
45<p>Start / stop sims, backup inventories / sims. This script does
46different things depending on where it is called from, and the name it is
47called as. It has afew options you can pass to it on the command line.</p>
48
49<ul>
50<li>-a - Used internally as part of the "start up everything" mentioned below.</li>
51<li>-d X - Define a delay to wait between sims when starting up everything, the default is 60 seconds.</li>
52<li>-q - Don't show the tmux console os start up.</li>
53<li>-w - Wait until the "INITIALIZATION COMPLETE FOR " line shows in the console before continuing.</li>
54</ul>
55
56<h2>Called as backup-inventory</h2>
57<p>Backs up the inventory of the user specified in the arguments to an .iar file and updates the _gitIAR.tar.xz file.</p>
58
59<pre>&nbsp; &nbsp;./backup-inventory Avatar Name</pre>
60
61<h2>Called as backup-sim from config/simXX</h2>
62<p>Backs up the sim to an .oar and updates the _gitOAR.tar.xz file.</p>
63
64<h2>Called as start-sim from config/ROBUST</h2>
65<p>Starts up ROBUST if it is called from the config directory holding the ROBUST configuration.</p>
66
67<h2>Called as start-sim from config/simXX</h2>
68<p>Starts up the sim if it is called from the config directory holding the sim configuration.</p>
69
70<h2>Called as start-sim from opensim-SC/scripts</h2>
71<p>Will start up everything.</p>
72
73<h2>Called as start-sim from opensim-SC/bin</h2>
74<p>Used internally by the "start up everything" process to start up the sims. It assumes that ROBUST was recently started.</p>
75
76<h2>Called as stop-sim from config/ROBUST</h2>
77<p>Stops ROBUST if it is called from the config director holding the ROBUST configuration.</p>
78
79<h2>Called as stop-sim from config/simXX</h2>
80<p>Stops the sim if it is called from the config director holding the sim
81configuration. It gives users on the sim a couple of warnings, waits a
82while, then shuts down the sim.</p>
83
84<h1>opensim-SC/scripts/install/create_sim.sh</h1>
85<p>Create a sim. Ther are several optional arguments. If an argument is missing or blank, a default is used.</p>
86
87<ul>
88<li>"sim name" - The name of the sime you want, the default is "No name sim XXX" where XXX is a random number.</li>
89<li>1234,1234 - The map location of the sim, the default is some random location.</li>
90<li>256 - The size of the sim, the default is 256 x 256 meters.</li>
91</ul>
92
93<pre>&nbsp; &nbsp;./create_sim "My Dobule Sized Sim", 1234,1234 512</pre>
94
95<h1>opensim-SC/scripts/install/go_live.sh</h1>
96
97<p>Installs the monit config files. Note that a recent version of Monit
98seems to have issue with this, that I haven't tracked down yet. Monit
99isn't needed most of the time, and I want to replace it with something
100internal in the next major release.</p>
101
102<h1>opensim-SC/scripts/install/group_migrate.sql</h1>
103<p>An obsolete SQL script for migrating to OS groups.</p>
104<h1>opensim-SC/scripts/install/opensim-monit.conf</h1>
105<p>The template monit config file.</p>
106
107<h1>opensim-SC/scripts/install/opensim.tmux.conf</h1>
108
109<p>The tmux config file. Note that tmux has a tendency to change how
110their config files work from one version to the next. It would be wise
111to test this before trying to use it.</p>
112
113<h1>opensim-SC/scripts/install/secure.sh</h1>
114
115<p>Script to properly set ownership and permissions for files and
116directories in opensim-SC. Once you have a lot of assets, this wil take
117along time. It is called from InstallItAll.sh</p>
118
119<p>&nbsp;</p>
120</body>
121</html>
diff --git a/doc/web_pages.html b/doc/web_pages.html
new file mode 100644
index 0000000..6a76b00
--- /dev/null
+++ b/doc/web_pages.html
@@ -0,0 +1,44 @@
1<html>
2<title>opensim-SC web pages documentation</title>
3<head>
4</head>
5<body bgcolor="black" text="white" alink="red" link="blue" vlink="purple">
6
7<p>In the examples/web directory there are several example web pages. In
8the default configuration, these web pages are presented to viewers as
9the various web pages that the viewer can display, as might be listed in
10the viewers grid manager. They will be available at
11http://example.com:8002/web/, or what ever you configured BaseHostname
12and PublicPort to be.</p>
13
14<p>These web pages are just basic, you can customise them to suit your
15grid. There are also a few PNG images that you can replace.</p>
16
17<h1>about.html</h1>
18<p>The web page grid managers will show as "web site". I don't think any viewers actually show or link to this.</p>
19<h1>help.html</h1>
20<p>The web page grid managers will show as "support URL". I don't think any viewers actually show or link to this.</p>
21<h1>loginpage.html</h1>
22<p>This is the web page shown in viewers when they pick your grid to log onto.</p>
23<h1>password_help.html</h1>
24<p>Viewers will often include this link, usually on the lower right, for helping with passwords.</p>
25<h1>register.html</h1>
26<p>Viewers will often include this link, usually on the lower right, for registering new accounts.</p>
27<h1>stats.html</h1>
28<p>This is basic stats for your grid, not for viewers. You could register this with stats collection web sites.</p>
29<p>&nbsp;</p>
30<h1>SledjHamr.png</h1>
31<p>The background image used in loginpage.html</p>
32<h1>SledjHamrIcon.png</h1>
33<p>A medium sized icon.</p>
34<h1>SledjHamrIconSmall.png</h1>
35<p>A small icon suitable for the web sites favicon.</p>
36<p>&nbsp;</p>
37<h1>Variables.</h1>
38<p>In each of these pages you can insert variables that will get replaced with current data using -</p>
39<pre>
40&lt;!--#echo var="variable_name" --&gt;
41</pre>
42<p>The stats.html file should contain examples and descritpions of all of these variables.</p>
43</body>
44</html>
generated by cgit v1.1 at 2025-04-18 19:26:27 +0000