1 files changed, 76 insertions, 112 deletions
diff --git a/README.md b/README.md
index 12cba74..2aea328 100644
--- a/README.md
+++ b/README.md
@@ -1,152 +1,116 @@
-Use this to create a sim that links into Infinite Grid from Linux.
+Welcome to OpenSim!
-It's only been tested on Ubuntu 10.04, 11.04, 12.04, 16.04' as well as
+# Overview
-Debian 8, YMMV.  This is also a WIP, use it at your own risk.  It's been
-used to set up a few freshly installed Ubuntu servers though.
-The directory layout.
+OpenSim is a BSD Licensed Open Source project to develop a functioning
---------------------
+virtual worlds server platform capable of supporting multiple clients
+and servers in a heterogeneous grid structure. OpenSim is written in
+C#, and can run under Mono or the Microsoft .NET runtimes.
-The various directories are -
+This is considered an alpha release.  Some stuff works, a lot doesn't.
+If it breaks, you get to keep *both* pieces.
-.git            Used by git for it's internal accounting, and the older versions.
+# Compiling OpenSim
-.nant           Used by the nant build tool.
+Please see BUILDING.md if you downloaded a source distribution and 
+need to build OpenSim before running it.
-OpenSim         OpenSim source code.
+# Running OpenSim on Windows
-Prebuild        Used by the build system.
+You will need .NET 4.0 installed to run OpenSimulator.
-ThirdParty      For third party OpenSim modules.
+We recommend that you run OpenSim from a command prompt on Windows in order
+to capture any errors.
-addon-modules   Also for third party modules.  Don't ask me why there's two.
+To run OpenSim from a command prompt
-bin             The OpenSim binaries, and other files.
+ * cd to the bin/ directory where you unpacked OpenSim
+ * run OpenSim.exe
-doc             Supposedly for documentation, which I wish OpenSim devs would write some.
+Now see the "Configuring OpenSim" section
-scripts         Various Linux scripts for managing OpenSim.
+# Running OpenSim on Linux
-share           No idea really.
+You will need Mono >= 2.10.8.1 to run OpenSimulator.  On some Linux distributions you
+may need to install additional packages.  See http://opensimulator.org/wiki/Dependencies
+for more information.
-Also, the installation script moves the following directories to outside
+To run OpenSim, from the unpacked distribution type:
-of this main directory, they are all used for writing various things. 
-Makes it easy to upgrade, and separates them from actual executable
-stuff.
-AssetFiles      Stores assets if running in grid mode.
+ * cd bin
+ * mono OpenSim.exe
-backups         All sim and inventory backups are stored here.
+Now see the "Configuring OpenSim" section
-caches          Various cached things.
+# Configuring OpenSim
-config          All your configurtion files.
+When OpenSim starts for the first time, you will be prompted with a
+series of questions that look something like:
-db              If you are not using MySQL, your data lives here.
+        [09-17 03:54:40] DEFAULT REGION CONFIG: Simulator Name [OpenSim Test]:
-logs            Log files get stored here.
+For all the options except simulator name, you can safely hit enter to accept
+the default if you want to connect using a client on the same machine or over
+your local network.
+You will then be asked "Do you wish to join an existing estate?".  If you're
+starting OpenSim for the first time then answer no (which is the default) and
+provide an estate name.
-Follow these steps.
+Shortly afterwards, you will then be asked to enter an estate owner first name,
-------------------
+last name, password and e-mail (which can be left blank).  Do not forget these
+details, since initially only this account will be able to manage your region
+in-world.  You can also use these details to perform your first login.
-Go to -
+Once you are presented with a prompt that looks like:
-https://www.infinitegrid.org/drupal/content/How_to_link_your_OpenSim_region_to_Infinite_Grid_LinuxMySQL
+        Region (My region name) #
-and follow the directions to create an admin user account.  You can skip
+You have successfully started OpenSim.
-that bit if you already have a suitable user with sudo access.
-Note that these scripts pretty much follow that above wiki description,
+If you want to create another user account to login rather than the estate
-with some exceptions.  The configuration information per sim has been
+account, then type "create user" on the OpenSim console and follow the prompts.
-rearranged so that there is only ONE copy of the OpenSim installation.
-Next you need to figure out what password you want to use for OpenSims
+Helpful resources:
-access to the database.  We will call this "DatabasePassword".  Run the
+ * http://opensimulator.org/wiki/Configuration
-following script, from inside the OpenSim directory -
+ * http://opensimulator.org/wiki/Configuring_Regions
-./InstallItAll.sh DatabasePassword
+# Connecting to your OpenSim
-This will do most of the work for you, except for creating sims.  There
+By default your sim will be available for login on port 9000.  You can login by
-is a final step that needs to be done manually for now.  Edit
+adding -loginuri http://127.0.0.1:9000 to the command that starts Second Life
-/etc/rc.local, make sure it has the following line in it somewhere,
+(e.g. in the Target: box of the client icon properties on Windows).  You can
-probably at the end -
+also login using the network IP address of the machine running OpenSim (e.g.
+http://192.168.1.2:9000)
-/opt/opensim/current/scripts/fix_var_run.sh
+To login, use the avatar details that you gave for your estate ownership or the
+one you set up using the "create user" command.
+# Bug reports
-Creating sims.
+In the very likely event of bugs biting you (err, your OpenSim) we
--------------
+encourage you to see whether the problem has already been reported on
+the [OpenSim mantis system](http://opensimulator.org/mantis/main_page.php).
-A separate script is here for sim creation, you can use it to create many
+If your bug has already been reported, you might want to add to the
-sims.  You will need -
+bug description and supply additional information.
-Your host name, or it could be your IP, we will use "sims.example.net".
+If your bug has not been reported yet, file a bug report ("opening a
+mantis"). Useful information to include:
+ * description of what went wrong
+ * stack trace
+ * OpenSim.log (attach as file)
+ * OpenSim.ini (attach as file)
+ * if running under mono: run OpenSim.exe with the "--debug" flag:
-A name for your sim, we will use "My new sim".  It should be unique on
+       mono --debug OpenSim.exe
-the grid.
-A location for your sim, we will use "1234,5678".  You can use the
+# More Information on OpenSim
-Infinite Grid web based map to poke around and find a good location. 
-Choose an empty spot.
-Once you have all that information sorted out, run this script from the
+More extensive information on building, running, and configuring
-installed scripts directory -
+OpenSim, as well as how to report bugs, and participate in the OpenSim
+project can always be found at http://opensimulator.org.
-./create_sim.sh "My new sim" "1234,5678" "sims.example.net"
+Thanks for trying OpenSim, we hope it is a pleasant experience.
-Or this if you want to override the detected IP address -
-./create_sim.sh "My new sim" "1234,5678" "sims.example.net" "1.2.3.4"
-Also, you can create a varregion with something like -
-./create_sim.sh "My new sim" "1234,5678" "sims.example.net" "1.2.3.4" 512
-Note that the size has to be a multiple of 256, so 512, 768, 1024, etc.
-Running sims.
-------------
-Now you can go to /opt/opensim/config/sim01 and run the following script
-to start it up -
-./start-sim
-You will see the screen console.  You can run the screen console again by
-running that command once more, or running the sim-console command.
-You can stop the sim with -
-./stop-sim
-You can backup the sim with -
-./backup-sim
-Finishing up.
-------------
-Once it's all tested, you can use this to finish things off (back in
-the scripts directory) -
-./go_live.sh
-Which sets up the monit control file/s, though you should double check
-it all, and you still have to do the basic configuration and enabling of
-monit yourself.  This is in case you already have monit set the way you
-like.
-NOTES -
-This attempts to use only one copy of the OS install for all sims.  We
-are running one instance of OS for each sim though, as this prevents one
-sim crashing from bringing down the others.  OS however really wants to
-write data to directories within it's own bin directory.  I'm not at all
-certian if that data can be shared.  For the same reason, so far I've
-not been able to get to the point where we can make the OS directory
-read only.  This complicates things during upgrades.

diff --git a/README.md b/README.md index 12cba74..2aea328 100644 --- a/README.md +++ b/README.md
@@ -1,152 +1,116 @@
1	Use this to create a sim that links into Infinite Grid from Linux.	1	Welcome to OpenSim!
2		2
3	It's only been tested on Ubuntu 10.04, 11.04, 12.04, 16.04' as well as	3	# Overview
4	Debian 8, YMMV. This is also a WIP, use it at your own risk. It's been
5	used to set up a few freshly installed Ubuntu servers though.
6		4
7	The directory layout.	5	OpenSim is a BSD Licensed Open Source project to develop a functioning
8	---------------------	6	virtual worlds server platform capable of supporting multiple clients
		7	and servers in a heterogeneous grid structure. OpenSim is written in
		8	C#, and can run under Mono or the Microsoft .NET runtimes.
9		9
10	The various directories are -	10	This is considered an alpha release. Some stuff works, a lot doesn't.
		11	If it breaks, you get to keep both pieces.
11		12
12	.git Used by git for it's internal accounting, and the older versions.	13	# Compiling OpenSim
13		14
14	.nant Used by the nant build tool.	15	Please see BUILDING.md if you downloaded a source distribution and
		16	need to build OpenSim before running it.
15		17
16	OpenSim OpenSim source code.	18	# Running OpenSim on Windows
17		19
18	Prebuild Used by the build system.	20	You will need .NET 4.0 installed to run OpenSimulator.
19		21
20	ThirdParty For third party OpenSim modules.	22	We recommend that you run OpenSim from a command prompt on Windows in order
		23	to capture any errors.
21		24
22	addon-modules Also for third party modules. Don't ask me why there's two.	25	To run OpenSim from a command prompt
23		26
24	bin The OpenSim binaries, and other files.	27	* cd to the bin/ directory where you unpacked OpenSim
		28	* run OpenSim.exe
25		29
26	doc Supposedly for documentation, which I wish OpenSim devs would write some.	30	Now see the "Configuring OpenSim" section
27		31
28	scripts Various Linux scripts for managing OpenSim.	32	# Running OpenSim on Linux
29		33
30	share No idea really.	34	You will need Mono >= 2.10.8.1 to run OpenSimulator. On some Linux distributions you
		35	may need to install additional packages. See http://opensimulator.org/wiki/Dependencies
		36	for more information.
31		37
32	Also, the installation script moves the following directories to outside	38	To run OpenSim, from the unpacked distribution type:
33	of this main directory, they are all used for writing various things.
34	Makes it easy to upgrade, and separates them from actual executable
35	stuff.
36		39
37	AssetFiles Stores assets if running in grid mode.	40	* cd bin
		41	* mono OpenSim.exe
38		42
39	backups All sim and inventory backups are stored here.	43	Now see the "Configuring OpenSim" section
40		44
41	caches Various cached things.	45	# Configuring OpenSim
42		46
43	config All your configurtion files.	47	When OpenSim starts for the first time, you will be prompted with a
		48	series of questions that look something like:
44		49
45	db If you are not using MySQL, your data lives here.	50	[09-17 03:54:40] DEFAULT REGION CONFIG: Simulator Name [OpenSim Test]:
46		51
47	logs Log files get stored here.	52	For all the options except simulator name, you can safely hit enter to accept
		53	the default if you want to connect using a client on the same machine or over
		54	your local network.
48		55
		56	You will then be asked "Do you wish to join an existing estate?". If you're
		57	starting OpenSim for the first time then answer no (which is the default) and
		58	provide an estate name.
49		59
50	Follow these steps.	60	Shortly afterwards, you will then be asked to enter an estate owner first name,
51	-------------------	61	last name, password and e-mail (which can be left blank). Do not forget these
		62	details, since initially only this account will be able to manage your region
		63	in-world. You can also use these details to perform your first login.
52		64
53	Go to -	65	Once you are presented with a prompt that looks like:
54		66
55	https://www.infinitegrid.org/drupal/content/How_to_link_your_OpenSim_region_to_Infinite_Grid_LinuxMySQL	67	Region (My region name) #
56		68
57	and follow the directions to create an admin user account. You can skip	69	You have successfully started OpenSim.
58	that bit if you already have a suitable user with sudo access.
59		70
60	Note that these scripts pretty much follow that above wiki description,	71	If you want to create another user account to login rather than the estate
61	with some exceptions. The configuration information per sim has been	72	account, then type "create user" on the OpenSim console and follow the prompts.
62	rearranged so that there is only ONE copy of the OpenSim installation.
63		73
64	Next you need to figure out what password you want to use for OpenSims	74	Helpful resources:
65	access to the database. We will call this "DatabasePassword". Run the	75	* http://opensimulator.org/wiki/Configuration
66	following script, from inside the OpenSim directory -	76	* http://opensimulator.org/wiki/Configuring_Regions
67		77
68	./InstallItAll.sh DatabasePassword	78	# Connecting to your OpenSim
69		79
70	This will do most of the work for you, except for creating sims. There	80	By default your sim will be available for login on port 9000. You can login by
71	is a final step that needs to be done manually for now. Edit	81	adding -loginuri http://127.0.0.1:9000 to the command that starts Second Life
72	/etc/rc.local, make sure it has the following line in it somewhere,	82	(e.g. in the Target: box of the client icon properties on Windows). You can
73	probably at the end -	83	also login using the network IP address of the machine running OpenSim (e.g.
		84	http://192.168.1.2:9000)
74		85
75	/opt/opensim/current/scripts/fix_var_run.sh	86	To login, use the avatar details that you gave for your estate ownership or the
		87	one you set up using the "create user" command.
76		88
		89	# Bug reports
77		90
78	Creating sims.	91	In the very likely event of bugs biting you (err, your OpenSim) we
79	--------------	92	encourage you to see whether the problem has already been reported on
		93	the [OpenSim mantis system](http://opensimulator.org/mantis/main_page.php).
80		94
81	A separate script is here for sim creation, you can use it to create many	95	If your bug has already been reported, you might want to add to the
82	sims. You will need -	96	bug description and supply additional information.
83		97
84	Your host name, or it could be your IP, we will use "sims.example.net".	98	If your bug has not been reported yet, file a bug report ("opening a
		99	mantis"). Useful information to include:
		100	* description of what went wrong
		101	* stack trace
		102	* OpenSim.log (attach as file)
		103	* OpenSim.ini (attach as file)
		104	* if running under mono: run OpenSim.exe with the "--debug" flag:
85		105
86	A name for your sim, we will use "My new sim". It should be unique on	106	mono --debug OpenSim.exe
87	the grid.
88		107
89	A location for your sim, we will use "1234,5678". You can use the	108	# More Information on OpenSim
90	Infinite Grid web based map to poke around and find a good location.
91	Choose an empty spot.
92		109
93	Once you have all that information sorted out, run this script from the	110	More extensive information on building, running, and configuring
94	installed scripts directory -	111	OpenSim, as well as how to report bugs, and participate in the OpenSim
		112	project can always be found at http://opensimulator.org.
95		113
96	./create_sim.sh "My new sim" "1234,5678" "sims.example.net"	114	Thanks for trying OpenSim, we hope it is a pleasant experience.
97		115
98	Or this if you want to override the detected IP address -
99
100	./create_sim.sh "My new sim" "1234,5678" "sims.example.net" "1.2.3.4"
101
102	Also, you can create a varregion with something like -
103
104	./create_sim.sh "My new sim" "1234,5678" "sims.example.net" "1.2.3.4" 512
105
106	Note that the size has to be a multiple of 256, so 512, 768, 1024, etc.
107
108	Running sims.
109	-------------
110
111	Now you can go to /opt/opensim/config/sim01 and run the following script
112	to start it up -
113
114	./start-sim
115
116	You will see the screen console. You can run the screen console again by
117	running that command once more, or running the sim-console command.
118
119	You can stop the sim with -
120
121	./stop-sim
122
123	You can backup the sim with -
124
125	./backup-sim
126
127
128
129	Finishing up.
130	-------------
131
132	Once it's all tested, you can use this to finish things off (back in
133	the scripts directory) -
134
135	./go_live.sh
136
137	Which sets up the monit control file/s, though you should double check
138	it all, and you still have to do the basic configuration and enabling of
139	monit yourself. This is in case you already have monit set the way you
140	like.
141
142
143	NOTES -
144
145	This attempts to use only one copy of the OS install for all sims. We
146	are running one instance of OS for each sim though, as this prevents one
147	sim crashing from bringing down the others. OS however really wants to
148	write data to directories within it's own bin directory. I'm not at all
149	certian if that data can be shared. For the same reason, so far I've
150	not been able to get to the point where we can make the OS directory
151	read only. This complicates things during upgrades.
152		116