diff options
author | David Walter Seikel | 2013-02-23 19:18:44 +1000 |
---|---|---|
committer | David Walter Seikel | 2013-02-23 19:18:44 +1000 |
commit | 958c10d0f13489c2ab3a26b802911df8144528ef (patch) | |
tree | 85692f95b4461eab57fac13a807a7eca074732a6 /addon-modules/OpenSimSearch/README | |
parent | No, we don't need to enshrine viewer bugs in the server, we need to fix the v... (diff) | |
download | opensim-SC_OLD-958c10d0f13489c2ab3a26b802911df8144528ef.zip opensim-SC_OLD-958c10d0f13489c2ab3a26b802911df8144528ef.tar.gz opensim-SC_OLD-958c10d0f13489c2ab3a26b802911df8144528ef.tar.bz2 opensim-SC_OLD-958c10d0f13489c2ab3a26b802911df8144528ef.tar.xz |
Add profile and search modules.
Diffstat (limited to 'addon-modules/OpenSimSearch/README')
-rw-r--r-- | addon-modules/OpenSimSearch/README | 294 |
1 files changed, 294 insertions, 0 deletions
diff --git a/addon-modules/OpenSimSearch/README b/addon-modules/OpenSimSearch/README new file mode 100644 index 0000000..ce826e3 --- /dev/null +++ b/addon-modules/OpenSimSearch/README | |||
@@ -0,0 +1,294 @@ | |||
1 | OpenSimSearch add-on module for Open Simulator | ||
2 | |||
3 | Requirements | ||
4 | |||
5 | The webserver needs PHP support with support for CURL and XMLRPC. | ||
6 | NOTE: Not all webservers may have CURL and XMLRPC support for PHP. | ||
7 | |||
8 | |||
9 | About the files | ||
10 | |||
11 | README - The file you are currently reading | ||
12 | |||
13 | bin/OpenSimSearch.Modules.dll - A pre-compiled module you can use | ||
14 | |||
15 | OpenSimSearch/ - Source code for OpenSim search module | ||
16 | |||
17 | webroot/*.php - Files to install on webserver | ||
18 | |||
19 | webroot/sql/ossearch.sql - This will create the needed database tables | ||
20 | webroot/sql/update-*.sql - Files used to update an older installation | ||
21 | |||
22 | webroot/wiredux/ - Files to add to an installation of wiredux | ||
23 | |||
24 | |||
25 | How it works | ||
26 | |||
27 | If you are looking for a detailed explanation of how the add-on search system | ||
28 | works you should study the contents of the files which accompany this README | ||
29 | file. What follows is a general overview of the search package to give you an | ||
30 | idea of how the pieces fit together in case you have any problems. | ||
31 | |||
32 | There are three main components to OpenSimSearch which are a database, a DLL | ||
33 | file, and several PHP files. | ||
34 | |||
35 | Most of the tables in the search database contain details on items which can | ||
36 | appear in the results of a search. The exception is the hostsregister table. | ||
37 | The hostsregister table contains the list of OpenSim instances which will be | ||
38 | checked periodically for information about searchable items. | ||
39 | |||
40 | When an OpenSim instance starts it accesses the register.php script (using the | ||
41 | URL of the data_services entry in OpenSim.ini) to record the host address and | ||
42 | port of the instance in the hostsregister table of the database. The host and | ||
43 | port entries are used by parser.php to retrieve the data to be indexed from | ||
44 | the running instances. | ||
45 | |||
46 | Take note of the last part of the previous paragraph where it stated that | ||
47 | parser.php is used to index the data from an OpenSim instance and not from a | ||
48 | region. The parser retrieves data from an OpenSim instance. If the instance | ||
49 | is running a single region the data for a single region will be updated. If | ||
50 | the instance is running multiple regions the data for all regions hosted by | ||
51 | that instance will be indexed. | ||
52 | |||
53 | OpenSim instances use the data snapshot module to create an XML based record | ||
54 | of all searchable items in the regions they host. The XML record is retrieved | ||
55 | by parser.php using a URL created from the host, port and the query string | ||
56 | "?method=collector" (eg. http://127.0.0.1:9001/?method=collector). The | ||
57 | parser.php file will get one host/port pair from the hostregister table each | ||
58 | time it is called. It will parse the XML data from the OpenSim instance and | ||
59 | save the data to the various tables of the search database. | ||
60 | |||
61 | The query.php file is the heart of the search process. It receives an XML | ||
62 | message from the DLL based on the search request originating in a viewer. | ||
63 | The XML message is parsed to determine the type of search being performed, | ||
64 | SQL queries are built and executed to retrieve the data from the database | ||
65 | tables, and finally, the results are sent to the DLL file as an XML message | ||
66 | for any final processing before being passed along to the viewer for display. | ||
67 | |||
68 | |||
69 | Before you begin | ||
70 | |||
71 | In the information that follows there are references to settings to be made | ||
72 | in the OpenSim.ini files. As of the release of the 0.7 version of OpenSim | ||
73 | some of the settings may no longer be in the OpenSim.ini file but may be | ||
74 | found in the OpenSimDefault.ini file. If a section of the OpenSim.ini file | ||
75 | mentioned in the information which follows doesn't exist in your copy of | ||
76 | the file, you will either need to add the section and settings to the main | ||
77 | OpenSim.ini file or make the changes to the OpenSimDefaults.ini file. | ||
78 | |||
79 | |||
80 | Compiling the module | ||
81 | |||
82 | Adding the OpenSimSearch C# source file to the source tree of OpenSim so it | ||
83 | will be compiled at the same time as OpenSim is compiled is the easiest way | ||
84 | to create to the DLL file needed by OpenSim. | ||
85 | |||
86 | Copy the OpenSimSearch directory in to the addon-modules directory of your | ||
87 | OpenSim source tree. After you have done that, compile OpenSim in the usual | ||
88 | way (runprebuild and nant) to create the DLL file. When nant finishes, you | ||
89 | will have an OpenSimSearch.Modules.dll file in the main bin directory of | ||
90 | your OpenSim source tree along with a matching .pdb (or .mdb) file. These | ||
91 | two files will be copied to the bin directory of your OpenSim instances | ||
92 | during the installation or update steps. | ||
93 | |||
94 | |||
95 | First time installation | ||
96 | |||
97 | The first installation step is the creation of a database that will hold | ||
98 | the data to be searched. If you have already installed the add-on module | ||
99 | osprofile you should use the same database as osprofile as it shares some | ||
100 | tables in common with ossearch. If you don't have osprofile installed you | ||
101 | will need to create a new database that will hold the search tables. Having | ||
102 | decided on the database to be used, use ossearch.sql (located in the | ||
103 | webroot/sql directory) to create the required tables in the database. The | ||
104 | name of this database will be needed when configuring one of the PHP files | ||
105 | in the next steps. | ||
106 | |||
107 | Copy the PHP files (located in the webroot directory) to your webserver. | ||
108 | Remember to set the permissions on the file so the webserver may access the | ||
109 | files. Use a text editor to open databaseinfo.php and enter the name or IP | ||
110 | address of the database server, the name of the database, and the user name | ||
111 | and password required to access the database. | ||
112 | |||
113 | The next part of the installation process is to set up and configure your | ||
114 | OpenSim instances. | ||
115 | |||
116 | Copy the two OpenSimSearch.Modules files created during the compile steps | ||
117 | (above) in to the bin directory of each of your OpenSim instances. The next | ||
118 | part of the installation process requires some changes to the OpenSim.ini in | ||
119 | all of your OpenSim instances. | ||
120 | |||
121 | Add the following lines to all OpenSim.ini files: | ||
122 | |||
123 | [Search] | ||
124 | ;/////////////////////////////////////////////////////////////////////////// | ||
125 | ;// The SearchURL is important. It must be correct or search won't work. // | ||
126 | ;// // | ||
127 | ;// Change the URL to point to the query.php file on your own HTTP server // | ||
128 | ;SearchURL = http://192.168.0.1/query.php | ||
129 | ;// // | ||
130 | ;/////////////////////////////////////////////////////////////////////////// | ||
131 | |||
132 | NOTE: You do not need to indent the above lines when adding them to your own | ||
133 | OpenSim.ini files. The lines were indented to offset them from the rest of the | ||
134 | text in this file. | ||
135 | |||
136 | Uncomment and edit the SearchURL line so it contains the correct address for | ||
137 | the webserver and needed path to where the query.php file was installed on | ||
138 | your webserver. | ||
139 | |||
140 | To allow the Teleport and Show on Map buttons to work properly (for search | ||
141 | results containing locations) the following two lines must be added to the | ||
142 | [Modules] section of the OpenSim.ini file: | ||
143 | |||
144 | LandServices = "RemoteLandServicesConnector" | ||
145 | LandServiceInConnector = "true" | ||
146 | |||
147 | The last changes to be made to the OpenSim.ini file are in the [DataSnapshot] | ||
148 | section. Change index_sims to true. You can have data_exposure set to all but | ||
149 | it is better to leave it on minimum so users can control what items can appear | ||
150 | in search results by using the "Show In Search" checkboxes. You can leave | ||
151 | default_snapshot_period commented out or you can uncomment it and set it to | ||
152 | whatever value you wish. The section on optimizing the configuration will | ||
153 | help you to decide an appropriate value for this setting. | ||
154 | |||
155 | The last change for OpenSim.ini is the setting for data_services. This line | ||
156 | must be uncommented and contain a valid URL for your webserver and the path | ||
157 | to the register.php file which you installed earlier. If you do not enter a | ||
158 | valid URL the OS instance will not get listed in the hostsregister table and | ||
159 | search data for the regions hosted by the OS instance will not be recorded or | ||
160 | updated. After entering the URL, exit and save the updated OpenSim.ini file. | ||
161 | |||
162 | |||
163 | Updating an existing installation | ||
164 | |||
165 | Updating an existing installation of ossearch is just a matter of copying a | ||
166 | few files to the same places where you had previously installed the files. | ||
167 | |||
168 | Copy all of the PHP files (located in the webroot directory) EXCEPT for | ||
169 | databaseinfo.php to the directory on your webserver where you place the | ||
170 | previous copies. If you also copy databaseinfo.php when copying the other | ||
171 | PHP files you will have to edit databaseinfo.php and reset the information | ||
172 | used to connect to the database. | ||
173 | |||
174 | Copy the two OpenSimSearch.Modules files created during compilation to the | ||
175 | bin directory of each of your OpenSim instances. | ||
176 | |||
177 | Finally, execute all of the SQL files located in the webroot/sql directory | ||
178 | where the filenames start with "update-". This step is very important to | ||
179 | make certain your database tables are up-to-date. | ||
180 | |||
181 | |||
182 | Configuration | ||
183 | |||
184 | With everything in place, the next step is to set up a task on your webserver | ||
185 | (or some other machine) which will invoke the URL to the parser.php file on | ||
186 | your webserver on a regular basis to ensure the contents of the database are | ||
187 | kept up-to-date. For a machine running Linux you can set up a cron job. For | ||
188 | a machine running Windows you can use Windows Scheduler. | ||
189 | |||
190 | See the section on optimizing the configuration to help you decide how often | ||
191 | the parser.php should be run. | ||
192 | |||
193 | |||
194 | Optimizing the configuration | ||
195 | |||
196 | When you change what items are to be found in search by clicking the checkbox | ||
197 | "Show In Search" or by removing an item that was set to show in search results | ||
198 | there is a delay before the change is reflected in the database tables. There | ||
199 | are four main factors that affect the length of this delay. They are: the | ||
200 | number of OpenSim instances, the value of default_snapshot_period used by the | ||
201 | DataSnapshot module, the time between calls to parser.php, and the number of | ||
202 | OpenSim instances processed each time parser.php is run. You can't easily | ||
203 | control the number of instances but you can control the other factors. | ||
204 | |||
205 | To explain how the factors affect the delay take a grid with 100 regions. If | ||
206 | you have one region per instance you have 100 instances. Using the default | ||
207 | settings and calling parser once an hour it would take 100 hours, or more than | ||
208 | four days, for changes to appear in search results. A more realistic setup is | ||
209 | one where you have an average of 4 regions run by each OpenSim instance. This | ||
210 | reduces the delay to 25 hours. This is a rather long delay for a relatively | ||
211 | small number of regions and instances. The delay can be reduced substantially. | ||
212 | |||
213 | A simple way to reduce the delay is to run parser.php more frequently. If | ||
214 | parser.php is run once every 15 minutes instead of once an hour (60 minutes) | ||
215 | the delay is reduced by a factor of 4 from 25 hours to 6.25 hours. Much better | ||
216 | but still a long delay. The delay can be reduced even further but to do so | ||
217 | requires a change to the parser.php file. | ||
218 | |||
219 | Near the end of the parser.php file is a SQL query that ends with "LIMIT 0,1". | ||
220 | It is the value "1" which is important. That value limits the number of OS | ||
221 | instances that will be processed each time parser.php is run. If the value is | ||
222 | changed from 1 to 3 then three OS instances will be processed on each run of | ||
223 | the parser.php file. This reduces the delay by a factor of 3 to just over | ||
224 | 2 hours. This is a much better delay than the original value of 25 hours. | ||
225 | |||
226 | For those of you who like math, the amount of delay can be expressed using | ||
227 | the following simple formula: | ||
228 | delay = # instances * time between runs of parser / limit value in parser | ||
229 | |||
230 | Three factors affecting the delay have been discussed but earlier it was | ||
231 | stated that there are four factors. The fourth factor is the value of | ||
232 | default_snapshot_period value located in the [DataSnapshot] section of the | ||
233 | OpenSim.ini file. This setting is specified in seconds and controls how often | ||
234 | the data used by parser.php will be updated. This setting doesn't have any | ||
235 | direct impact on the delay between updates of the database but if it is set | ||
236 | incorrecty it can efffectively increase the delay between database updates. | ||
237 | |||
238 | The example grid setup discussed earlier was adjusted to reduce the update | ||
239 | delay to just over 2 hours (2 hours and 5 minutes to be more precise). If the | ||
240 | value of default_snapshot_period is set to a value slightly greater than the | ||
241 | calculated delay it would be possible for parser.php to be called twice before | ||
242 | the data it retrieves would have been updated. This would turn a delay of two | ||
243 | hours into a delay of four hours. The proper setting is one that is *less* | ||
244 | than the delay calculated from the other three factors discussed earlier. | ||
245 | |||
246 | Given a delay of just over 2 hours, a good value for default_snapshot_period | ||
247 | would be 7200 (2 hours expressed in seconds). By keeping the value of this | ||
248 | setting close to, but less than, the delay between when parser.php is used | ||
249 | to get the data for an instance will minimize any overhead imposed on the | ||
250 | OpenSim instance when it creates the snapshot of searchable items while, at | ||
251 | the same time, ensures the data will have been updated by the next time the | ||
252 | parser.php is run to update the database. | ||
253 | |||
254 | A final comment about the setting for the time between runs of parser.php and | ||
255 | the value in the limit statement in that file. Avoid running parser.php too | ||
256 | frequently or setting the value in the LIMIT statement too high. Doing either | ||
257 | can cause unnecessary overhead or high loads on the webserver used to run | ||
258 | parser.php, or on the database server while it updates all the tables with | ||
259 | the latest information from the OpenSim instances. | ||
260 | |||
261 | |||
262 | Additional Information | ||
263 | |||
264 | A few words about event listings and the events database table. | ||
265 | Support is included for events but the event listings need to be created | ||
266 | using an external webpage. | ||
267 | |||
268 | The category for an event is stored as a number. The numbers for the | ||
269 | categories are as follows: | ||
270 | 0 - Any (NOTE: Event information will show "*Unspecified*") | ||
271 | 18- Discussion | ||
272 | 19- Sports | ||
273 | 20- Live Music | ||
274 | 22- Commercial | ||
275 | 23- Nightlife/Entertainment | ||
276 | 24- Games/Contests | ||
277 | 25- Pageants | ||
278 | 26- Education | ||
279 | 27- Arts and Culture | ||
280 | 28- Charity/Support Groups | ||
281 | 29- Miscellaneous | ||
282 | |||
283 | The dateUTC field is a timestamp for the event in UTC time. | ||
284 | |||
285 | The covercharge field is a boolean. Set it to 0 if there is no cover charge | ||
286 | for the event. When covercharge is not 0, the amount is in the coveramount | ||
287 | field. (It seems silly to require the boolean but this has been left in to | ||
288 | avoid any compatability issues.) | ||
289 | |||
290 | The globalPos field is the location of the event as a global grid coordinate. | ||
291 | The format is "x/y/z". where x and y are the grid X and Y positions (times | ||
292 | 256) plus the x and y offset within the region named by the simname field. | ||
293 | |||
294 | The eventflags field is 0 for a PG event, 1 for Mature, and 2 for Adult. | ||